@mmerterden/multi-agent-pipeline 19.1.4 → 20.0.0

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -1,58 +1,187 @@
 ---
-description: "Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left off."
-description-tr: "Durmuş veya hata almış bir görevi kaldığı fazdan devam ettirir."
-argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
+description: "Pick up unfinished work: a pipeline run that stopped mid-phase, or work already written on the current branch that never went through the pipeline. Use when a task stopped or failed, or when hand-written local work needs review, build, PR and reporting."
+description-tr: "Yarım kalan işi sürdürür: ortada duran bir pipeline koşusu ya da mevcut branch'te elle yazılmış, pipeline'dan hiç geçmemiş iş."
+argument-hint: "[#id | PROJ-12345] [--base <branch>] [autopilot]  -  no argument: pick from the list"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, Skill
 ---
 
-# multi-agent resume  -  Resume Paused Task
+# multi-agent resume  -  Continue Unfinished Work
 
 **Input**: $ARGUMENTS
 
-Resume a paused or failed task from the last successful phase.
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` renders its `question`, option `label`s and option `description`s in `outputLanguage`; only `header` stays English (<=12-char chip); external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
-> **Not the same as `/multi-agent:resume-local`.** `resume` continues a **tracked pipeline task** (needs its `agent-state.json`/worktree) from where it stopped. `/multi-agent:resume-local` takes **ad-hoc local work** on the current branch (no prior task required) and runs the pipeline tail - Review → Build+Test → PR → Jira report - over it.
+Unfinished work reaches this command from two directions, and which one you are in is a property of the repository, not of how you typed the command:
+
+- **A tracked run stopped.** It has an `agent-state.json`, a phase it was inside, and possibly a worktree. It resumes from where it stopped.
+- **Work exists on the current branch with no run behind it.** You wrote it by hand, or a run outside the pipeline produced it. There is nothing to resume, so the **pipeline tail** runs over the diff: Review (with its build gate) → Commit/PR → Report. Plan and Dev never run; the diff already on the branch is the Dev output.
+
+Step 1 finds both and asks. A single command means you do not have to know which case you are in before you can ask the question.
+
+## Input
+
+```bash
+/multi-agent:resume                       # list everything resumable, pick one
+/multi-agent:resume #2                    # a tracked run by task number
+/multi-agent:resume PROJ-12345            # a tracked run by Jira id, or bind the tail to that id
+/multi-agent:resume --base develop        # tail path: override the base branch for the diff
+/multi-agent:resume autopilot             # no gate prompts: auto-fix, auto-PR, auto-comment
+```
+
+## When NOT to use it
+
+- The change is not written yet  -  use `/multi-agent`.
+- Only the review is wanted  -  `/multi-agent:review`. Only the report  -  `/multi-agent:channels`. Only device UI testing  -  `/multi-agent:test` / `/multi-agent:manual-test`.
+- The run is abandoned rather than paused  -  `/multi-agent:kill #N`, or `/multi-agent:garbage-collect --abandoned` for the Phase 0 leftovers.
 
 ## Steps
 
-1. **Find the task**  -  parse `#N` from the argument, or pick the most recent worktree with `status != "done"`.
-
-2. **Read + validate state**  -  parse `agent-state.json`:
-   - Validate first: `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check, tolerant of legacy shapes). On non-zero exit, do NOT guess a phase  -  surface the errors and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
-   - Confirm the worktree (`worktreePath` / `projects[].worktreePath`) exists and is usable; if missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
-- **Unless `state.worktreeRemovedAt` is set.** Then the worktree was removed on purpose by Phase 4 once the PR opened, the branch is still local, and the artefacts live under `state.artifactsPath`. Do NOT heal or recreate it: read state from `artifactsPath`, and if the remaining work needs a checkout (a Phase 5 pause needs none), ask before moving the user's HEAD  -  they may be mid-work on another branch, which is exactly why the removal did not check the branch out.
-   - `currentPhase`  -  last completed phase
-   - `status`  -  `paused` | `failed` | `in_progress`
-   - `haltReason`  -  if set, show it so the user knows why the run stopped; clear it on successful re-entry
-   - `circuitBreaker`  -  if `tripped`, show `trigger` + `detail`, then set `tripped: false` and keep `counters`; if the same trigger fires again at the next checkpoint the breaker re-trips (no silent bypass)
-   - `autopilot`  -  preserve the mode
-
-3. **Load context**  -  rebuild working context from durable artifacts, never from conversation memory:
-   - **Handoff first (v10.8.0)**: read the LATEST `## Handoff` block in `agent-log.md`  -  it carries done/remaining/decisions/open-findings and the exact re-entry point (phase + subStep). When present, it is the primary context source; cross-check its `Next:` line against `state.currentPhase` and trust state on mismatch (state is the machine truth, handoff is the narrative).
-   - Fall back to per-phase findings for logs written before v10.8 (no handoff blocks):
-     - Phase 1 analysis → use it from Phase 2+
-     - Phase 1 plan → use it from Phase 2+
-     - Phase 3 code → already in the worktree
-   - Recent `git log --oneline -10` in the worktree grounds what was actually committed vs. claimed.
-
-4. **Rebuild the phase tiles**  -  load `tracker-state.json` for the task (never re-init it; `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
-   - Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
-   - Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
-
-5. **Continue the pipeline.** Read `state.waitingFor` FIRST: when it names a step, the
-   run re-enters THAT step rather than the next phase. `currentPhase + 1` is the fallback,
-   not the rule - a run that stopped mid-phase to ask a human has `currentPhase` pointing at
-   the phase it is still inside, so resuming past it skips the question permanently. That
-   was already true of Phase 5's channels pause, which documented itself as resumable
-   through this field while this file never mentioned it.
-
-   | `waitingFor` | Re-entry |
-   |---|---|
-   | `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`) |
-   | `user-channels-choice` | Phase 5, the channels multi-select, with the stored `channelsInput` |
-   | absent | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
-
-   Clear `waitingFor` in the same write that records the answer, the moment the step is
-   re-entered. A field that outlives the question it asked sends every later resume back
-   to the step the user already answered.
-
-6. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`
+### Step 1  -  Build the resumable list, then ask
+
+Collect both sources before rendering anything. An argument that names a run (`#N`, a Jira id, a GitHub issue number) selects it directly and skips the question; an argument that names nothing resumable is an error, never a silent fall-through to the tail.
+
+**Source A  -  tracked runs.** Every `agent-state.json` under `$HOME/.claude/logs/multi-agent/{project}/` whose `status != "done"`. Each row carries what the choice actually turns on: task id, the phase it stopped inside, its workspace (the worktree path, or `local` when `worktreePath` is the project root), how long it has been sitting, and `haltReason` when set.
+
+**Source B  -  untracked work on the current branch.** Resolve the base branch in order: `--base <arg>` → `figma-config.project.baseBranch` → `develop` → the branch's upstream/merge-base. The work is `git diff <base>...HEAD` plus uncommitted working-tree changes. The row appears only when that diff is non-empty **and** no Source A run already owns this branch  -  otherwise the same work would be offered twice under two different contracts.
+
+**Ask.** Full rules: `$HOME/.claude/multi-agent-refs/picker-contract.md`. This is a one-step chain, so the breadcrumb is `Step 1/1: which unfinished work to pick up`, rendered in `outputLanguage` above the picker. `question`, every `label` and every `description` render in `outputLanguage`; `header` stays English (`Resume what`). Source A rows first (newest first), Source B last. Labels carry proper nouns verbatim - task id, branch name - and the run branches on which row was selected, never on the label text.
+
+**One candidate is still a question.** A single row is asked with a genuine escape as its second option, because `AskUserQuestion` refuses a call with fewer than two declared options and discards every question batched with it:
+
+| Only row | Second option |
+|---|---|
+| one stopped run | **Show every run** - re-opens with the `status != "done"` filter dropped, so a run that recorded itself finished but left work behind is still reachable |
+| only the branch diff | **Pick a stopped run instead** - re-opens listing Source A unfiltered, and says so when it is empty |
+
+Zero rows in both sources: do not ask. Stop with `ERR: nothing to resume  -  no stopped run for this project and no local changes on {branch} vs {base}`.
+
+**The answer routes.** A Source A row runs Steps 2-5 and nothing else; a Source B row runs Steps 6-7 and nothing else. The two halves never both run in one invocation.
+
+### Step 2  -  Tracked run: read and validate state
+
+- Validate first: `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check, tolerant of legacy shapes). On non-zero exit, do NOT guess a phase  -  surface the errors and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
+- Confirm the worktree (`worktreePath` / `projects[].worktreePath`) exists and is usable; if missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
+  - **Unless `state.worktreeRemovedAt` is set.** Then the worktree was removed on purpose by Phase 4 once the PR opened, the branch is still local, and the artefacts live under `state.artifactsPath`. Do NOT heal or recreate it: read state from `artifactsPath`, and if the remaining work needs a checkout (a Phase 5 pause needs none), ask before moving the user's HEAD  -  they may be mid-work on another branch, which is exactly why the removal did not check the branch out.
+- `currentPhase`  -  last completed phase
+- `status`  -  `paused` | `failed` | `in_progress`
+- `haltReason`  -  if set, show it so the user knows why the run stopped; clear it on successful re-entry
+- `circuitBreaker`  -  if `tripped`, show `trigger` + `detail`, then set `tripped: false` and keep `counters`; if the same trigger fires again at the next checkpoint the breaker re-trips (no silent bypass)
+- `autopilot`  -  preserve the mode
+
+### Step 3  -  Tracked run: load context
+
+Rebuild working context from durable artifacts, never from conversation memory:
+
+- **Handoff first**: read the LATEST `## Handoff` block in `agent-log.md`  -  it carries done/remaining/decisions/open-findings and the exact re-entry point (phase + subStep). When present, it is the primary context source; cross-check its `Next:` line against `state.currentPhase` and trust state on mismatch (state is the machine truth, handoff is the narrative).
+- Fall back to per-phase findings for logs written before handoff blocks existed:
+  - Phase 1 analysis and plan → use them from Phase 2 on
+  - Phase 2 code → already in the worktree
+- Recent `git log --oneline -10` in the worktree grounds what was actually committed vs. claimed.
+
+### Step 4  -  Tracked run: rebuild the phase tiles
+
+Load `tracker-state.json` for the task (never re-init it; `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
+
+- Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
+- Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
+
+### Step 5  -  Tracked run: continue the pipeline
+
+Read `state.waitingFor` FIRST: when it names a step, the run re-enters THAT step rather than the next phase. `currentPhase + 1` is the fallback, not the rule - a run that stopped mid-phase to ask a human has `currentPhase` pointing at the phase it is still inside, so resuming past it skips the question permanently.
+
+| `waitingFor` | Re-entry |
+|---|---|
+| `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`) |
+| `user-channels-choice` | Phase 5, the channels multi-select, with the stored `channelsInput` |
+| `local-test` | Phase 3, the user-test gate, with the checkout the gate was waiting on |
+| absent | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
+
+Clear `waitingFor` in the same write that records the answer, the moment the step is re-entered. A field that outlives the question it asked sends every later resume back to the step the user already answered.
+
+Log: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`
+
+### Step 6  -  Untracked branch work: context resolution
+
+1. **Project + branch:** detect project (cwd), current branch (`git branch --show-current`). No worktree is created; the work is already in this checkout.
+2. **Base + diff:** as resolved in Step 1. Abort with `ERR: no local work to resume on <branch> vs <base>` if the diff went empty between the question and the answer.
+3. **Task binding:** Jira id from the argument, else parsed from the branch name (`bugfix/PROJ-XXXX` / `feature/PROJ-XXXX`); `taskType` inferred from the diff (bugfix/feature/refactor/chore) for the report wording. GitHub issue `#N` from branch or argument when present.
+4. **Prior state (optional):** if a tracker state exists for this branch from an earlier run, load its analysis summary and Jira/issue binding to enrich the report. Never require a prior pipeline run.
+5. Persist state under `$HOME/.claude/logs/multi-agent/{project}/{taskId}/`, the same location every run uses.
+
+### Step 7  -  Untracked branch work: run the tail
+
+```
+Phase 0: Init          → project/branch detect, base + diff, Jira id, state (no worktree)
+Phase 3: Review        → the Verify gate first (stack-aware build + existing tests; SUCCESS required), then
+                         parallel review (Fable + Opus + Sonnet) + Fable triage
+Phase 4: Commit        → commit remaining local changes + push + open PR if none exists
+Phase 5: Report        → technical analysis + Jira comment with test scenarios (channels: Jira / PR / Confluence / Wiki)
+```
+
+Phases 1 and 2 (Plan / Dev) do not run: the branch's diff is the Dev output, so the **Plan Approval Gate** has no plan to approve here. That is the only path where it is absent for a reason other than `autopilot` having nobody to ask.
+
+**Why Review runs the build gate here.** Verify is Phase 2 Dev's exit gate, and this path has no Dev: the work arrived already written. The gate still has to run, so Review runs it before dispatching reviewers. Reviewing a branch whose build was never checked is the failure this ordering prevents.
+
+- **Phase 3 Review** - per `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Opus + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
+  - interactive: present them and ask (`AskUserQuestion`) whether to fix now (loop back through a minimal Phase-2-style TDD fix) or proceed;
+  - `autopilot` (or `prefs.global.resume.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
+- **Phase 3 Verify gate** - the **automated success gate** (the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/web build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" - never fabricate test results.**
+- **Phase 4 Commit/PR** - per `$HOME/.claude/multi-agent-refs/phases/phase-4-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/multi-agent-refs/rules.md` "External System Outputs" and `$HOME/.claude/rules/git-conventions.md` - `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- **Phase 5 Report** - per `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content: a Jira **comment** carrying the technical analysis + the test scenarios (and, when the PR was opened, the PR description). Every body runs through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
+
+## Modes
+
+- **interactive** (default): stops at the Phase 4 gate when there are blocking/important findings; asks before committing/PR when appropriate.
+- **`autopilot`**: no prompts  -  auto-fix accepted blocking/important findings, auto-commit/push/PR, auto-post the Jira comment.
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of a run that starts in the middle.
+
+## Required: Phase Tracker Contract
+
+**The phase tracker is required.** Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
+
+A tracked run rebuilds its tiles from `tracker-state.json` (Step 4) and never re-declares a phase set. The untracked-branch path registers its own active set  -  `0:Init 3:Review 4:Commit 5:Report`  -  but NEVER resets a tracker an earlier run already built (load-or-continue; contract section "Continuation runs"):
+
+```bash
+# Phase 0, first shell call (every CLI). init ONLY when no prior state exists -
+# a task handed off from the user test inside Phase 3 ("awaiting local test")
+# keeps its full phase 0-2 history (elapsed, tokens, USD).
+STATE="$HOME/.claude/logs/multi-agent/${TASK_ID}/tracker-state.json"
+if [ ! -f "$STATE" ]; then
+  bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+fi
+for p in "0:Init" "3:Review" "4:Commit" "5:Report"; do
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"   # idempotent: existing phases keep their history
+done
+bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+
+# Every phase boundary (every CLI):
+bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
+# After every LLM call (every CLI):
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
+```
+
+**Continuation path (prior state existed):** (1) if Phase 3 was left `in_progress` with `Now: awaiting local test (user)`, mark it `update 3 completed` + `meta 3 Result "local test done (user)"` before this run's own work (it re-opens Phase 3 with `update 3 in_progress` when the Verify gate runs; elapsed keeps the original `started_at`, which is expected); (2) print ONE line in `outputLanguage` summarizing the inherited history, e.g. `Continuing PROJ-12345: phases 0-3 finished earlier (12m, 38.4k tok, ~$0.74)` (USD via `phase-tracker.sh cost total`); (3) `render`.
+
+### Visual channel  -  Claude Code (native TaskList widget, required)
+
+Fresh state: register one tile per phase in strict phase-number order (`0 → 3 → 4 → 5`) BEFORE any TaskUpdate, capture each `taskId`, persist via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, then flip status with `TaskUpdate` at each boundary. Out-of-order TaskCreate scrambles the tile stack. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` "TaskCreate ordering (strict)".
+
+Continuation: rebuild the FULL TaskList from the state file (completed tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta  -  same as the contract's "Resume behaviour".
+
+### Visual channel  -  Copilot CLI / plain shell
+
+No TaskList widget. After every state change call `bash $HOME/.claude/scripts/phase-tracker.sh render` (prints the bordered ANSI phase table as the last tool result). Do NOT call TaskCreate on these CLIs.
+
+## Examples
+
+```bash
+/multi-agent "PROJ-12345"                 # a run that stops at the user-test gate
+/multi-agent:resume                        # ... pick it back up from that gate
+
+# ... or, with no run behind it at all:
+# you write the change by hand on bugfix/PROJ-12345-flight-filter
+/multi-agent:resume                        # review + build/test + PR + Jira analysis & test scenarios
+```

package/pipeline/commands/multi-agent/save/SKILL.md

@@ -7,6 +7,8 @@ allowed-tools: Bash, Read, AskUserQuestion
 
 # multi-agent save  -  Save a Routine
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 **Input**: $ARGUMENTS (optional routine name)
 
 Turn a recurring, project-specific procedure into a first-class `/multi-agent:<name>` command. The saved routine is a **local-only** command (`local-only: true`) plus a registry entry in `prefs.global.routines`; it is never synced to the public repo (the `/multi-agent:sync` backstops enforce this).

package/pipeline/commands/multi-agent/stack/SKILL.md

@@ -7,6 +7,8 @@ allowed-tools: Bash, Read, Edit, Write, AskUserQuestion
 
 # multi-agent stack  -  Select Stack(s) via Plugin Enablement
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. Two toolkits are stack-independent and always enabled alongside the stack plugin(s): `ai-common-toolkit` (accessibility audit, humanizer, Firebase) and `ai-analyst-toolkit` (GitHub and package-registry evidence, community signal for analysis work).
 
 On Claude Code the marketplace plugins are the ONLY source of stack skills - nothing is copied into `~/.claude/skills` anymore. A stack that is not enabled here is simply absent from the session. Copilot CLI and Codex CLI have no plugin loader; they receive a local copy filtered to the enabled stacks at install time, which is why step 5 below offers to refresh those copies after a change.

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -65,8 +65,8 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 60 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 60 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 57 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 57 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -90,7 +90,7 @@ Step 0 gate rules and why: `features/doctor.md`.
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync the shared sections** (Claude ↔ Copilot):
-   - Pipeline entries table (base / :local / :autopilot / :local-autopilot) + the Full-or-Short depth question
+   - Pipeline entries table (base / :autopilot)
    - Project detection (URL-based + cwd-based)
    - Figma pipeline flow
    - Git conventions (author, branch, commit format)
@@ -494,15 +494,14 @@ same 56 specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**60 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**57 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
 autopilot-status, build-optimize, channels, complaint-analysis, create-jira,
 design-check, diff-explain, doctor, feedback, forget, garbage-collect, graph, help,
-ios-coding-standard, issue, jira, kill, language, local, local-autopilot, log,
-manual-test, model, prune-logs, prune-prompts, purge, refactor, resume, resume-local,
-review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
+ios-coding-standard, issue, jira, kill, language, log,
+manual-test, model, prune-logs, prune-prompts, purge, refactor, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
 routines, save, scan, search, setup, stack, status, steer, store-ready, sync, test,
 test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
 testflight-validation, uninstall, update

package/pipeline/commands/multi-agent/test-screenshots/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[locale]  -  boş = tr; örn. tr | en | de | ar"
 
 # /multi-agent:test-screenshots  -  Locale screenshot set
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Fixed-scenario alias, **parameterised by locale**. The scenario is pinned; the
 language is not, because one command per language would put a parameter in a name.
 

package/pipeline/commands/multi-agent/uninstall/SKILL.md

@@ -7,6 +7,8 @@ argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>
 
 # multi-agent uninstall  -  Token-Preserving Uninstall
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Uninstalls the pipeline itself from the system. **This is different from `:purge`:**
 
 | Command | What it removes |

package/pipeline/lib/repo-hygiene.sh

@@ -8,7 +8,7 @@
 # (.multi-agent/). Only the first was ever excluded, and only by a one-line
 # guard duplicated across two phase docs and gc-worktrees.sh. The other two
 # were never excluded anywhere, which is invisible in worktree mode (the
-# worktree is deleted) and permanent in --local mode (nothing deletes it).
+# worktree is deleted) and permanent with a local workspace (nothing deletes it).
 #
 # Functions:
 #   ma_hygiene_ensure_exclusions <repo-root>   Write the managed block into

package/pipeline/multi-agent-refs/analysis/render.md

@@ -64,7 +64,7 @@ Phase 3.2 produced the list. Sort every entry and act:
 | Bucket | Meaning | Action |
 |---|---|---|
 | A. Not searched | The evidence is reachable and this run did not look | Run the search; it closes, and never becomes a question |
-| B. The user knows | Channel scope, which service backs a screen, what is in scope | Ask, `AskUserQuestion`, at most 4 per call |
+| B. The user knows | Channel scope, which service backs a screen, what is in scope | Ask, `AskUserQuestion` per `picker-contract.md`, at most 4 per call |
 | C. External | Final copy, a legal basis, a contract nobody has written | Record as `AS-NN` in Section 20 |
 
 **Bucket A must be empty before Phase 3.5.** A gap reaches C only with a stamp:

package/pipeline/multi-agent-refs/analysis/resolve.md

@@ -6,7 +6,7 @@
 
 ## New Locked decisions (this command)
 
-1. **One question per `AskUserQuestion` call.** Never batch Section 20 rows. Sequential resolution keeps each decision explicit and traceable.
+1. **One question per `AskUserQuestion` call**, shaped by `picker-contract.md`. Never batch Section 20 rows. Sequential resolution keeps each decision explicit and traceable.
 2. **Up to 3 source-labeled candidates plus Defer = 4 options max.** Each candidate's `description` carries its source label: `From evidence - <doc section / citation>`, `From repo - <file:line>`, `AI reasoned - <one-line rationale>`. The auto-provided Other accepts free text and stop tokens.
 3. **Three sources, never blended.**
    - **From evidence**: the answer is already derivable from the doc's own sections and their citations (Sections 5, 6, 9, 13, 21) or from cached `state.analysisSpec.evidence.*` when the session still holds it. Cite the section or evidence bucket.

package/pipeline/multi-agent-refs/analysis/synthesis.md

@@ -34,7 +34,7 @@ synthesizedSections = {
 
 #### Phase 2a - Pass B preview (Locked 25)
 
-Before Pass B renders any file, present the resolved convention table to the user via `AskUserQuestion`. The table is one row per concept, one column per selected platform.
+Before Pass B renders any file, present the resolved convention table to the user via `AskUserQuestion` (`picker-contract.md`). The table is one row per concept, one column per selected platform.
 
 Example (iOS + Android selected):
 

package/pipeline/multi-agent-refs/analysis-template.md

@@ -830,7 +830,7 @@ Framework: iOS XCUITest (`waitForExistence`, identifier-driven); Android Compose
 
 ### 15.7 Manuel test senaryoları / Manual test scenarios
 
-The scenarios a person runs by hand. Same format the pipeline already posts as the Jira test-scenario comment (`/multi-agent:resume-local`), defined once and read by both. Omitted entirely when the feature has none (Locked 2); never rendered as an empty table.
+The scenarios a person runs by hand. Same format the pipeline already posts as the Jira test-scenario comment (`/multi-agent:resume`), defined once and read by both. Omitted entirely when the feature has none (Locked 2); never rendered as an empty table.
 
 Each row is executable by someone who did not write the feature: no "verify it works", no implied setup. Cover the happy path, at least one boundary, and every failure mode that reaches the user - the same four-way split Locked 30 requires of unit tests.
 

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -7,7 +7,6 @@
 - [Subphase contract (dispatch-layer owned)](#subphase-contract-dispatch-layer-owned)
 - [Multi-repo report](#multi-repo-report)
 - [Failure + resume](#failure-resume)
-- [Short-run behaviour](#short-run-behaviour)
 - [Cross-CLI behaviour (intentional divergence)](#cross-cli-behaviour-intentional-divergence)
 <!-- /toc -->
 
@@ -79,7 +78,6 @@ Emit `→ dispatching create-component <componentName>` via the progress contrac
 
 - `figmaUrl`  -  primary argument (the plugin skill's `<figma-url>`)
 - the component name + the analysis Section 6 (Bileşen Envanteri) row + Section 13.1 conventions as context (the plugin skill does not re-read the pipeline's analysis doc on its own  -  pass what it needs)
-- `mode`  -  `"dev"` vs `"full"`, from `state.onlyDevelop`, so the plugin can elide tests/wiki on a Short run
 
 Plugin skills are user-facing lifecycle skills; they do **not** accept an `agentState` path and do **not** write `agent-state.json`. State tracking therefore moves to the dispatch layer (next section).
 
@@ -120,12 +118,6 @@ On failure (the plugin skill returns an unrecoverable build/test error, or the d
 3. Retry re-invokes the plugin skill (it is idempotent on an existing component; it reconciles rather than duplicating). There is no bundled `phase-<N>` resume anymore.
 4. Hard kill at `retryCount === 3` → surface the errors to the user, halt Phase 2. Do not loop indefinitely.
 
-## Short-run behaviour
-
-When the Phase 0 Step 7.5 depth picker answered Short (`state.onlyDevelop === true`), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 5). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
-
-Phase 3 runs in a Short run as it does in a Full one, and its reviewer count is **not** Phase 3's concern  -  the Step 1.77 scope gate decides that from diff risk, independently of `mode`. What the dispatch layer owes Phase 4 is the record of which plugin skill it delegated to, appended to `state.telemetry.skillCalls[]`, so the review can check the delivered component against the criteria that skill imposes.
-
 ## Cross-CLI behaviour (intentional divergence)
 
 Component dispatch is **no longer byte-identical across CLIs** and that is by design (see `cross-cli-contract.md` section 1.1):

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (60 commands)](#1-command-inventory-60-commands)
+- [1. Command Inventory (57 commands)](#1-command-inventory-57-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,15 +20,15 @@
 
 ---
 
-## 1. Command Inventory (60 commands)
+## 1. Command Inventory (57 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, local, local-autopilot, log, manual-test, model, prune-logs,
-prune-prompts, purge, refactor, resume, resume-local, review,
+language, log, manual-test, model, prune-logs,
+prune-prompts, purge, refactor, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,
@@ -40,8 +40,8 @@ Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
-- **Pipeline entries**: `autopilot`, `local`, `local-autopilot` (plus the bare `/multi-agent` in the dispatcher). Depth is not a command: `/multi-agent` and `local` ask Full or Short at Phase 0 Step 7.5; the two autopilot entries never ask and always run Full.
-- **Tail modes** (run the pipeline tail over already-done local work): `resume-local`
+- **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
+- **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `complaint-analysis`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `prune-logs`, `prune-prompts`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
@@ -367,11 +367,10 @@ Given the same user input, both CLIs must produce identical parsed state:
 | `#42` or bare `42` | `input.type = "github-issue-number"`, `input.issueNo = 42` |
 | Any other string | `input.type = "free-text"`, `input.summary = <string>` |
 
-Modifier flags are orthogonal and compose:
-- `autopilot`  -  skip confirmations
-- Short depth  -  init → dev → review → test → commit → report (Phase 0 Step 7.5 picker, not a flag)
-- `--local`  -  no worktree
-- Combinations: `--local autopilot`. Short plus autopilot is NOT a combination: autopilot never asks the depth question and always runs Full.
+One modifier exists:
+- `autopilot`  -  skip confirmations, and resolve the workspace to a worktree without asking.
+
+The workspace is not a flag. Where the branch lives is a Phase 0 Step 5b question on attended runs.
 
 ---
 

package/pipeline/multi-agent-refs/features/external-context-injection.md

@@ -7,6 +7,8 @@
 - [Log line shape](#log-line-shape)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
 
 ```bash

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -63,7 +63,7 @@ DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE
 jq -c --argjson d "$DELTA_JSON" --argjson i "$((ITERATION-1))" \
   '{reviewIterations: (.reviewIterations | .[$i] += {delta: ($d + {computedAt: (now | todate)})})}' "$STATE_FILE" \
   | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.delta iteration=$ITERATION \
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.delta iteration=$ITERATION \
   new=$(jq '.counts.new // 0' <<< "$DELTA_JSON") still_present=$(jq '.counts.stillPresent // 0' <<< "$DELTA_JSON") \
   resolved=$(jq '.counts.resolved // 0' <<< "$DELTA_JSON") plateau=$(jq '.plateau // false' <<< "$DELTA_JSON") tripped=$([ "$DELTA_RC" -eq 3 ] && echo true || echo false)
 ```

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -57,9 +57,9 @@ And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives t
 
 **Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
 ```bash
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=common status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=uicomponents status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.combined_diff repos=2 bytes=$BYTES truncated=false
 ```
 
 ---

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -22,7 +22,7 @@ Phase 4 used to select its review criteria from `detectedStack`, a string Phase
 - The dev side and the review side could disagree about the standard without either noticing. A component built by a plugin skill was reviewed against `clean-code`.
 - "Did it do this correctly?" had no fixed denominator, so the only available answer was "it looks fine", and a reviewer that opened nothing produced the same output as a reviewer that checked everything.
 
-A Short run makes this sharper: it has no Phase 1 at all, so the sole input to the old selection logic was absent.
+The sharper case is a document whose evidence supported few sections: the sole input to the old selection logic was then nearly empty.
 
 ## The four rules that make it work
 

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -123,7 +123,8 @@ section still renders, saying so.
 ## 3. After  -  Phase 2, not the Phase 3 user test
 
 The user test is the natural home: the simulator is already up. It is also **dropped by
-every `autopilot` and `--local` entry** (`phase-3-review.md` TLDR), so a capture
+every `autopilot` entry and by any run whose
+workspace is local** (`phase-3-review.md` TLDR), so a capture
 that lives only there produces nothing for unattended runs - which are exactly
 the runs where nobody watched the screen.
 

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -20,7 +20,7 @@ Removing it at PR-open is only safe because of the salvage, so the two are one s
 
 | Condition | Why it blocks |
 |---|---|
-| `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
+| `worktreePath == projectRoot` (local workspace) | there is no worktree; removing it would delete the user's checkout |
 | cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 4 legitimately `cd`s into the worktree earlier |
 | not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
 | real uncommitted changes | never discarded; see the artefact carve-out below |

package/pipeline/multi-agent-refs/generate-issue.md

@@ -9,6 +9,8 @@
 
 > **TLDR**  -  Shared 12-step flow for `/multi-agent:create-jira`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Consumed by `create-jira/SKILL.md`. This ref is never invoked directly.
 
 ## Hard rules (must not regress)

package/pipeline/multi-agent-refs/issue-jira-triad.md

@@ -9,6 +9,8 @@
 - [Cross-CLI parity](#cross-cli-parity)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 > **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 5 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.

package/pipeline/multi-agent-refs/keychain.md

@@ -1,5 +1,7 @@
 ## Keychain Token Registry
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Tokens live in the platform-native credential store (macOS Keychain / Linux libsecret / Windows Credential Manager). Key names are resolved via **preferences mapping**  -  never hardcoded.
 
 ### Rule 1  -  Never prompt for a token *value* mid-run

package/pipeline/multi-agent-refs/knowledge.md

@@ -49,13 +49,6 @@ Each task teaches the project a bit more. Token cost decreases over time.
 
 They all complement each other  -  no conflicts.
 
-### Knowledge in a Short run
-
-A Short run skips Phase 1, but knowledge **is still read**:
-
-- Knowledge files are added to the prompt before the Opus agent starts in Phase 3
-- Knowledge capture is still performed in Phase 5 (simplified report)
-
 ### Knowledge Maintenance
 
 Knowledge files grow over time. Maintenance rules:

package/pipeline/multi-agent-refs/outside-the-pipeline.md

@@ -47,7 +47,7 @@ and a review between fetch and action; an ordinary session has neither.
 | Read an issue, page, log, crash, scan result | Resolve the credential and fetch |
 | Comment on Jira, edit an issue, move a board column | `/multi-agent:channels` |
 | Create an issue | `/multi-agent:create-jira` |
-| Open or update a PR | a pipeline run, or `/multi-agent:resume-local` |
+| Open or update a PR | a pipeline run, or `/multi-agent:resume` |
 
 The split is not bureaucracy. Outward writes carry rules that live in those commands:
 issues are never auto-closed (four approvals), PR bodies use `Ref:` and never