arch-index

arch-index

Produces one artifact: .arch/index.json, a commit-pinned map from each architectural component of a repository to the real directories and files that implement it. Every claimed path is verified to exist by a script with an exit code, not by a promise in a prompt.

Guiding principle — Paths or it does not exist. The protocol that consumers follow is team:architecture.md. This file is the producer.

What this skill is for, and what it is not for

It is for answering, mechanically: which files implement this component, and has that stopped being true.

It is not a design tool. The index is reverse-only — it describes code that exists on disk at a known commit. There is no mode for specifying a system that has not been built, because the central check is that every path resolves. Forward design work belongs in /team think, the SI-*-Design councils, or /util:create-architecture-documentation.

It is not a codebase-mapping tool either, and it should not act like one. When .planning/codebase/ exists, gsd-map-codebase has already produced seven structured documents covering the stack, integrations, architecture, structure, conventions, testing, and concerns. This skill reads those and skips crawling entirely. Crawling a repository that has already been mapped is the exact waste this skill was designed to avoid, and duplicating gsd-map-codebase would make it a worse version of a tool that already exists.

It is not a work-allocation mechanism. The index sits at C4-Container altitude, so a single component can own thousands of files. Nothing derives per-agent file ownership from it.

Modes

Resolve the mode from the invocation. When none is given, use drift if .arch/pinned-commit exists and build if it does not.

build

Step 1 — find prior art before doing any work. In this order:

1. If .planning/codebase/ exists, read ARCHITECTURE.md, STRUCTURE.md, STACK.md, and INTEGRATIONS.md from it. Set source to gsd-codebase-map. Skip to step 2. Do not crawl.

2. Otherwise, if gitnexus is available for this repository, call mcp__gitnexus__context and mcp__gitnexus__group_list for a deterministic view of module grouping. Set source to gitnexus. Skip to step 2.

   A gitnexus index that is behind HEAD is still usable here, and list_repos reports exactly how far behind it is. Record that number in ecosystem.sourceCommitsBehind. The reason staleness is tolerable is structural rather than optimistic: gitnexus informs component grouping, while every path the index claims is checked by the validator against the working tree. A path that moved since gitnexus was indexed fails check 5 and blocks the build. Stale grouping advice can therefore make the decomposition slightly dated, but it cannot introduce a path that does not exist. Still run scripts/repo_tree.py for the authoritative current tree.

3. Otherwise crawl. Run scripts/repo_tree.py --repo-root . for a filtered, depth-adaptive tree, then perform one exploration pass under references/tool-frugality.md, writing .arch/ANALYSIS.md against the seven-section skeleton in references/analysis-taxonomy.md under its ten-thousand-character cap. Set source to crawl.

If the tree came back truncated, say so at the top of the analysis and set ecosystem.treeTruncated to true in the index. A truncated tree disables drift mode entirely, by design.

Step 2 — synthesise, with no tool use. Read only the gathered summary plus the tree. Emit .arch/index.json per references/schema.md, bound by references/component-rules.md. This stage does not explore; separating exploration from formatting is why the structured output stays in schema.

Step 3 — validate.

python3 ~/.claude/skills/arch-index/scripts/validate_index.py .arch/index.json --repo-root .

Exit zero proceeds. Non-zero loops back to step 2 with the exact violation lines, bounded to three rounds, then stops and reports the remaining violations. If the validator cannot be executed at all, that is a BLOCK, not a pass — there is no prose fallback, because a fallback an agent can narrate is the failure this gate exists to remove.

Step 4 — write the derived artifacts, using templates/. Write .arch/ARCH-EVIDENCE.md capturing the command, the exit code, and the per-check table. Write .arch/INDEX.md for humans. Emit the Mermaid C4Container source and render it through design:mermaid (beautiful-mermaid), never the standard Mermaid CDN.

Step 5 — advance the pin. Write git rev-parse HEAD to .arch/pinned-commit only after the validator has exited zero. A failed run leaves the previous pin untouched, so a broken index can never present itself as current.

drift

Deterministic first, and often only.

python3 ~/.claude/skills/arch-index/scripts/arch_drift.py --repo-root .

The script reads the pin, diffs it against HEAD with --name-status and --numstat, tests every primary path, and writes .arch/DRIFT.json with a per-component verdict of REMOVE, PRUNE, or KEEP, plus the files added outside every claimed path. It resolves the gate itself:

Gate	Meaning	What to do
NONE	Every verdict is KEEP and nothing unclaimed was added	Report NO DRIFT and stop. Zero model calls.
FULL_REBUILD	More than 300 files or 50,000 lines changed since the pin	A rebuild is cheaper than a patch. Run build.
INCREMENTAL	Anything else	Continue below.

If the script exits 2, the scan could not run. That is never NO DRIFT; report why.

In the INCREMENTAL case the model receives DRIFT.json as settled fact and answers exactly one open question: do the unclaimed added files constitute a component that should exist? Apply the verdicts without re-deciding them, preserve surviving component identifiers, prune connections to removed components, then validate and advance the pin as in build steps 3 through 5.

Never preserve a component whose code is gone. See the deletion-first rule in references/component-rules.md.

check

Runs the validator alone and writes .arch/ARCH-EVIDENCE.md. Makes no model calls and never writes index.json. This is what /team verify and /team ship call.

Artifacts

Path	Committed	Notes
.arch/index.json	Yes	The contract. Diffable history is the point.
.arch/pinned-commit	Yes	Advanced only on validator exit 0.
.arch/INDEX.md	Yes	Derived; regenerated every build.
.arch/ARCH-EVIDENCE.md	Yes	The captured gate.
.arch/ANALYSIS.md	Yes	Fallback path only; cached against the pin.
.arch/DRIFT.json	No	Derived scratch; gitignored.

.arch/ is committed deliberately. An untracked file cannot be diffed across runs, does not exist in the clean checkout that /team ship verifies from, and would be silently erased by git clean, reverting every consumer to a degraded path without saying so.

Scope limits, stated plainly

Structural drift only. A commit that swaps a component's datastore, rewrites it end to end, or violates a declared boundary entirely inside already-claimed paths returns NO DRIFT. Every artifact carries these words, and no consumer may drop them.

Currency is caller-enforced. No script compares the pin to HEAD; the caller does, per team:architecture.md step 2. An index behind HEAD is STALE, and claims resting on it are UNVERIFIED rather than clean.

The read budget is not enforced. There is no transcript API and no way to count a subagent's tool calls from outside it. references/tool-frugality.md is guidance, and no artifact reports it as verified.

Monorepos do not fit. The three-to-eight ladder forces distinct concerns to merge in a repository with dozens of packages. One index per workspace package plus a root index whose components are the packages is the eventual answer, and is out of scope for 1.0.

Files

File	Purpose
references/schema.md	The contract and the twelve checks
references/arch-plan.md	The forward plan contract, and why declare-then-verify works
references/component-rules.md	What qualifies, naming, counting, merging
references/tool-frugality.md	The read budget for the fallback crawl
references/analysis-taxonomy.md	The seven-section exploration skeleton
scripts/validate_index.py	The gate. Twelve checks, stdlib only, exit 0 or 1
scripts/arch_drift.py	Deterministic drift scan. Zero model calls
scripts/verify_arch_plan.py	Forward plan: --declare before a build, --verify after
scripts/repo_tree.py	Filtered, depth-adaptive tree
scripts/run_fixtures.sh	Regression suite for the validator
templates/	INDEX.md and ARCH-EVIDENCE.md skeletons

Regression gate for any change to the validator:

bash skills/arch-index/scripts/run_fixtures.sh

Attribution

The design this skill implements is adapted from devildev by lak7, licensed Apache-2.0, https://github.com/lak7/devildev. No upstream source code was copied; what was taken is prompt text, one schema idea, and four procedures.

Borrowed	Upstream source
Component-to-code ownership taxonomy	prompts/ReverseArchitecture.ts
Component rules, count ladder, naming and purpose formulas, anti-patterns	prompts/ReverseArchitecture.ts:278-371, :493-507
Deletion-first reconciliation	prompts/ReverseArchitecture.ts:578-641
Two-stage explore-then-synthesise split	actions/reverse-architecture.ts:696-805
Tool-frugality read budget	actions/reverse-architecture.ts:715-749
Seven-section analysis taxonomy and character cap	actions/reverse-architecture.ts:771-805

Per-file modification notices required by Apache-2.0 § 4(b) are recorded at the foot of each reference file. The most significant modification is that upstream stated its exact-path-matching rule emphatically in prose, with a validation checklist of unchecked boxes, and never verified a single path in roughly 1,300 lines of code; here that rule is scripts/validate_index.py checks 5 and 6, with a process exit code. Also not carried across: all presentation fields, numeric confidence bands, the celebrity-persona framing, the framework-only admission gate, and the credits economy.