AGENTS.md Author

Purpose

Create a short AGENTS.md that routes agents to authoritative docs and commands without becoming a giant project knowledge dump.

Use nested-agents-md-author after the root file is healthy when apps, packages, or docs need scoped local instructions.

Inspect First

• existing AGENTS.md or other agent instruction files
• docs/00-index.md, README, architecture docs, testing docs, and command docs
• manifests and scripts to confirm standard commands

Procedure

1. Keep AGENTS.md short.

   • Target under 120 lines.
   • Put detailed knowledge in docs/.
   • Link to docs instead of repeating them.

2. Include only stable operating contract.

   • Read-first docs.
   • Standard commands.
   • Non-negotiable repo rules.
   • Architecture and quality gate pointers.
   • Validation expectations.

3. Preserve local policy.

   • If existing instructions contain project-specific constraints, keep them or move them to the right doc and link back.
   • Remove stale, duplicated, or framework-generic prose.

4. Update related docs.

   • If AGENTS.md references a missing doc, create or update that doc through repo-knowledge-base-builder.
   • If commands changed, update docs/development/commands.md.
   • If directory-specific rules are needed, keep root AGENTS.md as the map and create scoped files through nested-agents-md-author.
   • If control-loop artifacts exist, link to feature state, progress, decisions, startup readiness, definition of done, and session handoff docs.
   • If instructions are long or duplicated, run or recommend check_instruction_snr.py.
   • Use project-local-skill-generator when project-specific workflows belong in .codex/skills instead of root AGENTS.md.

Required Shape

Use this structure unless the repo already has a stronger convention:

# Agent Instructions

This file is a map. The authoritative project knowledge is in `docs/`.

## Read first

- `docs/00-index.md`
- `docs/architecture/overview.md`
- `docs/architecture/boundaries.md`
- `docs/development/commands.md`
- `docs/testing/strategy.md`
- `docs/quality/code-style.md`

## Standard commands

- Dev: `./scripts/dev`
- Lint: `./scripts/lint`
- Typecheck: `./scripts/typecheck`
- Test: `./scripts/test`
- Build: `./scripts/build`
- Full validation: `./scripts/validate`

## Rules

- Inspect existing code and docs before changing behavior.
- Prefer established patterns over new abstractions.
- Add or update tests for behavior changes.
- Update docs when commands, environment variables, routes, schemas, or architecture change.
- Run the narrowest relevant check first, then `./scripts/validate`.
- If validation cannot run, state the exact command, error, and likely cause.

## Architecture boundaries

See `docs/architecture/boundaries.md`.

Validation

• Check every linked doc exists.
• Check every listed command exists or is documented as intentionally absent.
• Check the file is concise and not duplicating architecture, product, or testing docs.
• Check root instructions route to state and handoff files when the repo uses them.

Completion Criteria

• AGENTS.md is a routing file, not a manual.
• It contains no stale commands or missing links.
• It preserves project-specific constraints in the right location.