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.

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

# 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

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