Skip to content

Implementation Repository AGENTS.md

Implementation repository AGENTS.md files tell Codex how to work inside a code-owning repository after the repository's docs foundation exists.

Do not create or refresh implementation repository AGENTS.md before docs/bootstrap/BootstrapContext.md, docs/process/ChangeWorkflow.md, docs/core, and docs/state exist.

flowchart TD
  bootstrap["BootstrapContext.md"] --> workflow["ChangeWorkflow.md"]
  workflow --> localDocs["docs/core and docs/state"]
  localDocs --> agents["AGENTS.md"]
  agents --> implementation["Repository implementation work"]
  implementation --> verification["Verification and docs parity"]

Preconditions

Before creating or refreshing AGENTS.md, verify:

  • docs/bootstrap/BootstrapContext.md
  • docs/process/ChangeWorkflow.md
  • docs/core/
  • docs/state/
  • docs/process/
  • docs/changes/
  • mkdocs.yml
  • hooks.py
  • docs/index.md
  • docs/stylesheets.css

If docs/bootstrap/BootstrapContext.md is missing, stop. Generate it from the product-main repository and copy it into the implementation repository first.

Required Emphasis

Implementation repository AGENTS.md should:

  • identify implementation ownership boundaries
  • reference Bootstrap Context and local docs instead of embedding long architecture explanations
  • point to docs/process/ChangeWorkflow.md
  • list repository-specific commands for lint, typecheck, tests, build, generated files, and docs checks
  • require docs parity for behavior changes
  • preserve unrelated user changes
  • escalate to product-main or handbook planning when ownership boundaries or shared process are unclear

Read First

Point Codex to:

  • docs/bootstrap/BootstrapContext.md
  • docs/process/ChangeWorkflow.md
  • key docs/core pages
  • key docs/state pages
  • repository-specific build, test, or generated artifact docs

Change Workflow

Implementation repository AGENTS.md should reference:

docs/process/ChangeWorkflow.md

This workflow should use the handbook's Implementation Repository Change Workflow structure, including the Standard Prompts section.

Verification

Verification should match repository risk:

  • docs-only changes: git diff --check and mkdocs build --strict
  • normal implementation changes: lint, typecheck, and targeted tests
  • schema or generated artifact changes: repository generation commands
  • broad workflow changes: integration, end-to-end, build, or smoke checks

If a check cannot be run, Codex should explain why in the final response.