Swarm

---
description: >
  Parallel work decomposition — plan streams, run, review, merge.
  Decomposition only when it clearly helps; single agent is the default.
    /swarm plan    — write the manifest
    /swarm status  — current branch state
    /swarm review  — per-stream peer review
    /swarm merge   — sequential merge with tests between
---

# Swarm

Split a goal into independent streams. Each stream owns its files, runs on
its own branch, and gets its own peer review. Merge one at a time with
build/lint/tests between each.

**Streams describe work, not agents.** One agent runs them sequentially.
Multiple agents take one each. The manifest works either way.

> Follows `rules/integrity.md`. Shared formatting + Visual Emphasis in
> `skills/shared/formatting.md` (use **bold** for key terms, tables for
> manifests, `▎` blockquotes for gates).

---

## When to use

Score the goal first. Single agent is usually enough.

| Signal | Points |
|--------|--------|
| Work spans 2+ independent areas (no shared files) | +3 |
| Each stream can be tested independently | +2 |
| Total scope exceeds ~5 tasks | +1 |
| Work touches shared code both streams need | −3 |
| Total scope is under 3 tasks | −2 |

**Score ≥ 4:** suggest `/swarm`. **< 2:** use the skill chain directly (see `RECIPES.md`).

---

## Output structure — Option A inverted pyramid

`/swarm` follows the **Inverted-Pyramid Output** pattern in
`skills/shared/formatting.md`. Each sub-command (`plan`, `status`, `review`,
`merge`) is its own emission with its own header + receipts + gate.

### Progress block

The progress block shows the whole swarm chain so the user always knows
where they are, regardless of which sub-command they invoked.

```
/swarm ═══════════════════════════════════════════════════════════════════════════════

  ▸ Phase 1  Plan        Manifest + stream ownership
  ○ Phase 2  Implement   Stream execution (parallel or sequential)
  ○ Phase 3  Review      Per-stream peer review
  ○ Phase 4  Merge       Sequential merge with tests between
  ○ Phase 5  Integrate   /review on full diff to base
  ○ Phase 6  Ship        Handoff to /ship

══════════════════════════════════════════════════════════════════════════════════════
```

Marker semantics: `▸` (current) · `✓` (done) · `○` (pending) · `—` (skipped).
Each sub-command re-emits the **full progress block** with its phase marked
`▸` and prior phases marked `✓`.

---

## Execution flow (mandatory)

The progress-block phases are the only valid sequence. Each gate must
complete before the next phase runs.

| From | Gate | Next |
|---|---|---|
| Phase 1 (Plan) | User approves manifest | Phase 2 (Implement) |
| Phase 2 (Implement) | All streams complete | Phase 3 (Review) |
| Phase 3 (Review) | All streams APPROVED | Phase 4 (Merge) |
| Phase 4 (Merge) | Build + lint + tests pass | Phase 5 (Integrate) |
| Phase 5 (Integrate) | `/hashb:review` APPROVED on full diff | Phase 6 (Ship) |
| Phase 6 (Ship) | — | `/hashb:ship` runs |

> **Critical.** After streams finish, you MUST run Phase 3 (`/swarm review`)
> BEFORE Phase 4 (merge). Never merge unreviewed streams. This is a
> blocking gate, not a suggestion.

### Autonomous mode — gate suppression

When `/swarm` is **downstream** (HANDOFF present in conversation context,
`Verbose: true` absent): all three gates are suppressed. `/swarm` runs
autonomously using `Principles:` values from the HANDOFF for decisions.

**Detection:** HANDOFF present AND `Verbose: true` absent → autonomous.
HANDOFF absent OR `Verbose: true` present → interactive (gates shown).

**Principle mapping:**

| Principle | What it controls in `/swarm` |
|-----------|------------------------------|
| P2 Architecture | Manifest structure: minimal → fewest streams; balanced → recommended; ideal → cleanest boundaries |
| P3 Risk | Gate 1 escalation threshold: aggressive → auto-approve unless completeness fails; moderate → auto-approve with /eng context; conservative → escalate to user |
| P4 Tests | Forwarded to stream agents for per-stream TDD depth |

**Safety thresholds (Gate 1 only) — escalate regardless of P3:**
- Manifest has >6 streams
- Completeness rule fails (unowned files detected)
- `graphify` flags hidden cross-stream dependencies not declared in contracts

Gates 2 and 3 are always suppressed in autonomous mode — they are
pause points with no decisions. Their escape hatches (ESCALATE, merge
conflicts) are handled by the existing autonomous flow.

---

## Flow

### Phase 1 · `/swarm plan` — emit, then Gate 1

Phase 1 emits the **full progress block** at the start, then the inverted-
pyramid header (3 `▎` blocks), receipts, and Gate 1 at the bottom.

```
/swarm ═══════════════════════════════════════════════════════════════════════════════

  ▸ Phase 1  Plan        Manifest + stream ownership
  ○ Phase 2  Implement
  ○ Phase 3  Review
  ○ Phase 4  Merge
  ○ Phase 5  Integrate
  ○ Phase 6  Ship

══════════════════════════════════════════════════════════════════════════════════════
```

#### Inputs

If `/eng` ran earlier in the session, use its outputs as input:

- **Scope card** → system name, constraints, scale targets
- **Implementation order** → stream prerequisites and ordering
- **File inventory** (from scope challenge) → stream file ownership
- **ADRs** (if architecture mode was used) → constraints for all streams

If `/eng` did not run, gather scope from scratch.

#### Tracker Detection (preflight)

Run **Tracker Detection** (`skills/shared/tracker.md` §Tracker Detection) to
cache `TRACKER_TYPE`. If already set in session context, reuse it.

When `TRACKER_TYPE=github-issues` and `/decompose` output is visible in
conversation context (TODOS file, decompose receipts, or HANDOFF with
`Task:` references), extract the **task-to-issue mapping**:

1. Scan for decompose task lines: `- [ ] P{N} [{size}] #{issue} {title}`
2. Build a map: `{ stream-label → issue-number }` — each stream that
   implements a decompose task gets its issue number
3. Cache as `TASK_MAP` alongside preflight values:
   ```
   TASK_MAP={A: #42, B: #43, SP-1: #41}   (or empty — no decompose context)
   ```

When no decompose context is visible or `TRACKER_TYPE` is empty, `TASK_MAP`
stays empty and all tracker operations are skipped.

**Stream rule:** if two pieces of work touch the same file, they're the same stream.

#### Graph-aware independence check (if `graphify` MCP is available)

If the consumer's Project Profile lists `graphify`, query the dependency
graph to verify stream independence. Confirm no stream's file set has
dependencies on another stream's file set beyond declared contracts. Flag
hidden cross-stream dependencies before manifest approval. Also verify
shared dependencies (modules imported by multiple streams) are assigned to
prerequisites or infrastructure. Max 1 query.

If `graphify` is absent, infer independence from file paths and directory
structure.

#### 1a · Inverted-pyramid header

```
▎ ★ THE PLAN
▎
▎ {1–2 plain-English lines: what's being decomposed into how many streams +
▎ rough shape — sequential prerequisites, parallel mainline, merge order.}

▎ ⚠ HEADLINE RISKS
▎
▎ • {plan-level risk — hidden cross-stream dep, orphan infra file, contract drift}
▎ • {plan-level risk}
▎ • {2–3 bullets max}

▎ ✎ STREAMS · {N} streams · {M} prerequisites
▎
▎ SP-1  prereq  {what} · branch swarm/{goal}/sp-1
▎ A     stream  {scope summary} · branch swarm/{goal}/a
▎ B     stream  {scope summary} · branch swarm/{goal}/b
▎ ...
```

#### 1b · Receipts — between header and gate

```
══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Manifest
══════════════════════════════════════════════════════════════════════════════════════

  Goal:    {what's being built}
  Base:    {branch}

  PREREQUISITES
    SP-1  {what} — branch: swarm/{goal}/sp-1

  STREAMS
    A  swarm/{goal}/a — {scope + files owned}
    B  swarm/{goal}/b — {scope + files owned}

  CONTRACTS (cross-stream boundaries)
    A → B       {what A exports that B consumes — types, events, APIs}
    SP-1 → A,B  {shared interfaces or schemas}

  INFRASTRUCTURE (shared files not owned by any stream)
    {DI/service config, middleware/pipeline, CI config, docker-compose,
     env templates, shared route registrations, etc.}
    → Assign to: SP-{N} or dedicated stream

  MERGE ORDER: SP-1 → A → B
```

**When `TASK_MAP` is set** (tracker active + decompose context), two changes:

1. **Branch names** include the issue number: `swarm/{goal}/42-{slug}`
   instead of `swarm/{goal}/a`. This lets the Issue Resolution Block
   (source 3: branch name) resolve the issue inside worktree agents.
2. **Task annotation** per stream: append `· Task: #42` to the stream line.

Example with tracker:
```
  STREAMS
    A  swarm/{goal}/42-auth-middleware — {scope + files owned} · Task: #42
    B  swarm/{goal}/43-jwt-config — {scope + files owned} · Task: #43
```

`CONTRACTS` is required when streams have dependencies. If streams are fully
independent (no shared interfaces), write `CONTRACTS: none`.

`INFRASTRUCTURE` lists files that need modification but don't belong to any
stream's scope (config, CI, env templates, etc.). Every listed file must be
assigned to a prerequisite or a dedicated stream.

> **Completeness rule.** Every file the feature touches must be owned by
> exactly one stream, prerequisite, or infrastructure entry. Before
> approving, enumerate every expected file and verify each appears once.
> Unowned files = manifest is incomplete.

#### 1c · Gate 1 — at the bottom

**When `/swarm` is downstream** (HANDOFF present, `Verbose: true` absent):
Gate 1 is suppressed. Use P2 to guide manifest structure (minimal → fewest
streams; balanced → recommended; ideal → cleanest boundaries). Use P3 for
escalation: aggressive/moderate → auto-approve if completeness rule passes
and `/eng` context is available; conservative → escalate to user.

**Safety thresholds — escalate regardless of P3:**
- Manifest has >6 streams
- Completeness rule fails (unowned files detected)
- `graphify` flags hidden cross-stream dependencies not declared in contracts

When auto-approved, emit a transition line instead of the gate:

```
══ /swarm · Phase 1 — {N} streams · {M} prereqs · manifest approved ═══════════
```

**When `/swarm` is the entry point** (user invoked directly) or `Verbose: true`:

```
▎ ▸ GATE 1 — approve manifest?
▎
▎ Reply "go" to launch streams, or override (e.g. "split A", "merge SP-1 into A").
▎ Override: "{stream}: {revision}" applies before launch.
```

### Phase 2 · Implement — launch streams, run, report

Phase 2 re-emits the progress block with Phase 1 ✓, Phase 2 ▸. Launches
stream agents and waits for completion.

```
/swarm ═══════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Plan        approved · {N} streams · {M} prerequisites
  ▸ Phase 2  Implement   running...
  ○ Phase 3  Review
  ○ Phase 4  Merge
  ○ Phase 5  Integrate
  ○ Phase 6  Ship

══════════════════════════════════════════════════════════════════════════════════════
```

**Launch.** Use the `Agent` tool with `isolation: "worktree"` for each
stream. Independent streams run in parallel. Dependent streams run
sequentially (respecting the manifest's prerequisite + merge order).

> **Worktree safety — agent-write-leak prevention (mandatory).**
> `isolation: "worktree"` creates an isolated checkout, but it does NOT
> guarantee the agent's filesystem writes land inside the worktree. If the
> agent's first Bash call `cd`s to (or defaults to) the main repo, absolute
> paths in subsequent `Write` / `Edit` tool calls resolve to the main
> repo's working tree — leaking partial commits outside the worktree.
> Every stream / prereq agent prompt MUST include:
>
> 1. **"All filesystem writes use paths under `<worktree-path>/`. Never
>    write to `<main-repo-absolute-path>/…` directly."** Pass the worktree
>    path explicitly in the prompt.
> 2. **"Before any Bash call that would `cd` or run git, run `pwd` first
>    and confirm you are inside the worktree."** If pwd shows the main
>    repo, `cd` to the worktree before proceeding.
> 3. **"If a write lands outside the worktree, stop and report — do not
>    self-recover with stash/restore, the orchestrator will discard the
>    leak at Phase 4 entry."** Self-recovery via PowerShell `Set-Content`
>    has its own encoding hazard (mojibake on non-ASCII chars like `→`);
>    orchestrator catch-and-discard is safer.

> **Worktree safety — base-branch alignment (mandatory).**
> `isolation: "worktree"` creates the worktree from the harness's
> current-at-launch-time view of the parent ref. If the parent `dev` (or
> the integration branch a sequential stream depends on) has moved between
> launches and the harness picked the stale tip, the agent works against
> the wrong base — heavy cherry-pick conflicts and/or missing prerequisite
> commits at Phase 4. RECURRING 3x (batches 3, 4, 6) → escalated to hard
> rule (batch-7 prework, 2026-05-04). Every parallel-stream launch MUST
> follow either path A or path B:
>
> **Path A (preferred): orchestrator pre-creates the worktree.**
> Before the `Agent(isolation: "worktree")` call, run `git worktree add
> <path> <expected-base-branch-or-sha>` from the main repo. Pass `<path>`
> as `cwd` to the agent (or instruct the agent to `cd` there first). This
> bypasses the harness's auto-base entirely — the worktree's HEAD is
> whatever the orchestrator pinned.
>
> **Path B (fallback): agent self-verifies base on first action.**
> Pass `$EXPECTED_BASE_SHA` (from `git rev-parse <branch>` immediately
> before launch) in the agent prompt, plus this directive:
>
> > "Before editing any file, run `git rev-parse --abbrev-ref HEAD` and
> > `git log -1 --format=%H`. If `git log --oneline | grep $EXPECTED_BASE_SHA`
> > returns no match, the worktree is on the wrong base. Try
> > `git reset --hard <expected-branch>`; if that fails (ref unreachable),
> > STOP and surface to orchestrator — do NOT attempt rebase on an
> > unreachable ref."
>
> **Sequential streams trigger this most.** Parallel streams off the same
> base rarely diverge; sequential streams (A/B/C → integration → D) hit it
> when the orchestrator's branch state changes between launches and the
> harness picks the pre-update tip. Apply path A or B regardless.

> **Tracker context — Task reference in agent prompts (when TASK_MAP is set).**
> Stream agents run in worktree isolation with no conversation context from
> `/decompose`. Without an explicit `Task:` reference, downstream skills
> (`/eng`, `/tdd`, `/review`) inside the stream agent cannot resolve the
> GitHub Issue via the Issue Resolution Block (source 1: handoff line).
> When `TASK_MAP` maps a stream to an issue number, the stream agent prompt
> MUST include:
>
> `"Task: #{N} — {task title}. Use this issue number for all tracker
> operations (status swaps, badge labels)."`
>
> This ensures `/eng` and `/tdd` inside the worktree agent pick up
> `TASK_ISSUE` from the handoff context without needing to resolve it from
> the branch name (source 3) or conversation (source 4).
>
> When `TASK_MAP` is empty, omit the `Task:` line — stream agents run
> without tracker context, matching pre-v2.4.0 behavior.

After all streams complete, emit:

```
══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Stream completion
══════════════════════════════════════════════════════════════════════════════════════

  S1  {name}    ✓ commit {hash}
  S2  {name}    ✓ commit {hash}
  S3  {name}    ✓ commit {hash}
```

Phase 2 has no gate — it auto-chains to Phase 3 without a user prompt. Do
NOT merge here. The next visible thing is Phase 3's progress-block re-emit.

### Phase 3 · `/swarm review` — per-stream peer review, then Gate 2

Phase 3 re-emits the progress block. Spawns one `hashb:reviewer` subagent
per stream against that stream's diff + manifest + active rules.

Reviewers run in fresh context. `/swarm` already saw the implementer's
reasoning; an inline `/review` call would inherit that context and defeat
the fresh-context guarantee.

```
/swarm ═══════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Plan
  ✓ Phase 2  Implement   {N} streams · all complete
  ▸ Phase 3  Review
  ○ Phase 4  Merge
  ○ Phase 5  Integrate
  ○ Phase 6  Ship

══════════════════════════════════════════════════════════════════════════════════════
```

**Invocation:** `Agent(subagent_type: "hashb:reviewer", ...)` (defined in
`agents/reviewer.md` at plugin root). Pass each subagent its diff +
manifest + active rules.

**Per-stream verdicts:** APPROVED / CHANGES REQUESTED / ESCALATE.

**Cross-stream contract check:** if Stream B consumes exports from Stream A,
verify the contract matches (types, signatures, event schemas).

**Autonomous flow:**

- All APPROVED → proceed to Phase 4
- Any CHANGES REQUESTED → implementer fixes, re-review (max 2 cycles)
- Any ESCALATE → stop, present to user

#### 3a · Inverted-pyramid header

```
▎ ★ THE VERDICT
▎
▎ {1–2 plain-English lines: how many streams reviewed, how many APPROVED,
▎ any blocking issues.}

▎ ⚠ FINDINGS
▎
▎ • {finding — only if non-clean}
▎ • {finding}

▎ ✎ VERDICTS · {N} streams
▎
▎ S1   APPROVED
▎ S2   APPROVED
▎ S3   CHANGES REQUESTED → fixed → APPROVED
▎ Contracts   VERIFIED
```

If all clean and verdicts unanimous, drop `⚠ FINDINGS` entirely.

#### 3b · Gate 2 — at the bottom

**When `/swarm` is downstream** (HANDOFF present, `Verbose: true` absent):
Gate 2 is suppressed. All APPROVED → auto-proceed to Phase 4. Emit a
transition line instead of the gate:

```
══ /swarm · Phase 3 — all APPROVED · contracts verified · starting merge ═══════
```

**When `/swarm` is the entry point** (user invoked directly) or `Verbose: true`:

```
▎ ▸ GATE 2 — start merge?
▎
▎ Reply "go" to start /swarm merge.
▎ Reply "stop" to pause (streams stay queued).
▎ Override: "{stream}: re-review" forces another review cycle.
```

### Phase 4 · `/swarm merge` — sequential merge

Phase 4 re-emits the progress block. Verifies build + lint + tests on every
stream, creates an integration branch from base, and merges prerequisites
then streams in defined order — testing between each.

```
/swarm ═══════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Plan
  ✓ Phase 2  Implement
  ✓ Phase 3  Review      all APPROVED
  ▸ Phase 4  Merge
  ○ Phase 5  Integrate
  ○ Phase 6  Ship

══════════════════════════════════════════════════════════════════════════════════════
```

**Pre-merge checks** (skip merge if any fail):

0. **Orchestrator cwd + working-tree check (mandatory).** Before any
   cherry-pick / merge / branch operation:
   - Run `pwd` → must be the main repo path. If pwd resolves inside a
     worktree subdirectory, `cd` to the main repo IMMEDIATELY. Worktrees
     share the parent's `.git/refs/`, so `git rev-parse <base>` returns
     the right SHA even from a worktree subdir — but `git status` reports
     the worktree's branch, and cherry-picks land on that branch, not on
     the base.
   - Run `git branch --show-current` → must be the declared base. If it
     returns a `worktree-agent-*` branch, the bash session is in the wrong
     directory; do NOT proceed until cd'd to the main repo.
   - Run `git status -s` in the main repo → must show only expected
     manifest/spec edits (e.g. `TODOS.md`). Anything else is a leaked
     partial agent write from `isolation: "worktree"` — `git checkout --
     <leaked-files>` to discard BEFORE cherry-picking. Without this check,
     leaked files cause spurious cherry-pick conflicts.
1. All streams done with passing build, lint, and tests
2. All streams have APPROVED review verdict
3. Integration branch created from base

**Merge loop** — for each stream in order (prerequisites first):

1. Merge stream into integration branch
2. Build + lint + test
3. **Cross-stream integration check** — do imports resolve? do types match across stream boundaries? do events published by one stream get handled by another?
4. If conflicts: stop, surface them, user decides
5. Continue to next stream

**Cleanup after final merge:**

- Delete worktree directories created for streams (warn if uncommitted changes)
- Delete local + remote swarm branches (`swarm/*/*`)
- Remove any `.swarm/` state files

**Tracker badge verification (when TASK_MAP is set):**

After each stream is successfully merged, verify tracker state for its
mapped issue. Stream agents should have applied status swaps and badge
labels during their `/eng` → `/tdd` → `/review` run, but worktree isolation
can cause missed updates (network errors inside worktree, agent early exit).

For each stream with a mapped issue (`TASK_MAP[stream] = #N`):

```bash
# Badge verification — see skills/shared/tracker.md §Badge Label Block
if [ "$TRACKER_TYPE" = "github-issues" ] && [ -n "$TASK_ISSUE" ]; then
  EXISTING=$(gh issue view "$TASK_ISSUE" --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null)
  for badge in hashb:eng hashb:tdd hashb:review; do
    echo "$EXISTING" | grep -q "$badge" || \
      gh issue edit "$TASK_ISSUE" --add-label "$badge" 2>/dev/null
  done
fi
```

Best-effort — skip silently on failure. The stream agent's own badge
writes are the primary mechanism; this is a catch-up pass.

#### 4a · Receipts — merge progress

```
══════════════════════════════════════════════════════════════════════════════════════
  Receipts — Merge progress
══════════════════════════════════════════════════════════════════════════════════════

  S1  merged ✓  tests: ✓
  S2  merged ✓  tests: ✓  (conflicts resolved: file.cs)
  S3  merged ✓  tests: ✓
  Cleanup    ✓  worktrees + branches removed
```

#### 4b · Gate 3 — at the bottom (chain handoff)

**When `/swarm` is downstream** (HANDOFF present, `Verbose: true` absent):
Gate 3 is suppressed. Merge complete + tests green → auto-proceed to
Phase 5 (integrated review). Emit a transition line instead of the gate:

```
══ /swarm · Phase 4 — {N} streams merged · tests green · starting review ═══════
```

**When `/swarm` is the entry point** (user invoked directly) or `Verbose: true`:

```
▎ ▸ GATE 3 — start integrated review?
▎
▎ Next: /hashb:review (recommended — full diff vs base on merged result)
▎
▎ Reply "go" to spawn hashb:reviewer on the merged diff.
▎ Reply "stop" to pause (merge complete; integration deferred).
```

> **Integrated review is mandatory.** Stream reviews check code quality
> within boundaries; the integrated review checks the combined diff against
> base for cross-cutting issues — missing runtime wiring, contract
> mismatches between streams, dependency conflicts, integration gaps.
> Watch merge resolution code carefully — those lines aren't in any single
> stream's diff, so they didn't get reviewed.

### Phase 5–6 · Integrate · Ship — handoff to hashb chain

After Phase 4 completes, `/swarm` auto-chains:

1. **Phase 5 · Integrate.** Spawn `subagent_type: hashb:reviewer` against the full merged diff to base.
2. **Phase 6 · Ship.** Invoke `/hashb:ship` for changelog + commit + PR.

Each phase re-emits the progress block as its entry banner. Each carries
the canonical `Next:` line at its terminating gate.

---

## `/swarm status`

Lightweight status report — single emission, no phase progression. Reads
git state for each stream branch and reports what's done, what's active,
and flags any files modified outside a stream's scope.

```
══════════════════════════════════════════════════════════════════════════════════════
  Status — {goal}
══════════════════════════════════════════════════════════════════════════════════════

  S1  {name}    {branch state} · {N} ahead · last: {timestamp}
  S2  {name}    {branch state} · {N} ahead · last: {timestamp}
  ⚠ {file path} modified outside any stream scope (in {stream})
```

---

## Next step

| Condition | Next |
|---|---|
| All streams merged, tests pass | `/hashb:review` → `/hashb:ship` |
| Integrated review CHANGES REQUESTED | `/hashb:fix` → re-review (max 2 cycles) |
| Stream review failed after 2 cycles | Escalate to user |
| Merge conflicts can't be auto-resolved | Escalate to user |

**Autonomous mode** — in a recipe chain (HANDOFF present, `Verbose: true` absent):

- All merged + tests green → auto-proceed to `/hashb:review`, then `/hashb:ship`
- Integrated review CHANGES REQUESTED → `/hashb:fix` + re-review (max 2 cycles)
- Blocked → stop the chain, present the issue to user

After all phases complete, emit a final transition line:

```
══ /swarm · {N} streams · all merged · integrated review APPROVED ══════════════
```

---

## Handoff Summary

After completion, emit a compact handoff block for the downstream skill.
When the chain continues after Phase 5 (integrated review), the handoff
targets `/ship`. When swarm completes all phases (through Phase 6), `/ship`
is the downstream skill.

```
HANDOFF → /ship
  Scope:       {one-line what was built}
  Streams:     {N} streams · {M} prereqs · all merged
  Tasks:       #42, #43, #44              ← only when TASK_MAP is set
  Review:      integrated — {verdict}
  Principles:  {forwarded from upstream HANDOFF, if present}
  Verbose:     true                          ← only if present in upstream
  Spec file:   specs/{capability-name}.md
  Risks:       {top 2 integration risks, one line each}
```

Rules:
- Total handoff: ≤10 lines.
- `Tasks:` line: comma-separated issue numbers from `TASK_MAP`. Omit when `TASK_MAP` is empty. `/ship` uses this to close all tracked issues via the Issue Close Block.
- `Principles:` line: forward from upstream HANDOFF if present.
- `Verbose:` line: forward from upstream HANDOFF if present. Omit by default.

---

## Rules

| Rule | Why |
|------|-----|
| Single agent is the default | Only swarm when it clearly helps. Score the goal first. |
| Prerequisites first | Shared code changes before parallel streams. |
| Streams own their files | Touching outside scope = stop and escalate. |
| Never merge without review | Each stream gets a peer review before integration. No exceptions. |
| Phase order is mandatory | The execution flow above is the only valid sequence. |
| Merge one at a time | Build, lint, and test between each merge. |
| Cross-stream contracts validated | If streams share boundaries, verify contracts match. |
| No nested swarms | One level of decomposition only. |
| Worktree cwd verified at Phase 4 | After `isolation: "worktree"` agents finish, orchestrator pwd may have drifted into a worktree subdir. Always `cd` to main repo + run `git branch --show-current` + `git status -s` before any cherry-pick. See Phase 4 Pre-merge check #0. |
| Agent prompts forbid main-repo writes | Stream agent prompts must direct: writes use worktree-relative paths only; `pwd` before any Bash `cd`; report don't self-recover on leak. See Phase 2 Launch worktree-safety callout. |
| Worktree base alignment verified at launch | RECURRING 3x → hard rule. Either orchestrator pre-creates worktree via `git worktree add <path> <base>` (path A), or agent prompt carries `$EXPECTED_BASE_SHA` and self-verifies via `git log --oneline \| grep $EXPECTED_BASE_SHA` before any edit (path B). Sequential streams (A/B/C → integration → D) trigger this most. See Phase 2 Launch worktree-safety base-alignment callout. |
| Autonomous mode: HANDOFF + no Verbose → suppress gates | Matches `/eng`, `/tdd`, `/design`, `/simplify` pattern. Gates 2–3 are pause points with no decisions. Gate 1 has safety thresholds (>6 streams, completeness failure, graphify hidden deps, P3=conservative). |
| Tracker context flows to stream agents | When `TASK_MAP` is set, every stream agent prompt includes `Task: #N`. Issue-based branch names (`swarm/{goal}/42-{slug}`) provide fallback resolution. Badge verification runs at Phase 4 merge. `Tasks:` line in handoff lets `/ship` close all issues. |