Skip to content

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.

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-"
  1. Copy the template (Start a project).
  2. /kickoff asks for the name, personas, stack, license, code owners, security contact, CI and first milestone in batched rounds, then previews the seed issues.
  3. /import-design (optional) turns a design guide into .claude/rules/frontend.md.
  4. /spec new writes your spec (or /spec <path> audits one) until the completeness gate passes.
  5. /spec import refuses a spec the gate has not passed, then turns it into tracker issues and writes Issue: #N back into the spec. Later, /spec revise makes the next version and a re-import updates the issues you confirm.

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"
  1. glab issue list --search "<key terms>" --all for duplicates and partial overlaps.
  2. File the issue.
  3. Ask whether it is committed or uncommitted. In a dated-milestone project, ask which release:: label applies instead.
  4. /tracker-hygiene sweeps later for label, duplicate, and staleness drift.

More in Issues and the tracker.

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/"
  1. A release is cut.
  2. /dotplanning resolves the scope, builds the feature-to-asset map, flags missing assets and open questions, sequences workstreams, records the plan on a Plan: <v> issue (ships in 0.8), and writes an HTML report.
  3. File every 🔴 finding as an issue.
  4. Label each issue committed or uncommitted. A project with dated milestones uses release::committed, release::reserve, or release::stretch instead.
  5. 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/"
  1. /wave spawns one pinned wave-worker agent per issue. Claude Code gives each one an isolated worktree under .claude/worktrees/, and the worker runs scripts/wt adopt there. A /wave --harness run, for issues that change the harness, uses a scripts/wt new worktree and an unpinned agent instead (ADR 0010).
  2. Each agent runs only the gates in its change class’s fast-path row.
  3. The pre-MR gates (regression-check, security-review, rbac-check, perf-check) run as one parallel batch.
  4. completeness-check runs and changelog-check (a script, make check-changelog) passes, then the MR opens.
  5. /fix-mr gets a red MR to green.
  6. /mass-merge lands the green wave. It runs scripts/wt remove <issue> after each MR merges, so a run that stops partway still cleans up what it landed.
  7. A final scripts/wt prune catches anything the per-MR removals missed.

More in Parallel work and the development workflow.

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. /wave passes model: "sonnet" when it spawns them, which overrides the Opus default in security-review. rbac-check runs on Opus as a measured trial, and completeness-check runs once per branch on Opus or Sonnet by risk tier (see its agent page).
  • Model and effort are always explicit. /wave names 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.

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/"
  1. At feature freeze, run /pre-release full once.
  2. Fix 🔴 findings (each is also filed as an issue, and a full run posts a summary comment on the Plan: <v> issue; ships in 0.8); triage 🟡 into milestone issues.
  3. Write each 🔴 and 🟡 finding’s class back into the day-to-day gate that should have caught it: /pre-release full proposes 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.
  4. Re-run only if the fixes were substantial.
  5. uncommitted issues move to the next milestone without discussion. (In a dated-milestone project, those are the release::stretch issues.)
  6. /release cuts the release branch and MR.
  7. Tag and run glab release create by hand.
  8. On the full variant, open the main to production MR.
  9. Once real users report, run /voc-audit --calibrate.
  10. Run /dotplanning for the next milestone. That closes the loop back to flow 2.

More in Release workflow.

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"
  1. /voc surfaces adoption blockers before design.
  2. threat-model, only if the feature crosses a trust boundary.
  3. architect, given the VoC and threat-model output.
  4. ux-design, given the architect review.
  5. Implement.
  6. ux-review and accessibility check the result.

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"
  1. Ask which milestone and labels.
  2. 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.
  3. Select independent issues.
  4. Create one scripts/wt worktree per issue.
  5. Each delegated agent implements and runs make pre-push-checks, then stops.
  6. completeness-check audits, then the branch is pushed and the MR opened.
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
  1. Pre-flight, then Phase A simulates the merge train.
  2. Phase B, per MR: rebase, wait for a green pipeline, merge, then scripts/wt remove.
  3. After the loop, scripts/wt prune catches anything missed.
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
  1. Confirm the version, then run the pre-flight checks.
  2. scripts/release.sh shows the notes for your approval, then creates the release branch.
  3. Open the MR to main.
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
  1. Resolve the milestone and gather inputs.
  2. Build the feature-to-asset map.
  3. Propose and confirm the commitment ledger (committed / uncommitted, or release:: values in a dated-milestone project).
  4. 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
  1. Pre-flight checks, then write the description.
  2. The description carries Requirements and Gates sections.
  3. 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.