build-codebase-handbook

name

build-codebase-handbook

description

Generate, refresh, validate, or use a planner-ready handbook for a software repository. Use when Codex is asked to map or document a codebase, create a navigation skill, replace an API-backed handbook generator, update or validate an existing handbook, or use a handbook to locate, plan, implement, debug, test, or review a repository task—especially unfamiliar or cross-cutting work. Do not use when no handbook exists and the user only wants an ordinary code change without requesting one, for non-code research or writing, for API/product documentation lookup, or for an isolated edit whose exact file is already known and has no plausible repository-wide impact. Performs reasoning in the active Codex session and never requires an external LLM API key.

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.

3. Write the generated skill

Read references/handbook-format.md completely before creating or updating output files. Follow its required layout and schemas.

Create:

<output>/
├── SKILL.md
├── agents/openai.yaml
└── references/
    ├── overview.md
    ├── index.md
    ├── registers.md
    ├── stage-rules.json
    ├── coverage.json
    └── stages/<stage-id>.md

Write exact repository-relative paths and symbol names. Summarize behavior rather than copying source bodies. Never include credentials, environment values, private keys, or secret file contents.

The generated SKILL.md must tell future agents to use the handbook for routing, then inspect real source before planning or editing. The handbook is not ground truth for verbatim code.

4. Compile complete coverage

Express the primary file-to-stage assignment in references/stage-rules.json. Prefer narrow, non-overlapping glob rules; use exact path overrides for exceptions.

Run:

python3 "$HANDBOOK_BUILDER_ROOT/scripts/compile_coverage.py" \
  --inventory "<work>/inventory.json" \
  --rules "<output>/references/stage-rules.json" \
  --output "<output>/references/coverage.json"

Fix unmatched files, overlapping rules, unknown overrides, and invalid stage IDs. Do not use a catch-all rule to conceal an incomplete architecture analysis.

5. Validate and reconcile

Run:

python3 "$HANDBOOK_BUILDER_ROOT/scripts/validate_handbook.py" \
  --source-root "<source>" \
  --skill-dir "<output>"

Resolve every error. Review warnings and fix any that affect routing quality. Then:

• Check that every stage page links from index.md.
• Spot-check paths, symbols, lifecycle order, and register read/write claims against current source.
• Review the output diff for accidental source excerpts or sensitive information.
• Report the output path, eligible-file coverage, validation result, and any intentionally skipped categories.

Refresh an existing handbook

Re-run the inventory and validator first. Use stale hashes and new/deleted paths to identify affected stages. Re-read changed source, update those stage pages, then roll changes upward into registers.md, index.md, and overview.md. Recompile coverage and validate again.

Do not rewrite unaffected prose solely for stylistic consistency.

Package this builder skill for sharing

The builder carries its own Apache-2.0 LICENSE, so a ZIP remains licensed when detached from this repository. The repository has no NOTICE file to propagate.

Create a deterministic archive:

python3 "$HANDBOOK_BUILDER_ROOT/scripts/package_skill.py" \
  --output "<destination>/build-codebase-handbook.zip"

The archive contains one top-level build-codebase-handbook/ directory and excludes caches, temporary files, existing archives, and VCS metadata. It includes requirements.txt automatically if one exists.

Do not assume the same Apache license applies to handbooks generated from someone else's repository. Before distributing a generated handbook, use the license and notices authorized by that repository's owner.