Skip to content

The agentic layer

AGENTS.md, rules, skills, subagents, hooks, solution docs and MCP servers. What each hook does, which agents run it, and what each of the 10 agent targets gets.

13 min read

PagesThe agentic layer

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.

LayerWhere it lands in every repoWhat it is for
RulesRoot 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.mdRepeated work, run by name
Agents.agents/agents/<id>.mdSubagents with their own prompt
Hooks.agents/hooks/: one copy of each guard, run.mjs, guards.jsonChecks that run around a tool call
Solution docsdocs/solutions/The mistakes, written down in advance
MCP serversEach agent's own MCP configTools 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.md in the folder it governs, like src/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>.md with the rule's exact paths:. 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, git and security load every session.
  • testing covers tests/** and test files under src/.
  • deployment covers next.config.ts, vercel.json, package.json, src/proxy.ts, src/app/**/route.ts and .env.example.
  • ui-kit covers src/components/** and src/app/**: build from the component kit, never a one-off.
  • landing-and-legal covers src/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:

AgentHook 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 PreToolUse hook runs before the call. Exit code 2 (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 PostToolUse hook 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.
HookRunsWhat it doesShips in
block-destructiveBefore BashRefuses 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-detectorBefore Bash, Read, GrepRefuses 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-writeAfter Edit, Write, MultiEdit, Bash, Read, GrepReplaces 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-typecheckBefore BashRewrites 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-lintAfter Edit, Write, MultiEditRuns Biome on the one file that changed, applies the safe fixes, and reports what it could not fix.Solo and team
enforce-doc-metaAfter Edit, Write, MultiEditChecks the frontmatter on files in docs/solutions/ and docs/plans/, and says what is missing.Solo and team
enforce-git-trackedBefore BashRefuses a git commit while untracked files exist.Team only
plan-gateBefore Edit, Write, MultiEdit, NotebookEdit, BashRefuses writes under src/ until a plan in docs/plans/ says status: approved. See solo and team mode.Team only
guard-neon-sqlBefore BashRefuses 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-typecheck refuses the bare tsc and names the command to run instead.
  • Redaction is Claude Code only. Elsewhere env-leak-detector-write checks edits and writes only, and the check before the command is what stops a leak. In Codex, env-leak-detector runs 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:hooks

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

AgentIts own filesGuard 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.jsonYes
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.mdYes
GitHub Copilot.github/hooks/agentic-guards.json, .github/agents/<id>.agent.md, .github/copilot/settings.json (plugin), .mcp.jsonYes
Antigravity.agents/hooks.json, .agents/mcp_config.json. It reads .agents/skills/, .agents/agents/ and .agents/rules/ as they areYes
Gemini CLI.gemini/settings.json (makes it read AGENTS.md, plus hooks and MCP), .gemini/agents/Yes
OpenCodeopencode.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/ itselfNo
Windsurf.devin/hooks.v1.json for Devin Local (the default agent in Windsurf, now called Devin Desktop, and in the Devin CLI), .mcp.jsonYes
Kiro.kiro/skills/ (Kiro does not read .agents/skills/), .kiro/settings/mcp.json, .kiro/steering/ for rules that did not fitNo

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.md on its own (since 2.1.277) only while no CLAUDE.md exists in the project or any folder above it. A CLAUDE.md in a parent folder (from bun init, say) turns that off.
  • So the repo ships .claude/rules/agents-md.md, whose first line imports the root AGENTS.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, so claudeMdExcludes in .claude/settings.json turns 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.json and .github/copilot/settings.json declare 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.toml makes codex plugin list fail.
  • 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.