| name | map-system |
| model | sonnet |
| description | Map a repository at a higher level in its domain vocabulary. Two modes: simplified is a one-shot ~30-line textual orientation; complete (default) does an exhaustive pass and renders a self-contained themed HTML deck (overview, business insights, architecture, API/data contracts). --save (on) writes docs/system-map/; --output markdown|html. Manual invocation only. Ships in starter.
|
System Mapping
Overview
map-system answers "what is this area / this repo, in our own words?"
at two depths:
simplified — a one-shot, ~30-line textual orientation map. Its
value is the invocation discipline: sample, do not crawl, one screen.complete (the default) — an exhaustive pass that renders a
self-contained, themed HTML deck of the repository: the human-facing
"what is this project" artifact a new engineer is walked through and a
manager reuses. onboarding presents this deck during the ramp.
The two modes are different jobs. simplified keeps the micro-skill
discipline; complete is allowed — and expected — to crawl.
When to Engage
Engage only when the user explicitly invokes the skill ("map this",
"zoom out", "generate the system map", "I don't know this area"). This
skill is manual-invocation only — agents must not engage it
autonomously.
Do not engage when:
- The user already named specific files (read them directly).
- A glossary lookup would answer the question (use
CONTEXT.md).
- The task is a small, local change (
simplified is overhead; complete
even more so).
Invocation — three orthogonal axes
map-system → DEFAULT: complete + save + html + dark-blue
→ docs/system-map/<repo>.html
map-system --mode simplified --no-save → the quick ~30-line textual map, inline (old default)
map-system --no-save → complete picture, inline (not written)
map-system --output markdown → complete picture saved as a markdown doc
map-system --theme light-jade → complete deck, light-jade theme
map-system --design-from "<prompt>" → complete deck, custom theme via frontend-design
--mode simplified | complete — content depth. Default complete.--save / --no-save — write to a file or return inline. Default
save on. --no-save returns the content inline as readable markdown,
regardless of --output.--output markdown | html — saved-file format. Default html
(the themed deck via frontend-design); markdown is the same content as
a plain document (no theme, no frontend-design).
Theme flags (--theme, default dark-blue; --design-from) apply to
--output html only. Saved files default to docs/system-map/<repo>.<html|md>.
Protocol — simplified mode
Step 1 — Pick the abstraction level
Decide the level one above where the question is being asked:
- Question about a function → map the module that owns it.
- Question about a module → map the feature area.
- Question about a feature → map the system boundary.
Never map at the same level as the question — that is just reading the code
with extra steps.
Step 2 — Identify modules and callers
For the chosen level, list the modules in the area (3–10), their principal
callers, and the data that flows between them — in CONTEXT.md vocabulary.
Step 3 — Output the map
Render as a short list or table, ~30 lines, in the project's domain
language. If CONTEXT.md is missing, surface that — the map falls back to
code identifiers.
Protocol — complete mode
The default. Crawls the repository and renders the deck.
Step 1 — Crawl
Walk the repo exhaustively enough to fill the deck sections below. Read
CONTEXT.md, README, docs/adr/*, the module tree, and (when an API is
present) the route/DTO definitions. This is the one path where the
anti-crawl discipline does not apply.
Step 2 — Assemble the deck sections
Each section degrades gracefully when its source is absent:
- Cover — repo name, one-line purpose, theme branding, generation date.
- Project overview & business insights — what the project does and why,
in domain vocabulary (sources:
CONTEXT.md, README, the "why" in ADRs).
- Architecture & module map — modules, responsibilities, and how they
connect, as inline SVG diagrams (authored in Mermaid, pre-rendered to
SVG so the deck needs no runtime).
- Contracts — when an API is detected, the endpoints, DTOs, enums, and
status codes. Reuse the API-detection heuristics from
audit-contracts.
- Data model — when a DB is detected, the entities and relationships.
- Decisions of record — the ADRs that shape the codebase, summarized.
Keep it a presentation: curated and screen-paced, not a 200-page reference.
Step 3 — Resolve the theme (html output only)
Mirror the launch-release cascade (first match wins):
--design-from="<prompt>" → synthesize a theme via frontend-design.--theme=<name> flag..octopus.yml top-level theme: key.- Default:
dark-blue.
Presets live alongside the launch-release themes
(skills/launch-release/templates/themes/): dark-blue (default —
GitHub dark-mode / Primer palette), dark-jade, light-jade.
Step 4 — Render and save
Render the self-contained HTML by filling templates/deck.html.tmpl — the
content slots from the crawl, the THEME_* variables from the resolved
theme (inline CSS, diagrams as inline SVG — no script runtime, no external
assets). This is
deterministic and needs no other skill. When frontend-design is
available, use it to refine the visual design beyond the base template.
Write to docs/system-map/<repo>.html (or .md for --output markdown),
unless --no-save.
When frontend-design is unavailable
frontend-design is an enhancer, not the renderer:
- Preset themes (
--theme <name>, default dark-blue) render the HTML
deck deterministically from the template — they do not need
frontend-design. You get the template's base look; if frontend-design
is present it refines the visuals.
--design-from "<prompt>" (custom theme synthesis) is the only path
that requires frontend-design. When it is not available, say so and
fall back to a preset theme — mirroring the launch-release
--design-from contract.--output markdown never involves frontend-design.
Never fail the run or the ramp over a missing enhancer.
Anti-Patterns
Scoped to simplified mode (the discipline that defines it):
- Auto-invocation — the description carries the manual-only flag; respect it.
- Mapping at the same abstraction level as the question.
- Implementation jargon when the project has its own glossary.
- Producing a 200-line map —
simplified is one screen, ~30 lines.
- Reading every file in the area —
simplified samples; it does not crawl.
For complete mode:
- Forking the styling system — reuse
launch-release themes; do not invent one.
- Emitting HTML with external dependencies — the deck must be self-contained.
- Turning the deck into exhaustive reference docs — it is a presentation.
Integration with Other Skills
frontend-design — refines the complete HTML deck and synthesizes
custom themes for --design-from; an enhancer, not required for presets.launch-release — the theme schema and presets the deck reuses.audit-contracts — the API-detection heuristics for the contracts section.onboarding — presents the complete deck during the ramp.doc-align — often called before it, so grilling starts from shared geography.doc-lifecycle — when the map reveals an undocumented area, the follow-up
is usually a CONTEXT.md update or an ADR.
