Create Starter

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; the root README stays English-only.

Security checks inspect local workflow definitions and referenced starter-series/.github policy, including composite actions and invoked scripts. Evidence includes source paths and content hashes. Unreadable or unsupported reusable workflows are reported as unverified; this checks configuration, not the latest Actions run or a live vulnerability scan.

Currently implemented

• CLI — package and binary identity are starter-series; npx starter-series my-package --template npm-package scaffolds one of 6 public 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 ..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. 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 . -incomplete- 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 6 public Starter Series templates. 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

npx starter-series my-package --template npm-package

Or build from a create-starter checkout:

npm ci npm run build node dist/index.js my-package --template npm-package

starter-series — scaffold a project from the Starter Series.

Usage starter-series --template [options] starter-series audit [path] starter-series audit-cd [path] starter-series audit-security [path] starter-series check [path] [--instructions] starter-series audit-instructions [path] starter-series proof-report [path] [--output ] [--stdout] starter-series seed-security-guidance [path] [--force] starter-series add-component [path] [--component ] [--starter ] [--apply] [--force] starter-series --list starter-series --help

Options -t, --template Template ID (see --list) -d, --description One-line project description -o, --output-dir Output directory (default: ./ ) --no-git Skip "git init" after scaffold --output proof-report output (default: /launch-proof-report.md) --stdout print proof-report Markdown; with --output, also writes the file --component add-component group: ci, security, dependabot, maintenance, all --starter 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

Only the six public templates listed here are available for generation and component downloads. Existing projects based on former templates can still be audited.

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 (한국어) — 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

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 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.

To rebuild the bundle locally:

npm ci

npm run bundle:mcpb # produces create-starter- .mcpb

Use as MCP server

Register the built binary in your MCP client (Claude Desktop, Cursor, etc.):

{

"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):

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 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 for the publish flow.

For npm release setup (trusted-publisher registration, including the post-2026-05-20 allowed-action step), see docs/RELEASING.md.

Tools

Scaffolding:

• **