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 <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 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 <name> --template <id> [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 <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

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

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:

• 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:

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

Instruction checks

starter-series check --instructions [path]
starter-series check --instructions [path] --json
starter-series check --instructions [path] --update-state

check without --instructions runs the existing release, CD, security and instruction audits. audit-instructions remains a compatible alias. MCP clients keep using audit_instructions(path?, update_state?); the library entry remains auditInstructions(path?, { updateState? }).

One scan covers AGENTS/CLAUDE/GEMINI, overrides, Copilot instructions, Cursor rules, Claude rules/skills and .agents rules/skills/workflows. The check reports import and symlink aliases, verbatim mirrors, local overrides, exact duplicates and cross-file overlap. Canonical selection is inferred from links and filenames unless explicitly configured. It does not detect semantic similarity. Instruction source files are never rewritten.

Optional .starter-series/instructions.json selects a canonical source and records owner decisions. Copy the exact id, evidenceHash and paths from the JSON report into a decision's id, evidenceHash and scope; then explicitly supply the owner's reason, identity and approval date:

{
  "schemaVersion": 1,
  "canonical": "AGENTS.md",
  "decisions": []
}

Each decision requires reason, approvedBy, approvedAt (YYYY-MM-DD), and at least one of reviewAfter, expiresAt (YYYY-MM-DD) or reviewReason. A decision only accepts its exact finding and scope. Evidence changes, expiry or a due review make it stale; approval is never generated by the checker. Accepted findings remain visible. This file records owner approval; it is not an authentication mechanism.

Checks are read-only by default. --update-state (or MCP update_state: true) explicitly saves .starter-series/instructions-state.json for new/changed/known/resolved delta comparison. State contains identities and evidence hashes, not instruction text; commit it only if the team wants a shared baseline. Malformed metadata fails the check. Exit codes remain 0 for clean/advisory or accepted findings, 1 for pending/stale review findings, and 2 for usage or operational errors.