# AGENTS.md

## Always-on rules
This file is for instructions that matter on most coding tasks. Keep it lean, concrete, and executable.

Use these storage layers deliberately:
- root `AGENTS.md` for cross-cutting, always-on rules
- deeper `AGENTS.md` or `AGENTS.override.md` for path-specific rules
- repo skills in `.agents/skills/` and/or `.github/skills/` for detailed, situational workflows
- custom agents in `.github/agents/` for specialist roles with constrained tools

## Mission
Ship correct, minimal, maintainable code changes that match local patterns and read clearly. Prefer root-cause fixes over surface patches. Optimize for correctness, architectural fit, low diff surface, and verifiable results.

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

## Speed and token economy
Optimize for latency and token use on every task.

Default rules:
- keep messages, plans, and handoffs terse
- do not restate repo context, prior outputs, or the user request unless needed to act
- prefer one capable agent over many small agents
- spawn subagents only when the work is meaningfully parallel or requires a distinct specialty
- keep subagent prompts minimal: objective, owned scope, constraints, expected output
- avoid multi-stage agent chains unless the task is high-risk or cross-cutting
- summarize tool results instead of pasting long outputs
- quote only the lines needed to justify a decision
- read only the files and line ranges needed for the current step
- stop searching once you have enough evidence to act
- summarize large logs, traces, or generated diffs before reading raw artifacts end to end
- prefer targeted filters, focused test runs, and structured summaries over dumping thousands of lines into context
- for CI failures, triage with a dedicated log or CI skill before inspecting full logs
- keep root instructions concise enough that critical guidance is not truncated

## 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.

## Fast tools
Use the fastest repo-aware tools by default.

Rules:
- never use `grep` for project-wide search; use `rg`
- prefer `fd` or `fdfind` for file discovery; otherwise use `rg --files`
- never use `ls -R`; use `rg --files`
- prefer `rg -n -A 3 -B 3` for targeted context
- cap file reads at 250 lines per read
- use `jq` for JSON parsing and transformation
- avoid `cat | grep`; use `rg "pattern" file`
- avoid for repo-wide search: `grep`, `find`, `ls -R`

Common replacements:
- `grep -R "pattern" .` -> `rg "pattern"`
- `find . -name "*foo*"` -> `fd foo` or `rg --files | rg "foo"`
- `ls -R` -> `rg --files`
- `cat package.json | grep scripts` -> `jq '.scripts' package.json`

## 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:
- `task-breakdown` for very complicated, ambiguous, or multi-track requests that need durable narrowed problem briefs in `.tasks/`
- `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`
- `implement`
- `plan`
- `publish`
- `task-breakdown`
- `skill-creator`
- `skill-installer`

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 and should execute the `instruction_change` route before the final gate
- skip unnecessary downstream skills when the task is trivial and risk is low

Quick routing table:
- docs-only task -> `docs_only`
- trivial one-file code fix -> `trivial_code`
- very complicated or ambiguous problem that must be narrowed into durable subproblems first -> `task-breakdown`
- cross-file feature or bug fix -> `planned_change`
- AGENTS / skills / custom-agent change -> `instruction_change`
- final delivery check only -> `release_gate`
- production-impact incident or user-visible degradation -> `incident`
- capability-gap request (missing skill/agent) after initial discovery -> `planned_change` plus `skill-creator` or `skill-installer` before implementation

## Canonical routing profiles
Treat these profiles as the canonical routing vocabulary. The shipped config and workflow docs should use the same names and chains.
Standalone `.codex/agents/*.toml` files are the agent catalog source of truth; `.codex/config.toml` only carries global agent settings.

- `docs_only`: `docs-writer -> reviewer`
- `trivial_code`: `implementer -> reviewer`
- `planned_change`: `planner -> architecture-reviewer -> feature-builder -> implementer -> test-engineer -> reviewer`
- `instruction_change`: `instruction-maintainer -> reviewer -> gatekeeper`
- `release_gate`: `release-manager -> gatekeeper`
- `incident`: `incident-response -> ops-investigator -> gatekeeper`

## 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, pass only the minimum context needed for that owned scope
- keep every agent handoff synthetic and compact
- if a required agent cannot be spawned, stop and report the workflow as blocked

Default routing:
- `docs_only` enters at `docs-writer`
- `trivial_code` enters at `implementer`
- `planned_change` enters at `planner` and must include `architecture-reviewer` before `feature-builder`
- `instruction_change` enters at `instruction-maintainer`
- `release_gate` enters at `release-manager`
- `incident` enters at `incident-response`

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-creator` for creating or updating skills
- `skill-installer` for installing skills from curated sources or repositories
- `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 only when discovery is needed
- route by canonical profile first, then by specialist need
- 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 should return merged summaries, not long transcripts
- each agent should return 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

Delegation thresholds:
- do not spawn agents for trivial one-file edits, simple reads, or straightforward command execution
- prefer at most one active specialist unless parallel work clearly reduces wall-clock time
- if coordination overhead is likely to exceed the work, do the task in the current thread
- reviewers should be added only for risky, user-visible, or cross-file changes

## 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 keeps the approved plan summary concise and passes it forward only if needed

This skill is blocked if either agent cannot be spawned.

Use `task-breakdown` when:
- the request is too broad, ambiguous, or multi-track to plan cleanly in one pass
- you want durable narrowed-down problem records in `.tasks/`
- multiple follow-on plans or implementations may branch from one original request

Do not use `task-breakdown` for:
- a single narrow bug fix or feature request
- work that already has a concise, executable plan
- docs-only edits that do not need durable decomposition

When `task-breakdown` is called, run this flow:
1. coordinator ensures a root `.tasks/` directory exists
2. coordinator inspects existing `.tasks/*.json` files and chooses the next three-digit number
3. spawn `planner` to narrow the original request into discrete subproblems
4. coordinator writes one numbered JSON file per narrowed problem using the skill template contract
5. hand off each resulting problem to `plan` or `implement` as appropriate

This skill is blocked if `planner` 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. follow the gate and routing rules defined in the `implement` skill
2. split the implementation into independent features or file scopes only when parallel ownership is clean
3. coordinator records owned scope for each implementation agent in the handoff
4. spawn one `implementer` per independent scope, in parallel only when those scopes are disjoint
5. require each implementer to return a compact result summary
6. run `test-engineer`, `clean-code-reviewer`, and `reviewer` only when needed by risk or the skill gates
7. require each review agent to return compact findings only
8. coordinator merges findings before handoff

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 carries forward only the final docs outcome

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 only the final routing outcome in the handoff

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

Profile notes:
- `docs_only` and `trivial_code` are direct routes and should avoid unnecessary orchestration.
- `planned_change` is the default for non-trivial implementation work.
- `instruction_change`, `release_gate`, and `incident` are gated routes and should not silently downgrade to lighter paths.

## Agent handoff format
Do not create a repo memory system unless a nested skill explicitly requires it.

Default handoff format between agents:
- objective
- owned scope
- result
- blockers
- next step

Rules:
- keep handoffs under 10 lines when possible
- prefer direct coordinator-to-agent handoff over shared state files
- use shared files only when parallel agents need durable coordination
- if durable coordination is required, use one compact JSON file with only current state

## 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 standalone custom-agent validity (`name`, `description`, `developer_instructions`, supported optional fields, and filename/name parity) 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
