Skip to main content
command CX Codex

arch — Claude Code command: architecture map

Command to build and validate .arch/index.json, which maps each architecture component to the files implementing it. Detects when files and component descriptions have drifted apart.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/arch.md
Open on GitHub

What arch does

The arch command handles two workflows: create an architecture map from scratch or verify whether an existing map matches the current codebase. It runs through three subcommands: build generates .arch/index.json from the current repository state, drift compares an existing map against the file tree and finds mismatches, check runs validation only without writing changes.

Execution happens in four layers. The first is deterministic and agent-free: the command detects the ecosystem, evaluates whether too many files changed since the last pin, and exits immediately for unchanged trees. The second spawns an architect agent to synthesize the index. The third runs two parallel reviews—one examines decomposition and coupling, the other verifies that component descriptions match the actual code. The fourth applies feedback and renders a diagram.

Each run pins to a commit via .arch/pinned-commit, and the index updates only when all checks pass. Output goes to .arch/index.json, validation evidence to .arch/ARCH-EVIDENCE.md.

What it helps with

  • identify which files implement a specific architecture component
  • verify that documented components match the actual codebase
  • detect architectural drift after refactoring
  • create a validated machine-readable map of project structure
  • record component decomposition with path validation

Example prompts for the agent

  • Which files implement the 'api' component?
  • /team arch drift
  • /team arch build --full

How to install arch

Manually: put the files in place

.claude/commands/arch.md

Call it with /arch. For all projects use ~/.claude/commands/

Questions about arch

How do I install arch in Claude Code?

Copy .claude/commands/arch.md into your repository at .claude/commands/. The command becomes available as /team arch in Claude Code.

What does arch do?

The command builds and validates .arch/index.json, an index linking each architecture component to its implementation files. It also finds when files and component descriptions have diverged.

What's the difference between build, drift, and check?

build creates the index from scratch, drift reconciles an existing index against the current tree and updates it, check runs validation alone without writing output.

Source text

arch.md · MIT
---
description: "Use when asked which files implement a component, to build or refresh .arch/index.json, or to check whether the architecture map drifted. Pins the index to a commit, validates every path, and writes ARCH-EVIDENCE.md."
---
# /team arch — Architecture Index Pipeline

> Called by team.md router when action is `arch`.
> Builds and validates `.arch/index.json`, the commit-pinned map from each
> architectural component to the real files that implement it, and detects when that
> map has stopped being true.
>
> Governed by `team:architecture.md`. **Paths or it does not exist.**

## Usage

```
/team arch [build|drift|check] [scope] [--full] [--roles <ids>]
```

Default subcommand: `drift` when `.arch/pinned-commit` exists, `build` when it does not.
Scope is optional; when given it narrows the analysis to a subtree.

| Subcommand | Purpose |
|---|---|
| `build` | Produce a fresh index from scratch |
| `drift` | Reconcile an existing index against the current tree |
| `check` | Run the validator alone and capture evidence. No model calls, no writes to `index.json`. |

## Role Selection Bias

| Layer | Preferred Roles | Count |
|-------|----------------|-------|
| L1 | technical-analyst; security-analyst if domain includes api/backend/infrastructure; repo-cartographer only on the fallback crawl | 0-2 |
| L2 | solution-architect | 1 |
| L3 | architecture-reviewer, domain-accuracy | 2 |
| L4 | principal-architect | 1 |

Layer 1 is **zero agents** when `.planning/codebase/` exists. That is the intended
common case, not a degradation.

## Pipeline Customization

### Stage 0: Deterministic gate — no agents, runs before pre-flight

This stage exists so that the most common invocation costs nothing.

1. Resolve the subcommand. Record `git rev-parse HEAD` as the pin candidate.
2. Detect the ecosystem from whichever manifest exists: `package.json`,
   `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `*.csproj`.
3. Check for `.planning/codebase/` and for a gitnexus index.
4. For `drift`, run the scan and evaluate its gate:

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

| Gate | Action |
|---|---|
| `NONE` | Report `NO DRIFT — structural only`, write `.arch/ARCH-EVIDENCE.md`, and **end the run here**. No team is created, no agent is spawned. |
| `FULL_REBUILD` | Report that more than 300 files or 50,000 lines changed since the pin, so a rebuild is cheaper than a patch. Re-enter as `build`. |
| `INCREMENTAL` | Continue to pre-flight. |
| exit 2 | The scan could not run. Report why. This is **never** `NO DRIFT`. |

### Layer 1: Structural context (parallel, mode `default`)

**Skipped entirely when `.planning/codebase/` exists.** Read `ARCHITECTURE.md`,
`STRUCTURE.md`, `STACK.md`, and `INTEGRATIONS.md` from there directly and report the
skip. Spawning agents to re-derive a map that `gsd-map-codebase` already wrote is the
exact waste this action was built to remove.

Otherwise, if gitnexus is available, call `mcp__gitnexus__context` and
`mcp__gitnexus__group_list`. Record how many commits behind the index is in
`ecosystem.sourceCommitsBehind`. Stale grouping advice is tolerable here because every
path is checked against the working tree by the validator, so staleness can date the
decomposition but cannot introduce a path that does not exist.

Only if neither exists, spawn `repo-cartographer` under the three-phase read budget in
`skills/arch-index/references/tool-frugality.md`, writing `.arch/ANALYSIS.md` against the
seven-section skeleton in `references/analysis-taxonomy.md`.

Always run `python3 ~/.claude/skills/arch-index/scripts/repo_tree.py --repo-root .` for the
authoritative current tree. If it reports truncation, propagate that into
`ecosystem.treeTruncated` and **do not run `drift`** — reconciling against a partial
tree deletes components whose code is merely unseen.

### Layer 2: Synthesis (1 agent, `solution-architect`, mode `bypassPermissions`)

**Writes confined to `.arch/`.** This agent does not touch source files.

No tool use during synthesis. Read only the gathered summary plus the tree, and emit
`.arch/index.json` per `references/schema.md`, bound by `references/component-rules.md`.
Separating exploration from formatting is why the structured output stays in schema.

For `drift`, apply the `DRIFT.json` verdicts as settled fact: `REMOVE` deletes the
component and every connection to it, `PRUNE` drops the dead paths and keeps the
identifier, `KEEP` changes nothing. Preserve surviving identifiers. Then answer the one
open question the script cannot: do the unclaimed added files constitute a component
that should exist?

### Validation gate: deterministic, and a real BLOCK

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

Capture the command line, the exit code, and the per-check table into
`.arch/ARCH-EVIDENCE.md` per the template in `skills/arch-index/templates/`.

Exit 0 proceeds. Non-zero loops back to Layer 2 with the exact violation lines, bounded
to three rounds, then stops and reports what remains. **A validator that cannot be
executed is a BLOCK, not a pass.** There is deliberately no prose fallback here: a
fallback an agent can narrate is the failure mode this gate exists to remove. See
`team:architecture.md`.

### Layer 3: Review (parallel, read-only, mode `default`, 2 agents)

- **architecture-reviewer** — decomposition, coupling, boundary coherence, wishful
  components, vague titles, altitude drift.
- **domain-accuracy** — does each component's described capability match what the code
  at those paths actually does?

Findings use `CRITICAL | MAJOR | MINOR | SUGGESTION` with the component id and a quote,
compressed into `CRITIQUE-SUMMARY.md` at the standard 200-line cap. Any CRITICAL blocks
back to Layer 2.

Neither reviewer may treat a passing validator as evidence that the architecture is
sound. The validator proves the paths exist and the graph is well-formed, and nothing
more.

### Layer 4: Finalise (1 agent, `principal-architect`)

Apply the critique, re-run the validator, write `.arch/INDEX.md` from the template, and
emit the Mermaid `C4Container` source for rendering through `design:mermaid`
(beautiful-mermaid).

**Advance `.arch/pinned-commit` only after the validator exits 0.** A failed run leaves
the previous pin untouched, so a broken index can never present itself as current.

Emit feedback entries in the format at `_index.md`.

## Fast path

`build` is **not** fast-path eligible. An index that skips its review layer is worse
than no index, mirroring the evidence carve-out in the router.

`drift` is fast-path eligible in a stronger sense than any other action: Stage 0 can
complete the entire run with zero agents, and on an unchanged tree it always does.

## Artifacts

All of `.arch/` is committed except `DRIFT.json`, which is derived scratch and
gitignored. The index is only useful if it is diffable across runs and present in the
clean checkout that `team:ship.md` verifies from.

## Scope limit

This action detects **structural** drift: components whose code was deleted, moved, or
never claimed. It does not detect semantic drift, such as a component whose datastore
was swapped inside its own already-claimed directory. Every artifact it writes says so
in those words, and no consumer may drop them.

## GSD Integration

When `.planning/` exists, Layer 1 reads `.planning/codebase/` in preference to crawling,
and `plan.md` may use the index to populate the `files_modified` frontmatter field of
generated phase plans.

© coco-research · MIT · coco-research/coco

Similar slash commands

All slash commands for Code review and refactoring →

From the same set82

The whole set →

Project sponsors

Companies that keep this analytics open