Skip to main content
command CX Codex

architecture — Claude Code command: architecture conformance checks

A slash command that pins down what counts as following the architecture in a /team run and makes every such claim carry a validator exit code.

MIT ★ 328 updated 2026-10-29

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

What architecture does

/architecture sets one meaning for “follows the architecture” inside the /team pipeline: which paths a component owns, whether module boundaries still hold, whether a deliverable matches the index. The single source of truth is .arch/index.json at the commit recorded in .arch/pinned-commit. A prose retelling or a diagram does not count.

Before a claim is made, the caller compares pinnedCommit against git rev-parse HEAD. Equal means CURRENT and the index may be trusted. Different means STALE: conformance statements stay UNVERIFIED until /team arch drift reconciles the index. The validator never runs that comparison itself, so it falls to whoever invokes the command. Two scripts follow: validate_index.py for checks 1 through 12 and arch_drift.py, a scan that makes no model calls. Everything lands in .arch/ARCH-EVIDENCE.md with the command line, the exit code and the check table.

Only exit code 0 passes. Validator could not run? Block. Component path missing on disk? Block. A component title describing something that does not exist yet? Block again. Reconciling drift against a truncated file tree is also off the table, since deletion-first reconciliation would drop components whose code was simply unseen. The scripts sit at ~/.claude/skills/arch-index/scripts/ and need Python 3; without them the gate blocks instead of passing.

What it helps with

  • catch a component that exists on paper while its paths are gone from disk
  • tell a stale index from a current one before review
  • put conformance evidence into one file for the pull request body
  • stop a PR where tests are green but module boundaries already broke
  • remove components that no longer exist in the tree

Example prompts for the agent

  • /architecture check that the billing component owns src/billing/ and nothing crosses the boundary
  • Run /architecture and save the evidence to .arch/ARCH-EVIDENCE.md before I open the PR
  • Is the index STALE? Call /architecture first and tell me before any conformance claim

How to install architecture

Manually: put the files in place

.claude/commands/architecture.md

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

Questions about architecture

How to install architecture in Claude Code?

Put the command file at .claude/commands/architecture.md in your project. The command is then available as /architecture.

What does architecture do?

It gives the /team pipeline one definition of architectural conformance and demands proof for it: a validator run, its exit code and a check table in .arch/ARCH-EVIDENCE.md.

What happens when .arch/index.json is missing?

The protocol does not apply and no architectural claim may be made. Run /team arch build first, or state that the run has no baseline.

Source text

architecture.md · MIT
---
description: "Use when any /team pipeline claims a component owns a path, that module boundaries hold, or that a deliverable follows the architecture. Defines the .arch/index.json baseline, the currency check, and the ARCH-EVIDENCE.md a claim needs."
---
# Architecture Conformance Protocol

> **Purpose:** One canonical definition of what "follows the architecture",
> "component X owns Y", and "no boundary violations" mean inside the `/team`
> pipeline. Referenced by `team:arch.md`, `team:verify.md`, `team:develop.md`,
> `team:reanalyse.md`, `team:fix.md`, `team:plan.md`, and `team:ship.md`. Whenever
> any of those pipelines makes an architectural claim, it must follow this protocol
> and produce the `.arch/ARCH-EVIDENCE.md` artifact described below.
>
> **Guiding principle — Paths or it does not exist.** Every architectural claim must
> be backed by a captured validator invocation and its exit code. A component that
> claims a path which does not resolve on disk is a defect, not a plan. Any claim
> without matching evidence is deleted from the deliverable or blocks the pull
> request.

This protocol exists because a pipeline can satisfy every requirement identifier and
every test gate while having silently abandoned the module boundaries it was built
against. Tests do not fail when a component is relocated, merged into another, or
deleted outright — they fail only when behaviour changes. Nothing in the four
existing `verify` failure modes can detect structural abandonment, because all four
are test-evidence traps. The steps below remove that blind spot, and only that one.

This protocol is also written against a specific upstream failure. The design it
draws on stated its path-matching rule emphatically, in prose, with a validation
checklist of unchecked boxes, and then never verified a single path in roughly
thirteen hundred lines of code. The lesson taken from that is structural rather than
rhetorical: **every rule in this document either maps to a numbered check in a
script, or is listed in "What is not mechanically enforced" below.** There is no
third category, and a rule that cannot be pointed at a check must be deleted from
this file rather than left to be narrated.

---

## The protocol

### 1. Determine the authoritative artifact

The authoritative artifact is `.arch/index.json` at the commit recorded in
`.arch/pinned-commit`. It is never a prose restatement of the architecture, never a
diagram, and never a subagent's summary of what the components are. `.arch/INDEX.md`
is a rendering for humans; if the two disagree, the JSON wins and `INDEX.md` must be
regenerated.

If `.arch/index.json` does not exist, this protocol does not apply and no
architectural claim may be made. Run `/team arch build` first, or state plainly that
the run has no architectural baseline.

### 2. Establish currency

Compare `pinnedCommit` in the index to `git rev-parse HEAD`.

- Equal — the index is `CURRENT` and conformance claims may rest on it.
- Different — the index is `STALE`. Run `/team arch drift` to reconcile it. Until
  that reconciliation completes and the validator exits zero, every conformance claim
  is `UNVERIFIED`, not clean. A stale index trusted as fact produces confidently
  wrong verdicts, which is worse than having no index at all.

The validator does not perform this comparison. It is the caller's responsibility,
and it is the single largest correctness risk in this protocol.

**The baseline convention.** A pipeline that records the pin *before* it changes anything
and checks *after* is a different case, and the rule above would misread it. There the pin
is expected to be behind HEAD by the end, and `git diff <pin>..HEAD` is precisely the set
of changes that pipeline made, which is what makes any drift attributable to it rather than
to unrelated history. `team:ship.md` works this way: it captures currency at Stage 1 and
evaluates its gate after Stage 6. Under this convention `STALE` means the pin was already
behind HEAD *at capture time*, never at check time. State which convention a run is using
and do not mix them.

### 3. Run and capture

Execute the validator and capture its command line, exit code, and per-check results:

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

For a drift assessment, additionally execute the deterministic scan, which makes no
model calls:

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

The orchestrator runs these commands and captures the output itself. A subagent's
prose summary ("the architecture is being followed") is not a substitute for a
captured exit code. Violation lines print to standard output, one per violation; the
per-check summary table prints to standard error.

### 4. Apply the pass rules

These rules are absolute — they are the definition of architectural conformance.
Each one names the check that enforces it.

- Any failed validator check is a **BLOCK.** (checks 1 through 12)
- A component with no primary paths is a **BLOCK.** (check 4)
- A primary path that does not resolve on disk is a **BLOCK.** (check 5)
- A shared path that does not resolve on disk is a **BLOCK.** (check 6)
- A one-directional or dangling connection is a **BLOCK.** (check 8)
- A wishful or aspirational component title is a **BLOCK.** (check 10) The index is
  reverse-only; it describes what exists.
- A validator that cannot be executed is a **BLOCK, never a pass.** (check 0) There
  is no prose fallback. A fallback that an agent can narrate is precisely the failure
  mode this gate exists to remove.
- An index whose pin is behind HEAD is **STALE**, and drift must be reconciled before
  any conformance claim. (step 2, caller-enforced)
- Drift detected but not reconciled is **UNVERIFIED, never a pass.**
  (`arch_drift.py` gate, caller-enforced)
- A component with zero surviving primary paths is a **BLOCK.** (`arch_drift.py`
  verdict `REMOVE`)
- An index built from a truncated file tree may not be used for drift reconciliation
  at all. (`ecosystem.treeTruncated`) Deletion-first reconciliation treats the tree as
  the source of truth, so reconciling against a partial tree deletes components whose
  code is merely unseen.

### 5. Write `.arch/ARCH-EVIDENCE.md`

Write the artifact using the template below. This file is the single source of truth
for every architectural claim that reaches a deliverable, a review summary, or a pull
request body.

---

## `.arch/ARCH-EVIDENCE.md` template

```markdown
# Architecture Index Evidence — <branch> — <ISO timestamp>

## Pin
- index pinnedCommit: <sha>
- git rev-parse HEAD:  <sha>
- currency: CURRENT | STALE

## Gate: validate (`python3 ~/.claude/skills/arch-index/scripts/validate_index.py .arch/index.json --repo-root .`)
exit: 0

| # | Check | Result | Detail |
|---|-------|--------|--------|
| 1 | schemaVersion known | PASS | 1.0 |
| ... | ... | ... | ... |

paths verified: <n> | paths missing: <n> | untracked-but-present: <n>

## Gate: drift (`python3 ~/.claude/skills/arch-index/scripts/arch_drift.py --repo-root .`)
gate: NONE | INCREMENTAL | FULL_REBUILD
files changed since pin: <n> | lines changed: <n>

| Component | Verdict | Surviving | Dead |
|---|---|---|---|
| <id> | KEEP | <paths> | — |

unclaimed added files: <n>

## Scope limit
Structural drift only. Semantic drift — a datastore swapped inside an
already-claimed directory, a rewritten component, a violated boundary entirely
within claimed paths — is NOT detected by this gate.
```

---

## Claim rule

Every architectural claim in a deliverable, a pull-request body, or a review summary
— "follows the architecture", "component X owns Y", "no boundary violations",
"respects module boundaries", "architecturally sound" — must correspond to an entry
in `.arch/ARCH-EVIDENCE.md`. If it does not, **delete the claim.**

A `NO DRIFT` result licenses exactly one sentence: that no structural drift was
found. It does not license "the architecture is intact", "the build follows the
design", or any statement about quality, coupling, or correctness.

---

## What is not mechanically enforced

Listed here rather than left implicit, because a gate that overstates its reach is
worse than one that does not exist.

**Semantic drift.** The scan sees structural facts 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`. This is a labelling
mitigation, not a technical one: the words "structural drift only" appear in
`ARCH-EVIDENCE.md`, in `INDEX.md`, and in this file, and no consumer may drop them.

**Currency.** Step 2 is caller-enforced. No script compares the pin to HEAD.

**Whether the decomposition is good.** Checks 10 and 11 catch two mechanical naming
failures. Whether components carve the system at sensible joints, whether coupling is
reasonable, and whether a title is too vague are Layer 3 review judgements made by
`architecture-reviewer`, and they carry no exit code.

**Work allocation.** The index is at C4-Container altitude and a single component may
own thousands of files. It is a conformance and triage aid. It is **not** a mechanism
for dividing files among parallel agents, and no consumer derives file ownership from
it.

**Read budgets.** The tool-frugality protocol in `arch-index` bounds how many files
the exploration stage may read. There is no transcript API and no way to count a
subagent's tool calls from outside it, so that budget is prose-enforced. It is stated
as guidance and never reported as a verified constraint.

---

## Hard gate semantics (shared by all pipelines)

- **BLOCK is real.** A failed gate stops the pipeline and loops back for a fix
  (bounded to a maximum of 3 rounds). It is never advisory.
- **Stale ≠ current.** An index behind HEAD is `UNVERIFIED` until reconciled, never
  clean.
- **Paths or it does not exist.** No matching `.arch/ARCH-EVIDENCE.md` entry → the
  claim is deleted.
- **A validator that cannot run is a BLOCK.** Never a pass, and never satisfied by
  narration.

---

## Attribution

The deletion-first reconciliation algorithm and the component anti-pattern list are
adapted from devildev by lak7 (Apache-2.0), <https://github.com/lak7/devildev>,
principally `prompts/ReverseArchitecture.ts`. The exact-path-matching rule is
upstream's; its implementation as a process exit code is not, because upstream never
verified a path. See `skills/arch-index/references/schema.md` for the full
modification notice required by Apache-2.0 § 4(b).

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

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →
Python Backend Architecture Review rknall Python Backend Architecture Review — a skill that reviews Python backend architecture: patterns, database, API, security, scalability. Useful when the design doc exists and you want the weak spots found before release. CX Codex +1 528installs architecture-review davila7 architecture-review — a Claude Code command that walks through project structure and returns concrete improvement recommendations. Run it when the codebase has grown past the point where you can hold it in your head. CX Codex +1 3,419installs clean-architecture pproenca clean-architecture — a skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong. CX Codex +1 2,100installs architecture-survey Yeachan-Heo architecture-survey inspects your module graph to spot shallow boundaries, false seams, and misplaced logic. Useful when changes start rippling across too many files at once. CX Codex +1 201installs guarding-architecture riekelt guarding-architecture enforces system boundaries by turning structural invariants into breaking build tests. Useful when code crosses module limits or adds unwanted cross-package imports. CX Codex +1 25,600installs architecture-critic official Anthropic architecture-critic — a subagent that audits architectural designs and modernized code with a skeptical lens. Spots over-engineering, unstated latency risks, and redundant service boundaries. CX Codex ★ 47,914repo stars

From the same set82

The whole set →
chromatic-glitch chromatic-glitch guides code generation for GSAP-based chromatic and slice glitch effects that snap into sharp focus. CX Codex +1 ★ 328repo stars anchored-layout-expand The anchored-layout-expand rule describes one-axis panel expansion with the following content moving in step. Use it for dropdowns, input cards, or panes that push a neighbor. CX Codex +1 ★ 328repo stars chart-scrub-readout chart-scrub-readout — a Claude rule that turns a chart already on screen into something you can scrub: a tracking line, a marker on the polyline, and a tooltip reading out date and value. CX Codex +1 ★ 328repo stars multi-cursor-choreography multi-cursor-choreography is a Claude Code rule for staging several labeled cursors on one canvas. It choreographs team-like motion without camera tracking. CX Codex +1 ★ 328repo stars toolkit The toolkit command maps project tasks to tools and skills, noting the best option, a fallback and when to skip it; it runs inside /team runs. CX Codex +1 ★ 328repo stars arch-index Builds a validated map of repository components in .arch/index.json and checks it for drift against the code. Use it to trace a component to its files or review structural changes after a refactor. CX Codex +1 ★ 328repo stars hyperframes-keyframes hyperframes-keyframes keeps HyperFrames motion seekable: builds keyframes for GSAP, CSS, Anime.js and WAAPI, then verifies frames before a render. CX Codex +1 ★ 328repo stars pmstudio-meeting-notes pmstudio-meeting-notes converts call transcripts into structured Markdown meeting notes. Cross-references people against stakeholder tables, logs decisions, and flags PRD updates. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open