| 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
- Resolve the project (
swarmvault.py context .; doctor if that fails).
- 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.
- 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 |
- 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/clear context to save tokens, and continue — the vault is
your state. Quality first: never compact mid-work if continuity is carrying the task. Details
in swarm-orchestrate.
- Never silently skip a user-validated gate; user-requested phase jumps are allowed with
a one-line warning about what's being skipped.
- On phase completion, the finishing skill updates flow-state
(
phase:, mode:, description: compact status); offer — don't force — the next phase
in gated mode.
- Monorepos: the nearest
.swarmvault marker wins.
flow-state format:
---
name: flow-state
description: "phase: implement — M2, 3/9 tickets open, next TK-014"
project: MyApp
type: plan
phase: implement
mode: auto
---
Influences: Pocock's ask-matt (routing stance) — see CREDITS.md.
