| name | agents-md-template |
| description | Use when bootstrapping a new repo for AI-assisted development, when no AGENTS.md / CLAUDE.md / copilot-instructions.md / .cursorrules exists yet, or when consolidating scattered tool-specific config into one source of truth. Triggers on "create AGENTS.md", "set up agent instructions", "new project setup", "configure Claude/Cursor/Copilot/Codex", "onboarding a repo", or noticing duplicated agent config across tool-specific files. |
AGENTS.md Template
Design principle: AGENTS.md is the single source of truth. Tool-specific files (CLAUDE.md, copilot-instructions.md, .cursor/rules/) all point here. — substratia.io
Quick Reference
| |
|---|
| Use when | Bootstrapping a repo for AI-assisted dev; no AGENTS.md exists yet |
| Skip when | AGENTS.md already exists — edit in place; don't recreate |
| Output | AGENTS.md at repo root + one-line pointer files for each tool |
| Sequence | Step 0 — before any documentation chain work begins |
| Iron rule | One source of truth. CLAUDE.md / .cursor / copilot all point here. |
| Sibling skills | [[project-kickoff-prd]] · [[technical-specification]] · [[architecture-decision-record]] · [[implementation-plan]] · [[status-tracker]] · [[independent-verification]] · [[git-workflow]] |
Template
Copy everything below into your project root as AGENTS.md, then fill in the brackets.
> **Stop. Read this entire file before doing anything.**
> This is the single source of truth for how we work on this project.
> Tool-specific files (CLAUDE.md, copilot-instructions.md, .cursor/rules/)
> all point here. Do not look for instructions elsewhere.
## 1. Project Identity
- **Name:** [Project Name]
- **One-liner:** [What this project does in one sentence]
- **Tech stack:** [e.g., Python 3.12 / FastAPI / Terraform / GitHub Actions]
- **Repo structure:**
## 2. Documentation Chain — Read Before You Code
This project uses a six-document chain. **Read them in order.**
| Doc | Path | Purpose | When to Read |
|-----|------|---------|-------------|
| **PRD** | `docs/prd.md` | What we're building and why | Before any feature work |
| **SPEC** | `docs/spec/*.md` | Precise technical contracts (API, data model, edge cases) | Before writing any code |
| **ADR** | `docs/adr/ADR-*.md` | Why we chose A over B — append-only, never rewrite | Before making architectural decisions |
| **IMPL PLAN** | `docs/plans/implementation-plan.md` | Milestones and step-by-step tasks | Before starting a task |
| **STATUS** | `docs/status.md` | Where we are right now — live progress | **First thing every session** |
| **VERIFICATION LOG** | `docs/verification-log.md` | Verdicts with evidence for every completed task — append-only | Before marking anything done; when auditing what "done" meant |
### Session Protocol
1. **Start of session:** Read `docs/status.md`. If the In-Flight Checkpoint is not `none`, the previous session crashed — recover from it. Otherwise the latest handoff log entry is your briefing.
Read the SPEC for the module you're working on. Follow the contract exactly.
Check before making any architectural choice. If no ADR covers it, flag it to the user.
If anything decided in this session makes a fundamental document (PRD, SPEC, ADR, IMPL PLAN, this file) stale or contradicted — or the user proposes a new feature — flag it the moment it happens and propose the update. Route the change through the chain before writing code.
Checkpoint (In-Flight Checkpoint + module table). Push the task branch and open a draft PR, then request independent verification — the task stays at 🔍 until a verifier with fresh context returns PASS. Never mark your own work ✅; never merge your own PR.
Update — module table, header block, append a handoff log entry, reset the In-Flight Checkpoint to .
---
[e.g., Python — strict typing, all functions annotated]
[e.g., ruff format]
[e.g., ruff check --fix]
[e.g., pytest]
[e.g., ]
[e.g., ]
[e.g., ]
---
[e.g., Cloud-neutral orchestration; cloud-specific only at the provider layer (ADR-001)]
[e.g., All network calls isolated behind a single function for offline testability (ADR-003)]
[e.g., Point-in-time correctness: never read data filed after the decision date (ADR-005)]
---
without asking.
without asking.
They are append-only. Supersede with a new ADR if needed.
(PRD, SPEC, ADR, IMPL PLAN, AGENTS.md) without the user's explicit approval — propose the change, then wait for the nod.
Every session ends with a handoff log entry.
Ask the user.
Marking a task ✅ requires an independent verifier's PASS, not your claim.
The suite count only goes up (test ratchet). A failing test is information, not an obstacle.
Acceptance criteria are locked when the task starts; changes require the user's explicit approval.
Every task gets its own branch and ships as a draft PR (one task = one PR).
Merge requires the verifier's PASS and a human who has read the diff.
---
Before claiming a task is built:
exits 0
— report exact count (e.g., "142/142 pytest")
all pre-existing tests still pass
suite count ≥ previous baseline — no tests deleted or skipped
every acceptance criterion in the relevant spec is met
reflects what you just did
A verifier with — sub-agent or fresh session, never this conversation — re-runs the task's done condition exactly as written in the SPEC / IMPL PLAN and appends a verdict with evidence to .
Only a PASS verdict moves the task from 🔍 to ✅ in STATUS.
Three consecutive FAILs on the same task → stop and escalate to the user. Do not loop indefinitely; do not weaken criteria to converge.
A human reads the diff and can explain the change in their own words before it merges. Code you can't explain is comprehension debt — and it compounds.
The verification log entry is the review digest: what changed, what was proven, what the risks are.
---
How Tool-Specific Files Should Reference AGENTS.md
Each AI coding tool has its own config file. They should all contain only one instruction:
CLAUDE.md:
Read and follow AGENTS.md in the project root. It is the single source of truth.
.github/copilot-instructions.md:
Read and follow AGENTS.md in the project root. It is the single source of truth.
.cursor/rules/main.mdc:
Read and follow AGENTS.md in the project root. It is the single source of truth.
This ensures any Agent, regardless of tool, gets the same instructions.
