Skip to content
Octopus Octopus Octopus

map-system

map-system answers “what is this — in our own words?” at two depths. The original skill was a deliberately tiny one: a ~30-line textual orientation map, anti-exhaustive by design. That survives as the simplified mode; a complete mode — now the default — adds one that renders a self-contained, themed HTML deck of the whole repository.

Two modes

  • simplified --no-save — the original micro map. Sample, do not crawl, ~one screen, in the project’s domain vocabulary. The right tool for “I don’t know this area, zoom me out”.
  • complete (the default) — an exhaustive pass that produces the human-facing “what is this project” artifact: cover, project overview and business insights, an architecture/module map as inline SVG diagrams (Mermaid pre-rendered), API contracts (when an API is detected), the data model, and the decisions of record. onboarding walks a new engineer through this deck.

Three orthogonal axes

map-system                              → DEFAULT: complete + save + html + dark-blue
                                          → docs/system-map/<repo>.html
map-system --mode simplified --no-save  → the quick textual map, inline (old default)
map-system --no-save                    → complete picture, inline
map-system --output markdown            → complete picture saved as markdown
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 — persist to a file or return inline (default save).
  • --output markdown | html — saved format (default html, the themed deck; markdown is the same content as a plain document).

Themed, and self-contained

The complete + html deck reuses the launch-release theme system — the same schema, presets, and --design-from synthesis via frontend-design — rather than inventing a styling layer. Three presets ship: dark-blue (the default — the GitHub dark-mode / Primer palette, #0d1117 background, #58a6ff accent), dark-jade, and light-jade. The output is a single self-contained .html file (inline styles, diagrams as inline SVG, no script runtime) — openable and presentable with no build step, written to docs/system-map/<repo>.html.

A new default, deliberately

A bare map-system now generates and saves the deck — a breaking change from the old inline micro map. The blast radius is bounded: the skill is manual-invocation only (agents must not run it on their own), and the old behaviour is one flag away (--mode simplified --no-save). It does not add a hard frontend-design dependency: preset HTML decks render deterministically from the template; frontend-design only refines the visuals when present, and is required solely for --design-from (which falls back to a preset). This is the rationale for generating and saving a complete deck by default.

Composes with

  • launch-release — the theme schema and presets the deck reuses.
  • frontend-design — refines the HTML deck and synthesizes custom themes for --design-from; an enhancer, not required for preset decks.
  • audit-contracts — the API-detection heuristics for the contracts section.
  • onboarding — presents the complete deck during the ramp.

Source: skills/map-system/SKILL.md