Flows — how the pieces chain together
The big picture: For the whole loop on one page, with what to type at each step, start with The lifecycle. Every skill and gate has its own page. This page shows the order they run in across a project’s life, one small top-to-bottom diagram per flow.
Why it matters: The ordering is the harness. Seeing it at a glance tells you which step comes next, and which step is a one-time gate rather than a loop.
How to read it: Click any command or agent in a diagram to open its entry in the command or agent reference. Each diagram has a plain-text list under it, because diagrams need JavaScript to draw.
1. Creation flows
Section titled “1. Creation flows”Project creation
Section titled “Project creation”Start here: Turn the template into a project, then load your spec into the tracker.
flowchart TB T["Template"] --> K["/kickoff"] K --> D["/import-design (optional)"] D --> SI["/spec new"] SI --> S["/spec import"] S --> I["Issues in the tracker"] click K "/reference/commands/" click D "/reference/commands/#import-design" click SI "/reference/commands/#spec-" click S "/reference/commands/#spec-"
- Copy the template (Start a project).
/kickoffasks for the name, personas, stack, license, code owners, security contact, CI and first milestone in batched rounds, then previews the seed issues./import-design(optional) turns a design guide into.claude/rules/frontend.md./spec newwrites your spec (or/spec <path>audits one) until the completeness gate passes./spec importrefuses a spec the gate has not passed, then turns it into tracker issues and writesIssue: #Nback into the spec. Later,/spec revisemakes the next version and a re-import updates the issues you confirm.
Issue creation
Section titled “Issue creation”Search first, file second, label only by asking. Commitment is a plain
committed / uncommitted label the user picks every time. Projects that run dated
milestones add exactly one release:: label per issue instead (the opt-in variant,
described in docs/harness/milestone-commitment.md).
flowchart TB Q["Duplicate search"] --> F["File the issue"] F --> L["committed / uncommitted label (ask, never infer)"] L --> H["/tracker-hygiene"] click H "/reference/commands/#tracker-hygiene"
glab issue list --search "<key terms>" --allfor duplicates and partial overlaps.- File the issue.
- Ask whether it is
committedoruncommitted. In a dated-milestone project, ask whichrelease::label applies instead. /tracker-hygienesweeps later for label, duplicate, and staleness drift.
More in Issues and the tracker.
2. New milestone flow
Section titled “2. New milestone flow”Plan once, before any code. /dotplanning runs once per milestone, not once per
feature.
flowchart TB R["Release cut"] --> P["/dotplanning"] P --> F["File 🔴 findings as issues"] F --> C["committed / uncommitted"] C --> B["Development begins"] click P "/reference/commands/"
- A release is cut.
/dotplanningresolves the scope, builds the feature-to-asset map, flags missing assets and open questions, sequences workstreams, records the plan on aPlan: <v>issue (ships in 0.8), and writes an HTML report.- File every 🔴 finding as an issue.
- Label each issue
committedoruncommitted. A project with dated milestones usesrelease::committed,release::reserve, orrelease::stretchinstead. - Development begins.
3. Working in the early stage (pre-1.0, simple variant)
Section titled “3. Working in the early stage (pre-1.0, simple variant)”One wave, one worktree per issue. /wave fans a wave of issues out to delegated
agents; /mass-merge lands the green MRs.
Delegate and build:
flowchart TB B["/wave"] --> W["isolated worktree + one pinned worker per issue"] W --> R["Fast-path gate row"] R --> G["Pre-MR gate batch (parallel)"] click B "/reference/commands/"
Gate, open, and fix:
flowchart TB CC["completeness-check"] --> CL["changelog-check"] CL --> MR["Open the MR"] MR --> FX["/fix-mr if red"] click CC "/reference/agents/#completeness-check" click CL "/reference/agents/#changelog" click FX "/reference/commands/"
Land the wave:
flowchart TB
MM["/mass-merge"]
subgraph LOOP["Per MR"]
direction TB
MG["Merge"] --> RM["scripts/wt remove issue"]
end
MM --> LOOP
LOOP --> PR["scripts/wt prune (after the loop)"]
click MM "/reference/commands/"
/wavespawns one pinnedwave-workeragent per issue. Claude Code gives each one an isolated worktree under.claude/worktrees/, and the worker runsscripts/wt adoptthere. A/wave --harnessrun, for issues that change the harness, uses ascripts/wt newworktree and an unpinned agent instead (ADR 0010).- Each agent runs only the gates in its change class’s fast-path row.
- The pre-MR gates (
regression-check,security-review,rbac-check,perf-check) run as one parallel batch. completeness-checkruns andchangelog-check(a script,make check-changelog) passes, then the MR opens./fix-mrgets a red MR to green./mass-mergelands the green wave. It runsscripts/wt remove <issue>after each MR merges, so a run that stops partway still cleans up what it landed.- A final
scripts/wt prunecatches anything the per-MR removals missed.
More in Parallel work and the development workflow.
4. Using /wave for a single issue
Section titled “4. Using /wave for a single issue”Use /wave even for a wave of one. It picks the model for the job. The full walkthrough is
Start work with /wave.
Why it matters:
- Sonnet by default. In measured waves, Opus subagents were most of the bill, and most issues do not need it.
- Opus only on a named criterion: the root cause is unknown (not met when the issue names the candidate mechanisms), the fix spans three or more packages, it changes core domain semantics, or it needs a design judgment the issue does not settle.
- Fable only as a rescue (ships in 0.8): after an escalated Opus agent has failed on the
same issue, and only when you answer
/wave’s question to run it. Never a default. - Read-only gates run on Sonnet.
/wavepassesmodel: "sonnet"when it spawns them, which overrides the Opus default insecurity-review.rbac-checkruns on Opus as a measured trial, andcompleteness-checkruns once per branch on Opus or Sonnet by risk tier (see its agent page). - Model and effort are always explicit.
/wavenames both on every agent it spawns and shows them in its report, so you can see what each issue actually ran on. - By hand, you get whatever the main session runs on, often Opus, and every gate shares that one expensive context.
Through /wave:
flowchart TB
I["One issue"] --> B["/wave"]
B --> C{"Escalation criterion?"}
C -- no --> S["Sonnet agent"]
C -- yes --> O["Opus agent"]
click B "/reference/commands/"
By hand:
flowchart TB I["One issue"] --> M["Main session (often Opus)"] M --> G["Every gate in the same context"]
See /wave for the full model-choice rules.
5. Flows leading up to /release
Section titled “5. Flows leading up to /release”Audit once, cut, tag by hand, then close the loop. Each step below is a one-time gate, not a loop.
Before the cut:
flowchart TB FF["Feature freeze"] --> PR["/pre-release full"] PR --> FX["Fix 🔴, triage 🟡 into issues"] FX --> WB["Write each finding's class back into its gate (own MR)"] WB --> ST["uncommitted work moves to next milestone (dated milestones: release::stretch)"] ST --> RL["/release"] click PR "/reference/commands/#pre-release" click RL "/reference/commands/"
After the cut:
flowchart TB T["Manual tag + glab release create"] --> PM["main to production MR (full GitLab Flow)"] PM --> VA["/voc-audit --calibrate"] VA --> DP["/dotplanning (next milestone)"] click VA "/reference/commands/" click DP "/reference/commands/"
- At feature freeze, run
/pre-release fullonce. - Fix 🔴 findings (each is also filed as an issue, and a
fullrun posts a summary comment on thePlan: <v>issue; ships in 0.8); triage 🟡 into milestone issues. - Write each 🔴 and 🟡 finding’s class back into the day-to-day gate that should have caught it:
/pre-release fullproposes the rules, records the approved and declined ones on one write-back issue, and they land in their own MR (a kaizen issue when no gate fits; ships in 0.8). This never triggers a re-run. - Re-run only if the fixes were substantial.
uncommittedissues move to the next milestone without discussion. (In a dated-milestone project, those are therelease::stretchissues.)/releasecuts the release branch and MR.- Tag and run
glab release createby hand. - On the full variant, open the
maintoproductionMR. - Once real users report, run
/voc-audit --calibrate. - Run
/dotplanningfor the next milestone. That closes the loop back to flow 2.
More in Release workflow.
6. Feature design sequence
Section titled “6. Feature design sequence”Design before code, in this order. threat-model runs only when the feature crosses
a trust boundary.
flowchart TB V["/voc"] --> TM["threat-model (trust boundary only)"] TM --> A["architect"] A --> U["ux-design"] click V "/reference/commands/#voc" click TM "/reference/agents/#threat-model" click A "/reference/agents/#architect" click U "/reference/agents/#ux-design"
After design:
flowchart TB IM["Implement"] --> UXR["ux-review"] UXR --> ACC["accessibility"] click UXR "/reference/agents/#ux-review" click ACC "/reference/agents/#accessibility"
/vocsurfaces adoption blockers before design.threat-model, only if the feature crosses a trust boundary.architect, given the VoC and threat-model output.ux-design, given the architect review.- Implement.
ux-reviewandaccessibilitycheck the result.
7. Anatomy of a command
Section titled “7. Anatomy of a command”Each command is a box; what it runs sits inside. One small diagram per command.
flowchart TB
subgraph WAVE["/wave"]
direction TB
A["Ask: milestone, labels"] --> RES["Resume: classify leftover claims<br/>and worktrees (wave-resume.py)"]
RES --> SEL["Select issues"]
SEL --> PRE["Pre-flight: open, done on main,<br/>or remaining (wave-preflight.py)"]
PRE -->|"open only"| WT["scripts/wt new"]
subgraph AG["Delegated agent per issue"]
direction TB
IMP["Implement"] --> PP["make pre-push-checks"]
end
WT --> AG
AG --> CC["completeness-check"]
CC --> PU["Push, open MR"]
end
click CC "/reference/agents/#completeness-check"
- Ask which milestone and labels.
- Classify leftover claims and worktrees you hold (
wave-resume.py) and offer resume, hand back or release for each. An open green MR is never re-spawned, and a worktree whose agent is live or unknown is only handed back. - Select independent issues.
- Create one
scripts/wtworktree per issue. - Each delegated agent implements and runs
make pre-push-checks, then stops. completeness-checkaudits, then the branch is pushed and the MR opened.
/mass-merge
Section titled “/mass-merge”flowchart TB
subgraph MASS["/mass-merge"]
direction TB
PF["Pre-flight"] --> SIM["Phase A: simulate"]
subgraph LAND["Phase B: per MR"]
direction TB
RB["Rebase"] --> PL["Pipeline green"] --> MG["Merge"] --> RM["scripts/wt remove"]
end
SIM --> LAND
LAND --> PRN["scripts/wt prune"]
end
- Pre-flight, then Phase A simulates the merge train.
- Phase B, per MR: rebase, wait for a green pipeline, merge, then
scripts/wt remove. - After the loop,
scripts/wt prunecatches anything missed.
/release
Section titled “/release”flowchart TB
subgraph REL["/release"]
direction TB
VER["Version"] --> PRE["Pre-flight"]
subgraph SCR["scripts/release.sh"]
direction TB
NT["Confirm notes"] --> BR["Release branch"]
end
PRE --> SCR
SCR --> MRG["MR to main"]
end
- Confirm the version, then run the pre-flight checks.
scripts/release.shshows the notes for your approval, then creates the release branch.- Open the MR to
main.
/dotplanning
Section titled “/dotplanning”flowchart TB
subgraph DP["/dotplanning"]
direction TB
MS["Resolve milestone"] --> IN["Gather inputs"]
IN --> MAP["Feature-to-asset map"]
subgraph LED["commitment ledger"]
direction TB
PROP["Propose"] --> CONF["Confirm"]
end
MAP --> LED
LED --> RPT["Plan issue + HTML report"]
end
- Resolve the milestone and gather inputs.
- Build the feature-to-asset map.
- Propose and confirm the commitment ledger (
committed/uncommitted, orrelease::values in a dated-milestone project). - Record the plan on the
Plan: <v>issue (ships in 0.8) and emit the HTML report.
flowchart TB
subgraph MRC["/mr"]
direction TB
PF["Pre-flight"] --> DESC["Description"]
subgraph SEC["Description sections"]
direction TB
REQ["Requirements"] --> GT["Gates"]
end
DESC --> SEC
SEC --> CR["glab mr create, then stop"]
end
- Pre-flight checks, then write the description.
- The description carries Requirements and Gates sections.
glab mr create, then stop. Never merge.
Mermaid draws click links only at the “loose” security level, which this site enables because every diagram is authored in this repository. Command links go to the commands page rather than a heading anchor, so renaming a heading cannot break them.
Read the real steps in each skill’s SKILL.md under .claude/skills/; these diagrams
show the shape, not every rule.