Plenty of starter kits wire up Stripe. That part is table stakes. This generator exists for the layer on top: the config that lets an agent open the repo cold and act like it has worked here for a month.
It is not tied to one agent. AGENTS.md is the instruction file, and
.agents/ holds the rest. Both ship in every repo, whatever you
pick. Each agent you pick in the builder also gets the files only it reads.
Claude Code is one of those agents, not a requirement.
That layer has six parts. They are the six fields of the AgentLayer type in
packages/core/src/types.ts, and the six counters in the builder. Every
generated repo ships rules, skills, agents, hooks and solution docs. MCP servers
come with the batteries that have one (10 of 26), so a Blank repo has none.
| Layer | Where it lands in every repo | What it is for |
|---|---|---|
| Rules | Root AGENTS.md, a nested AGENTS.md per rule folder, each rule in full in .agents/rules/ | Conventions, scoped to the paths they govern |
| Skills | .agents/skills/<name>/SKILL.md | Repeated work, run by name |
| Agents | .agents/agents/<id>.md | Subagents with their own prompt |
| Hooks | .agents/hooks/: one copy of each guard, run.mjs, guards.json | Checks that run around a tool call |
| Solution docs | docs/solutions/ | The mistakes, written down in advance |
| MCP servers | Each agent's own MCP config | Tools the agent can call |
Each agent target adds a copy in its own format where it can't read these. See what each agent target gets.
A battery that only adds files is a worse version of installing the package yourself. That is why the contribution gate exists: no config, no battery.
Rules are path-scoped
A rule is markdown with a paths: list in its frontmatter:
---
title: Never build Stripe objects client-side
paths:
- src/lib/billing/**
- src/app/api/webhooks/stripe/**
---
Verify every webhook signature. Build every Stripe object on the server.
Scope matters more than content. Put forty rules in one file at the root and
the agent loads all forty on every task. Each one costs context, relevant or
not. A rule on src/lib/billing/** should load when the agent works on billing.
The agent editing a marketing page never sees it.
So the generator writes each rule where agents look for it:
- A rule for the whole repo goes in the root
AGENTS.md. - A scoped rule goes in a nested
AGENTS.mdin the folder it governs, likesrc/lib/billing/AGENTS.md. Most agents load that file when they work in the folder. - Every rule is also in
.agents/rules/<id>.md, in full. - Claude Code gets
.claude/rules/<id>.mdwith the rule's exactpaths:. It loads one when it reads a matching file.
Codex reads at most 32 KiB of AGENTS.md per chain: the root file plus every
nested one down to the folder it works in. Every chain stays under 30 KiB. When
a file runs out of room, it links the rule to .agents/rules/<id>.md instead
of copying it in. Agents with glob-scoped rules then get a native copy
for exactly those globs: .cursor/rules/<id>.mdc in Cursor, trigger: glob in
Antigravity, .kiro/steering/ in Kiro, and .github/instructions/ in Copilot
when Claude Code is not picked.
The stack ships seven rules in every repo:
code-style,gitandsecurityload every session.testingcoverstests/**and test files undersrc/.deploymentcoversnext.config.ts,vercel.json,package.json,src/proxy.ts,src/app/**/route.tsand.env.example.ui-kitcoverssrc/components/**andsrc/app/**: build from the component kit, never a one-off.landing-and-legalcoverssrc/lib/site.ts, the landing page, the legal pages and/llms.txt.
Two more come with the features they govern. app-shell ships with any auth
battery and covers the signed-in app. billing-core ships with any payments
battery and covers the shared billing layer. The design adds tokens-only.
Batteries add rules for the paths they own.
Rules are checkable statements, not advice. "Before you finish a task, re-read the files you touched" is a rule an agent can follow. "Write clean code" is not.
Skills are the repeated work
A skill is a named command with instructions attached, in the Agent Skills
format (SKILL.md). Run one as /name in most agents, or $name in Codex.
They live in .agents/skills/, which Codex, Cursor, GitHub Copilot, Gemini CLI,
Antigravity, OpenCode, Windsurf and Junie read. Claude Code gets a copy in
.claude/skills/, and Kiro in .kiro/skills/.
The stack ships /setup, /verify, /write-spec, /qa-feature,
/deploy-to-vercel, /security-audit, /landing-copy and /help. With an
auth battery it adds /add-app-page, and with a payments battery
/edit-pricing. Every design adds /new-component. Batteries add their own:
- Stripe and Lemon Squeezy:
/add-plan,/test-webhook - Polar and Dodo:
/add-product,/test-webhook - Better Auth:
/add-oauth-provider,/protect-route - Admin panel:
/add-admin-page,/add-admin-action - Neon:
/db-branch,/migrate-on-neon - Drizzle:
/add-table,/migrate - PostHog:
/add-event,/ask-product
The test: have you explained it twice? The third time, write it down.
Agents are narrower than the main thread
Four subagents ship with the stack:
pr-reviewer: reviews against this repo's rules, not general taste.security-auditor: secrets, auth boundaries, injection, dependency scan.documentarian: keeps README, DESIGN.md and the solution docs current.system-manager: owns the agent setup itself (AGENTS.md,.agents/and each agent's own folder), and adds a rule when a correction repeats. It is why the setup gets better instead of going stale.
Every design adds designer. Batteries can add specialists. Neon ships
db-inspector, which is told to run SELECT and EXPLAIN only. Its Neon MCP
server is read-only (?readonly=true in each agent's MCP config). It still has
a shell, so only its prompt stands between it and a write through psql. The
guard-neon-sql hook blocks DDL and unqualified delete, not insert or
update. PostHog ships product-analyst.
Each subagent's prompt is in .agents/agents/<id>.md, which Antigravity and
Windsurf read. Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and
OpenCode get a copy in their own folder and format, such as
.codex/agents/<id>.toml or .github/agents/<id>.agent.md.
Hooks: checks the model can't skip
Rules are instructions. An agent can misread them. Hooks are code the agent runs around a tool call.
Every guard is written once, in Claude Code's hook format, and lives in
.agents/hooks/. Each agent's own hook config runs it through
.agents/hooks/run.mjs. The launcher turns that agent's payload into the
format the guards speak, runs the guard, and answers in the agent's own format.
The guards run in seven agents:
| Agent | Hook config |
|---|---|
| Claude Code | .claude/settings.json |
| Codex | .codex/hooks.json |
| Cursor | .cursor/hooks.json |
| GitHub Copilot | .github/hooks/agentic-guards.json |
| Antigravity | .agents/hooks.json |
| Gemini CLI | .gemini/settings.json |
| Windsurf (Devin Local) | .devin/hooks.v1.json |
OpenCode, JetBrains AI and Kiro run none of them. OpenCode runs hooks as
plugins, and its plugin API changed between v1 and v2. Junie reads hooks from
user config only. Kiro does not document its tool names. The rules in
AGENTS.md still apply there.
A guard is declared with Claude Code's event names:
- A
PreToolUsehook runs before the call. Exit code2(or a deny decision) means the call never happens, and the agent is told why in the same turn. In Claude Code it can also rewrite the call. - A
PostToolUsehook runs after the call. It can't undo it. It can report a problem to the agent, or, in Claude Code, redact what the agent sees.
| Hook | Runs | What it does | Ships in |
|---|---|---|---|
block-destructive | Before Bash | Refuses recursive force deletes, DROP and TRUNCATE sent to a database, force pushes, git reset --hard, git clean, dd, and truncating redirects onto tracked files. | Solo and team |
env-leak-detector | Before Bash, Read, Grep | Refuses anything that would print, send or commit a secret: echo $DATABASE_URL, grep KEY .env.local, the Read tool on .env.local, a bearer token in a curl header, git add .env. It also matches live values read from your env files, so a real key is caught even when the command looks innocent. | Solo and team |
env-leak-detector-write | After Edit, Write, MultiEdit, Bash, Read, Grep | Replaces any live secret in command, read or search output with [redacted: KEY] before the agent sees it. On writes, it flags a key pasted into a file, a private env var read in a client component, and a secret inside a log call. | Solo and team |
enforce-typecheck | Before Bash | Rewrites a bare tsc (or npx tsc, ./node_modules/.bin/tsc) into the project's typecheck script before it runs, through the hook's updatedInput. Blocks a tsc inside $(...) or bash -c, where there is nothing clean to rewrite. | Solo and team |
auto-lint | After Edit, Write, MultiEdit | Runs Biome on the one file that changed, applies the safe fixes, and reports what it could not fix. | Solo and team |
enforce-doc-meta | After Edit, Write, MultiEdit | Checks the frontmatter on files in docs/solutions/ and docs/plans/, and says what is missing. | Solo and team |
enforce-git-tracked | Before Bash | Refuses a git commit while untracked files exist. | Team only |
plan-gate | Before Edit, Write, MultiEdit, NotebookEdit, Bash | Refuses writes under src/ until a plan in docs/plans/ says status: approved. See solo and team mode. | Team only |
guard-neon-sql | Before Bash | Refuses raw DDL through psql, migrations that would run through the Neon pooler, and schema pushes that skip migration files. The repo's own db:migrate scripts pass. | Neon battery |
The tool names are Claude Code's. Each agent's config maps them to its own
tools, and leaves out a tool it has no hook for. .agents/hooks/README.md in
your repo says which guard runs on which tools in each agent.
How many you get:
- Solo: 6 hooks. 3 run before the call, 3 after.
- Team: 8 hooks. 5 before, 3 after.
- Neon adds 1, before the call.
Outside Claude Code, a few things work differently:
- A rewrite becomes a block.
enforce-typecheckrefuses the baretscand names the command to run instead. - Redaction is Claude Code only. Elsewhere
env-leak-detector-writechecks edits and writes only, and the check before the command is what stops a leak. In Codex,env-leak-detectorruns on shell commands only. - Trust comes first. Codex, Cursor and Gemini CLI run project hooks only
in a folder you trust. Codex also asks you to review each hook once in
/hooks. - Cursor runs each guard once. Cursor also loads Claude Code hooks from
.claude/settings.json. When it does, the launcher steps aside, so a guard runs once per call.
Know the limits. env-leak-detector-write runs after the write lands, so the
secret is on disk before the agent is told to remove it and rotate it. A guard
that fails to run lets the call through, with a warning, and so does a repo
whose dependencies are not installed yet. No hook stops a human pasting a key
into a file by hand.
Prove they work
A guard is only worth something while it is still wired up. Every generated repo ships a self-test:
bun run verify:hooksIt feeds every guard, battery guards included, synthetic tool calls through
.agents/hooks/run.mjs, the same launcher every agent's config runs. First in
Claude Code's format: every probe, with its exit code and message. Then again
in the format of each other agent the repo has a hook config for, on the tools
that config wires. Each guard gets block cases and allow cases. Block cases run
again from src/, as they would after the agent runs cd. A guard that lets a
block case through, or blocks an allow case, fails the script. On the Indie
SaaS preset that is 374 probes.
Run it on a fresh clone, and after any change to .agents/hooks/ or to an
agent's hook config.
Solution docs are memory
docs/solutions/ is seeded per battery: idempotent Stripe webhooks, edge
session pitfalls with Better Auth, Neon pooling and branching, the PostHog
identify race, Sentry source maps on Vercel. The problems your team was going to
hit in week three, written before week one. They are plain markdown, so every
agent can read them.
Every one is also public in the cookbook. Contributors write them for a stranger, because a stranger is who reads them.
New ones get written as you go. /ce-compound at the end of a piece of work
turns a debugging session into a doc instead of letting it evaporate.
MCP servers
Batteries declare MCP servers in their manifest. The generator writes the one
list into each agent's own MCP config: .mcp.json (Claude Code, GitHub Copilot
and Windsurf), .codex/config.toml, .cursor/mcp.json, .gemini/settings.json,
.agents/mcp_config.json (Antigravity), opencode.json, .junie/mcp/mcp.json
and .kiro/settings/mcp.json.
10 of the 26 batteries ship one: Better Auth, DataFast, Dodo Payments, Neon, Polar, PostHog, Postmark, Sentry, Stripe and Supabase. A server that doesn't exist is worse than none, so the registry only ships real ones.
Remote servers sign in with OAuth from the agent. No agent reads .env.local.
Local servers that need a key (Postmark, Supabase) are left out of the
Antigravity, OpenCode and Junie configs, which have no safe way to pass one.
SETUP.md says so, and says how to connect each server in each agent.
What each agent target gets
In the builder you pick your AI tools. These are the agent targets. All 10 are
ticked by default, and none is locked. A target adds only the files its agent
can't read from AGENTS.md and .agents/:
| Agent | Its own files | Guard hooks |
|---|---|---|
| Claude Code | .claude/rules/agents-md.md (imports AGENTS.md), .claude/rules/<id>.md with paths: for every rule the root AGENTS.md does not carry in full, .claude/skills/, .claude/agents/, .claude/settings.json (hooks, plugin), .mcp.json | Yes |
| Codex | .codex/hooks.json, .codex/agents/<id>.toml, .codex/config.toml (MCP) | Yes |
| Cursor | .cursor/hooks.json, .cursor/agents/, .cursor/mcp.json, .cursor/rules/<id>.mdc only for rules that did not fit in their AGENTS.md | Yes |
| GitHub Copilot | .github/hooks/agentic-guards.json, .github/agents/<id>.agent.md, .github/copilot/settings.json (plugin), .mcp.json | Yes |
| Antigravity | .agents/hooks.json, .agents/mcp_config.json. It reads .agents/skills/, .agents/agents/ and .agents/rules/ as they are | Yes |
| Gemini CLI | .gemini/settings.json (makes it read AGENTS.md, plus hooks and MCP), .gemini/agents/ | Yes |
| OpenCode | opencode.json (MCP), .opencode/agents/ | No |
| JetBrains AI | .aiassistant/rules/agents-md.md (AI Assistant chat does not read AGENTS.md, so this always-on rule points at it), .junie/mcp/mcp.json. Junie reads AGENTS.md and .agents/skills/ itself | No |
| Windsurf | .devin/hooks.v1.json for Devin Local (the default agent in Windsurf, now called Devin Desktop, and in the Devin CLI), .mcp.json | Yes |
| Kiro | .kiro/skills/ (Kiro does not read .agents/skills/), .kiro/settings/mcp.json, .kiro/steering/ for rules that did not fit | No |
Amp, Factory Droid, Warp, Cline, Kilo Code, Zed, Goose, Augment Code, Qwen
Code, Crush and Jules need no files of their own. They read AGENTS.md as it
is, and all but Jules read .agents/skills/.
Codex, Cursor, Gemini CLI, Kiro and JetBrains load project config (hooks, MCP, subagents) only after you trust the folder.
Why there is no root CLAUDE.md
On purpose. We measured it:
- Claude Code reads
AGENTS.mdon its own (since 2.1.277) only while noCLAUDE.mdexists in the project or any folder above it. ACLAUDE.mdin a parent folder (frombun init, say) turns that off. - So the repo ships
.claude/rules/agents-md.md, whose first line imports the rootAGENTS.md. Claude Code loads it once, in every version (checked on 2.1.285). - Claude Code would also load each nested
AGENTS.md. Its scoped rules come from.claude/rules/instead, soclaudeMdExcludesin.claude/settings.jsonturns the nested files off for Claude Code alone.
Zed reads the first match of .rules, .cursorrules, .windsurfrules,
.clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md,
CLAUDE.md and GEMINI.md. So the repo ships none of the names that come
before AGENTS.md in that list.
The workflow on top
The Compound Engineering plugin adds the loop: /ce-brainstorm, /ce-plan,
/ce-work, /ce-code-review and /ce-compound (they start with $ in
Codex). It is not forked.
- Claude Code and GitHub Copilot get it through settings.
.claude/settings.jsonand.github/copilot/settings.jsondeclare the plugin's marketplace, pinned to a release tag, and enable the plugin. Each offers it once you trust the folder. - Codex, Cursor, Antigravity, Windsurf and OpenCode get the install line
in
SETUP.md. Codex gets no project config for it on purpose: a marketplace declared in.codex/config.tomlmakescodex plugin listfail. - Gemini CLI, JetBrains AI and Kiro have no install path yet. The repo's own skills still work there.
Plans land in docs/plans/. Learnings land in docs/solutions/. The loop
closes.
The pin is on purpose. An upstream breaking change should be something you upgrade into, not something that shows up one morning mid-task.