# Multi-Agent Pipeline - Phase Reference ## Phase Files | Phase | File | | --------------------------------- | -------------------------------------------------------------------- | | Modes (depth picker, autopilot, --local) | `$HOME/.claude/multi-agent-refs/phases/modes.md` | | Operations (kill, purge, resume) | `$HOME/.claude/multi-agent-refs/phases/operations.md` | | Phase 0: Init | `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` | | Phase 1: Analysis | `$HOME/.claude/multi-agent-refs/phases/phase-1-analysis.md` | | Phase 2: Planning | `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` | | Phase 3: Dev | `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` | | Phase 4: Review | `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` | | Phase 5: Test | `$HOME/.claude/multi-agent-refs/phases/phase-5-test.md` | | Phase 6: Commit & PR | `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md` | | Phase 7: Report | `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` | | Log format | `$HOME/.claude/multi-agent-refs/phases/log-format.md` | ## Pipeline Flow ``` Full: 0-Init -> 1-Analysis -> 2-Planning -> 3-Dev -> 4-Review -> 5-Test -> 6-Commit -> 7-Report Short: 0-Init -> (1,2 skipped) --------------> 3-Dev -> 4-Review -> 5-Test -> 6-Commit -> 7-Report --local: Either of the above with no worktree - works directly on a local branch Full or Short is the Phase 0 Step 7.5 question, not a command name. Autopilot never asks and always runs Full. ``` ## Visual Phase Tracker Two channels run in parallel at every phase boundary. Both are required in their target CLIs - skipping either is the #1 source of "I see no progress" complaints. | Mechanism | Available in | Status | Style | | -------------------------------- | ---------------- | ------------- | ---------------------------------------------------- | | **`phase-tracker.sh`** (state) | Every CLI | required | Drives `tracker-state.json`; powers `:resume`/`:log`/`:status` | | **`TaskCreate` / `TaskUpdate`** | Claude Code only | required here | Native sticky TaskList widget - the only progress signal Claude Code surfaces | | **`phase-tracker.sh render`** | Every other CLI | required here | Bordered ANSI card printed as last tool result so the user sees the phase table | | **`phase-banner.sh`** | Every CLI | Optional | One-shot ANSI banner per phase boundary (extra emphasis) | **Cross-CLI contract**: every phase boundary MUST update both the state channel (`phase-tracker.sh`) AND the visual channel (TaskList in Claude Code, render in every other CLI). The tracker is the cross-CLI source of truth; the visual is what the user actually sees. ### Tracker bootstrap (Phase 0, mandatory) Phase 0 MUST initialize the tracker and register all 8 phases: ```bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID" for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}" done ``` This produces an initial card stack printed by both CLIs. ### Tracker updates (every phase boundary) As each phase enters/exits: ```bash $HOME/.claude/scripts/phase-tracker.sh update in_progress # phase starts # ...do the work... $HOME/.claude/scripts/phase-tracker.sh update completed # phase ends OK # or: $HOME/.claude/scripts/phase-tracker.sh update failed # phase failed $HOME/.claude/scripts/phase-tracker.sh update skipped # e.g. 1 and 2 in a Short run ``` After every LLM call (counts are additive; skipping this is why runs end with durations but no cost - nothing reconstructs spend afterwards): ```bash $HOME/.claude/scripts/phase-tracker.sh tokens [cached] ``` For sub-phase progress (e.g. Phase 1's parallel Explore agents, Phase 4's reviewer dispatch + triage + validator gate, Phase 6's commit + push + PR sub-steps): ```bash $HOME/.claude/scripts/phase-tracker.sh sub 1 "" pending # register $HOME/.claude/scripts/phase-tracker.sh sub 1 "" in_progress # advance $HOME/.claude/scripts/phase-tracker.sh sub 1 "" completed # done ``` State persists at `$HOME/.claude/logs/multi-agent//tracker-state.json` - atomic writes mean concurrent worktrees don't corrupt each other. ### Optional banner (single-event flair) Call alongside tracker update for extra emphasis: ```bash $HOME/.claude/scripts/phase-banner.sh start "" "" $HOME/.claude/scripts/phase-banner.sh end done "" "" $HOME/.claude/scripts/phase-banner.sh sub 2 "" "" ``` Banner status enum on `end`: `done` | `failed` | `skipped`. Anything else exits 64. ### TaskCreate registration (Claude Code - required) In Claude Code the agent MUST register one TaskCreate tile per phase at Phase 0 startup (one per phase the current COMMAND runs - `/multi-agent` = 0..7, `:local` and the autopilot entries = 0/1/2/3/4/6/7, `:analysis` = 0/1/2/4/6/7). Capture the returned `taskId`, persist it via `phase-tracker.sh meta tasklist_id ""` so `:resume` can rebuild the widget. Per phase boundary: ```text # Phase entry - flip the tile to in_progress alongside the state update TaskUpdate({ taskId: , status: "in_progress" }) bash phase-tracker.sh update in_progress # Active sub-step inside a phase - keeps the spinner header live TaskUpdate({ taskId: , activeForm: "Editing TopBarView.swift" }) TaskUpdate({ taskId: , activeForm: "Running xcodebuild test" }) # Phase exit - flip both channels TaskUpdate({ taskId: , status: "completed" }) bash phase-tracker.sh update completed ``` A phase outside the command's set gets no TaskCreate at all. Depth is different: it is not known at registration time, because the tracker boots at Step -1 and the depth question runs at Step 7.5, so a Short run registers Phases 1 and 2 like any other and flips them to `skipped` when the answer lands. Pre-marking them before Phase 0 produces visually scrambled tile stacks - see the ordering rule below. **(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number - out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN - register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)". **Copilot CLI / plain shell**: do NOT call TaskCreate - the tool does not exist on these CLIs. Instead, after every state update, call `bash phase-tracker.sh render` so the bordered ANSI card prints as the last tool result. That's the equivalent visual signal there. ## Preferences File Path: `$HOME/.claude/multi-agent-preferences.json` - persistent state across sessions. ## Host Configuration Pipeline uses placeholder hosts for corporate services. Set these before first use: | Placeholder | Purpose | Example | | ------------------- | -------------------------- | ------------------------ | | `{JIRA_HOST}` | Jira server hostname | `jira.company.com` | | `{BITBUCKET_HOST}` | Bitbucket server hostname | `bitbucket.company.com` | | `{CONFLUENCE_HOST}` | Confluence server hostname | `confluence.company.com` | | `{CORP_DOMAIN}` | Corporate domain | `company.com` | Configure via preferences or environment variables. If not set, VPN check (Phase 0) skips gracefully. Read modes.md first (always), then the phase file for the current stage. For operations (status, kill, resume, purge): read operations.md. ## Token Budget Each phase doc is lazy-loaded - only the current phase's spec is in context. Budget enforced by `smoke-token-budget.sh`. | Phase | File | Max Tokens | Warn | | ----------- | ------------------- | ---------- | ----- | | 0: Init | phase-0-init.md | 4,000 | 3,500 | | 1: Analysis | phase-1-analysis.md | 1,500 | 1,200 | | 2: Planning | phase-2-planning.md | 1,000 | 800 | | 3: Dev | phase-3-dev.md | 1,800 | 1,500 | | 4: Review | phase-4-review.md | 2,200 | 1,800 | | 5: Test | phase-5-test.md | 800 | 600 | | 6: Commit | phase-6-commit.md | 2,800 | 2,400 | | 7: Report | phase-7-report.md | 3,200 | 2,700 | | **Total** | | **17,000** | | Token estimate: `ceil(chars / 4)`. Budget covers phase-\*.md files only. Guides, rules, and agents are loaded separately on demand. **Prompt caching (token learning-curve):** assemble each phase prompt as a stable, cacheable prefix (phase instructions + repo learnings brief + conventions + repo evidence) followed by the volatile task suffix, so repeated runs on a known repo pay cache-read price on the prefix. Full contract: `$HOME/.claude/multi-agent-refs/prompt-assembly.md`. The effect (rising cache ratio, falling tokens/task) is what `learning-curve.mjs` trends. ## SubPhase Convention When a specialized skill takes over a main pipeline phase, progress is reported as **SubPhases** nested under the parent. Top-level stays 8 phases (0-7); specialized flows get sub-phase detail. **Visual example:** ``` ■ Phase 0: Init completed ■ Phase 1: Analysis completed ■ Phase 2: Planning completed * Phase 3: Dev (figma) in progress ■ SubPhase 3.0: Init completed ■ SubPhase 3.1: Gather completed ■ SubPhase 3.4A: Configuration completed ■ SubPhase 3.4B: View completed * SubPhase 3.4F: Wiki writing wiki pages... □ SubPhase 3.5A: ViewInspector pending □ SubPhase 3.6: Code Connect pending □ SubPhase 3.7: Issue Update pending □ Phase 4: Review pending □ Phase 5: Test pending □ Phase 6: Commit pending □ Phase 7: Report pending □ SubPhase 7.1: Jira comment pending □ SubPhase 7.2: Wiki + screenshots pending □ SubPhase 7.3: Confluence pending □ SubPhase 7.4: Report + log pending □ SubPhase 7.5: Knowledge capture pending ``` **TaskCreate pattern:** Parent phase + SubPhases linked via `addBlockedBy`. SubPhases block parent from completing. **Why SubPhases, not separate phases:** - Main pipeline stays a fixed 8-phase contract (0-7) regardless of task type. Wiki, Confluence, and Figma screenshots all live as SubPhases under Phase 7 Report - external delivery grouped logically, internal report + knowledge after. - Conditional phases are a code smell - they force every reader to learn which phase runs when.