architecture-map

name	architecture-map
description	Generate or refresh the repo-wide architecture map — architecture-out/architecture-map.json (machine contract with named flows) + architecture-map.html (self-contained viewer). Use when the user asks for an architecture map, repo map, "/architecture-map", or when an agent needs a fresh machine-readable architecture overview. NOT for per-epic C4 deep-dives (use c4-architecture-docs) and NOT for building the knowledge graph itself (use /graphify).
docs	{"status":"reviewed","source_sha":"ff1a7f56a769","updated":"2026-08-06T00:00:00.000Z"}

Architecture Map

Produce <repo>/architecture-out/architecture-map.json + .html. The JSON is the source of truth; the HTML is rendered from it by scripts/build.sh — never write HTML by hand.

0. Freshness gate (always first)

HEAD=$(git rev-parse HEAD)
LAST=$(node -e "try{const v=JSON.parse(require('fs').readFileSync('architecture-out/architecture-map.json')).analyzedAtCommit;console.log(typeof v==='string'&&v.length>=7?v:'')}catch{console.log('')}")

• LAST == HEAD → report "architecture map is up to date (commit )" and STOP.
• LAST non-empty → incremental mode: git diff --name-only $LAST..HEAD → map changed paths onto existing modules[].path prefixes; re-describe ONLY touched modules, re-check only flows whose steps reference them; keep the rest.
• LAST empty → full analysis.

1. Inventory (ground truth, no invention)

• .claude/project.json — name, repos, stack, domainTerms.
• Root CLAUDE.md — layout section, commands, hard rules → conventions + importantNotes.
• graphify-out/graph.json if present (nodes have community/community_name, top-level built_at_commit): communities are candidate module groupings, god nodes are candidate hubs. Curate — target 15–40 modules, never 1:1 with communities. If graphify's built_at_commit trails HEAD, note it in importantNotes and lean on direct exploration instead.
• Manifests (package.json, go.mod, plugin.json, workflow YAML) → techStack, entryPoints, externalServices.

2. Layers

Pick 3–7 layers that fit THIS repo (do not force presentation/domain/infra onto a repo that is a plugin marketplace or a CLI). order = left-to-right viewer columns, upstream (actors/entrypoints) first.

3. Modules (fan out)

Dispatch parallel read-only subagents, one per layer (or per module group for big layers). Each returns, per module: responsibility (1–2 sentences), keyFiles (3–7 real paths — verify each exists), exports (public surface: commands, endpoints, functions), dependencies (ids of modules it imports/calls). Real paths only — a file that does not exist is a hard failure.

4. Flows (the point of the map)

5–10 named end-to-end scenarios a developer actually asks about ("what happens when X"). Each step: from/to module ids, action, file anchor (at least one per flow), payload where meaningful. Prefer flows crossing ≥ 3 modules.

5. Synthesize + validate + render

Assemble the full JSON (schemaVersion: 1, analyzedAt = today, analyzedAtCommit = HEAD). Then:

Bundled files (schema, validator, renderer) live under ${CLAUDE_PLUGIN_ROOT}/skills/architecture-map/ — never copy them into the project.

mkdir -p architecture-out
node "${CLAUDE_PLUGIN_ROOT}/skills/architecture-map/scripts/validate.mjs" architecture-out/architecture-map.json
bash "${CLAUDE_PLUGIN_ROOT}/skills/architecture-map/scripts/build.sh" \
  --json architecture-out/architecture-map.json \
  --out  architecture-out/architecture-map.html

Fix every validator error before rendering. Finish by reporting: module/flow counts, commit stamp, and the two artifact paths.

How to use

What it does

This skill builds a whole-repository architecture map: a machine-readable JSON file with layers, modules, and named end-to-end flows, plus a self-contained HTML viewer rendered from that JSON. It reads the repository as it actually is — manifests, entry points, real file paths — so the map describes shipped code rather than an idealized design. Re-running it is cheap: if the map is already stamped with the current commit it stops, and if it trails behind it only re-describes the modules the diff touched.

When to use it

• You want a repo-wide picture of layers, modules, and how a request travels across them.
• Someone new needs to answer "what happens when X" without reading every directory.
• The map exists but the repo has moved on, and you want it refreshed against the current commit.
• Another agent needs a machine-readable architecture overview to plan against.

When not to use it

• You need a deep C4 breakdown of one epic or feature — use the c4-architecture-docs skill instead.
• You need the underlying knowledge graph built or queried — use the graphify skill.
• You only want to render an existing Mermaid diagram — use the mermaid-viewer skill.

How to invoke

Skill(skill: "architecture-pack:architecture-map")

Run it from the repository root you want mapped; everything else is discovered from the repo itself.

Inputs

• Repository — the working directory the skill runs in — required, and it must be a git checkout, since the freshness gate stamps the map with HEAD.
• .claude/project.json — project name, repos, stack, domain terms — optional, used as ground truth when present.
• graphify-out/graph.json — an existing knowledge graph — optional, used only as candidate module groupings.

What you get back

Two files under architecture-out/ in the repository: architecture-map.json (the source of truth, schema version 1, stamped with the analysis date and commit) and architecture-map.html (a self-contained viewer built from that JSON). The JSON is validated before the HTML is rendered, and every validator error is fixed first. The final message reports module and flow counts, the commit stamp, and both artifact paths.

Worked example

Skill(skill: "architecture-pack:architecture-map")

→ freshness gate: stored commit 4f2a19c, HEAD 9bc7e01 → incremental mode
→ 6 layers, 23 modules re-checked against the diff, 8 named flows
→ validate.mjs passed, viewer rendered

architecture-out/architecture-map.json
architecture-out/architecture-map.html

Open the HTML file in a browser to walk the layers left to right and step through each flow with its file anchors.

Related

• c4-architecture-docs — when the subject is one epic or feature, not the whole repository.
• graphify — when you need the knowledge graph itself, or want to query relationships directly.
• impact — when the question is which code a specific change ripples into.