| name | spec-system-map |
| argument-hint | [create|amend] |
| description | Create or amend spec/system-map.md. Use for architecture scope, system shape, runtime boundaries, core flows, invariants, storage/external systems, or SYSTEM_MAP. |
| disable-model-invocation | true |
| compatibility | Requires git. |
| metadata | {"related-skills":"spec-charter, spec-grill, dev-backlog"} |
spec-system-map
Create or amend spec/system-map.md, the high-level map of how the project is shaped. This is narrower than a generic ARCHITECTURE.md: it names project-wide structure, boundaries, flows, storage/external systems, invariants, and pointers to deeper docs.
Use this when
- scoping or documenting architecture: system shape, runtime boundaries, core flows, invariants, or storage/external systems
spec/system-map.md is absent and the project wants a first system mapspec/system-map.md exists but its shape, boundaries, flows, invariants, or pointers have drifted from the repo- deciding whether a change belongs here versus
spec/charter.md (why/direction) or spec/capabilities.md (capability contracts)
Execution contract
Mode router
create: use when spec/system-map.md is absent or the user asks for a first system map.amend: use when the file exists and the user asks to update architecture shape, boundaries, flows, invariants, or links.
When no mode is specified, route by file state. Create spec/ if needed.
Completion contract
End create and amend modes with:
Evidence Read: concise bullets naming the concrete docs, entrypoints, configs, tests, storage/external surfaces, and history inspected.Evidence Missing: concise bullets naming unavailable or ambiguous evidence that affects confidence.
Done when the map reflects only evidence-backed project-wide changes, low-level detail has been demoted or refused, charter or capability changes have been routed out, and the final response names evidence read and evidence missing.
Boundary
| File | Role |
|---|
spec/charter.md | Why / good state / Objectives / Decisions |
spec/system-map.md | System shape / runtime boundaries / core flows / invariants / pointers |
spec/capabilities.md | Capability-level contracts / Hard Constraints / Learnings |
Do not turn system-map.md into exhaustive module documentation, API reference, runbook, ADR log, or implementation notes. Demote subsystem detail to linked docs; promote only project-wide structure or invariants.
Create mode
- Read bounded signals:
spec/charter.md if present, README.md, AGENTS.md/CLAUDE.md, top-level directories, package/config files, and existing docs that appear architecture-related.
- Run a Repo Evidence Pass before drafting. Inspect enough code reality to understand system shape: entrypoints and command surfaces, package/config scripts, runtime boundaries, storage/state surfaces, external systems, tests that reveal intended behavior, and recent commit history and execution logs (e.g. sprint files) when available.
- Draft from
templates/system-map.md; keep sections short and link out instead of expanding subsystem detail.
- Include these sections: System Shape, Runtime Boundaries, Core Flows, Storage And External Systems, Project-Wide Invariants, Candidate Capability Boundaries, Where To Go Next.
- If the repo is brownfield, explicitly mark uncertain boundaries as assumptions rather than inventing detail.
- Use Candidate Capability Boundaries to hand off concrete, short candidates to
spec-grill. Each candidate should name evidence, the contract surface it appears to own, and the uncertainty spec-grill must resolve.
- Recommend asking
spec-grill to review the candidate capability boundaries when the map reveals durable boundaries that are not yet in spec/capabilities.md.
- If the user is running the full spec pipeline, point them to the ready-to-commit checklist in
../spec-grill/references/spec-pipeline-ready.md after the map and at least one accepted capability exist.
The Repo Evidence Pass is an agent checklist, not a new script. Report evidence in the conversation, not as inventory inside spec/system-map.md.
Amend mode
- Re-read
spec/system-map.md and the concrete change evidence.
- Update only project-wide shape, boundaries, flows, storage/external systems, invariants, or pointers.
- Move low-level module details, endpoint lists, deployment commands, and temporary implementation notes out of the map.
- If a change is really a capability contract, route it to
spec-grill. If it changes why/good-state, route it to spec-charter amend.
Quality checks
Before finishing, verify:
- A reader can understand the project shape in under 5 minutes.
- Every section names current project-wide facts, not aspirational design.
- The map links to deeper docs instead of copying them.
- No subsystem gets more detail than the whole-system flow needs.
- Candidate Capability Boundaries are short handoff candidates, not a module inventory.
- No stale module-level TODOs, endpoint inventories, or runbook commands are included.
- Brownfield maps are not based only on README/top-level directory skimming; unsupported boundaries are labeled as assumptions.
Failure modes
- drafting from README and top-level folders alone, skipping the Repo Evidence Pass, so the map reads plausibly but isn't evidence-backed
- sections drifting into aspirational design ("will support X") instead of current, evidence-backed facts
- endpoint or API inventories creeping into Core Flows or Storage And External Systems, turning the map into a de facto API reference
- amend mode absorbing low-level module detail (helper functions, single endpoints, deployment commands) instead of demoting it to linked docs
- charter-level direction changes or capability-level contract changes getting edited into the map instead of routed to
spec-charter amend or spec-grill
Verification prompts
Use these as quick pressure tests when changing the skill or a generated map:
- "Create a system map for an existing repo with many modules and no architecture docs." Expected: short
spec/system-map.md, uncertainty labeled, subsystem details linked or deferred.
- "Create a system map after reading only README and top-level folders." Expected: continue the Repo Evidence Pass before drafting or label the map as insufficiently evidenced.
- "Update this map with a new helper function and endpoint." Expected: refuse or demote as too low-level unless it changes a project-wide flow or invariant.
- "Turn this ARCHITECTURE.md into spec/system-map.md." Expected: preserve high-level boundaries and flows, remove runbook/API/module inventories, add pointers.
References
