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`](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-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
npx starter-series my-bot --template discord-bot

# Or build from a create-starter checkout:
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 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

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