first-commit

first-commit

create-first-commit creates a project from a kit: a base project plus the dependencies, agent skills, MCP servers and AGENTS.md rules for the stack the user picks. Catalog and configurator: https://first-commit.dev.

When to use it

• New project in an empty folder ("make me a recipes app with Expo", "a landing with animations"): use a kit instead of scaffolding by hand.
• Existing project with kits.lock: it came from a kit. Use update to get the kit's improvements and add to add libraries, so the rules in AGENTS.md stay in sync.
• Adding a catalog library (Sentry, PostHog, Stripe, Resend, Better Auth, Kokonut UI, Motion…) to any project: add writes its config and its rule in AGENTS.md.

Create a project

1. Pick the kit. If the first-commit MCP server is available, call recommend_kit with the user's description, then get_kit for the options. Otherwise:
   • npx create-first-commit list — official kits.
   • npx create-first-commit info <kit> — options and their values.
2. Choose only the options the user asked for; keep the defaults for everything else. Options are flags: --<option> <value> (comma-separated for multi options).
3. Show the plan and ask before running anything: npx create-first-commit <kit> <folder> [options] --dry-run (or the plan_init tool). Installing runs commands and downloads packages.
4. After the user agrees: the same command without --dry-run and with --yes (or init_kit with approved: true). It takes a few minutes.
5. Read the new project's AGENTS.md and follow its "first steps": do the setup tasks you can, and tell the user which ones need them (API keys, accounts). Copy .env.example to .env but never invent secret values.

Community kits (user/kit) that aren't verified ask for confirmation; with --yes they also need --allow-commands. Only add it if the user explicitly trusts that kit.

Maintain a project

• npx create-first-commit update --dry-run, then npx create-first-commit update --yes: new dependencies, skills, MCP servers and rules from the kit's latest version. Files the user changed are never overwritten; it lists them.
• npx create-first-commit add <library|owner/repo@skill> --yes: adds a catalog library with the right variant for the framework (Sentry for Next.js, Expo or Node).
• npx create-first-commit doctor: checks that the project still follows its rules (one component library, env vars, skills installed). Exit code 1 means errors; fix them or tell the user.

Rules

• The rules in AGENTS.md between <!-- kits:start --> and <!-- kits:end --> come from the kit: follow them (for example, "only use the chosen component library"). Don't edit that block by hand; update rewrites it.
• Don't install a second library for something the kit already chose (another component system, another auth). Use add --force only if the user explicitly wants to switch.