io.github.starter-series/create-starter
Scaffold Starter Series projects and check release, deployment, security, and agent instructions.
Open source Open in the app JSON README (API)
About
Scaffold Starter Series projects and check release, deployment, security, and agent instructions.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- starter-series
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.4.0
- Stars
- 2
- Open pull requests
- 5
- Last push
- 2026-09-02T02:05:55Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:27
- Updated
- 2026-09-11 16:02:06
- Origin id
io.github.starter-series/create-starter
README
# create-starter
> Scaffold and audit Starter Series projects — MCP server, Claude Code skill, and CLI in one package.
Part of: **Human-Controlled AI Systems** — scaffolding is the easy half. What keeps a shipped repo trustworthy is the audit primitives (`audit`, `audit-cd`, `audit-security`) verifying release, CD, and CI security hygiene against a known bar — gating each merge instead of asking a human to re-check by hand.
Korean documentation is maintained under [`docs/ko/README.md`](docs/ko/README.md); the root README stays English-only.
## Currently implemented
- **CLI** — package and binary identity are `starter-series`; after the unscoped npm package is published, `npx starter-series my-bot --template discord-bot` scaffolds one of 11 templates with Zod-validated input, atomic rename on success, retry + timeout + 50 MB download cap.
- **MCP server** — nine stdio tools: `list_templates`, `create_project`, `audit_release`, `audit_cd`, `audit_security`, `audit_instructions`, `generate_launch_proof_report`, `seed_security_guidance`, `add_component`. One binary chooses the mode by argv (positional -> CLI, none -> MCP stdio).
- **Claude Desktop extension** — `.mcpb` bundle on every release; drag onto the Claude Desktop settings window.
- **Claude Code plugin + skill** — `/plugin install create-starter@starter-series` ships the MCP server and the conversational `create` skill together.
- **MCP Registry metadata** — `io.github.starter-series/create-starter`; registry submission is gated on the unscoped npm package being live and tarball-verified.
- **`audit_release`** — detects matched starter, version vs last-tag drift, CHANGELOG drift vs merged PRs (`git log <tag>..HEAD`), publish-workflow kind (release-please / publish-on-tag / auto-release).
- **`audit_cd`** — probes npm, PyPI, Open VSX, VS Marketplace, AMO, GitHub Releases for per-destination publish drift (in-sync / needs-publish / local-stale / not-found / unsupported).
- **`audit_security`** — checks 9 items: 8 core CI primitives (gitleaks with pin check, CodeQL, dependency audit, license check, `--ignore-scripts`, Dependabot grouped, secret-scanning hint, claude-code-security-review Action) plus the optional repo-author `claude-security-guidance.md`. The 8 core checks gate the HARDENED verdict; this repo passes 8/8 core.
- **`audit_instructions` / `audit-instructions`** — reviews agent instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions) for exact same-file duplicates, cross-file surface overlap, and keyword-based risk reminders. Duplicate/overlap findings need review; keyword risk summaries are advisory only and not exhaustive safety or semantic drift detection.
- **`proof-report` / `generate_launch_proof_report`** — runs release, CD, security, and instruction-review audits together and writes a client-ready [`Launch Proof Report`](docs/launch-proof-report.md). This is the monetizable handoff surface: evidence first, no "certified" claim, exit code 1 unless the repo is actually launch-ready.
- **`add_component`** — the remediation half of the audit loop: lifts a starter's CI/CD layer (ci / security / dependabot / maintenance / all) into an *existing* repo without re-scaffolding. Dry-run by default with a per-file plan (create / identical / skip-exists / overwrite); refuses a dirty git tree unless forced; never touches app code or secrets-bearing CD workflows. The dry-run plan doubles as a drift report against the starter.
- **Graduation guide** — `docs/graduation-from-vibe-coding.md` (+ Korean): five-step path from Lovable/Bolt/v0 exports to GitHub Actions + a real deploy target, using the release/CD/security audit primitives.
## Planned
- `audit_cd` support for Chrome Web Store, EAS, Railway, Fly, and GHCR. Currently reported as `unsupported` because those destinations require auth or have no public read API.
## Design intent
- **One binary, two surfaces.** CLI and MCP stdio share one scaffolding engine. Argv decides which surface answers. No duplicated logic for "the same thing called from a human vs an agent".
- **Atomic on failure.** Extraction happens in a sibling `.<name>-incomplete-<rand>` directory and only renames into the final path on success. Network failure, corrupt archive, partial write — none of them leaves a half-scaffolded directory behind.
- **Audit is first-class.** Templates ship a security baseline (gitleaks pinned to SHA, CodeQL, Dependabot grouped, `--ignore-scripts`, claude-code-security-review). The audit commands check whether a downstream repo still matches that bar — turning the baseline from a one-time scaffold into an ongoing gate.
- **Eat your own dogfood.** This repo passes `audit_security` 8/8 core checks (HARDENED); the 9th is the optional `claude-security-guidance.md`. If the tool that audits other repos can't pass its own bar, the bar isn't real.
- **Read-only outside its sandbox.** Downloads are capped (50 MB, 30 s timeout, 3 retries). Relative output paths cannot escape cwd; absolute paths are accepted only as explicit user intent. `git init` failure is logged but non-fatal.
## Non-goals
- **Full vendor parity in `audit_cd`.** Destinations without a public read API stay `unsupported` rather than reporting confidently-wrong state.
- **Rewriting app code.** The graduation flow lifts CI/CD from the matching starter; it never touches application code.
- **A general-purpose project generator.** Templates are the Starter Series 11. New stacks land as new starters, not as flags on `create_project`.
- **Semantic instruction drift or AI safety enforcement.** `audit_instructions` is a review aid for exact duplicate/surface overlap and keyword reminders. It is not a semantic similarity engine, runtime guardrail, red-team harness, or exhaustive safety/security linter.
## Quick start — CLI
```bash
# After the unscoped npm package is published:
npx starter-series my-bot --template discord-bot
# Before npm publication, run from source:
npm ci
npm run build
node dist/index.js my-bot --template discord-bot
```
```
starter-series — scaffold a project from the Starter Series.
Usage
starter-series <name> --template <id> [options]
starter-series audit [path]
starter-series audit-cd [path]
starter-series audit-security [path]
starter-series audit-instructions [path]
starter-series proof-report [path] [--output <file>] [--stdout]
starter-series seed-security-guidance [path] [--force]
starter-series add-component [path] [--component <g>] [--starter <id>] [--apply] [--force]
starter-series --list
starter-series --help
Options
-t, --template <id> Template ID (see --list)
-d, --description <text> One-line project description
-o, --output-dir <path> Output directory (default: ./<name>)
--no-git Skip "git init" after scaffold
--output <file> proof-report output (default: <path>/launch-proof-report.md)
--stdout print proof-report Markdown; with --output, also writes the file
--component <group> add-component group: ci, security, dependabot, maintenance, all
--starter <id> add-component source starter override
--apply Write the add-component plan (default is dry-run)
--force Overwrite differing component files or guidance
--list List templates and exit
-h, --help Show help and exit
-v, --version Print version and exit
Environment
CREATE_STARTER_DEBUG=1 Emit verbose stderr logs
```
## Available templates
| ID | Stack |
|----|-------|
| `mcp-server` | TypeScript + `@modelcontextprotocol/sdk` + Zod |
| `mcp-server-python` | Python + FastMCP |
| `npm-package` | Jest + ESLint + OIDC publish |
| `discord-bot` | discord.js v14 + Docker |
| `telegram-bot` | grammY + Docker |
| `browser-extension` | Chrome/Firefox MV3 |
| `vscode-extension` | VS Marketplace + Open VSX |
| `electron-app` | cross-platform + code signing |
| `react-native` | Expo + EAS |
| `cloudflare-pages` | Wrangler + Pages |
| `docker-deploy` | any language + GHCR + SSH |
Run `starter-series --list` (CLI) or call `list_templates` (MCP) for the authoritative, up-to-date list.
## Graduating from Lovable / Bolt / v0
Already have a working app on a vibe-coding platform and want to graduate to GitHub Actions + your own deploy target? Read [`docs/graduation-from-vibe-coding.md`](docs/graduation-from-vibe-coding.md) ([한국어](docs/graduation-from-vibe-coding.ko.md)) — a 5-step path that uses `audit`, `audit-cd`, and `audit-security` to diagnose your repo, then lifts CI/CD from the matching starter without rewriting your app code.
## Install from source
```bash
git clone https://github.com/starter-series/create-starter
cd create-starter
npm install
npm run build
```
Requires Node.js ≥22.
## One-click install in Claude Desktop
Grab the latest `.mcpb` bundle from the [Releases page](https://github.com/starter-series/create-starter/releases/latest) and drag it onto the Claude Desktop settings window. Claude Desktop unpacks the bundled `dist/` and `node_modules/` and registers `create-starter` as an MCP server — no `npm`, no config file, no absolute path.
> `.mcpb` (MCP Bundle, formerly `.dxt`) is Anthropic's packaged extension format for MCP servers. See [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
To rebuild the bundle locally:
```bash
npm ci
npm run bundle:mcpb # produces create-starter-<version>.mcpb
```
## Use as MCP server
Register the built binary in your MCP client (Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"create-starter": {
"command": "node",
"args": ["/absolute/path/to/create-starter/dist/index.js"]
}
}
}
```
Then ask your agent: *"Use create-starter to scaffold a new discord bot named `my-bot`."* The agent will call `list_templates` if needed and then `create_project`.
> The binary speaks **MCP stdio** when called with no extra arguments, and switches to **CLI mode** when given any positional argument or flag. Both modes share the same scaffolding engine.
## Use as Claude Code plugin
The plugin bundles both the MCP server and the `create` skill — one install wires them up together.
From the Claude Code REPL:
```
/plugin marketplace add starter-series/create-starter
/plugin install create-starter@starter-series
```
Then ask Claude: *"scaffold a new discord bot named `my-bot`"* and the `create-starter:create` skill guides the conversation into the MCP tools.
For local development (no marketplace round-trip):
```bash
claude --plugin-dir /path/to/create-starter
```
Point at a git clone so edits in `skills/create/SKILL.md` or `dist/index.js` take effect the moment the session starts.
## Use via MCP Registry
After registry publication, this server uses the [Official MCP Registry](https://registry.modelcontextprotocol.io/) namespace:
```
io.github.starter-series/create-starter
```
MCP-compatible clients that integrate registry discovery can install it by name without manual path wiring. The registry entry points at the npm package `starter-series`, so the registry step must run only after the npm package is published and verified.
Ownership is verified through GitHub OIDC (namespace `io.github.starter-series/*`) and npm tarball inspection (`package.json#mcpName`). See [`.github/workflows/publish-mcp-registry.yml`](https://github.com/starter-series/create-starter/blob/main/.github/workflows/publish-mcp-registry.yml) for the publish flow.
For npm release setup (trusted-publisher registration, including the post-2026-05-20 allowed-action step), see [`docs/RELEASING.md`](docs/RELEASING.md).
## Tools
Scaffolding:
- **`list_templates`** — returns the full template table as JSON.
- **`create_project`** — args:
- `template` *(required)* — template ID from the table above.
- `name` *(required)* — project name matching `^[A-Za-z0-9][A-Za-z0-9_-]*$`.
- `description` *(optional)* — one-line description.
- `output_dir` *(optional)* — defaults to `./<name>` relative to the MCP server's cwd. Relative paths must stay inside cwd; absolute paths are accepted as explicit user intent.
- `init_git` *(optional, default `true`)* — run `git init` after scaffold.
Audit (each takes an optional `path` arg, default = MCP server cwd; all read-only):
- **`audit_release`** — release-readiness diagnosis. CLI mirror: `starter-series audit [path]`.
- **`audit_cd`** — per-destination publish-drift probe. CLI mirror: `starter-series audit-cd [path]`.
- **`audit_security`** — baseline CI security hygiene check. CLI mirror: `starter-series audit-security [path]`.
- **`audit_instructions`** — agent-instruction duplicate and surface-overlap review, with advisory keyword risk summaries. CLI mirror: `starter-series audit-instructions [path]`.
- **`generate_launch_proof_report`** — combined Markdown launch handoff from release, CD, security, and instruction-review audits. CLI mirror: `starter-series proof-report [path] [--output <file>] [--stdout]`.
- **`seed_security_guidance`** — generate a starter-aware `claude-security-guidance.md` draft. CLI mirror: `starter-series seed-security-guidance [path] [--force]`.
- **`add_component`** — propose or apply starter CI/CD components to an existing repo as a dry-run plan. CLI mirror: `starter-series add-component [path] [--component <g>] [--starter <id>] [--apply] [--force]`.
## Safety & reliability
- Project names are regex-validated before any filesystem touch; relative output paths are rejected if they escape the working directory.
- Downloads enforce a 30 s timeout, 3-attempt exponential backoff, and a 50 MB size cap.
- Extraction happens in a sibling `.<name>-incomplete-<rand>` dir; on any failure (network, corrupt archive, extraction error) the tmp dir is removed. The final path only appears via an atomic `rename` once everything succeeded.
- `git init` failures are logged to stderr but do not fail the scaffold; the project is usable without a `.git` directory.
## Supply-chain security pre-wired
Every Starter Series template ships with the 9 checks `audit_security` looks for — no opt-in required:
| Check | What it catches |
|---|---|
| **gitleaks** (SHA256-pinned manual install) | Committed secrets in code or history |
| **CodeQL** (weekly + PR) | Static analysis for JS/TS/Python |
| **Dependency audit** (`npm audit --audit-level=moderate` / `pip-audit`) | Known CVEs in transitive deps |
| **License check** | GPL/AGPL contamination |
| **`--ignore-scripts`** on every `npm/pnpm/yarn install` | Malicious postinstall scripts |
| **Dependabot grouped updates** | Lockfile-conflict storms from one-by-one bumps |
| **GitHub secret scanning + push protection** | Tokens leaked at push time |
| **`anthropics/claude-code-security-review`** Action on PR | AI-based diff review |
| **`claude-security-guidance.md`** *(this is the only one you write)* | Org-specific rules consumed by Anthropic's in-session [Claude Code Security Guidance Plugin](https://www.anthropic.com/news/claude-code-plugins) (released 2026-05-26) |
This was Vercel's stack during their 2026-04-21 npm supply-chain incident — they pre-empted compromise via the same pre-wired checks plus Socket/npm/GitHub coordination. The Starter Series ships those checks pre-wired in every starter.
## License
MIT © heznpc