/swarm-flow

name: swarm-flow
description: The SDLC router — figures out where a project stands and runs the right phase. Use at the START of any work in a SwarmVault project: continuing/resuming a project, starting a new one, "what's next", or before writing any feature code, spec, design, or ticket. Also use when unsure which phase (requirements, design, implementation, review) comes next. Resume-from-anywhere on any platform.

swarm-flow — the SDLC router

Thin by design: this skill decides *which* phase runs; all expertise lives in the phase skills. Load the chosen skill before proceeding.

**Read this before working, not after.** In a SwarmVault-registered project this skill is the entry point for *any* substantive request — including ones that sound like a direct order ("add login", "fix the schema", "build the dashboard"). Route first, then work: two tool calls of routing prevent building the wrong thing, code with no ticket, or two agents editing the same file. If you are about to write feature code and cannot name the ticket it belongs to, you skipped this step — come back and route.

**Deciding you can skip the flow is itself a flow decision.** For genuinely trivial or one-off asks (a typo, a question about existing code, a shell one-liner) say so in one clause and proceed — but say it, so the user can disagree. Never skip silently.

**The resume promise:** routing needs ONLY vault state — flow-state, ticket statuses, the question queue, memory. "Continue project X" works from a cold session; never ask the user what happened last time, and never require a previous transcript. A session that died mid-work still lands correctly: stale claims surface via TTL, half-done phases surface via their artifacts.

Route

1. Resolve the project (`swarmvault.py context .`; `doctor` if that fails). 2. Read `30 Plans/<P>/flow-state.md` — but **artifacts on disk win** over stale state; correct the note with a logged line if they disagree. 3. Decide by the first matching row:

| Observed state | Phase → skill | |---|---| | No SRS, no specs | requirements → **swarm-spec** | | SRS/specs `draft` or `mined-draft` | validation pass → **swarm-spec** | | SRS validated; no design doc | design → offer the **lane choice** below (+ **swarm-design-ui** if the SRS declares any user interface) | | Designs validated; no tickets | ticket planning → **swarm-implement** | | Open/claimed tickets | work the next unblocked ticket → **swarm-implement** | | Milestone's tickets all done, no sweep report | milestone gate → **swarm-review** | | Sweep findings open | fix tickets → **swarm-implement** | | All milestones done | maintenance: bugs → **swarm-debug**; new asks → **swarm-spec** (change mgmt) | | Any request whose deliverable is end-user-facing text | **swarm-write** (README, marketing, posts, UI copy, release notes) | | User wants SwarmVault out of this project | offboarding → **swarm-eject** |

4. Announce phase + evidence in one line ("SRS validated, 3 open tickets in M2 → implementing"), then proceed.

Design lanes (recorded in flow-state as `design-lane: standard|deep`)

Asked once, when the design phase opens; the answer routes the whole phase. If it is already recorded, don't re-ask — resume that lane.

• **standard** *(default, recommended)* — **swarm-design**. The agent proposes the

architecture, the user validates it. Right for most projects.

• **deep** — **swarm-design-deep**. Developer-driven: the user commits to each approach before

anything is written, down to pseudocode, algorithms and test vectors. Slower and more expensive on purpose. Offer it when the user says they want to own or fully understand the system, asks for pseudocode/algorithm-level planning, or names "developer mode".

They replace each other — never run both. Switching lanes mid-phase keeps closed work.

Modes (recorded in flow-state as `mode: gated|auto`)

• **gated** — stop at every phase/milestone boundary for the user's stakeholder

verification before continuing.

• **auto** — chain phases without stopping; the swarm-review sweep is the milestone gate;

append non-blocking questions to the question queue; stop only when truly blocked (credentials, contradictory requirements, destructive/irreversible actions).

The mode is asked once at SRS validation (swarm-spec) and the user may change it anytime.

Classify the ask before routing a change

Once an SRS is validated, a request is one of six things, and misreading it is how specs rot. The test: **does any accepted criterion of an existing FR change?**

| the ask | classification | goes to | |---|---|---| | already answered by the SRS | **clarification** | answer, change nothing | | an existing FR's criterion changes | **amendment** | swarm-spec | | new criterion inside an existing FR's story | **extension** | swarm-spec | | a new user goal | **new requirement** | swarm-spec (allocate FR-XX) | | behavior contradicts an accepted criterion | **defect** | swarm-debug — *never* edit the spec to match the bug | | an FR goes away | **withdrawal** | swarm-spec (`status: withdrawn`, ID never reused) |

The label isn't the deliverable; the **impact set** is — which FRs, ADRs, open tickets, and tests this touches. State the read in one line before acting ("amendment to FR-11, impacts ADR-004 and 2 open tickets"). In gated mode, wait for a nod on *new requirement* and *withdrawal* only. Log it as a `CR-NNN` entry in the requirements tracker either way.

Rules

• **Scheduled continuation:** if context shows a `⏳ Scheduled continuation` (or

`plan-continue show` returns one), you were resumed to push a usage-limited project forward — just route to the current phase and continue. When all milestones are done (or the plan's `--scope` is reached), clear it: `plan-continue clear --project <P>`. See swarm-orchestrate for scheduling one.

• **Safe-state compaction:** on a long task, at a resumable boundary you may `checkpoint`

(record a safe-state note), compact