Skip to content

Implementation Repository Process

Implementation repositories own product code, repository-local docs, verification, and implementation change history.

Each implementation repository must have a docs-first structure before AGENTS.md is created or refreshed. AGENTS.md should reference existing repository context, not invent it.

flowchart TD
  bootstrap["docs/bootstrap/BootstrapContext.md"] --> workflow["docs/process/ChangeWorkflow.md"]
  workflow --> docs["docs/core, docs/state, docs/process, docs/changes"]
  docs --> agents["AGENTS.md"]
  agents --> work["Implementation work"]
  work --> parity["Code, docs, tests, and project status parity"]

Required Repository Shape

Implementation repositories should include:

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

The four required implementation docs folders are:

  • docs/core: current system behavior and durable architecture.
  • docs/state: routing, runtime, operational, persistence, or repository state orientation.
  • docs/process: repository-local contributor workflows, including ChangeWorkflow.md.
  • docs/changes: large change reasoning, plans, and implementation logs.

docs/bootstrap/BootstrapContext.md is also required. It explains what the implementation repository is supposed to do and guides creation of docs/core and docs/state.

MkDocs Requirements

Implementation repositories should use Material for MkDocs with the project docs folder as the docs source.

Required root files:

  • mkdocs.yml
  • hooks.py

Required docs files:

  • docs/index.md
  • docs/stylesheets.css

The mkdocs.yml nav should point to pages under docs/ and include at least:

  • Bootstrap
  • Core
  • State
  • Process
  • Changes

When docs are created, renamed, moved, or deleted under docs/core, docs/state, docs/process, or docs/changes, update only the nav section of mkdocs.yml.

Bootstrap Context Source

The Bootstrap Context for an implementation repository can be generated by anuva-main-video-creator and manually copied into the implementation repository at:

docs/bootstrap/BootstrapContext.md

The Bootstrap Context should describe:

  • the repository purpose
  • product role and ownership boundaries
  • expected capabilities
  • expected docs to generate under docs/core and docs/state
  • known integration points with other repositories
  • verification expectations known at product-main level

It should not contain implementation code.

Required Order

Bootstrap or refresh implementation repositories in this order:

  1. Generate BootstrapContext.md via anuva-main-video-creator and copy it to docs/bootstrap/BootstrapContext.md.
  2. Generate docs/process/ChangeWorkflow.md in the implementation repository.
  3. Generate the implementation docs folder structure and docs under docs/core, docs/state, docs/process, and docs/changes.
  4. Generate or refresh root AGENTS.md in the implementation repository.

Do not create or refresh AGENTS.md until the Bootstrap Context, Change Workflow, and local docs exist. AGENTS.md should point Codex to those files in its Read First, Documentation Rules, Change Workflow, and Verification sections.

Preflight Gate

Before bootstrapping or refreshing an implementation repository, Codex should inspect the repository and verify:

docs/bootstrap/BootstrapContext.md exists
docs/process/ChangeWorkflow.md exists or is the current generation target
docs/core/ exists
docs/state/ exists
docs/process/ exists
docs/changes/ exists
mkdocs.yml exists
hooks.py exists
docs/index.md exists
docs/stylesheets.css exists

If the structure is missing, create the missing structure before generating docs that depend on it.

If docs/bootstrap/BootstrapContext.md is missing, stop before generating ChangeWorkflow.md, docs/core, docs/state, or AGENTS.md. Ask for the Bootstrap Context to be generated from the product-main repository and copied into place.

Example Guard Prompt

Use this prompt inside an implementation repository when bootstrapping or refreshing it:

Bootstrap or refresh this implementation repository.

Before creating or updating AGENTS.md, verify this exact structure:
- docs/bootstrap/BootstrapContext.md
- docs/core/
- docs/state/
- docs/process/
- docs/changes/
- docs/process/ChangeWorkflow.md
- mkdocs.yml
- hooks.py
- docs/index.md
- docs/stylesheets.css

If docs/bootstrap/BootstrapContext.md is missing, stop and do not proceed. Tell me to generate it from anuva-main-video-creator and copy it to docs/bootstrap/BootstrapContext.md.

If the Bootstrap Context exists but the docs folders or MkDocs files are missing, create the required structure first.

Then proceed in this order:
1. Create or refresh docs/process/ChangeWorkflow.md using the Implementation Repository Change Workflow structure from anuva-engineering-handbook.
2. Create or refresh docs/core, docs/state, docs/process, and docs/changes documents based on docs/bootstrap/BootstrapContext.md and the repository contents.
3. Create or refresh AGENTS.md so it references BootstrapContext, ChangeWorkflow, docs/core, docs/state, and the repository verification commands.

Do not invent implementation details. Preserve unrelated user changes. Run git diff --check and mkdocs build --strict if available.

AGENTS.md Dependency

Implementation repository AGENTS.md should reference:

  • docs/bootstrap/BootstrapContext.md
  • docs/process/ChangeWorkflow.md
  • key docs/core pages
  • key docs/state pages
  • repository verification commands

This dependency is why AGENTS.md comes last in the bootstrap order.