Codebase Handbook Builder

Build Codebase Handbook

Create or use a compact source-location index that helps Codex find every place a change touches. Use the active Codex session for analysis; do not call an LLM endpoint, API client, or API-backed generator.

Choose the workflow

Resolve this skill's directory from the selected SKILL.md and call it HANDBOOK_BUILDER_ROOT.

Choose one mode:

• Task mode: Use an existing generated handbook to route a concrete planning, implementation, debugging, testing, explanation, or review task.
• Build mode: Generate, refresh, or validate a handbook skill.
• Combined mode: Build or refresh the handbook first, then use it for the task.

Do not generate a handbook merely because a normal coding task mentions a repository. Task mode requires an existing handbook or an explicit request to create/use one.

Use an existing handbook for a task

1. Resolve the handbook named by the user or already selected by Codex. Otherwise inspect <source>/.agents/skills/*-handbook/SKILL.md, excluding this builder. If several match, choose by repository name and described scope; ask only when ambiguity would materially change the task.
2. Read the generated handbook's SKILL.md completely. Read its references/overview.md, route through references/index.md, then load only the relevant stage pages and references/registers.md.
3. Inspect references/coverage.json for freshness of the routed files. When useful, run this builder's validator. Treat validation failures as drift signals, not as permission to skip the user's task.
4. Read the real source at every cited path and symbol. Search for callers, tests, configuration, and state readers/writers that may have changed since generation.
5. Follow the user's requested action boundary:
   • For explanation, diagnosis, planning, or review, remain read-only.
   • For a requested change, implement it and verify it in proportion to risk.
   • For broad changes, use the handbook index and registers as a coverage checklist.
6. If the task changes covered source, refresh the handbook only when the user asks to keep it synchronized or repository instructions require it. Otherwise report that its coverage hashes are now stale.

Never treat handbook prose as authoritative code text.

Build or refresh a handbook

Set the scope

Use:

• Source root: the user's requested repository, otherwise the current repository.
• Output: the user's requested path, otherwise <source>/.agents/skills/<repository-slug>-handbook.
• Work directory: a task-specific temporary directory outside the output skill.
• Language: the user's requested language, otherwise English.

Run the bundled utilities with Python 3.10 or newer. They use only the Python standard library, so this skill intentionally has no requirements.txt. If a future version adds a third-party import, add and package a pinned requirements.txt.

Make the generated folder independently shareable. Do not import code or templates from the source repository or this skill. Do not add a README, build log, scratch notes, or source snapshot.

If the output already exists, update it in place. Preserve useful hand-written content, inspect changes before overwriting, and never delete the whole folder as a shortcut.

1. Inventory before interpreting

Read applicable AGENTS.md files and repository instructions first.

Run:

python3 "$HANDBOOK_BUILDER_ROOT/scripts/inventory.py" \
  --source-root "<source>" \
  --output "<work>/inventory.json"

Review the summary and skipped-file reasons. Add --exclude PATTERN for generated trees or project-specific noise. Never weaken the default secret and private-key exclusions.

Treat the inventory as the coverage contract. Do not silently omit an eligible file because it looks unimportant.

2. Derive the behavioral map

Inspect the actual source with repository search and targeted reads. Use the inventory to work in bounded batches.

Identify:

1. Entry points and external inputs.
2. Ordered runtime or build stages.
3. Core domain logic and orchestration.
4. State, configuration, persistence, queues, caches, and other registers.
5. Boundaries such as APIs, CLIs, databases, providers, and subprocesses.
6. Error, retry, cancellation, cleanup, and shutdown paths.
7. Tests that establish contracts or exercise cross-stage behavior.

Group files by behavior and lifecycle, not merely by directory. Prefer 4–12 stages for a typical repository. A file must have one primary stage even when referenced from several pages.

For large repositories, analyze independent inventory slices concurrently with subagents when that capability is available. Give each agent only its file slice and request factual notes with exact paths and symbols. Reconcile their notes against the source yourself. Otherwise process the slices sequentially.