One AGENTS.md configures Claude Code (Claude), OpenAI Codex (GPT), and the
GitHub Copilot cloud agent for a project — shared standards, native slash commands,
and three default methodology tools: Superpowers (workflow), ponytail (minimal
code), OpenSpec (spec layer). The agent CLIs you use are assumed already installed
(the script verifies them; it installs the methodology tools).
Run inside the project you want to configure:
# Default — prompts you through which agents to enable
curl -fsSL https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh | bash
# Default + all optional extras (graphify code graph, Claude guardrail + process hooks)
curl -fsSL https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh \
| bash -s -- --with-all-extras
# No curl? Same via wget
wget -qO- https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh | bash
wget -qO- https://raw.githubusercontent.com/sirinsoftware/ai-dev-kit/main/bootstrap.sh \
| bash -s -- --with-all-extrasNon-interactive: append bash -s -- --yes --agents=claude,codex,copilot. All flags: ./setup.sh --help.
Everything you customize lives in one file — AGENTS.md. Fill in every {{…}} — or run
/fill-agents to have your agent infer them from the repo's code, git history, and config
(best-guess; review the git diff after). All three agents read it. This is where your code
standards, check tools, and PR/commit formats go:
| What you set | Section in AGENTS.md |
Placeholder(s) |
|---|---|---|
| Project overview / tech stack | top | {{PROJECT_OVERVIEW}}, {{TECH_STACK}} |
| Code standards + formatter | Standards → Code | {{CODE_STANDARDS}}, {{FORMAT_COMMAND}} |
| Commit message format | Standards → Commit messages | {{COMMIT_STANDARDS}} |
| PR rules + description format | Standards → Pull requests | {{PR_STANDARDS}}, {{PR_DESCRIPTION_FORMAT}} |
| Code-review rubric (priorities, severity, merge gates) | Standards → Code review | {{REVIEW_STANDARDS}}, {{REVIEW_MERGE_GATES}} |
| Code-check tools (lint/type/security) | Standards → Static analysis | {{LINT_COMMAND}}, {{TYPECHECK_COMMAND}}, {{SECURITY_SCAN_COMMAND}} |
| Test command + coverage target | Standards → Tests | {{TEST_COMMAND}}, {{COVERAGE_TARGET}} |
| Real device / environment | Standards → Real device | {{REAL_DEVICE_NOTES}}, {{REAL_DEVICE_TEST_SCRIPT}}, {{REAL_DEVICE_PREREQS}} |
| Extra guardrails | Guardrails | {{EXTRA_GUARDRAILS}} |
Only edit one other file — and only if you use the Copilot cloud agent:
.github/workflows/copilot-setup-steps.yml — replace the TODO with your real toolchain +
the lint/test installs, then commit it to the default branch.
Share vs. local — .gitignore. Your agent config (AGENTS.md, .claude/, .codex/,
.github/, openspec/, slash commands) is committed by default, so the whole team shares one
setup. Keep *.local.*, .claude/settings.local.json, *.adk-bak, .ai-dev-kit-manifest,
and .ai-dev-kit-config ignored — those are personal/local. (With graphify enabled, the
graph is ignored too; to share it instead, remove its line from the managed block and
git add -f graphify-out/ — tracked files override .gitignore and survive re-runs.)
Everything else is generated and managed for you — leave it alone:
CLAUDE.md, .claude/, .codex/config.toml, .github/copilot-instructions.md, and the
slash-command files.
- Codex: open the project once and trust it (so
.codex/config.tomlloads); restart Codex to load the/prompts:*commands. - Copilot: pick the model in the task model-picker.
- Restart your agents so the OpenSpec + ponytail skills load.
| Tool | Owns | Example |
|---|---|---|
| OpenSpec | What to build — proposal, specs, design, tasks; validated + archived on disk | /openspec-propose "reset password" → review → APPROVED.md |
| Superpowers | How it gets built — brainstorm → plan → failing-test-first → review | "Add feature X" → it plans + writes tests first |
| ponytail | How little gets built — YAGNI, stdlib/native first, shortest diff | "Add a date picker" → <input type="date"> |
Routing (baked into AGENTS.md): work touching 3+ files, a schema, or a shared API gets
an OpenSpec change; smaller work uses Superpowers alone. OpenSpec owns proposal/design/archive
(no duplicate design docs or task lists), Superpowers owns execution (worktree per change,
TDD), ponytail rules apply throughout. Archive the change last. openspec validate runs as a
CI check on spec changes.
/openspec-propose "user can reset password by email" # spec: proposal + design + tasks
# review it, then create openspec/changes/<id>/APPROVED.md
/openspec-apply-change # TDD implementation from tasks.md
/verify-feature <id> # reviews ∥ tests ∥ device ∥ docs
/openspec-archive-change # fold the change into the specs
(Codex invokes OpenSpec skills as $openspec-propose etc.; Claude/Copilot use /openspec-….)
Guides scaffolded into your project: docs/guides/develop-a-feature.md · docs/guides/test-a-feature.md.
In Claude Code these run as skills, roughly in order; Codex/Copilot follow the same flow via AGENTS.md.
| Skill | Activates | Does |
|---|---|---|
brainstorming |
before writing code | refines a rough idea through questions, explores alternatives, presents the design for validation (for an OpenSpec change, the proposal/design docs take this role) |
using-git-worktrees |
after design approval | creates an isolated workspace on a new branch, runs project setup, verifies a clean test baseline |
writing-plans |
with an approved design | breaks work into bite-sized tasks (for an OpenSpec change, tasks.md already is the plan) |
subagent-driven-development / executing-plans |
with a plan | dispatches a fresh subagent per task with two-stage review, or executes in batches with human checkpoints |
test-driven-development |
during implementation | enforces RED → GREEN → REFACTOR; deletes code written before its test |
requesting-code-review |
between tasks | reviews against the plan and reports issues by severity — critical issues block progress |
finishing-a-development-branch |
when tasks complete | verifies tests, presents options (merge / PR / keep / discard), cleans up the worktree |
/ponytailtoggle lazy mode (/ponytail ultrafor max) ·/ponytail-reviewa diff ·/ponytail-auditthe repo- in-mode: "add a date picker" →
<input type="date">, not a library
Opt-in flags (--with-all-extras enables all three; interactive setup asks, defaulting to no):
| Extra | Does | Cost / notes | Flag |
|---|---|---|---|
| graphify | Queryable code knowledge graph: graphify query "how does auth work", path, explain |
Python/uv dependency; rebuild after code changes (graphify update .); graph is gitignored |
--with-graphify |
| Claude guardrail hooks | Deny secret-file reads + dangerous shell (cat .env, rm -rf /) — deterministic, Claude only |
none | --with-hooks |
| Process hooks | Block production edits while the branch's OpenSpec change lacks APPROVED.md; refuse to stop on a red build (ADK_PROCESS_OFF=1 bypass) |
Claude only | --with-process-hooks |
A project bootstrapped by an older kit version with graphify keeps it: setup and
update.sh detect the existing graph and record it as enabled instead of removing it.
Implement rate limiting for our HTTP API. Follow our workflow — don't jump straight to code.
1. Spec: /openspec-propose "per-client rate limiting on the public API" — requirements
with WHEN/THEN scenarios, a design that names the algorithm + storage, tasks.
2. Stop so I can review; I'll create APPROVED.md in the change folder.
3. Implement: /openspec-apply-change — failing test first per task, minimal code
(ponytail), worktree on a branch named after the change id.
4. Verify: /verify-feature — reviews, tests, device run, docs; commit message + PR
description written but nothing committed or pushed.
5. I'll merge; then /openspec-archive-change.
- Slash commands (where enabled):
/pr-review,/deep-test,/security-audit(no API key),/progress-report,/repeatable-task,/report-html,/fill-agents(fillAGENTS.mdfrom the repo),/update-tools,/review-fresh,/verify-feature. Codex uses/prompts:<name>. - HTML reports/plans: ask any report/plan command for HTML — or run
/report-html <topic|file>— for a styled, self-contained.html(Catppuccin Mocha) underdocs/reports/. The house style lives inAGENTS.md→ Output formats. - Options & conflict handling:
./setup.sh --help. Re-running is safe (idempotent; tracked in.ai-dev-kit-manifest);AGENTS.mdis never overwritten. - Update tools:
~/.ai-dev-kit/update.sh .(or/update-tools) — upgrades the OpenSpec CLI + project skills, upgrades graphify/rebuilds the graph where enabled, and cleans up anything an older kit version left (retired commands, old MCP entries). Add--dry-runto preview. - Uninstall:
~/.ai-dev-kit/uninstall.sh .(add--dry-runto preview) — restores backups, removes only kit files, strips kit.gitignore/hook entries; youropenspec/specs are never touched. - Docs: how each agent reads its config · design · tool catalog · QA test plan.