# AGENTS.md

## Mission
Ship the smallest correct change, verify it, and leave a short handoff that explains what changed, how it was checked, and what remains risky.

Keep this root file small. Put detailed procedures in skills or nested `AGENTS.md` files.

## Instruction layout
Use these layers on purpose:
- root `AGENTS.md` for always-on repository rules
- deeper `AGENTS.md` or `AGENTS.override.md` for path-specific rules
- `.agents/skills/` and `.github/skills/` for reusable workflows
- `.github/agents/` for specialist subagents

If the root file starts teaching full workflows, move that material into a skill.

## Discover commands first
Do not guess the repo command surface. Derive it from the repo before editing.

Use this order:
1. CI and automation: `rg -n "run:|uses:|make |just |uv |pytest|pnpm|npm|yarn|ruff|mypy|tox" .github/workflows .circleci .azure-pipelines 2>/dev/null`
2. Task runners and manifests: `rg -n "^[A-Za-z0-9_.-]+:|^\\s{2,}[A-Za-z0-9_.-]+:|\\[project\\]|\\[tool\\.|scripts|dependencies|devDependencies" Makefile justfile Taskfile pyproject.toml package.json tox.ini noxfile.py 2>/dev/null`
3. Local docs: `rg -n "install|setup|build|lint|format|typecheck|test|coverage|migrate" README* docs/ . 2>/dev/null`

Prefer `rg` and targeted reads over broad scans.

## Done means
The task is done only when all applicable items are true:
- the requested behavior is implemented or updated correctly
- the diff is minimal and follows local patterns
- validation matches the blast radius
- docs/examples/changelog were updated when user-visible behavior changed
- skipped checks and residual risk are disclosed

## Use skills, not prose
For any non-trivial task, route through a small skill set:
- `plan` for cross-file, risky, unfamiliar, or unclear work
- `implement` for code changes and validation
- `docs` for docs/examples/changelog work
- `publish` for final release-facing checks and handoff

Canonical repo skills:
- `docs`
- `exec-plan`
- `implement`
- `plan`
- `publish`
- `skill-instantiator`

Do not create large multi-purpose skills. Each skill should say:
- when to use it
- when not to use it
- inputs
- outputs
- success criteria

Routing rules:
- use exactly one primary skill as the entrypoint for a task
- a later skill may be called only as a downstream stage of the current skill
- choose the earliest necessary skill, not the latest possible one
- if the request changes AGENTS, skills, or agents, `publish` is the primary skill

Quick routing table:
- trivial one-file code fix -> `implement`
- cross-file feature or bug fix -> `plan`, then `implement`
- docs-only task -> `docs`
- code change with user-visible behavior -> `implement`, then `docs`, then `publish`
- capability-gap request (missing skill/agent) after initial discovery -> `feature-builder` and `skill-instantiator` before implementation
- AGENTS / skills / custom-agent change -> `publish`
- final delivery check only -> `publish`

## Spawn agents explicitly
Do not only describe delegation. When the platform supports subagents, actually spawn them.

Calling a skill is an execution instruction:
- do not stop after naming the skill
- start the agent sequence defined by that skill
- run the listed agents in order unless the skill defines a concurrent stage
- pass the output of each step to the next step
- when a stage fans out, give each spawned agent the current context and merge their results before continuing
- when agents run in parallel, they must communicate through a shared physical memory layer stored as JSON
- each agent writes a short synthetic update to that JSON memory before finishing its stage
- if a required agent cannot be spawned, stop and report the workflow as blocked

Default routing:
- trivial one-file edit: `implementer`
- non-trivial bug fix or feature: `feature-builder`, which then routes through planning, implementation, validation, review, docs, and gate steps
- planning-only request: `planner`
- docs-only change: `docs-writer`
- release or final quality pass: `gatekeeper`
- AGENTS, skills, or custom-agent changes: `instruction-maintainer`

Common specialist roles:
- `architecture-reviewer` for boundaries, dependency direction, and change schematics
- `api-contract-reviewer` for interface drift and compatibility risk
- `performance-reviewer` for hot paths and resource regressions
- `security-reviewer` for trust boundaries and exploitability
- `clean-code-reviewer` for maintainability and future change safety
- `bug-triager` for isolating repros and narrowing likely causes
- `ops-investigator` for CI, packaging, deployment, or environment failures
- `test-engineer` for focused validation and regression coverage
- `skill-instantiator` for creating missing skills, specialists, and catalog growth
- `docs-researcher` for official API or docs verification
- `docs-writer` for user-facing documentation updates
- `release-manager` for versioning and publish readiness

Execution rules:
- assign one coordinator agent for every skill invocation
- start with a read-only agent for non-trivial work
- write-capable agents may run concurrently only when each agent owns a disjoint file or feature scope
- if write scopes overlap or may overlap, use a single write-capable agent for that stage
- skills execute sequential stages by default, but may run multiple agents concurrently inside a stage when ownership is split cleanly
- concurrent agents must share findings through explicit handoffs or merged summaries before the next stage starts
- the coordinator creates the shared JSON memory layer before fan-out and closes the stage after merge
- each agent should append concise state: goal, owned scope, findings, outputs, blockers, and next recommendation
- before spawning parallel implementers, the coordinator must record the owned scope for each agent
- no agent may edit files outside its recorded owned scope
- skills are subagent workflows by design; do not replace them with an in-thread summary

## When to use each packaged skill
Use `plan` when:
- the task touches multiple files, layers, or packages
- the blast radius is unclear
- you need explicit invariants, sequencing, or validation planning

Do not use `plan` for:
- one-file typo fixes
- formatting-only edits
- trivial docs changes

When `plan` is called, run agents in this order:
1. coordinator spawns `planner`
2. coordinator passes the planner output to `architecture-reviewer`
3. coordinator writes the approved plan summary to memory

This skill is blocked if either agent cannot be spawned.

Use `implement` when:
- source code, tests, config, or behavior must change
- a bug fix needs repro plus validation
- a planned change is ready to execute

Do not use `implement` for:
- planning-only work
- docs-only edits with no code change

When `implement` is called, run agents in this order:
1. coordinator splits the implementation into independent features or file scopes
2. coordinator records owned scope for each implementation agent in memory
3. spawn one `implementer` per independent scope, in parallel only when those scopes are disjoint
4. require each implementer to read and update the shared JSON memory layer
5. coordinator merges the implementation outputs
6. run `test-engineer`, `clean-code-reviewer`, and `reviewer` concurrently on the merged result
7. require each review agent to append findings to memory
8. coordinator merges their findings before continuing

This skill is blocked if any required agent cannot be spawned.

Use `docs` when:
- docs, examples, changelog, onboarding, or migration notes must change
- the task is docs-only
- code changed in a user-visible way and docs need to catch up

Do not use `docs` for:
- code-only implementation with no documentation impact

When `docs` is called, run agents in this order:
1. coordinator spawns `docs-writer`
2. coordinator passes the result to `reviewer`
3. coordinator records docs outcome in memory

This skill is blocked if either agent cannot be spawned.

Use `publish` when:
- you need the final gate before handoff
- release notes, validation summary, or residual-risk disclosure matter
- AGENTS or skill changes need a routing-quality check

Do not use `publish` as a substitute for implementation or testing.

When `publish` is called, run agents in this order:
1. coordinator spawns `gatekeeper`

For AGENTS or skill changes, run:
1. coordinator spawns `instruction-maintainer`
2. coordinator passes the maintainer result to `reviewer`
3. coordinator passes the reviewer result to `gatekeeper`
4. coordinator records routing-eval outcome in memory

This skill is blocked if any required agent cannot be spawned.

## Shared memory layer
Spawned agents coordinate through a physical JSON memory layer in the repository or task workspace.

Use a memory directory, not one shared mutable JSON document:
- `.agent-memory/manifest.json` for task-level metadata
- `.agent-memory/events/<timestamp>-<agent>-<stage>.json` for append-only agent updates

`manifest.json` should contain:
- `task`
- `primary_skill`
- `coordinator`
- `status`
- `owned_scopes`
- `active_stage`
- `required_agents`
- `artifacts`

Each event record should stay synthetic and compact. Each agent writes:
- `agent`
- `stage`
- `goal`
- `owned_scope`
- `inputs_read`
- `decisions`
- `outputs`
- `blockers`
- `next_step`

Rules:
- read `manifest.json` and existing event files before starting work
- write a new event file after meaningful progress and at stage completion
- do not rewrite another agent's event file
- update `manifest.json` only through one designated coordinator agent for the stage
- include file paths or scope ids in every event written by a write-capable agent
- the coordinator is responsible for conflict detection, merge decisions, and final stage status
- use the memory layer to hand off context across concurrent agents
- do not treat the memory layer as a substitute for source-of-truth code or tests

## Required handoff for non-trivial work
The final handoff should include:
- what changed
- why the change is correct
- commands run and outcomes
- commands intentionally not run
- residual risks or follow-ups

Keep it short. The evidence matters more than narration.

## Instruction-system changes
If this repository changes any of the following:
- `AGENTS.md`
- `.github/agents/**`
- `.github/skills/**`
- `.agents/skills/**`
- `.codex/**`

Then:
- run the `publish` skill, which must execute `instruction-maintainer -> reviewer -> gatekeeper`
- include at least one positive and one negative routing check in the handoff
- if the change introduces new catalog artifacts, also check agent contract validity (`contract_version`, required policy fields, and `agent_contract` structure) in the final handoff

## Scope and precedence
- deeper `AGENTS.md` files override this file for their subtree
- `AGENTS.override.md` overrides `AGENTS.md` in the same directory
- direct user instructions override repository instructions
- code, tests, CI, and build config are the source of truth when docs drift
