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

1. Tech stack — options with trade-offs measured against the NFRs (not fashion), recommendation first; the user decides. Significant picks become ADRs.
2. 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.
3. Data model & contracts — entities, relationships, API contracts where relevant.
4. Cross-cutting strategy — error handling, logging, testing approach fit for the stack.
5. 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.