StartupKitstartupkit

Agent Guide

Add or refresh a project's AGENTS.md with the startupkit CLI — the default guide for any project, or the StartupKit Stack superset, and how to merge it without clobbering your own conventions.

The startupkit CLI installs and refreshes a project's AGENTS.md — the instructions your AI agents read automatically. There are two flavors, from one source:

  • Default guide — tool-agnostic defaults for any project: how we work, Linear workflow + etiquette, the git-worktree workflow, SDLC/ADLC, and boundaries. Installed by startupkit agents.
  • Stack guide — the default guide plus a ## StartupKit Stack section (commands, environment, layout). This is what init ships. Installed by startupkit agents --stack.

Pick the flavor

Use the Stack flavor if the project was scaffolded with StartupKit Stack — it has apps/web plus wrangler/wrangler.jsonc, bun run deploy/bun run migrate, and apps/web/.dev.vars. Otherwise use the default flavor.

Add the guide (no AGENTS.md yet)

npx startupkit agents            # default guide (any project)
npx startupkit agents --stack    # StartupKit Stack superset

This writes AGENTS.md + CLAUDE.md and ensures .worktrees/ is gitignored (it only appends to .gitignore if one already exists).

Update a project that already has one — merge, don't clobber

If the project already has an AGENTS.md with its own conventions, do not run the plain command and never --force — it replaces the whole file. Fetch the canonical text and merge it:

npx startupkit agents --out            # default guide to stdout
npx startupkit agents --out --stack    # Stack superset to stdout

Then:

  • Keep the project's own sections (release/review process, product specifics, custom commands).
  • Refresh StartupKit's sections: How we work, Development workflow (git worktrees), Linear, SDLC, ADLC, Boundaries — and, for the Stack flavor, ## StartupKit Stack.
  • Never duplicate a heading; merge into the existing one.
  • CLAUDE.md is just @AGENTS.md — leave or restore it, no merging needed.

Options

FlagEffect
-d, --dir <path>Target directory (default: current)
-f, --forceOverwrite existing files without prompting
--stackWrite the Stack superset instead of the default guide
--outPrint the guide to stdout and write nothing (for merges)

Verify

  • AGENTS.md ends with a newline and has no duplicated sections.
  • .gitignore contains .worktrees/.
  • CLAUDE.md contains exactly @AGENTS.md.

Then commit through the project's normal flow (branch + PR).

Scaffold a SaaS App

Optional: run npx startupkit init to scaffold a production-ready SaaS — Next.js on Cloudflare, auth on D1, Stripe billing, email, and a /kit page — or bring your own stack.

Agent Handoff Prompt

The copy-paste prompt that hands your AI agent a complete task: scaffold a production SaaS, wire GitHub, deploy, and verify each step.

On this page

Pick the flavorAdd the guide (no AGENTS.md yet)Update a project that already has one — merge, don't clobberOptionsVerify