Architecture
Lock how services, modules, endpoints, schemas, and stores talk to each other. Concrete at system boundaries, schematic inside. Types, call stacks, and file layout belong to
.
Core contract
- One capability or epic — work that will become multiple tickets, or one ticket that still needs new seams.
- The spec (if any) is the behavioural source of truth. This document is the recommended system shape.
- Inspect the repository. Prefer evidence over generic best practices.
- Read-only: inspect code, docs, tests, and history; do not modify production code.
- Stop after the architecture unless the user asks to continue.
Do
not include: per-function signatures, call stacks, file-change maps, implementation sequences, or pattern dumps with existing/proposed bodies. Those are
.
Do
not restate the spec. Link or summarise;
owns product narrative.
When to use / skip
text
wayfinder → grill-with-docs → /to-spec
↓
/architecture # this skill — new seams / multi-ticket
↓
/program-design # code shape, when taste matters
↓
/to-tickets → /implement
| Situation | Skill |
|---|
| Idea or trade-offs still open | or first |
| External API/vendor semantics unclear | first |
| Module interface is the unknown | , fold the result in |
| State model or UI feel uncertain | first |
| New seams, naming, or multi-ticket shape | |
| Architecture is obvious; code taste is not | Skip to |
| Obvious single-ticket, existing patterns | Skip to |
Steps
1. Establish the capability
Read the spec, conversation, ADRs, domain glossary (
), and project instructions.
Ready when
could slice this into tracer bullets. If the input is already a small ticket on an established pattern, recommend skipping this skill.
Record outcome, in-scope behaviour, non-goals, and constraints. Recommend defaults for non-blocking ambiguity. Stop for the user only when a decision changes behaviour, public APIs, data ownership, security, persistence, compatibility, system boundaries, dependencies, or scope.
This step is complete when outcome, non-goals, and blocking ambiguity are explicit.
2. Inspect the repository
Trace the current path through entry, domain logic, persistence, integrations, and tests. Note existing modules and conventions to reuse. Conflicting patterns: pick one, with evidence.
This step is complete when every proposed seam has an existing counterpart or is named as new and justified.
3. Design the end state
Show
before/after at module and system boundaries (
flowchart or sequence). Not class-level.
Define coarse structure only:
- Packages, modules, or top-level folders — not every file.
- Public contracts: endpoints, schemas, events, provider ids.
- Runtime flow from entry to observable result, at those boundaries.
When integrating external systems, add a short
Verified basis citing official docs. Use
for the long form; distill here.
Prefer, in order:
- Existing code over new code.
- Local code over a shared abstraction.
- Established repository patterns over new patterns.
- Explicit code over generic frameworks.
- Narrow MVP surface over speculative API roadmaps.
- One clear execution path over interchangeable layers.
New interfaces, factories, adapters, registries, or shared utilities require a current problem with multiple immediate call sites.
This step is complete when a reviewer can see the proposed system shape and how work flows through it.
4. Propose tracer-bullet slices
Recommend how
should break the capability. For each slice:
- Title
- Delivers — end-to-end behaviour when this slice merges
- Blocked by — other slices, or
- Architecture anchor — sections or contracts this slice implements
Each slice must be independently demoable or verifiable. Merge slices that only make sense together. Do not attach file lists or test commands.
This step is complete when the breakdown covers the capability and follows tracer-bullet rules.
5. Resolve architecture questions
Record material decisions:
- Question
- Chosen: recommendation and rationale
- Options not chosen: and why
Grill before writing when decisions are still unsettled. Include migration, security, performance, observability, and rollback only when the change creates them.
This step is complete when no blocking decision remains implicit.
6. Write the document
Capture git metadata for the frontmatter (
,
).
Write to the repository's established work-artifact location. If none exists, use
docs/agents/architecture/<short-slug>.md
.
Follow
references/architecture-template.md
. Before handing off, verify:
- One capability or epic, not a file tweak.
- Before/after architecture is visible at module boundaries.
- Proposed slices are tracer bullets with blocking edges.
- Public contracts only — no call stacks, function bodies, or file maps.
- No blocking decision remains implicit.
Shortened form
For a bounded capability that is one tracer-bullet ticket but still needs architectural approval:
- Frontmatter, summary, current / desired state, not doing
- One architecture diagram
- Public contracts
- Resolved decisions (if any)
- Approval gate
Handoff
Report:
- Path to the architecture document.
- Concise summary of the recommended system shape.
- Proposed slice count and frontier slice.
- Blocking decisions, or .
- Confirmation that production code was not modified.
- Next step:
text
/program-design using <architecture-path>
If code shape is obvious and the user will slice next:
text
/to-tickets using <architecture-path>