Scan Codebase C4

scan-codebase-c4 is a manually invoked Codex skill that turns a repository into a persistent, evidence-backed C4 architecture index.

It scans the active checkout, records what every included file contributes, builds Context / Container / Component / Code views, and keeps an audit trail linking architectural claims back to source evidence. The resulting index can be reused by later Codex tasks as compact project memory.

What it does

• indexes the repository in C4 order: Context, Container, Component, then Code;
• tracks both file coverage and unresolved architecture questions;
• uses a persistent analyst/reviewer loop before accepting index changes;
• resumes from durable JSON state after interruptions;
• refreshes an existing index when the checkout changes;
• supports diff-assisted discovery without weakening full-index coverage;
• records the scanned branch and exact commit SHA;
• registers the finished index in the repository's AGENTS.md for later retrieval.

Requirements

• Codex with built-in Goal support and agent collaboration tools;
• Git for checkout identity and diff-aware refreshes;
• Python 3 for the included deterministic helper scripts;
• rg (recommended) for efficient repository discovery.

The skill is opt-in and does not allow implicit invocation.

Installation

Clone the repository into your Codex skills directory:

git clone https://github.com/glebkudr/scan-codebase-c4.git ~/.codex/skills/scan-codebase-c4

Restart Codex or reload its skill catalog if the skill is not discovered immediately.

Usage

Explicitly name the skill and provide an unambiguous repository path:

Use $scan-codebase-c4 to fully scan /absolute/path/to/repository and build a persistent C4 index.

By default, scan state is written to:

<repository-root>/.codex/c4-scan/

You can also ask the skill to resume or refresh an existing index, or supply a different state-root path. A ref range may be used to speed up discovery, but the resulting index still describes the complete active checkout.

Generated state

The state root contains:

Path	Purpose
understanding.json	Compact C4 ontology and repository understanding
evidence-ledger.json	Source-backed audit trail for accepted claims
file-inventory.json	Included/excluded paths, hashes, and checkout identity
scan-status.json	Per-file coverage and scan history
scan-plan.json	Resumable internal task queue
hypotheses.json	Open knowledge questions awaiting verification
goal-audit.json	Goal epoch and repeated-blocker evidence
run-report.md	Human-readable execution report
staging/	Analyst proposals and reviewer decisions

Repository layout

.
├── SKILL.md                 # Trigger and top-level operating contract
├── GOAL.md                  # End-to-end scan lifecycle and finish gate
├── agents/openai.yaml       # Codex UI metadata and invocation policy
├── assets/
│   ├── examples/            # Example analyst/reviewer payloads
│   └── templates/           # Canonical state templates
├── references/              # State, validation, diff, and output contracts
└── scripts/                 # Deterministic digest and registration helpers

Design principles

• Evidence before acceptance. Architecture claims are staged and reviewed before canonical state changes.
• Complete means complete. The scan finishes only when both the file frontier and knowledge frontier are closed.
• Resumable by design. Durable state is authoritative across task and context boundaries.
• Current-checkout truth. Final reconciliation verifies that the index matches the active branch and commit.
• Compact memory, separate audit. The ontology stays concise while evidence remains independently inspectable.

Helper scripts

Verify or calculate the canonical repository snapshot digest:

python3 scripts/snapshot_digest.py /path/to/file-inventory.json --check

Register an existing C4 index in a repository's AGENTS.md:

First read the target AGENTS.md and follow the semantic duplicate/conflict checks in references/PROJECT_MEMORY_INTEGRATION.md. The helper can validate managed markers, but it cannot decide whether unmarked human-written instructions are equivalent or conflicting. Run it only after completing those checks:

python3 scripts/register_project_memory.py \
  --repo-root /path/to/repository \
  --state-root /path/to/repository/.codex/c4-scan \
  --confirm-semantic-checks

The skill normally invokes these helpers as part of its own workflow; they are documented here for inspection and recovery.

Safety notes

• The skill only runs when explicitly requested.
• It requires a concrete repository root instead of guessing a target.
• Its generated state is excluded from the source scan frontier.
• Canonical index updates are not accepted without reviewer approval.
• Project-memory registration requires human/agent semantic conflict checks and only manages its marked block in AGENTS.md.

License

MIT