@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/commands/multi-agent/{dev-local.md → dev-local/SKILL.md}

@@ -5,7 +5,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent dev-local  -  Fast + Local
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Dedicated form of the `--dev` + `--local` combination. A 4-phase fast pipeline (no worktree).
 
@@ -29,7 +29,7 @@ Phase 7: Report     → Jira / Wiki + log + knowledge/memory
 - A change you trust  -  no need for multi-model review
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
 
 > **Local mode:** no worktree is created, work happens on the current branch. Phase 0 Init still calls `init`  -  the `--local` flag is stored in tracker-state.json, and `:resume` restores the correct CWD.
 
@@ -57,7 +57,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
 
 ```text
 # Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
@@ -82,7 +82,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--dev local` that means: Phase 0 → Phase 3 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--dev local` that means: Phase 0 → Phase 3 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 
@@ -95,7 +95,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh render
 Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fails.
 ## Delegation
 
-Routes to the orchestrator with `--dev --local` flags. Apply the `$HOME/.claude/commands/multi-agent/dev.md` pipeline in local mode:
+Routes to the orchestrator with `--dev --local` flags. Apply the `$HOME/.claude/commands/multi-agent/dev/SKILL.md` pipeline in local mode:
 - Phase 0: skip worktree creation, continue on the current branch
 - Phase 1 (Analysis), Phase 2 (Planning + Approval Gate), Phase 4 (Review), and Phase 5 (User Test) are skipped (`--dev` + local/autopilot drop the interactive test gate)
 - Phase 3: develop on Opus (instead of the Sonnet TDD cycle)

package/pipeline/commands/multi-agent/{dev-local-autopilot.md → dev-local-autopilot/SKILL.md}

@@ -5,7 +5,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent dev-local-autopilot  -  Fastest + Local
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 The triple `--dev` + `--local` + `autopilot`  -  the fastest form available. Zero confirmations, NO worktree.
 
@@ -42,7 +42,7 @@ Routes to the orchestrator with `--dev --local autopilot` flags. The pipeline co
 ```
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
 
 > **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory  -  autopilot agent calls cannot skip it; skipping breaks `smoke-tracker-contract.sh`.
 
@@ -72,7 +72,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
 
 ```text
 # Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
@@ -97,7 +97,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--dev local autopilot` that means: Phase 0 → Phase 3 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--dev local autopilot` that means: Phase 0 → Phase 3 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/{finish.md → finish/SKILL.md}

@@ -5,7 +5,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent finish  -  Ship Local Work Through the Pipeline Tail
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 You already did the work locally  -  wrote code on the current branch and maybe tested it by hand (or ran `/multi-agent:local` / `/multi-agent:dev-local`, which skip Review + Test). `/multi-agent:finish` picks up from there and runs the **pipeline tail** over that existing local work in one command: parallel review, a build + test success gate, commit/push + PR, then the technical analysis and a **Jira comment with test scenarios**. It does NOT re-develop  -  Analysis / Planning / Dev (phases 1-3) are intentionally skipped; the diff already on the branch IS the input.
 
@@ -51,12 +51,12 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `finish` treats
 
 ## Phase execution (reuse the existing phase contracts)
 
-- **Phase 4 Review** — run per `refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
+- **Phase 4 Review** — run per `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + 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-3-style TDD fix) or proceed;
   - `autopilot` (or `prefs.global.finish.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
 - **Phase 5 Build+Test** — the **automated success gate** (this is what "build+test success" means here; the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/frontend 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 6 Commit/PR** — per `refs/phases/phase-6-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 `refs/pipeline-output-formatting` and `rules/git-conventions` — `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
-- **Phase 7 Report** — per `refs/phases/phase-7-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content for `finish`: 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.
+- **Phase 6 Commit/PR** — per `$HOME/.claude/multi-agent-refs/phases/phase-6-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/pipeline-output-formatting` and `rules/git-conventions` — `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- **Phase 7 Report** — per `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content for `finish`: 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
 
@@ -65,7 +65,7 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `finish` treats
 
 ## Required: Phase Tracker Contract
 
-**The phase tracker is required.** Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md). `finish` registers its active phase set  -  `0:Init 4:Review 5:Build+Test 6:Commit 7:Report`  -  but NEVER resets a tracker that an earlier run already built (load-or-continue; contract section "Continuation runs"):
+**The phase tracker is required.** Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md). `finish` registers its active phase set  -  `0:Init 4:Review 5:Build+Test 6:Commit 7:Report`  -  but NEVER resets a tracker that 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 -
@@ -90,7 +90,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
 
-Fresh state: register one tile per phase in strict phase-number order (`0 → 4 → 5 → 6 → 7`) 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: `refs/tracker-contract.md` "TaskCreate ordering (strict)".
+Fresh state: register one tile per phase in strict phase-number order (`0 → 4 → 5 → 6 → 7`) 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 0-3 tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta  -  same as the contract's "Resume behaviour".
 

package/pipeline/commands/multi-agent/{generate.md → generate/SKILL.md}

@@ -13,7 +13,7 @@ Creates exactly one Jira issue, and only after explicit approval. The issue type
 
 ## Issue types
 
-Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `refs/generate-issue.md` for the full A/C matrix and inclusion rules).
+Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `$HOME/.claude/multi-agent-refs/generate-issue.md` for the full A/C matrix and inclusion rules).
 
 | Type | Always-present sections | Conditional sections (included only when their trigger is present) |
 |---|---|---|
@@ -23,7 +23,7 @@ Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Eac
 
 ## Flow
 
-Read `$HOME/.claude/commands/multi-agent/refs/generate-issue.md` and execute the 11-step shared flow. Non-negotiables restated:
+Read `$HOME/.claude/multi-agent-refs/generate-issue.md` and execute the 11-step shared flow. Non-negotiables restated:
 
 - Ask the user (AskUserQuestion) for the issue type first, then about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields.
 - A conditional section renders only when its trigger is present (Figma URL, pasted screenshot/log, Swagger URL/contract, real Notes content). No empty placeholder headings; content the user did not supply and mining could not derive is never invented.
@@ -31,4 +31,4 @@ Read `$HOME/.claude/commands/multi-agent/refs/generate-issue.md` and execute the
 
 ## Error paths
 
-See `refs/generate-issue.md` Error paths. No command-specific additions.
+See `$HOME/.claude/multi-agent-refs/generate-issue.md` Error paths. No command-specific additions.

package/pipeline/commands/multi-agent/{help.md → help/SKILL.md}

@@ -115,14 +115,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
-  /multi-agent:refactor       Score project, draft an improvement plan, take approval, run dev + sync
+  /multi-agent:refactor       Adapted best-practices + bug hunt + upstream-drift check -> one plan, approval, dev + sync
 
 Setup & Maintenance:
 
   /multi-agent:setup          First-run wizard  -  Keychain tokens + Git identity + language
   /multi-agent:language [en|tr]   Show or set outputLanguage (promptLanguage stays English)
   /multi-agent:stack <id>     Select stack by enabling the matching marketplace plugin(s) (ios / android / mobile / backend / frontend / fullstack / all)
-  /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website + remote-control)
+  /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website)
   /multi-agent:update         Pull latest pipeline + reinstall + run migrations
   /multi-agent:delete         Uninstall pipeline from every CLI (Keychain tokens left intact, double confirm)
 
@@ -327,14 +327,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
-  /multi-agent:refactor       Projeyi skorla, iyileştirme planı çıkar, onay al, dev + sync çalıştır
+  /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift kontrolü -> tek plan, onay, dev + sync
 
 Setup & Maintenance:
 
   /multi-agent:setup              İlk kurulum sihirbazı  -  Keychain token + Git kimliği + dil
   /multi-agent:language [en|tr]   outputLanguage'ı göster veya ayarla (promptLanguage İngilizce kalır)
   /multi-agent:stack <id>         Stack'i eşleşen marketplace plugin'i etkinleştirerek seç (ios / android / mobile / backend / frontend / fullstack / all)
-  /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website + remote-control)
+  /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website)
   /multi-agent:update             En son pipeline'ı çek + reinstall + migration çalıştır
   /multi-agent:delete             Pipeline'ı tüm CLI'lerden kaldır (Keychain token dokunulmaz, çift onay)
 

package/pipeline/commands/multi-agent/{local.md → local/SKILL.md}

@@ -5,7 +5,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent local  -  Full Pipeline, Local Branch
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 The full pipeline in normal mode (Plan Approval Gate + parallel review + triage included), running on the **current branch with no worktree**. Dedicated alias for the `multi-agent "task" --local` flag form. Phase 5 (User Test) is skipped because there is no worktree to check the change out from; the other seven phases all run.
 
@@ -37,7 +37,7 @@ Phase 7: Report     → Jira / Wiki / Confluence + log + knowledge/memory
 
 ## Delegation
 
-This command routes to the orchestrator with the `--local` flag set. The Phase 0-7 contract from `refs/phases/phase-0-init.md` and the later phase docs applies as-is  -  only the worktree step is skipped, and `state.projects[*].worktreePath` stays `null`.
+This command routes to the orchestrator with the `--local` flag set. The Phase 0-7 contract from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` and the later phase docs applies as-is  -  only the worktree step is skipped, and `state.projects[*].worktreePath` stays `null`.
 
 Read the routing table in `$HOME/.claude/commands/multi-agent.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
 
@@ -50,7 +50,7 @@ Read the routing table in `$HOME/.claude/commands/multi-agent.md` and apply Phas
 ```
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
 
 > **Local mode:** no worktree is created, work happens on the current branch. Phase 0 Init still calls `init`  -  the `--local` flag is stored in tracker-state.json, and `:resume` restores the correct CWD.
 
@@ -78,7 +78,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
 
 ```text
 # Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
@@ -103,7 +103,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/{local-autopilot.md → local-autopilot/SKILL.md}

@@ -8,7 +8,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Run the full pipeline **without a worktree** and **with every confirmation skipped**. Phase 5 (User Test) does not run (no worktree to check out from, and no interaction), so 7 phases execute. The `autopilot + local` combination  -  vs `/multi-agent:autopilot` the only difference is no worktree (work stays on the current branch); vs `/multi-agent:local` the only difference is zero interaction.
 
@@ -68,10 +68,10 @@ Run the full pipeline **without a worktree** and **with every confirmation skipp
 
 ## Delegation
 
-Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `refs/phases/phase-0-init.md` Step 8 (local branch) + `refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
+Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
 ## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`refs/tracker-contract.md`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
 
 > **Autopilot mode:** user confirmations are skipped. The tracker is still mandatory  -  autopilot agent calls cannot skip it; skipping breaks `smoke-tracker-contract.sh`.
 
@@ -101,7 +101,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls 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, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls 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, 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)".
 
 ```text
 # Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
@@ -126,7 +126,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/{manual-test.md → manual-test/SKILL.md}

@@ -22,7 +22,7 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
    git checkout {branch-name}
    ```
 
-   Then mark the tracker as waiting (this CONTINUES the task's existing `tracker-state.json`; never `init` here - see `refs/tracker-contract.md` "Continuation runs"). On Claude Code in a fresh session, first rebuild the TaskList from state per the same contract:
+   Then mark the tracker as waiting (this CONTINUES the task's existing `tracker-state.json`; never `init` here - see `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs"). On Claude Code in a fresh session, first rebuild the TaskList from state per the same contract:
    ```bash
    bash $HOME/.claude/scripts/phase-tracker.sh update 5 in_progress
    bash $HOME/.claude/scripts/phase-tracker.sh now 5 "awaiting local test (user)"

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

@@ -0,0 +1,257 @@
+---
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, draft one plan, take approval, develop, then ask whether to sync."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch
+---
+
+# Multi-Agent Refactor
+
+**One command. Best-practices + Bug hunt + Upstream drift -> Score -> Plan -> Approval -> Develop -> Sync.**
+
+Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, scores everything, drafts a single prioritized plan, asks the user for approval, applies the approved items, and asks about sync at the end.
+
+**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", etc.)
+
+## Flow
+
+```
+Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
+Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
+Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
+Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
+Step 3:  SCORE           Each category /10, overall /100
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift), priority-ordered
+Step 5:  ASK             "Start the work?"  -  wait for user approval
+Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
+Step 7:  VERIFY          Confirm every test + lint passes
+Step 8:  ASK SYNC        "Run /multi-agent:sync?"  -  wait for user approval
+```
+
+Plan bands (all four feed the single Step 4 table):
+- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
+- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
+- **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
+- **D - Drift**: upstream updates to skills we derived from an external source.
+
+## Step 0: BEST-PRACTICES  -  research the field, adapt to us
+
+Do not copy features blindly. The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
+
+1. **Identify the domain** of the current project (read README + package/build manifests): what kind of project is it (CLI, SDK, app, pipeline, library), what stack, who uses it.
+2. **Research the best-in-class** for that exact domain:
+   - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
+   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners and tool authors actually recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
+   - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
+   - **Web**: "<domain> best practices <current-year>", official style guides, and the platform's own guidance.
+3. **For each candidate approach, record**:
+   - what it is, who does it well (source link)
+   - the concrete benefit
+   - **adaptation**: exactly how it would look in OUR repo (which file/dir/script), and what has to change for it to fit  -  not a generic "add tests" but "add a flow-assertion helper in `test/helpers/`"
+   - effort (Low/Med/High) and impact (Low/Med/High/Critical)
+4. **Discard** approaches that do not fit our stack, our scale, or our constraints  -  and say WHY (so the user sees the filter working, not just the survivors).
+
+Output (plan band A):
+```
+| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
+|--------|----------|------------------------|--------|--------|----------|
+| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
+| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
+```
+Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.
+
+## Step 0b: DRIFT  -  upstream-derived skill check
+
+Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
+
+The upstream mapping is **configuration, never hardcoded** (it can reference private sources, so it stays out of the shipped skill). Read it from `~/.claude/multi-agent-preferences.json` at `global.derivedSkillSources` (an array). Each entry:
+
+```jsonc
+{
+  "label": "<human name for this derivation>",
+  "localPath": "<repo-relative dir where our derived copy lives>",
+  "upstreamMarketplace": "<installed marketplace name>",   // resolved under ~/.claude/plugins/cache/<marketplace>/
+  "upstreamPlugin": "<plugin name>",
+  "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
+  "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
+  "upstreamRepoUrl": "<optional https url>"                // used only if the marketplace is not installed locally
+}
+```
+
+Procedure:
+1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured" (nothing to check). Never invent a source.
+2. For each entry, resolve the current upstream version:
+   - **Preferred**: read the newest installed version under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/` (its `.claude-plugin/plugin.json` `version`), plus that version's `CHANGELOG.md`.
+   - **Fallback**: if the marketplace is not installed locally and `upstreamRepoUrl` is set, `WebFetch` the upstream `plugin.json` + `CHANGELOG.md`.
+   - If neither is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole run).
+3. Compare the resolved upstream version to `derivedFromVersion`:
+   - equal -> "up to date" (no drift)
+   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs).
+4. Emit the drift table (plan band D):
+
+```
+| Derivation | Our copy (localPath) | Derived-from | Upstream now | Drift | What changed upstream |
+|------------|----------------------|--------------|--------------|-------|-----------------------|
+| <label>    | <path>               | 0.2.1        | 0.3.0        | YES   | <changelog + diff summary> |
+```
+
+5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>", with the specific skills to update. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
+
+## Step 1: SCAN
+
+```
+- file count, LOC (cloc or wc -l)
+- package.json / Package.swift / build.gradle analysis
+- dependency count (runtime vs dev)
+- Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
+- Is there test infrastructure? How many tests? Coverage?
+- Is a linter/formatter config in place?
+- Do README, LICENSE, SECURITY.md, CHANGELOG.md exist?
+- Git state: branch count, last commit date, tags
+```
+
+## Step 2: ANALYZE  -  10 categories + BUG HUNT
+
+### 2a. 10 categories (quality lens)
+
+| # | Category | What to check |
+|---|----------|---------------|
+| 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
+| 2 | **Code Quality** | Naming, magic numbers, dead code, complexity, DRY |
+| 3 | **Security** | Hardcoded secrets, input validation, Keychain, ATS, ATT |
+| 4 | **Tests** | Coverage, test pyramid, edge cases, mock/stub quality |
+| 5 | **CI/CD** | Build matrix, lint job, release automation, artifact caching |
+| 6 | **Docs** | README quality, JSDoc / Swift docs, API docs, CHANGELOG |
+| 7 | **Performance** | Bundle size, lazy loading, memory leaks, unnecessary re-renders |
+| 8 | **Accessibility** | a11y labels, tap targets, VoiceOver, Dynamic Type |
+| 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
+| 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |
+
+### 2b. BUG HUNT (real defects, not scores)
+
+Category scores measure quality; they do not find the bug that ships. Run an explicit defect hunt IN ADDITION to the scoring:
+
+- Dispatch focused review agents (Agent tool, `code-reviewer` persona where available) over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
+- For each candidate defect, record: **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
+- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones. Match the bar you would apply to a third party's code.
+
+Output (plan band B) - every confirmed defect becomes a P0/P1 item:
+```
+| # | Severity | File:line | Defect | Failure scenario |
+|---|----------|-----------|--------|------------------|
+| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
+```
+
+Improvement areas surfaced by 2a that are not outright bugs become band-C items.
+
+## Step 3: SCORE
+
+Each category is scored out of 10. Output:
+
+```
++---------------------+-------+
+| Category            | Score |
++---------------------+-------+
+| Architecture        | 9/10  |
+| Code Quality        | 8/10  |
+| Security            | 9/10  |
+| Tests               | 7/10  |
+| CI/CD               | 8/10  |
+| Docs                | 7/10  |
+| Performance         | 9/10  |
+| Accessibility       | 6/10  |
+| Dependency Mgmt     | 8/10  |
+| DevEx               | 9/10  |
++---------------------+-------+
+| TOTAL               | 80/100|
++---------------------+-------+
+```
+
+## Step 4: PLAN  -  one merged, prioritized table
+
+Merge all four bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift) so the source is visible.
+
+```
+| # | Priority | Band | Category | Item | Impact |
+|---|----------|------|----------|------|--------|
+| 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
+| 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
+| 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
+| 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
+| 5 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
+```
+
+Priority levels:
+- **P0**: bugs, security holes, broken functionality  -  must fix
+- **P1**: clear quality improvement or high-value adopted best-practice / drift port  -  should be done
+- **P2**: nice-to-have  -  if time allows
+
+## Step 5: ASK  -  user approval
+
+After showing the plan, ask:
+
+> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, and upstream drift. Should I start the work?"
+
+Options:
+- "Yes, do all"
+- "Only P0"
+- "P0 + P1 only"
+- "Only bugs (band B)"
+- (the user may pick specific items)
+
+**Never start the work without approval.**
+
+## Step 6: IMPLEMENT
+
+Apply the approved items one by one:
+
+1. For each item:
+   - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
+   - run the relevant tests
+   - on success, move to the next
+   - on failure, roll back and notify the user
+2. After all changes are done:
+   - run the full lint + test suite
+   - on success, commit
+
+Commit format: `refactor(scope): {short description}`
+
+## Step 7: VERIFY
+
+```bash
+# Lint
+npm run lint 2>/dev/null || swift build 2>/dev/null
+
+# Test
+npm test 2>/dev/null || swift test 2>/dev/null || xcodebuild test 2>/dev/null
+
+# Result
+echo "Lint: PASS/FAIL"
+echo "Test: PASS/FAIL (X/Y passed)"
+```
+
+## Step 8: ASK SYNC
+
+After every approved item is applied, ask:
+
+> "Work is complete. Should I run /multi-agent:sync?"
+
+Options:
+- "Yes" -> run the `/multi-agent:sync` command (full ecosystem sync)
+- "No" -> emit a report and stop
+- "Commit + push only" -> push the current repo without sync
+
+## Focus filter
+
+If $ARGUMENTS is set, focus on that band/category only:
+
+| Input | Focus |
+|-------|-------|
+| `bugs` | Bug hunt only (band B) |
+| `best-practices` | Field research + adapted plan only (band A) |
+| `drift` | Upstream derived-skill drift only (band D) |
+| `security` | Security analysis only |
+| `tests` | Test coverage and quality only |
+| `performance` | Performance optimisation only |
+| `docs` | Docs only |
+| `ci` | CI/CD pipeline only |
+| `deps` | Dependency updates only |
+| (empty) | Everything (default) |

package/pipeline/commands/multi-agent/{resume.md → resume/SKILL.md}

@@ -31,7 +31,7 @@ Resume a paused or failed task from the last successful phase.
      - 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; `refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
+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`.
 

package/pipeline/commands/multi-agent/{review.md → review/SKILL.md}

@@ -18,7 +18,7 @@ Skip Phase 0-3 and review a diff only. Five input shapes, two providers:
 | `https://github.com/.../pull/1250` | GitHub PR URL | Yes |
 | `https://bitbucket.<host>/projects/<KEY>/repos/<slug>/pull-requests/<N>/...` | Bitbucket Server PR URL | Yes |
 
-Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
+Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
 
 ## Steps
 
@@ -152,7 +152,7 @@ Scope note: a guide governs only files under its own directory  -  a guide found
 - Agent 2: `gpt-5.4` → edge cases, alternate perspective
 - Agent 3: `claude-sonnet-4-6` → general quality
 
-Each reviewer receives the diff, the module review guides from Step 2b (when any were found), plus the standard reviewer system prompt (see `refs/phases/phase-4-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
+Each reviewer receives the diff, the module review guides from Step 2b (when any were found), plus the standard reviewer system prompt (see `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
 
 ### 4. Store-compliance cross-reference
 
@@ -194,7 +194,7 @@ This summary ALWAYS prints, regardless of input mode. The chat is the live conve
 
 ### 7. Post to PR  -  only when input.kind === "pr"
 
-The contract (full spec: `refs/channels/pr-review-actions.md`):
+The contract (full spec: `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`):
 
 - **Decision**  -  purely from `accepted` finding counts:
   - 0 accepted blocking AND 0 accepted important → **APPROVE**
@@ -203,7 +203,7 @@ The contract (full spec: `refs/channels/pr-review-actions.md`):
 
 - **No monolith advisory comment.** "Render one big body and post via `gh pr comment`" is forbidden. Findings that need to surface on the PR become inline comments anchored to `file:line`.
 
-- **Body language follows `outputLanguage`.** Per `refs/rules.md` Language Application matrix, external payloads (PR comment bodies are external) render in `prefs.global.outputLanguage`. The renderer in `lib/post-pr-review.sh` honors this.
+- **Body language follows `outputLanguage`.** Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix, external payloads (PR comment bodies are external) render in `prefs.global.outputLanguage`. The renderer in `lib/post-pr-review.sh` honors this.
 
 Optional opt-out prompt (interactive mode only; autopilot skips and posts):
 
@@ -240,7 +240,7 @@ If the post fails (network, token, harness block), `post-pr-review.sh` exits non
 
 ### 8. Token telemetry
 
-Per the `refs/tracker-contract.md` tokens contract, after each reviewer LLM call:
+Per the `$HOME/.claude/multi-agent-refs/tracker-contract.md` tokens contract, after each reviewer LLM call:
 
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count>

package/pipeline/commands/multi-agent/{setup.md → setup/SKILL.md}

@@ -241,7 +241,7 @@ Missing token (first-time / unmapped):
   Select:
 ```
 
-Expired / rejected token (401 / 403 mid-run)  -  the Expired-token decision from `refs/keychain.md` Rule 1:
+Expired / rejected token (401 / 403 mid-run)  -  the Expired-token decision from `$HOME/.claude/multi-agent-refs/keychain.md` Rule 1:
 ```
 {Service} token expired (the service returned 401/403).
   Where to get a fresh one: {source URL/instructions}