How the workflow works

The big picture

The harness is built from top-level commands and a set of role-based agents. Commands are orchestrators: they don't write code themselves; they bring agents onto a team, brief them, route messages, and — in execution — launch a background unit-cycle Workflow per unit of work against GitHub-issue state, backed by a pure-shell discovery script that decides what's eligible each pass. The unified execution command is /ship, driven by ship-finder.sh (five stages: reconcile · analyze-bug · kickoff · fix-pr · close-pr). It spans all three kinds of work and routes kickoff by kind: — kind:feature / kind:enhancement launch implement-slice.mjs, kind:bug launches fix-bug.mjs. (/implement-feature + task-finder.sh remain as a feature-only fallback with four stages.) Durable state lives in three places: the GitHub issue and its labels, the issue body's task checklist (or, for a bug, its approved analysis comment), and the unit branch's commits — which means the loop can be stopped, resumed, or re-run without losing track of where work is.

                ┌──────────────────────────────────────────────────────────┐
                │                       USER (you)                        │
                └──┬────────────────────┬──────────────────────────────┬──┘
                   │ /deep-dive-feature │ /scaffold-project            │ /ship [milestone]
                   ▼                    ▼                              ▼
            ┌────────────┐         ┌────────────┐                ┌──────────────┐
            │ product-   │         │ scaffold-  │                │ orchestrator │
            │  owner →   │         │  project   │                │ (ship-finder │
            │ design-    │         │ (templates │                │  .sh · 5     │
            │  lead →    │         │ + seeds    │                │  stages)     │
            │ architect  │         │  locked    │                └──────┬───────┘
            │ + writers  │         │  tokens)   │            kickoff routes by kind:
            └─────┬──────┘         └─────┬──────┘                       ▼
                  │                      │            ┌───────────────────────────────────┐
                  ▼                      ▼            │ feature / enhancement → implement-  │
       PRD + design system + ADRs   bootable stack   │   slice.mjs (author E2E → cov gate  │
       + surfaces + contracts       + tokens         │   → implement → pass E2E → review)  │
       (committed on feature        (compose up;     │ bug → fix-bug.mjs (regression test  │
        branch; PR opened)           PR opened)      │   first → fix → review)             │
                                                     └─────────────────┬───────────────────┘
                                                                       ▼
                                                       draft PR → fix-pr / close-pr
                                                       (the outer loop's other stages)

       (bug lane adds an up-front  analyze-bug  stage: read-only reproduce + root-cause
        → # Bug Analysis comment → human approves → kickoff launches fix-bug.mjs)

What changed: 0.39 → 0.40

Everything in discovery (/deep-dive-feature, /scaffold-project) is unchanged. The whole shift is in execution. Through 0.39, /implement-feature was a nine-stage state machine: each step of a slice's life — implement a task, review it, fix it, validate E2E, review the slice, fix the slice — was its own label-driven stage that dispatched a one-shot agent and then ended the pass, handing control back to GitHub labels until the next pass re-discovered the work. In 0.40 that entire inner cycle collapses into one background implement-slice Workflow per slice, and the outer command keeps only the four stages that genuinely need to live outside a single run.

The differences that matter

What did not change: labels are still the cross-pass protocol for the durable state that remains; every state transition is still recoverable from GitHub + git; the orchestrator still never writes code or diagnoses failures (detect-and-dispatch); and /loop /implement-feature <feature-name> is still the way to ship a feature unattended.

Discovery vs. execution

There are two distinct phases, and they don't share state in memory — they share state through git and GitHub. Discovery produces documents; execution consumes those documents and produces code.

The agents

Role-based subagents under agents/. Each one is briefed by a command, a workflow, or a workflow skill — never by the user directly. Roles are sharp on purpose: product-owner never writes architecture; design-lead never writes code; engineer never writes E2E specs; reviewer is read-only on production code. In execution the agents are no longer dispatched by the /ship orchestrator directly — they are dispatched by the unit-cycle Workflow (implement-slice.mjs / fix-bug.mjs). The two exceptions the outer loop still owns are the read-only analyze-bug engineer (pre-approval) and the fix-pr engineer (an external-wait stage).

Discovery — /deep-dive-feature

Three sequential phases (product → design → architecture). The orchestrator grows the team one teammate at a time: it does not pre-create writers until the interviewer they answer is ready to hand off a dispatch payload.

Scaffold — /scaffold-project

Optional, runs once on a greenfield project (the skill aborts if any of backend/, frontend/, a compose file, or e2e/ already exists). Reads stack and topology decisions from docs/architecture-decision-record/ and materializes a bootable skeleton from templates. Ends in its own PR.

1. Confirm greenfield — all four surfaces (backend, frontend, compose, e2e) must be missing.
2. Read the ADRs to pick backend / frontend stack variants and the compose service list; assert the ADR-published docs/stack.yaml manifest exists (the adr writer publishes it at lock-in — scaffold distills it only as a fallback for older lock-ins). A declared stack without a template takes the skeleton path (layout + manifests + ci-checks.sh pinned; framework entry owned by the first engineer slice).
3. Create chore/scaffold-project.
4. Materialize backend → commit. Materialize frontend → commit. Materialize docker-compose.yaml → commit.
5. Boot check: docker compose up -d --build, probe each framework-metadata endpoint, then docker compose down. Stops on failure — does not mutate templates to mask a broken boot.
6. Materialize Playwright e2e → npm install → commit.
7. Materialize the CI pipeline + CI-parity pre-push hook + gitleaks pre-commit hook → commit.
8. Assert the design system exists: docs/design-system/tokens.md and surfaces.md must be present (locked upstream by design-lead during /deep-dive-feature). Fails loudly if absent — scaffold consumes the design system, it does not generate it.
9. Translate the locked tokens.md into frontend/src/styles/tokens.css and import it from the frontend entry → commit. (The ## Design taste section of CLAUDE.md is already authored by design-writer — scaffold doesn't re-write it.)
10. Push and open the PR.

Execution — /ship [milestone]

One sweep through the outer stages, in order. The orchestrator runs skills/operation-git/scripts/ship-finder.sh [milestone] once — pure shell, no LLM — to discover every eligible candidate against ONE GitHub-state snapshot, then walks the report top-to-bottom. /ship has five stages — reconcile → analyze-bug → kickoff → fix-pr → close-pr — spanning all three kinds. Milestone is optional: pass one to scope to a feature, omit it for the repo-wide maintenance lane (all open bugs + one-off enhancements). Each stage is self-skipping (its report section reads - (none) when there's nothing to do). One invocation = one pass — wrap with /loop /ship [milestone] to keep advancing until the work ships.

/implement-feature <feature-name> is the feature-only fallback: the same flow minus the analyze-bug stage (four stages, always milestone-scoped), driven by task-finder.sh.

The command's whole job is: reconcile dead-run locks, dispatch the read-only analyze-bug engineer for freshly-filed bugs (→ # Bug Analysis comment → human approval gate), launch a unit's Workflow at kickoff (routed by kind: — implement-slice.mjs for feature/enhancement, fix-bug.mjs for bug), and shepherd the resulting PR. The inner unit cycle — author E2E, coverage gate, implement, pass E2E, review, fix (or, for a bug, regression-test-first → fix → review) — is never the command's concern; it runs entirely inside the Workflow that kickoff launches (next section). The orchestrator never waits for backgrounded work within a pass: once it launches a workflow or dispatches an engineer, it ends the pass; a finished run re-invokes it (event-driven) and the next pass picks up what moved.

The four outer stages

Stage numbers are non-contiguous (0, 1, 8, 9) on purpose — they preserve the identity of the surviving stages from the old nine-stage scheme. Stages 2–7 (implement-task, review-task, fix-task, prepare-slice, review-slice, fix-slice) were retired: their work now lives inside the slice workflow.

Keep advancing

The slice runs as a workflow

The heart of v0.40. The slice lifecycle is exactly two workflow layers (Workflow nesting is one level deep — a child calling workflow() throws). A workflow script spawns every agent() as a peer in one flat pool, expressing fan-out the two-level Agent tree can't. Both scripts ship with the plugin under workflows/ and are invoked by scriptPath against ${CLAUDE_PLUGIN_ROOT}.

/loop /implement-feature <feature>        (outer driver: reconcile / kickoff / fix-pr / close-pr)
  └─ Stage 1 LAUNCHES (background, one per slice):
       implement-slice.mjs                ← TOP: owns author → implement → review → fix → PR
          ├─ agent()  e2e-author / engineer          (generative, serial — shared worktree)
          └─ runReviewSlice(…)  ← inlined fan-out: coverage gate + gate review + quality review (one axis-reviewer agent per pattern)
                └─ agent() ×N             (one per pattern-reviewer dimension + adversarial verify)

The split rule: assessment work that is parallel-decomposable → a fan-out child workflow; generative work that is sequential → a single agent. Only the reviewer stages qualify as workflows — the author / implement / pass-E2E / fix stages are TDD chains on one shared slice worktree, so they can't parallelize and stay single agent() dispatches.

implement-slice.mjs — the per-slice cycle (TOP)

One background run per slice. It owns the entire inner cycle that the old nine-stage /implement-feature used to round-trip through GitHub labels. GitHub keeps only durable, human-relevant state: the slice issue, the status:in-progress lock (held for the whole run), the status:need-attention halt, and the final draft PR. Task tracking lives in the slice body's ## Tasks static-ID checklist — Prep parses it, and each dispatched agent ticks its boxes as it finishes.

Gating fix loops are uncapped — coverage gate, implement re-dispatch, and the gate review each loop until they reach confidence to pass (review APPROVE, or every task ticked [x]). The quality review is the exception — bounded to one fix cycle + one re-review, never a loop (code quality never blocks, so its residual is triaged into tracking issues rather than chased to zero). Re-review rounds are anchored: each gets the prior round's findings + the exact sha that round judged, closure-checks them (same title/file, no upward re-grade of unchanged code), and hunts new findings only in the code changed since — convergence instead of an independent re-sample of the whole diff per round. A gating I:M is always classed Fix (never Defer) and the fix dispatch inlines the Fix-class findings, so a skipped gating MEDIUM can't flap into a later-round blocker. The fan-out's full adversarial verify is opt-in (verifyLenses arg, default OFF) — when on, only a finding that survives refutation holds a gate open; when off the dimension reviewer's own severity stands for non-blocking findings, but each newly-reported verdict-driving blocker still faces an always-on 2-lens (correctness + context) floor — neutralised only when both lenses refute it on concrete evidence (coverage gap dropped; gate blocker downgraded to MEDIUM, still fixed via the gating-I:M→Fix class). Either way the gate review blocks only on a gating-dimension I:H — spec-compliance, contract, or security — while code-quality findings are deferred debt handled by the separate quality review and never block the slice. halt() flips status:in-progress → status:need-attention and posts a comment — the only path to a human; the outer loop never recovers it. Two progress guards bound the uncapped loops: the oscillation stall (the same blocker surviving its own targeted fix for 3 consecutive rounds) and the churn guard (3 consecutive rounds each surfacing a new blocker on code unchanged since the prior round — reviewer noise, not defects). Resume is the slice branch's WIP commits (each carrying Task: <id> + Refs #<slice>) + the durable checklist + the Workflow resume journal — plus the verdict comments for review passage: every gate/review comment is stamped with the reviewed branch-tip SHA (**Reviewed tip:**) and an invisible <!-- resume-state --> marker carrying the loop-guard streaks. Each looping review (coverage gate, gate review) runs a one-shot read-only reviewEntryAction probe before its first review (the gate review's probe is hoisted to the Pass E2E phase): a durable coverage-gate APPROVE skips the gate; a gate APPROVE still at the remote tip skips Pass E2E + Gate review (straight to the idempotent AC-tick + PR, and the quality pass too when its comment already exists at that tip); a standing BLOCK verdict that nothing landed against — no commit and no fix-summary comment after it — returns fix-first, dispatching the fix straight away instead of re-running the fan-out only to reproduce the same BLOCK (a fix that did land, even partially, falls through to review, which catches the rest); and any BLOCK re-seeds the oscillation + churn streaks from its resume-state marker instead of resetting them. There are no handoff docs.

runReviewSlice() — inlined fan-out review

A function inside implement-slice.mjs (was a separate review-slice.mjs child workflow before this change), called for the pre-implementation coverage gate (scope:'test-coverage') and the two post-implementation review stages (scope:'production-code', switched by reviewMode: 'gate' runs the gating dimensions, 'quality' runs the code-quality axes). It isolates each review dimension onto its own axis-reviewer agent and — only when the verifyLenses arg is on (default OFF) — adversarially verifies every finding before it can block: verification batches same-dimension findings (≤10 per agent) through three independent skeptic lenses, so dispatch scales with dimensions × chunks rather than one agent per finding while the cross-lens majority vote stays intact. With verify off (the default) findings are trusted as the reviewer graded them and this pass is skipped — it is itself a self-review, so it is opt-in.

The new boundary (changed in 0.40): it posts the verdict comment and RETURNS the verdict object — it flips no label and opens no PR. The parent implement-slice owns the lock and the terminal draft PR. Previously, when the outer /loop called it directly at Stage 6, it flipped review:running → review:passed/need-fix and opened the PR itself; that boundary moved up into the parent.

 gate mode    : Prep ─► Gating dims (fan-out) ──── dedup ─ verify ─► compose ─► Publish   (BLOCK on gating I:H)
 quality mode : Prep ─► Quality dims (fan-out) ─── dedup ─ verify ─► compose ─► Publish   (ADVISORY, never blocks)
(worktree/diff)  gate: ≤3 gating pattern-reviewer-* dims · quality: the debt dims the touched surfaces select (incl. per-language lenses)
                 each fan-out + 3-lens refutation (opt-in)                                 (code)    (1 agent)

Each pass fans out, dedups, then verifies before composing — so the verdict decides on a confirmed finding, never a raw one. Dedup and scoring (severity → Impact, (Impact, Effort) → Fix/Defer/Nit/Drop, gate verdict = BLOCK iff a gating-dimension (spec/contract/security) I:H survives; quality verdict = always ADVISORY — every code-quality finding is deferred debt) are plain deterministic JS, not LLM steps. Each dimension agent reads exactly one pattern-reviewer-* skill and applies that skill's per-project .claude/memory/patterns/<skill>.md overlay — so dreamed rules reach the fan-out the same way they reach the single-agent fallback.

Scope coverage runs only the Spec-phase test-coverage dimension over the authored E2E specs, pre-implementation: the usual "test files are out of scope" rule inverts (the specs are the deliverable), the verdict is BLOCK on any confirmed coverage gap (not just I:H), and Quality is skipped entirely.

Quality review — one fix cycle, one re-review, then debt triage. Because code-quality findings never block, the slice doesn't churn on them: the quality review is a separate, bounded pass that runs only after the gate review APPROVES. It does exactly one review/fix cycle — review the code-quality axes, then a single engineer polish pass over the non-gating (Defer / Nit) findings — plus one final re-review (it is not a loop). Whatever debt remains after that pass is then triaged into tracking issues — one per review dimension, routed by kind: non-functional findings → kind:enhancement (they add observable behavior, so they earn a feature-shaped body with ACs + an e2e task and the full E2E/integration treatment); every other dimension → kind:refactor (behavior-preserving — a no-e2e ## Tasks checklist, so implement-slice skips all E2E machinery and the only new tests are unit tests for extracted seams). Both are created at status:ready-to-review (the human gate) and deduped against open issues of that kind, so the quality debt is recorded for the /ship maintenance lane instead of holding the slice. fix-bug.mjs mirrors the same two-stage split via its own runReview('gate') / runReview('quality') — gate fix loop, then one bounded quality cycle + triage — minus the AC-tick (a bug has no AC ledger; the regression test is its spec-compliance gate).

Two model tiers

The phases split across two models by the kind of work each does — judgment stays on Sonnet, mechanical work drops to Haiku. Tunable in one place via AGENT_MODEL / WRITER_MODEL at the top of the script.

Labels are the protocol

Agents don't share memory. They share GitHub state. The cross-pass protocol is a small set of labels; the within-slice task ledger is the slice body's checklist. That's why the lifecycle survives crashes, context limits, and user interruptions — the next pass just reads the state and re-derives where work is.

v0.40 deleted four whole label families. The inner slice cycle no longer round-trips through labels — it runs inside one workflow — so the labels that drove each inner step are gone: level:* type:* review:* e2e:*. level:* is moot (one issue per slice now), type:* lives in the checklist's per-task type, and review:* / e2e:* became in-memory state inside the workflow.

How labels flip

Two of the three lanes below are state machines over GitHub labels (the slice issue and the draft PR). The middle lane is different: the inner cycle that used to be a label machine is now a phase progression inside one workflow run — no labels flip between its phases. Read top to bottom for the happy path; the orange call-outs mark the failure loops. The pill on each arrow is the actor that performs the step.

Two cross-cutting rules emerge from the diagrams. (1) The status:in-progress label is the slice lock — held for the entire workflow run, it hides the slice from the next kickoff pass and is what the reconcile reaper releases when a run dies. (2) The inner cycle no longer flips labels — review verdicts, E2E validation, and fix loops are in-memory phase transitions inside one run; only the four durable transitions (lock, halt, draft PR, merge) touch GitHub.

Who talks to whom

Two distinct channels: a Team-shared channel for the interactive discovery agents (product-owner, design-lead, designer and doc-writer instances, architect) and a workflow dispatch channel for the lifecycle agents (engineer, e2e-author, axis-reviewer agents) — almost all of which are now dispatched by the implement-slice Workflow, not the command directly.

SendMessage handshake — Phase 2 example

            ┌──────────────┐               ┌────────────────────┐
            │    USER      │               │   orchestrator     │
            └──────┬───────┘               │ (/deep-dive)       │
                   │                       └─────────┬──────────┘
                   │   talks directly to             │ invites + briefs
                   │                                 │
                   ▼                                 ▼
            ┌──────────────┐    SendMessage    ┌────────────────┐
            │  architect   │ ◄──── pull ───────│ adr-writer     │
            │  (read-only) │ ─── payload ────► │ (subagent_type │
            │              │                   │  = doc-writer) │
            └──────────────┘                   └────────────────┘
                   ▲                                  │
                   │  also answers:                   │ commits ADRs
                   │  • implement-detail-writer       │ on the feature
                   │  • api-contract-writer           │ branch
                   │  • data-model-writer             │
                   │  • runbook-writer                │

Where the user sits

The user is in the loop in three specific places — and intentionally out of the loop everywhere else.

Everywhere else — task dispatch, code review, security review, fix loops, draft PR creation, merge of merge:auto PRs — the user can step away. The loop reads labels, dispatches one-shot agents, and advances. /loop /implement-feature <feature-name> keeps it going until the feature is shipped or until something hits status:need-attention.