System Map
Produce a self-contained interactive board — isometric buildings on a grid, real
control and data paths between them, clickable payloads quoted from the code, and
an explainer panel — so the user can discuss the system by pointing at it.
The board is a means. The value is the accuracy of the model behind it. A pretty
diagram of the wrong system is worse than no diagram.
Modes
| Mode |
Argument |
Answers |
map (default) |
optional subsystem or path scope |
How is this system put together, and what talks to what? |
change |
PR number, branch, or commit range |
What did this change touch, and what does it now talk to that it did not before? |
flow |
an entry point — route, CLI command, job, handler |
What actually happens, in order, along this path? |
Infer the mode from the request. Ask only when genuinely ambiguous.
Inputs it accepts
- One repository. The default.
- A workspace of several repositories. A directory whose subfolders are each
their own git repo. Declare them in
repos; citations get a repoId: prefix.
- Seeding context. Anything that describes the system: an architecture note,
a design doc, an ADR, a README, a root
CLAUDE.md, a wiki export — or the user
simply explaining it in the conversation. Read it first for the candidate
topology and the team's vocabulary, then confirm in code. A claim from context
never becomes code evidence; see rule 9.
- Context that arrives as conversation or pasted text has no file behind
it. Write it verbatim to
.maps/<mode>-<slug>/context.md, declare it in
sources with origin: "captured", and cite that. Never rest a board on a
claim with no artifact.
- A scope. A named pipeline, subsystem, or path. When a workspace describes
more than one pipeline over the same services, build one board per
pipeline and say which one in
repo.ref.
If the user names a document, read it before touching any code.
Required reading
Before drafting anything, read:
references/evidence-rules.md — the eight hard rules. Non-optional.references/model-schema.md — the exact shape of model.json.
Read references/visual-spec.md only if you need to know how a field renders.
Workflow
Resolve inputs.
Take in the seeding context, if any. Pull out the claimed topology, the
vocabulary the team actually uses, and every hint of a condition. Treat all
of it as hypothesis. If any of it came from the conversation rather than a
file, write it to context.md now, before you start reading code.
Recon. README, entry points, dependency manifest, CI config, top-level
packages. Read code, not the file tree. Find the spine: the one loop, request
path, or pipeline the system exists to run.
Mode-specific gathering.
map: nothing extra.change: git diff --stat <base>...<head> and the full diff for the files
that matter. Note which files are new, deleted, or heavily rewritten, and
which import edges appeared or disappeared.flow: locate the entry point, then follow the call chain by reading, not
guessing. Record the order — it becomes steps.
Draft groups and nodes. Apply rules 1, 2, and 6. Cap-check at 25 before
going further. Assign shape deliberately; shape is a claim.
Trace edges. For every pair you believe talks, grep for the call, import,
publish, or request and cite the line. On a multi-repo board set transport
on every edge — cite the producing side, since that is what proves the
edge. An edge the code does not confirm is deleted, or kept as
source: "doc" with the document line and a note saying what you could not
find. Never silently keep an unproven edge.
Harvest payloads. Three to five, quoted verbatim, each with a real
source and origin. Rules 4 and 5.
Hunt conditions. Rule 7. Feature flags off by default, TODO clusters,
duplicate implementations, skipped tests, config nothing reads. Budget real
effort here — this is often the most valuable content on the board.
Write the explainer. Four paragraphs at most in what: what the repo is,
what shape the system has and why, the one hard thing about it. Then
howToRead.
Lay out the grid. Spine left to right, supporting below, outputs right.
Step cells by 2, not 1, so the paths between buildings stay visible. Never put
a tower on the diagonal in front of a shorter node — it will hide it.
Write the model to <root>/.maps/<mode>-<slug>/model.json.
Validate — hard gate.
python3 <skill>/scripts/validate_model.py .maps/<mode>-<slug>/model.json \
--root <workspace root>
Fix every error. Read every warning and either fix it or be able to justify
it. Do not proceed to step 13 with errors outstanding.
Render.
python3 <skill>/scripts/render.py .maps/<mode>-<slug>/model.json \
-o .maps/<mode>-<slug>/index.html
Publish. Call the Artifact tool on the rendered index.html. Pass a
favicon and keep it stable across regenerations of the same map. Hand back
the URL. If Artifact is unavailable, give the local path instead.
Report — short. Three things and nothing else:
- The one-sentence claim the board makes about the system.
- The confirmed-vs-asserted count the validator prints, and which edges the
documents claim that the code did not confirm. On a doc-seeded run this is
the most valuable line in the report — lead with it.
- The node count, and what got collapsed into a nested board.
Rules for this skill
- The validator is a gate, not a linter. Never render or publish a model with
outstanding errors, and never edit the validator to make a model pass.
- Never author a payload. No real source, no payload.
- Never launder a doc claim into code evidence. If only a document says it,
it is
source: "doc", and the board says so.
- Never invent a citation. Grep before you write it.
- Do not regenerate
assets/board.html. It is authored once, by hand. If the
board needs a new capability, change the template deliberately and once — never
emit a bespoke renderer per run.
- Do not create
.gitignore entries without asking. Mention that .maps/ is
probably worth ignoring and let the user decide.
- Re-render is cheap. When the user corrects a node, edit
model.json and
re-run steps 11 to 13. Do not redo the analysis.
Regenerating an existing map
If .maps/<mode>-<slug>/model.json already exists, read it first. Update it in
place so the diff shows what changed about the system, and re-publish to the same
Artifact URL by passing url. A map whose URL churns on every run is not a
reference.
Layout and shape quick reference
| shape |
reads as |
use for |
flat |
a pad |
config, constants, thin adapter |
slab |
wide low block |
service, handler, API surface |
cube |
solid block |
a normal working subsystem |
stack |
layered plates |
store, archive, queue |
tower |
tall and narrow |
validation, measurement, gating |
Portability
Both scripts are Python 3 with no third-party imports — argparse, json,
pathlib, re, sys only. They run anywhere Python 3.9+ is installed, with no
install step and no virtualenv. python3 is written above because it works on
every machine; if a project standardises on a runner, uv run and poetry run
work identically.
Nothing in this skill assumes a language, framework, VCS host, or company
convention. It reads whatever is in front of it and cites what it finds.
Files
SKILL.md this file
references/evidence-rules.md the eight hard rules + working order
references/model-schema.md model.json field by field
references/visual-spec.md what the renderer does with each field
assets/board.html the board template — authored once, never generated
scripts/validate_model.py the gate
scripts/render.py model.json -> index.html
fixtures/example-model.json a working model, for reference and for testing
1---2name: system-map3description: Turn a codebase, a set of services, a change, or a runtime path into an interactive isometric system map you can point at and discuss. Works across one repo or many in a workspace, and can be seeded from architecture notes, design docs, a README or CLAUDE.md, or context given in conversation. Language- and stack-agnostic. Use when the user wants to understand how a repo is put together, how services interact, what a PR or commit range actually touched, or what happens along one entry point. Triggers on "map this repo", "system map", "map these services", "how does this fit together", "visualize the architecture", "show me what this PR changed", "trace this request", "explain this codebase visually".4---56# System Map78Produce a self-contained interactive board — isometric buildings on a grid, real9control and data paths between them, clickable payloads quoted from the code, and10an explainer panel — so the user can discuss the system by pointing at it.1112The board is a means. The value is the accuracy of the model behind it. A pretty13diagram of the wrong system is worse than no diagram.1415## Modes1617| Mode | Argument | Answers |18|---|---|---|19| `map` (default) | optional subsystem or path scope | How is this system put together, and what talks to what? |20| `change` | PR number, branch, or commit range | What did this change touch, and what does it now talk to that it did not before? |21| `flow` | an entry point — route, CLI command, job, handler | What actually happens, in order, along this path? |2223Infer the mode from the request. Ask only when genuinely ambiguous.2425## Inputs it accepts2627- **One repository.** The default.28- **A workspace of several repositories.** A directory whose subfolders are each29 their own git repo. Declare them in `repos`; citations get a `repoId:` prefix.30- **Seeding context.** Anything that describes the system: an architecture note,31 a design doc, an ADR, a README, a root `CLAUDE.md`, a wiki export — or the user32 simply explaining it in the conversation. Read it first for the candidate33 topology and the team's vocabulary, then confirm in code. A claim from context34 never becomes code evidence; see rule 9.35 - Context that arrives as **conversation or pasted text** has no file behind36 it. Write it verbatim to `.maps/<mode>-<slug>/context.md`, declare it in37 `sources` with `origin: "captured"`, and cite that. Never rest a board on a38 claim with no artifact.39- **A scope.** A named pipeline, subsystem, or path. When a workspace describes40 more than one pipeline over the same services, build **one board per41 pipeline** and say which one in `repo.ref`.4243If the user names a document, read it before touching any code.4445## Required reading4647Before drafting anything, read:4849- `references/evidence-rules.md` — the eight hard rules. Non-optional.50- `references/model-schema.md` — the exact shape of `model.json`.5152Read `references/visual-spec.md` only if you need to know how a field renders.5354## Workflow55561. **Resolve inputs.**57 - `mode`, and its argument. Any seeding documents. Any scope.58 - `root`: the workspace root that all citations resolve against.59 - Single repo: `git rev-parse --show-toplevel`.60 - Workspace: the directory holding the repos. It often is not a git repo61 itself — that is fine and expected.62 - `ref` per repo. In a workspace, loop the subfolders:63 ```64 for d in */; do git -C "$d" rev-parse --abbrev-ref HEAD; done65 ```66 Record each in `repos[].ref`. Mixed refs are normal and worth surfacing.67 - `slug`: a short kebab name for the output directory.68692. **Take in the seeding context**, if any. Pull out the claimed topology, the70 vocabulary the team actually uses, and every hint of a `condition`. Treat all71 of it as hypothesis. If any of it came from the conversation rather than a72 file, write it to `context.md` now, before you start reading code.73743. **Recon.** README, entry points, dependency manifest, CI config, top-level75 packages. Read code, not the file tree. Find the spine: the one loop, request76 path, or pipeline the system exists to run.77784. **Mode-specific gathering.**79 - `map`: nothing extra.80 - `change`: `git diff --stat <base>...<head>` and the full diff for the files81 that matter. Note which files are new, deleted, or heavily rewritten, and82 which import edges appeared or disappeared.83 - `flow`: locate the entry point, then follow the call chain by reading, not84 guessing. Record the order — it becomes `steps`.85865. **Draft groups and nodes.** Apply rules 1, 2, and 6. Cap-check at 25 before87 going further. Assign `shape` deliberately; shape is a claim.88896. **Trace edges.** For every pair you believe talks, grep for the call, import,90 publish, or request and cite the line. On a multi-repo board set `transport`91 on every edge — cite the **producing** side, since that is what proves the92 edge. An edge the code does not confirm is deleted, or kept as93 `source: "doc"` with the document line and a `note` saying what you could not94 find. Never silently keep an unproven edge.95967. **Harvest payloads.** Three to five, quoted verbatim, each with a real97 `source` and `origin`. Rules 4 and 5.98998. **Hunt conditions.** Rule 7. Feature flags off by default, `TODO` clusters,100 duplicate implementations, skipped tests, config nothing reads. Budget real101 effort here — this is often the most valuable content on the board.1021039. **Write the explainer.** Four paragraphs at most in `what`: what the repo is,104 what shape the system has and why, the one hard thing about it. Then105 `howToRead`.10610710. **Lay out the grid.** Spine left to right, supporting below, outputs right.108 Step cells by 2, not 1, so the paths between buildings stay visible. Never put109 a `tower` on the diagonal in front of a shorter node — it will hide it.11011111. **Write the model** to `<root>/.maps/<mode>-<slug>/model.json`.11211312. **Validate — hard gate.**114 ```115 python3 <skill>/scripts/validate_model.py .maps/<mode>-<slug>/model.json \116 --root <workspace root>117 ```118 Fix every error. Read every warning and either fix it or be able to justify119 it. Do not proceed to step 13 with errors outstanding.12012113. **Render.**122 ```123 python3 <skill>/scripts/render.py .maps/<mode>-<slug>/model.json \124 -o .maps/<mode>-<slug>/index.html125 ```12612714. **Publish.** Call the Artifact tool on the rendered `index.html`. Pass a128 `favicon` and keep it stable across regenerations of the same map. Hand back129 the URL. If Artifact is unavailable, give the local path instead.13013115. **Report — short.** Three things and nothing else:132 - The one-sentence claim the board makes about the system.133 - The confirmed-vs-asserted count the validator prints, and which edges the134 documents claim that the code did not confirm. On a doc-seeded run this is135 the most valuable line in the report — lead with it.136 - The node count, and what got collapsed into a nested board.137138## Rules for this skill139140- **The validator is a gate, not a linter.** Never render or publish a model with141 outstanding errors, and never edit the validator to make a model pass.142- **Never author a payload.** No real source, no payload.143- **Never launder a doc claim into code evidence.** If only a document says it,144 it is `source: "doc"`, and the board says so.145- **Never invent a citation.** Grep before you write it.146- **Do not regenerate `assets/board.html`.** It is authored once, by hand. If the147 board needs a new capability, change the template deliberately and once — never148 emit a bespoke renderer per run.149- **Do not create `.gitignore` entries without asking.** Mention that `.maps/` is150 probably worth ignoring and let the user decide.151- **Re-render is cheap.** When the user corrects a node, edit `model.json` and152 re-run steps 11 to 13. Do not redo the analysis.153154## Regenerating an existing map155156If `.maps/<mode>-<slug>/model.json` already exists, read it first. Update it in157place so the diff shows what changed about the system, and re-publish to the same158Artifact URL by passing `url`. A map whose URL churns on every run is not a159reference.160161## Layout and shape quick reference162163| shape | reads as | use for |164|---|---|---|165| `flat` | a pad | config, constants, thin adapter |166| `slab` | wide low block | service, handler, API surface |167| `cube` | solid block | a normal working subsystem |168| `stack` | layered plates | store, archive, queue |169| `tower` | tall and narrow | validation, measurement, gating |170171## Portability172173Both scripts are Python 3 with **no third-party imports** — `argparse`, `json`,174`pathlib`, `re`, `sys` only. They run anywhere Python 3.9+ is installed, with no175install step and no virtualenv. `python3` is written above because it works on176every machine; if a project standardises on a runner, `uv run` and `poetry run`177work identically.178179Nothing in this skill assumes a language, framework, VCS host, or company180convention. It reads whatever is in front of it and cites what it finds.181182## Files183184```185SKILL.md this file186references/evidence-rules.md the eight hard rules + working order187references/model-schema.md model.json field by field188references/visual-spec.md what the renderer does with each field189assets/board.html the board template — authored once, never generated190scripts/validate_model.py the gate191scripts/render.py model.json -> index.html192fixtures/example-model.json a working model, for reference and for testing193```
rohaquinlop