| name | swarm-design |
| description | System design phase — architecture, tech-stack options, module boundaries, data model, and ADRs from a validated SRS. Use after requirements are validated, when choosing a tech stack, designing system structure/APIs/data models, or recording an architecture decision. |
swarm-design — system design phase
Gate: requires a validated SRS (else route back to swarm-spec). Read the SRS and
feature specs first; the design must answer them, not your habits.
Lane: this is the standard, agent-driven lane — you propose, the user validates. If the
user wants to own the system rather than receive it (deep design, pseudocode, algorithm-level
planning, "developer mode"), hand the phase to swarm-design-deep instead; the two replace
each other and never run together.
Produce, in order
- Tech stack — options with trade-offs measured against the NFRs (not fashion),
recommendation first; the user decides. Significant picks become ADRs.
- Decomposition — modules/services with single responsibilities, boundaries, and
data flow. Prefer deep modules behind simple interfaces. Mermaid diagrams for the
system view and any non-obvious flow.
- Data model & contracts — entities, relationships, API contracts where relevant.
- Cross-cutting strategy — error handling, logging, testing approach fit for the
stack.
- Milestone boundaries — group FRs into build milestones; these become
swarm-implement's ticket batches.
Rules
- Traceability table required: every Must-FR ↦ component; every NFR ↦ one line on how
the design satisfies it. Nothing silently dropped.
- Options with recommendation for anything that meaningfully affects cost, lock-in,
or complexity — never decide those silently (mode: in auto, only stack-level choices
already delegated by the user proceed without asking; queue the rest).
- Simplicity doctrine: every moving part justifies itself; prefer known patterns
(refactoring.guru names) over invention; when two designs both satisfy the NFRs, ship
the smaller one.
- Each significant decision →
50 Decisions/<P>/ADR-NNN-<slug>.md (template:
90 Templates/decision.md): context, options, decision, consequences, FR/NFR links.
Output & gate
docs/design.md (human lane) + ADRs, mirrored to the vault by sync. End with the user
validation gate (gated mode) or a self-check against the traceability table (auto mode);
update flow-state to phase: design-ui (if the SRS declares an interface) or
phase: tickets.
Influences: Jeffallan's architecture-designer & api-designer; Pocock's codebase-design &
domain-modeling; refactoring.guru; Nygard ADRs — see CREDITS.md.
