Bootstrap a repository's AI coding agent operating system — AGENTS.md, CLAUDE.md, docs/agents (architecture, code-style, lessons-learned), docs/plans, docs/release.md, and portable plan-mode/code-review skills — all rewritten from evidence gathered in the target repo. Use when setting up agent docs for a new or existing project. Triggers on "bootstrap agent system", "set up AGENTS.md", "port agent docs", "create agent operating system", "agent onboarding docs".
Bootstrap a repository's AI coding agent operating system — AGENTS.md, CLAUDE.md, docs/agents (architecture, code-style, lessons-learned), docs/plans, docs/release.md, and portable plan-mode/code-review skills — all rewritten from evidence gathered in the target repo. Use when setting up agent docs for a new or existing project. Triggers on "bootstrap agent system", "set up AGENTS.md", "port agent docs", "create agent operating system", "agent onboarding docs".
license
MIT
metadata
{"version":"1.0.0"}
Bootstrap Agent System
You are setting up this repository's AI coding agent operating system, modeled on a proven pattern. Port the system and doctrine, then rewrite all content for THIS repo based on evidence you gather here. Never paste product-specific details from another codebase unless they verifiably apply to this repo.
Goal
Give AI agents (Cursor, Claude Code, etc.) a single, living contract for how to work in this repo:
Root entrypoint docs (AGENTS.md + CLAUDE.md)
Deeper agent docs under docs/agents/
Durable plans under docs/plans/
Release notes under docs/release.md
Project skills under the repo's skills directory (e.g. .agents/skills/)
Explicit rules that agents must use project scripts, keep docs living, and record lessons
Reference templates
This skill ships with templates in references/. Read each one when you reach the step that uses it:
Read these and take notes. Every claim in the docs you write must trace back to something you saw here:
package.json (root + each workspace): scripts, packageManager, workspaces
Lockfile(s): which package manager is actually in use
CI config (.github/workflows/, turbo.json, vercel.json, etc.): what "green" means
tsconfig.json / language configs: strictness flags agents must respect
Lint/format config (eslint, biome, oxlint, prettier, ultracite, etc.) and how it is invoked
Test setup: runner, file naming, colocation vs __tests__/
Existing docs: README.md, CONTRIBUTING.md, any existing AGENTS.md/CLAUDE.md/.cursor/rules — inventory overlaps so you consolidate instead of contradicting
Auth, database, migrations, deploy targets — only note what exists
If the repo already has a partial AGENTS.md or Cursor rules, merge — preserve unique local rules, deduplicate, and keep one source of truth.
Deliverables
AGENTS.md # root entrypoint (living document)
CLAUDE.md # symlink -> AGENTS.md
docs/
agents/
architecture.md # real system map, written from evidence
code-style.md # this repo's actual conventions
lessons-learned.md # seeded, append-only knowledge base
plans/
README.md # how durable plans work here
release.md # how THIS project ships
.agents/
skills/
plan-mode/SKILL.md # portable doctrine (references/skill-plan-mode.md)
code-review/SKILL.md # portable doctrine (references/skill-code-review.md)
<stack skills as applicable>
Process (in order)
Phase 0 evidence gathering (checklist above)
Write docs/agents/architecture.md and docs/agents/code-style.md from evidence, using the corresponding templates as structure
Write AGENTS.md from references/agents-md-template.md; then symlink: ln -sf AGENTS.md CLAUDE.md. If symlinks are not viable (e.g. Windows contributors without dev-mode), create CLAUDE.md containing only: See AGENTS.md — single source of truth.
Add docs/release.md, docs/plans/README.md, and seed docs/agents/lessons-learned.md from their templates
Create .agents/skills/plan-mode/SKILL.md (verbatim from references/skill-plan-mode.md, stripping the template preamble) and .agents/skills/code-review/SKILL.md (from references/skill-code-review.md, adapting commands to this repo)
Add stack-specific skills only if the dependency is verified in package.json (AI SDK, workflow/durable-execution, React best practices, etc.). Do NOT port product-specific skills from other codebases. If the repo has a frontend (react/next/vue/svelte/tailwind verified in package.json), follow the design-md skill to create DESIGN.md and .agents/skills/frontend-design/ — it classifies the repo first and never overwrites an existing design language.
Run the verification pass below
Report a short summary: files created, what was adapted vs skipped, conflicts found with existing docs, recommended next skills for this stack
Operating doctrine (must be encoded in AGENTS.md + skills)
Living docs — when an agent is wrong or learns a non-obvious invariant, it appends to docs/agents/lessons-learned.md, ideally in the same change
Scripts over raw tools — discover commands from AGENTS.md / package.json before running generic tsc / eslint / etc.
Plan before large changes — plan-mode doctrine for multi-file/architectural work; durable plans in docs/plans/
Separation of concerns — extract colocated modules instead of growing god-files
Verify with project CI — after changes, run the repo's canonical check script
Don't invent architecture — document what exists; if unclear, explore and ask
Verification pass (required before finishing)
Every command listed in AGENTS.md exists in package.json scripts (or is a real workspace tool invocation) — run each read-only one to confirm
Every relative link in AGENTS.md and docs/agents/* resolves to an existing file
CLAUDE.md resolves to AGENTS.md content (cat CLAUDE.md)
No section in any doc describes something you did not verify in this repo
No contradictions with pre-existing docs (README, CONTRIBUTING, lint configs)
AGENTS.md is scannable in under a minute (~100 lines)
Constraints
Do not copy another product's architecture (web/agent/sandbox splits, specific auth providers, database branching setups, etc.) unless verified in THIS repo
Prefer accurate short docs over impressive long docs — an agent that trusts a wrong doc is worse than one with no doc
No secrets or env values in docs; reference .env.example instead
Match this repo's markdown tone and formatting
If the target already has a partial AGENTS.md, merge carefully rather than overwriting unique local rules
Done when
An agent opening this repo can find commands, architecture, style, and lessons within one hop from AGENTS.md
CLAUDE.md resolves to the same content
Plan and review workflows exist as skills
Every doc statement is evidence-backed and the verification pass is clean
