# Swarm Design Deep

> swarm-design-deep — the developer-driven design lane

- Skill: `anmarhani/swarm-design-deep` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add anmarhani/swarm-design-deep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anmarhani/swarm-design-deep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AnmarHani (https://skillmd.com/u/anmarhani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/anmarhani/swarm-design-deep

---


# swarm-design-deep — the developer-driven design lane

**Gate:** requires a validated SRS. This lane **replaces** swarm-design for the phase — do not
run both; one skill owns the design artifacts.

The standard lane (swarm-design) is agent-driven: it proposes an architecture and the user
validates it. That is the right trade for most projects. This lane exists for the other case —
a developer who must hold the system in their head afterwards. It is slower and costs more
tokens on purpose, and it pays for itself only if implementation comes out mechanical.

## The contract

Treat the design session as the agent, and apply six of the 12 factors to it:

| | applied here |
|---|---|
| **8** own your control flow | The user decides what is designed next. Never advance the unit list yourself. |
| **7** contact humans with tool calls | Every unresolved choice is an explicit question. No assumption reaches the doc silently. |
| **3** own your context window | Design lives in per-unit files, not the transcript. This is what makes the depth affordable. |
| **6** launch/pause/resume | One unit per session, closed and dropped. A cold session resumes from the unit table. |
| **12** stateless reducer | Each session = (files so far + one decision) → updated files. |
| **10** small, focused agents | One unit designed to the bottom beats the whole system designed halfway. |

**Awareness is caused by producing, not by reading.** Forty pages of excellent design gets a
rubber stamp. The commit step below is the whole point of the lane; without it this is just
swarm-design with more words.

## Setup — the design profile (ask once)

Write `docs/design/profile.md`, then never ask again:

- **design language** — what algorithms and signatures are written in. *Independent of the
  implementation language*: designing in Java and building in Python is normal. Language-neutral
  pseudocode is a valid answer. Say this out loud when asking, because users assume it's the
  build language.
- **granularity** — what one unit is here (module / service / endpoint / algorithm).
- **diagram formats** — see `references/diagrams.md`.
- **standing depth override**, if any.

## Units and depth triage

Decompose into units and give each a class. Propose the triage, get it confirmed. **Depth is
allocated, not applied** — this is the primary token control.

| class | signals | owes |
|---|---|---|
| **algorithmic** | novel logic, ordering/state/concurrency, performance-sensitive, non-obvious data structure | pseudocode, data structures, invariants, complexity, edge-case table, **test-vector table** |
| **integration** | crosses a boundary — network, process, third party, filesystem, user | sequence diagram, contract (types in/out), failure modes with timeout/retry/idempotency stance |
| **mechanical** | CRUD, config, glue, framework-shaped, fully determined by its contract | signature + one line of intent. **No pseudocode.** |

Level-0 units are the standard lane's deliverables — stack, decomposition, data model,
milestone boundaries — run through the same loop. Level-1 units are the modules themselves.

If the user asks for algorithmic depth on something mechanical: **say what it costs and what it
buys, once**, then do as they decide. Pseudocode for a CRUD handler is waterfall with extra
steps, and saying so is part of the job — arguing twice is not.

## The unit loop

Per unit, in order. Steps 1–2 are the lane; skip step 2 and you are running swarm-design.

1. **Frame.** What must this unit do (FR refs), what constrains it (NFR refs), what goes in and
   out, and 2–3 candidate approaches with real trade-offs. **Write no implementation detail
   yet.** Read the relevant FR spec, not the whole SRS.
2. **Commit.** The user states the approach in their own words, or picks one and says why. Wait
   for it. If they delegate — "you pick" — decide, and record `decided-by: agent (delegated)`.
   Do not treat silence, a "sounds good", or a question as a commitment.
3. **Draft.** Write the unit file against *their* approach, not your preferred one. Include
   whatever the depth class owes.
4. **Check.** Ask 2–3 questions about **consequences**, not content: "what happens if the queue
   is empty when the timer fires?" Aim them at the parts most likely to be wrong. A wrong answer
   means the design or the explanation is wrong — fix it, don't re-explain harder. This is not a
   quiz and must not read as one.
5. **Close.** Record status and attribution in the unit table, drop the unit from context, and
   **report units remaining**.

The user may write any part themselves — a signature, the control flow, the whole unit. Complete
and critique it rather than replacing it, and record that they wrote it.

**When a committed approach proves wrong while drafting:** stop, show the conflict with evidence,
and return to step 1 for that unit. Never quietly design something else.

## Ownership accounting

Each unit carries `decided-by: user | agent (delegated)`. At the exit summary, report the ratio.
If more than half were delegated, say it in one plain line — the lane was chosen for ownership,
and that is how much of it they hold. State it and move on; it does not block.

## Files

```
docs/design/
  profile.md              design language, granularity, diagram formats, depth policy
  overview.md             system map · unit table (class · status · decided-by) · FR traceability
  units/NN-<slug>.md      one file per unit  (template: references/unit-template.md)
  diagrams/               .drawio.svg / .excalidraw.md sources
```

ADRs still go to `50 Decisions/<P>/ADR-NNN-<slug>.md`. Sync mirrors everything. Per-unit files
are for context economy, not tidiness: load `overview.md` plus the one live unit, never the
closed ones.

Without a vault, write to `docs/design/` and skip the mirroring — the lane works standalone.

## Token economy

The lane is expensive by construction, so make the controls visible:

- Triage honestly. Most units are mechanical, and mechanical units cost a signature.
- One unit per session where practical; `checkpoint` and compact at unit boundaries — they are
  safe states by definition (see swarm-orchestrate).
- Report units remaining at every close, so the user can stop, downgrade the remaining triage,
  or switch lanes with real information.

## Exit gate

- Every Must-priority FR maps to ≥1 unit (traceability table in `overview.md`).
- Every unit closed, or deferred with a stated reason.
- Every algorithmic unit has a test-vector table.
- **The handoff test:** swarm-implement can write tickets from these units without asking
  *how* — only *in what order*. If it can't, the lane didn't pay for itself; name the units
  that fail and finish them.

Then flow-state → `phase: design-ui` (if the SRS declares an interface) or `phase: tickets`.
Record `design-lane: deep` so a cold session resumes here.

---
*Influences: humanlayer's 12-factor-agents (Apache-2.0) — factors 3, 6, 7, 8, 10, 12, applied to
the design session rather than a runtime agent. See CREDITS.md.*