@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases/phase-3-dev.md

@@ -1,6 +1,6 @@
 ### Phase 3: Dev (Sonnet)
 
-> **TLDR**  -  Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. `--dev` mode uses Opus self-contained (no Phase 2 plan required). `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the `figma-to-component` skill  -  see next subsection.
+> **TLDR**  -  Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. `--dev` mode uses Opus self-contained (no Phase 2 plan required). `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`)  -  see next subsection.
 
 ## Phase 3 Pre-flight (BLOCKING, v9.0.0)
 
@@ -33,19 +33,19 @@ The analysis document is the SOLE design source in Phase 3. Variant choices, pad
 
 <!-- progress-contract: applied -->
 
-**Progress (per `refs/progress-contract.md`):** every non-trivial step emits one `→ <verb> <object>` line at immediate flush. Canonical set for standard TDD: `→ reading <file>`, `→ writing test <name>`, `→ running xcodebuild RED`, `→ writing code <file>`, `→ running xcodebuild GREEN`, `→ committing WIP <summary>`. Component-task dispatch emits the line `→ dispatching figma-to-component <componentName>` immediately before the delegation call and then relays the orchestrator's subphase lines verbatim under indent `    →`.
+**Progress (per `$HOME/.claude/multi-agent-refs/progress-contract.md`):** every non-trivial step emits one `→ <verb> <object>` line at immediate flush. Canonical set for standard TDD: `→ reading <file>`, `→ writing test <name>`, `→ running xcodebuild RED`, `→ writing code <file>`, `→ running xcodebuild GREEN`, `→ committing WIP <summary>`. Component-task dispatch emits the line `→ dispatching create-component <componentName>` immediately before the Skill-tool call and then relays the plugin skill's progress lines verbatim under indent `    →`.
 
 #### Input contract
 
 Phase 3 consumes the Phase 2 output object conforming to `pipeline/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
 
-**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `refs/features/plan-todos.md`.
+**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `$HOME/.claude/multi-agent-refs/features/plan-todos.md`.
 
-**Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `refs/features/shadow-git.md`.
+**Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `$HOME/.claude/multi-agent-refs/features/shadow-git.md`.
 
 #### Component tasks  -  delegated dispatch (taskType === "component")
 
-When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the entire phase to the `figma-to-component` skill under `pipeline/skills/figma-ios/` (iOS) or `pipeline/skills/figma-android/` (Android) and does NOT run the TDD loop below. The delegated skill consumes the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component; it never re-fetches from Figma in v9.0.0. The orchestrator owns subphases 3.0 - 3.8 and writes them to `state.phases["3"].subphases[]` - multi-agent's `phase-tracker` reads that array with no special case. Dispatch contract, failure/resume semantics, multi-repo report, `--dev` elisions, and cross-CLI requirements live in `refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 3 still owns: progress line `-> dispatching figma-to-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR analysis Section 6 has no row for the named component -> log anomaly, run TDD).
+When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the entire phase to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool and does NOT run the TDD loop below. The dispatch layer passes the plugin skill the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component as context. Because plugin skills do not write pipeline state, the **dispatch layer** (not the skill) owns `state.phases["3"].subphases[]`, recording a coarse component-build row - multi-agent's `phase-tracker` reads that array with no special case. Plugin resolution (dual-name), dispatch call, failure/resume, multi-repo, `--dev` elisions, and the intentional cross-CLI divergence live in `$HOME/.claude/multi-agent-refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 3 still owns: progress line `-> dispatching create-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR the plugin is not enabled in this repo -> log anomaly, halt or run TDD per component-dispatch.md).
 
 For non-component taskTypes (`bugfix`, `feature`, `refactor`, `chore`), continue with the standard TDD section below.
 
@@ -104,7 +104,7 @@ For each task (respecting dependency order):
 3. **TDD cycle** (Launch Agent with `model: "sonnet"`):
 
    **RED  -  Write ONE failing test first:**
-   - **Rework re-entry**: if `state.reviewIterations[-1].verifyByTest.redTests[]` exists (Phase 4 Step 3.7 ran), those failing repro tests ARE the RED step for their findings  -  make them green, do not write a duplicate failing test and do not delete or weaken them. See `refs/features/verify-by-test.md`.
+   - **Rework re-entry**: if `state.reviewIterations[-1].verifyByTest.redTests[]` exists (Phase 4 Step 3.7 ran), those failing repro tests ARE the RED step for their findings  -  make them green, do not write a duplicate failing test and do not delete or weaken them. See `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
    - Test framework: use whatever the project already uses. Detect from existing test files:
      - `@Test` / `#expect` → Swift Testing
      - `XCTestCase` / `XCTAssert` → XCTest
@@ -242,7 +242,7 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 
 #### Step 3.5  -  Dev Critic (Evaluator-Optimizer, opt-in)
 
-Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap  -  **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
+Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap  -  **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `$HOME/.claude/multi-agent-refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
 
 ---
 
@@ -296,7 +296,7 @@ When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with *
 
 **Combinable with autopilot**: `--dev autopilot` = zero interaction. Init → Dev → auto-commit → auto-PR → Report.
 
-**Tracker visibility during Opus dispatch**: on Claude Code the model switch to Opus happens via subagent dispatch, and the parent widget cannot move while an Agent call is in flight. Dispatch per task from the self-generated task list (never one monolithic call for the whole phase), set the pre-dispatch `activeForm` marker, and record tokens between chunks  -  full rules in `refs/tracker-contract.md` section "Delegated phases".
+**Tracker visibility during Opus dispatch**: on Claude Code the model switch to Opus happens via subagent dispatch, and the parent widget cannot move while an Agent call is in flight. Dispatch per task from the self-generated task list (never one monolithic call for the whole phase), set the pre-dispatch `activeForm` marker, and record tokens between chunks  -  full rules in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Delegated phases".
 
 ---
 
@@ -353,7 +353,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 dev.
   tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Model resolves from the active mode: full pipeline runs Sonnet, `--dev` modes run Opus. Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
+Model resolves from the active mode: full pipeline runs Sonnet, `--dev` modes run Opus. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.
 
 ---
 
@@ -365,6 +365,6 @@ After every LLM call in this phase (analysis, plan generation, code/diff write,
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 3 <input_count> <output_count>
 ```
 
-The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
+The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
 If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases/phase-4-review.md

@@ -3,7 +3,7 @@
 > **TLDR**  -  Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: AI models in parallel  -  reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers (Fable + Sonnet); Copilot CLI dispatches 3 reviewers (GPT-5.4 + Opus + Sonnet — Fable 5 is not offered on Copilot CLI). Stage 3: Fable triage (Opus on Copilot CLI)  -  evaluates raw findings, filters false-positives/out-of-scope, keeps only actionable items. Only triage-accepted blocking items loop back to Phase 3.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
 
 #### Step 1  -  Deterministic Gates (run BEFORE AI review)
 
@@ -127,7 +127,7 @@ echo "$RISK_JSON" | node pipeline/scripts/validate-diff-risk.mjs - >/dev/null 2>
 | `migration` | 4.0 | path matches DB schema / migration glob (.sql, /Migrations/, alembic/, prisma/migrations) |
 | `public_api` | 2.0 | added line declares `public func/class/struct/enum`, `@objc`, `open fun`, `@Composable`, or `export function/class/...` |
 | `no_test_change` | 2.5 | source file changed, no paired test file (`{Base}Tests.{ext}`, `{Base}.test.{ext}`, etc.) appears in the diff |
-| `test_lines_removed` | 3.0 | test-classified file whose diff removes more lines than it adds (immutable-test backstop, see `refs/rules.md`) |
+| `test_lines_removed` | 3.0 | test-classified file whose diff removes more lines than it adds (immutable-test backstop, see `$HOME/.claude/multi-agent-refs/rules.md`) |
 | `complexity_delta` | 1.5 | added control-flow tokens (`if`/`guard`/`switch`/`while`/`for`/ternary/`&&`/`\|\|`) |
 | `ui_critical` | 1.5 | path matches `*View.swift`, `*Screen.kt`, `*Configuration.swift`, etc. |
 | `loc_changed` | 1.0 | base sensitivity to total `+/-` lines |
@@ -190,7 +190,7 @@ Launch Agent instances **in parallel** using the shared `code-reviewer` subagent
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
-**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5). Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4-6`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing-v610`. Fable dispatches are subject to the fallback contract (`refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
+**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default (Fable 5). Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4-6`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing-v610`. Fable dispatches are subject to the fallback contract (`$HOME/.claude/multi-agent-refs/features/model-fallback.md`): dispatch-error retry walks `fable -> opus -> sonnet` and budget-ceiling downgrade.
 
 **Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). On Claude Code, Reviewer 2 (GPT-5.4) is not dispatched  -  its skill column is ignored. On Copilot CLI all three columns are used.
 
@@ -205,7 +205,7 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 Skills are injected into reviewer prompt context  -  the reviewer uses them as reference, not as commands.
 
-**iOS/Swift  -  interaction & convention skills (conditional).** When the diff touches SwiftUI UI files (`*View.swift`, `*Screen.swift`, `*Configuration.swift`, `*+Modifiers.swift`), additionally inject the relevant `figma-common` convention skills as reference for the iOS reviewers: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets` (interaction: emit-intent vs self-route/self-present; native-SwiftUI-first vs the project's `ui.*` custom system), and the enriched `figma-to-swiftui` accessibility rules (minimalism). These back the Step 1.5 iOS convention checks. Generic across SwiftUI projects  -  not tied to any one app. Omit when the diff has no SwiftUI UI changes (keeps the reviewer prompt lean).
+**iOS/Swift  -  interaction & convention checks (conditional).** When the diff touches SwiftUI UI files (`*View.swift`, `*Screen.swift`, `*Configuration.swift`, `*+Modifiers.swift`), the iOS reviewers additionally apply the component/interaction conventions documented in the analysis doc (Section 14 Code Connect mapping) and, where the repo has the marketplace component toolkit enabled (`ai-ios-engineering-toolkit`), that plugin's navigation / overlay / bottom-sheet conventions (interaction: emit-intent vs self-route/self-present; native-SwiftUI-first vs the project's `ui.*` custom system) plus the component accessibility rules (minimalism). These back the Step 1.5 iOS convention checks. Generic across SwiftUI projects  -  not tied to any one app. Omit when the diff has no SwiftUI UI changes (keeps the reviewer prompt lean).
 
 **Module review guides (conditional, all stacks).** A module in the repo may carry its own CLAUDE guide  -  a convention/checklist file living somewhere in the module's directory tree that the host CLI never auto-loads. When a changed file's module has such a guide, the review must consult it. Discovery is deterministic, from the diff's changed paths: for each changed file, walk its directory chain up to the repo root and collect `CLAUDE.md`, `*-CLAUDE.md`, and `AGENTS.md` files (root-level ones excluded  -  the host CLI already loads those). Dedupe, cap at 5 (log any dropped). Inject into every reviewer prompt with the directive: read each guide before reviewing and apply its rules/checklist to the changed files under its directory  -  a guide governs only its own subtree, and guide violations are findings triaged by severity like any other. No guides found → no-op, prompt stays lean. Same contract as `/multi-agent:review` Step 2b.
 
@@ -257,7 +257,7 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
 
 **CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag  -  reviewers hallucinate, misread scope, or repeat each other. Run Fable triage (Opus on Copilot CLI) to evaluate merged findings against task scope.
 
-Opt-in empirical layer: when `prefs.global.verifyByTest.enabled` is `true`, accepted blocking findings additionally go through Step 3.7 (verify-by-test), which tries to reproduce each one with a minimal failing test before the Phase 3 rework loop fires. Full wiring: `refs/features/verify-by-test.md`.
+Opt-in empirical layer: when `prefs.global.verifyByTest.enabled` is `true`, accepted blocking findings additionally go through Step 3.7 (verify-by-test), which tries to reproduce each one with a minimal failing test before the Phase 3 rework loop fires. Full wiring: `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.
 
 ##### 3.1 Short-circuit: no findings
 
@@ -368,7 +368,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 revi
 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.completed raw_count=$RAW accepted=$ACC deferred=$DEF rejected=$REJ approved=$APPROVED duration_ms=$DURATION
 ```
 
-`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `refs/progress-contract.md#token-telemetry-forwarding-v83`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort  -  never fails the pipeline.
+`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort  -  never fails the pipeline.
 
 ##### 3.5 Optional cross-check (single-point-of-failure mitigation)
 
@@ -392,7 +392,7 @@ After the triage verdict is computed, populate `triage.consensus`:
 
 ##### 3.7 Verify-by-test (opt-in, empirical validation of blocking findings)
 
-A triage verdict is judgment; a failing repro test is proof. Runs only when `prefs.global.verifyByTest.enabled` is `true` AND `accepted` contains a `blocking` finding; otherwise skip silently. **Full contract (verdict table, cleanup invariant, prompts): `refs/features/verify-by-test.md`  -  read it before executing this step.**
+A triage verdict is judgment; a failing repro test is proof. Runs only when `prefs.global.verifyByTest.enabled` is `true` AND `accepted` contains a `blocking` finding; otherwise skip silently. **Full contract (verdict table, cleanup invariant, prompts): `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`  -  read it before executing this step.**
 
 Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 3 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 3 rework RED test; test PASSES -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on the log, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
 
@@ -495,6 +495,6 @@ After every LLM call in this phase (analysis, plan generation, code/diff write,
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count> [cached_count]
 ```
 
-The optional 4th `cached_count` is the prompt-cache-read token count when the host reports it (Anthropic `cache_read_input_tokens`); it defaults to 0 and is priced at the cheaper `cacheReadPerMtok` rate in the Phase 7 cost ledger. The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 4  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
+The optional 4th `cached_count` is the prompt-cache-read token count when the host reports it (Anthropic `cache_read_input_tokens`); it defaults to 0 and is priced at the cheaper `cacheReadPerMtok` rate in the Phase 7 cost ledger. The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 4  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
 If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases/phase-5-test.md

@@ -3,7 +3,7 @@
 > **TLDR**  -  Optional test gate. Offers to boot the simulator/emulator (UI Bug Hunter) or hand off to the user for manual QA. Skipped in `autopilot` and `--dev` modes. If issues found, loops back to Phase 3.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for local-test prompt render, user-answer capture, repo checkout (if selected).
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for local-test prompt render, user-answer capture, repo checkout (if selected).
 
 #### Step 0  -  Test Gap Report (advisory)
 
@@ -100,7 +100,7 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    bash $HOME/.claude/scripts/phase-tracker.sh now 5 "awaiting local test (user)"
    bash $HOME/.claude/scripts/phase-tracker.sh render
    ```
-   The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:finish` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`refs/tracker-contract.md` "Continuation runs").
+   The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:finish` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs").
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
@@ -146,4 +146,4 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 5 audi
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-If Phase 5 is purely user-driven (no sub-agent ran), no token forwarding is required and the cost block stays empty for this phase. Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
+If Phase 5 is purely user-driven (no sub-agent ran), no token forwarding is required and the cost block stays empty for this phase. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases/phase-6-commit.md

@@ -3,7 +3,7 @@
 > **TLDR**  -  Commit with conventional message + ticket ID, push, open PR. Order: (1) identity confirm → (2) commit → (3) push → (4) fetch default reviewers → (5) ask DRAFT-or-READY → (6) build payload with heredoc+rawfile → (7) POST with `reviewers`+`fromRef`+`toRef`+`draft` required on Bitbucket (missing fields wipe defaults).
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for each per-repo squash, commit, push attempt (including retries), PR body generate, PR create, Jira comment post.
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for each per-repo squash, commit, push attempt (including retries), PR body generate, PR create, Jira comment post.
 >
 > ```
 >   commit ──► push ──► fetch default reviewers ──► draft/ready prompt
@@ -23,7 +23,7 @@ The "Build passes" checklist item below is evidence-gated, not self-asserted: Ph
 
 **Fires only when** `state.projects.length >= 2` (multi-repo task). Single-repo tasks skip this step silently  -  no prompt, no overhead.
 
-Full contract: `refs/multi-repo-integration-build.md`. Summary:
+Full contract: `$HOME/.claude/multi-agent-refs/multi-repo-integration-build.md`. Summary:
 
 1. Sort touched-repo basenames → `repoSet`.
 2. Look up `prefs.global.multiRepoIntegrationHosts[]` for matching `repoSet`.
@@ -64,7 +64,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 **Standard path (also used as fallback when instructionDriven=true but file missing):**
 
-1. **Local checkout test prompt** (skip in autopilot): If still in worktree AND Phase 5 was skipped, ask the user. Per `refs/rules.md` Language Application matrix: `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Render the picker accordingly:
+1. **Local checkout test prompt** (skip in autopilot): If still in worktree AND Phase 5 was skipped, ask the user. Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix: `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Render the picker accordingly:
    - `question` (in `outputLanguage`)  -  semantically: "Run a quick WIP-checkout test before commit?"
    - `header` (English, ≤12 chars): `"WIP checkout"`
    - `options` (description in `outputLanguage`, label in English):
@@ -338,4 +338,4 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 6 pr.b
   model=<sonnet|opus> tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
+Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases/phase-7-report.md

@@ -1,9 +1,9 @@
 ### Phase 7: Report
 
-> **TLDR**  -  Close the loop in two halves: **External delivery** delegated to `/multi-agent:channels` (multi-select kanal + content  -  always pauses in autopilot, 30-min timeout ends session). **Internal capture** stays inline: `agent-log.md` finalization, telemetry emission, knowledge base + memory update. Channels command is the single source of truth for Jira/Confluence/Wiki/PR-description delivery  -  full contract in `commands/multi-agent/channels.md`.
+> **TLDR**  -  Close the loop in two halves: **External delivery** delegated to `/multi-agent:channels` (multi-select kanal + content  -  always pauses in autopilot, 30-min timeout ends session). **Internal capture** stays inline: `agent-log.md` finalization, telemetry emission, knowledge base + memory update. Channels command is the single source of truth for Jira/Confluence/Wiki/PR-description delivery  -  full contract in `commands/multi-agent/channels/SKILL.md`.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for channels dispatch entry, per-adapter result, agent-log finalization, telemetry emission, knowledge+memory write.
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for channels dispatch entry, per-adapter result, agent-log finalization, telemetry emission, knowledge+memory write.
 
 ## Sub-step Tracking (required)
 
@@ -22,7 +22,7 @@ On entry: `phase-tracker.sh sub 7 <N> "<name>" in_progress`. On exit: `completed
 
 ## Autopilot pause contract
 
-Phase 7 is the single exception to the autopilot zero-interaction rule. Full contract in `refs/phases/modes.md`:
+Phase 7 is the single exception to the autopilot zero-interaction rule. Full contract in `$HOME/.claude/multi-agent-refs/phases/modes.md`:
 
 - **Normal / `--dev` / `autopilot`**  -  ALL modes pause at the channels multi-select menu.
 - **30-min timeout**  -  if user does not respond, session ends cleanly. External delivery is aborted (no silent apply of defaults  -  prevents accidental Jira comments / Confluence pages). Internal capture (Steps 2 + 3 below) STILL runs so `agent-log.md` + knowledge base are persisted.
@@ -66,7 +66,7 @@ Channels command reads this bundle, skips its own target-resolution step, goes s
 For every UI atom touched by the diff, the PR description, Jira comment, and Confluence page body MUST embed the Figma frame reference and screenshot URL. Channels adapters read `state.evidence.figma[]` and render a `## Figma reference` block per channel:
 
 - **PR description**  -  one row per frame: `<canonicalComponentName>  <fileKey>:<nodeId>  [screenshot](<screenshotUrl>)`.
-- **Jira comment**  -  same row shape; image macros may be added when the Jira project allows direct image embedding (see `refs/channels/jira.md`).
+- **Jira comment**  -  same row shape; image macros may be added when the Jira project allows direct image embedding (see `$HOME/.claude/multi-agent-refs/channels/jira.md`).
 - **Confluence page**: frame screenshots are uploaded as page attachments (cache locally first because Tier 2 signed URLs expire after 30 days) and referenced inline via `<ac:image><ri:attachment ri:filename="frame-<nodeId>.png"/></ac:image>`.
 
 Tier 3 rows append `(tier 3: pending design review)` after the canonical component name so reviewers know the choice is provisional. The block is suppressed when `state.evidence.figma[]` is empty (non-UI tasks).
@@ -99,7 +99,7 @@ Tracker: `phase-tracker.sh sub 7 1 "Channels dispatch" completed` (or `failed` i
 
 ## Step 1.5  -  GitHub Issue channel (when tracker is a GitHub issue)
 
-Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue  -  no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `refs/channels/issue-comment.md`.
+Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue  -  no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `$HOME/.claude/multi-agent-refs/channels/issue-comment.md`.
 
 **Approval gate:** interactive runs show the composed comment body (and the Progress-flag diff intent) through the same preview + approval gate as channels Step 6 (`channels.md`) before posting  -  Approve & post / Edit / Cancel. Autopilot posts directly.
 
@@ -131,7 +131,7 @@ The Progress flag values come from `state.flags`:
 
 Each value is `true` (🟢), `"yellow"` (🟡), or `false`/missing (⚪). Phase 3 / 5 / 6 are responsible for setting these honestly  -  Phase 7 only mirrors what's already in state.
 
-**Hard rule (per `refs/channels/issue-comment.md`):** never run only one of the two actions. The comment is the human-readable audit; flags are the machine-readable status. Either both or neither.
+**Hard rule (per `$HOME/.claude/multi-agent-refs/channels/issue-comment.md`):** never run only one of the two actions. The comment is the human-readable audit; flags are the machine-readable status. Either both or neither.
 
 ---
 

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/phases.md

@@ -4,17 +4,17 @@
 
 | Phase                             | File                                                                 |
 | --------------------------------- | -------------------------------------------------------------------- |
-| Modes (autopilot, --dev, --local) | `$HOME/.claude/commands/multi-agent/refs/phases/modes.md`            |
-| Operations (kill, purge, resume)  | `$HOME/.claude/commands/multi-agent/refs/phases/operations.md`       |
-| Phase 0: Init                     | `$HOME/.claude/commands/multi-agent/refs/phases/phase-0-init.md`     |
-| Phase 1: Analysis                 | `$HOME/.claude/commands/multi-agent/refs/phases/phase-1-analysis.md` |
-| Phase 2: Planning                 | `$HOME/.claude/commands/multi-agent/refs/phases/phase-2-planning.md` |
-| Phase 3: Dev              | `$HOME/.claude/commands/multi-agent/refs/phases/phase-3-dev.md`      |
-| Phase 4: Review                   | `$HOME/.claude/commands/multi-agent/refs/phases/phase-4-review.md`   |
-| Phase 5: Test                | `$HOME/.claude/commands/multi-agent/refs/phases/phase-5-test.md`     |
-| Phase 6: Commit & PR              | `$HOME/.claude/commands/multi-agent/refs/phases/phase-6-commit.md`   |
-| Phase 7: Report                  | `$HOME/.claude/commands/multi-agent/refs/phases/phase-7-report.md`  |
-| Log format                        | `$HOME/.claude/commands/multi-agent/refs/phases/log-format.md`       |
+| Modes (autopilot, --dev, --local) | `$HOME/.claude/multi-agent-refs/phases/modes.md`            |
+| Operations (kill, purge, resume)  | `$HOME/.claude/multi-agent-refs/phases/operations.md`       |
+| Phase 0: Init                     | `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md`     |
+| Phase 1: Analysis                 | `$HOME/.claude/multi-agent-refs/phases/phase-1-analysis.md` |
+| Phase 2: Planning                 | `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` |
+| Phase 3: Dev              | `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md`      |
+| Phase 4: Review                   | `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md`   |
+| Phase 5: Test                | `$HOME/.claude/multi-agent-refs/phases/phase-5-test.md`     |
+| Phase 6: Commit & PR              | `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md`   |
+| Phase 7: Report                  | `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md`  |
+| Log format                        | `$HOME/.claude/multi-agent-refs/phases/log-format.md`       |
 
 ## Pipeline Flow
 
@@ -107,7 +107,7 @@ bash phase-tracker.sh update <N> completed
 
 `--dev` mode does NOT TaskCreate phases 1/2/4 at all  -  those phases are not part of the `--dev` set (`0:Init 3:Dev 5:Test 6:Commit 7:Report`). Only register tiles for the active mode's phase set. (Earlier guidance suggested pre-marking 1/2/4 with `[SKIPPED]` activeForm; that produces visually scrambled tile stacks  -  see the v8.3.1 ordering rule below.)
 
-**(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 **Copilot CLI / plain shell**: do NOT call TaskCreate  -  the tool does not exist on these CLIs. Instead, after every state update, call `bash phase-tracker.sh render` so the bordered ANSI card prints as the last tool result. That's the equivalent visual signal there.
 

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/progress-contract.md

@@ -2,7 +2,7 @@
 
 > **TLDR**  -  Every non-trivial pipeline action emits an inline "I'm doing X right now" line so the user always knows what's happening. Immediate flush, no batching. One line per action, standard shape. Autopilot prefers verbose. Low overhead. Mirrored in telemetry as `progress.step` events.
 
-This contract is consumed by every phase (0-7) and every imported skill (figma-ios, figma-android). It is enforced by `smoke-progress-contract.sh`  -  any phase doc that drops the contract marker or diverges from the line shape fails CI.
+This contract is consumed by every phase (0-7) and every dispatched sub-skill (including the marketplace component toolkits when enabled). It is enforced by `smoke-progress-contract.sh`  -  any phase doc that drops the contract marker or diverges from the line shape fails CI.
 
 ---
 
@@ -21,7 +21,7 @@ Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence fo
 - **verb**  -  lowercase present participle or imperative, one word: `fetching`, `reading`, `running`, `writing`, `posting`, `waiting`, `dispatching`, `retrying`, `building`, `committing`, `checking`.
 - **object**  -  what is being acted on: file basename, API endpoint last segment, subagent name, command, smoke name.
 - **target**  -  optional, human-readable scope: repo name, ticket ID, URL host.
-- **Live mirror to the phase tracker**: each `normal`-tier emitted line is also mirrored to the active phase per `refs/tracker-contract.md` "Active phase" (Claude Code `TaskUpdate activeForm`, other CLIs `phase-tracker.sh now`) - the authoritative throttling rules live there.
+- **Live mirror to the phase tracker**: each `normal`-tier emitted line is also mirrored to the active phase per `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Active phase" (Claude Code `TaskUpdate activeForm`, other CLIs `phase-tracker.sh now`) - the authoritative throttling rules live there.
 
 ### Examples
 
@@ -69,7 +69,7 @@ Emit a progress line **at least** at every one of these moments:
 ### Phase 3 (Dev  -  non-component)
 - every TDD cycle step: read-target, write-test, run-test RED, write-code, run-test GREEN, run-build, wip-commit.
 
-### Phase 3 (Component  -  figma-to-component subphases)
+### Phase 3 (Component  -  create-component plugin dispatch)
 - subphase dispatch, Figma API call, token mapping, file write per artifact, build step, REVIEW.md gate.
 
 ### Phase 4 (Review)
@@ -157,7 +157,7 @@ The check is a silent no-op (exit 0) when the budget is disabled or no tracker d
 
 ## Phase adoption marker
 
-Every phase doc under `refs/phases/` must contain the marker line exactly once:
+Every phase doc under `$HOME/.claude/multi-agent-refs/phases/` must contain the marker line exactly once:
 
 ```
 <!-- progress-contract: applied -->

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/swiftui-guide.md

@@ -1,6 +1,6 @@
 ## SwiftUI Component Generation Guide (Generic)
 
-> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `pipeline/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
+> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `pipeline/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating a SwiftUI component (any project), follow this architecture.
 These practices come from the battle-tested Figma-to-SwiftUI pipeline  -  apply them in every iOS project.

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/tracker-contract.md

@@ -190,7 +190,7 @@ Throttling rules: mirror only canonical-set lines (`verbose`-tier internals are
 
 ### Delegated phases  -  mirror limitation + chunked dispatch (required)
 
-When a phase's work is delegated to a subagent (Phase 3 Dev on Opus in `--dev` modes, `figma-to-component` dispatch, Phase 1 explorers, Phase 4 reviewers), the visual channel freezes for the duration of the Agent call: the orchestrator is blocked while the call is in flight, so it cannot fire `TaskUpdate` / `now` / `tokens`, and a subagent cannot drive the parent session's TaskList (its own TaskCreate/TaskUpdate calls land on an invisible child list). The progress-line mirror above can therefore only fire while the orchestrator holds control. Rules:
+When a phase's work is delegated to a subagent (Phase 3 Dev on Opus in `--dev` modes, `create-component` plugin dispatch, Phase 1 explorers, Phase 4 reviewers), the visual channel freezes for the duration of the Agent call: the orchestrator is blocked while the call is in flight, so it cannot fire `TaskUpdate` / `now` / `tokens`, and a subagent cannot drive the parent session's TaskList (its own TaskCreate/TaskUpdate calls land on an invisible child list). The progress-line mirror above can therefore only fire while the orchestrator holds control. Rules:
 
 1. **Pre-dispatch marker.** Immediately before every Agent call, set the active-phase line to the delegation itself, so the frozen interval at least states what is running and on which model:
    - Claude Code: `TaskUpdate({activeForm: "Dev subagent (opus): <task subject>"})`
@@ -314,7 +314,7 @@ A pre-existing `tracker-state.json` for the task is never re-initialized. Rules
 
 ## Cross-reference
 
-- `refs/phases.md` section "Visual Phase Tracker" (canonical spec)
-- `refs/progress-contract.md` (one-line stdout format, runs alongside the tracker)
+- `$HOME/.claude/multi-agent-refs/phases.md` section "Visual Phase Tracker" (canonical spec)
+- `$HOME/.claude/multi-agent-refs/progress-contract.md` (one-line stdout format, runs alongside the tracker)
 - `pipeline/scripts/phase-tracker.sh` (state file CRUD)
 - `pipeline/scripts/run-aggregator.mjs` (post-hoc cost summary)

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/wiki-capture.md

@@ -2,7 +2,7 @@
 
 > **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.
 
-This doc is referenced from `commands/multi-agent/channels.md` (Wiki adapter) and indirectly from `refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
+This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
 
 ## Applicability
 
@@ -77,9 +77,9 @@ Save the answer to `prefs.global.wikiDefault` for next run. Migration script (`m
 
 ## Dispatch
 
-1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see `pipeline/skills/figma-ios/figma-component-wiki/SKILL.md` for per-mode path layout and push semantics.
+1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see the `ai-ios-engineering-toolkit:figma-component-wiki` plugin skill for per-mode path layout and push semantics.
 2. Emit progress line: `→ writing wiki {componentName} (mode: {mode})`.
-3. Dispatch to `pipeline/skills/figma-ios/figma-component-wiki` (iOS) or `pipeline/skills/figma-android/figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig, agentState}`.
+3. Dispatch to the plugin skill `ai-ios-engineering-toolkit:figma-component-wiki` (iOS) or `ai-android-engineering-toolkit:figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig}`.
 4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 7 summary's "Files written" section and push metadata (if any) to "External publishes".
 5. On adapter failure  -  log the adapter + mode + error, continue Phase 7. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.
 
@@ -107,6 +107,6 @@ Claude Code and Copilot CLI MUST:
 - Render byte-identical Case A / Case B menus (spacing, brackets, numbering).
 - Respect `prefs.global.wikiScope` array. Legacy `wikiDefault` boolean is migrated on first v5.7 load.
 - Treat adapter failures as non-blocking with the same log shape.
-- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
+- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`$HOME/.claude/multi-agent-refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
 
 `smoke-wiki-integration.sh` asserts every contract item documented above.

package/pipeline/preferences-template.json

@@ -71,7 +71,8 @@
       "warnPct": 80,
       "onExceed": "warn",
       "pricingModel": "opus"
-    }
+    },
+    "derivedSkillSources": []
   },
   "projects": {},
   "_figmaConfigTemplate": {
@@ -153,5 +154,20 @@
       "complex": "opus",
       "overrides": {}
     }
+  },
+  "_derivedSkillSourcesTemplate": {
+    "_comment": "Optional. Populate global.derivedSkillSources[] to let /multi-agent:refactor check whether skills you derived from an upstream marketplace plugin have been updated. Kept in your LOCAL prefs only (never synced), so it may reference private sources. Copy an entry like the one below.",
+    "_example": {
+      "label": "Component toolkit skills",
+      "localPath": "plugins/<my-plugin>/skills/workflow",
+      "upstreamMarketplace": "<installed-marketplace-name>",
+      "upstreamPlugin": "<upstream-plugin-name>",
+      "upstreamSkills": [
+        "<skill-a>",
+        "<skill-b>"
+      ],
+      "derivedFromVersion": "0.0.0",
+      "upstreamRepoUrl": "https://github.com/<org>/<repo>"
+    }
   }
 }

package/pipeline/rules/figma-pipeline.md

@@ -1,6 +1,6 @@
 ## Figma -> Component Generation
 
-Skill set under `pipeline/skills/figma-ios/` (iOS), `pipeline/skills/figma-android/` (Android), and `pipeline/skills/figma-common/` (shared). Activated when the task contains a Figma URL and target files are `.swift` (iOS) or `.kt` (Android).
+Skill set lives in the marketplace plugins  -  `ai-ios-engineering-toolkit` (iOS/SwiftUI) and `ai-android-engineering-toolkit` (Android/Compose). Activated when the task contains a Figma URL and target files are `.swift` (iOS) or `.kt` (Android).
 
 ### MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)
 
@@ -190,7 +190,7 @@ Phase 3.3: figma-iteration-commit     → Batch iteration commit (if iterating)
 | Wiki | enabled/disabled | `wiki.enabled` |
 | Figma API | MCP / REST fallback | `figma.mcpEnabled` |
 
-Provider interfaces are defined inline in the platform skill sets  -  see `pipeline/skills/figma-common/`, `pipeline/skills/figma-ios/`, and `pipeline/skills/figma-android/`.
+Provider interfaces are defined inline in the plugin skill sets  -  see the `ai-ios-engineering-toolkit` and `ai-android-engineering-toolkit` marketplace plugins.
 
 ### Optional Features (graceful skip when disabled)
 

package/pipeline/schemas/prefs.schema.json

@@ -613,40 +613,6 @@
           "default": true,
           "description": "When the Wiki channel produces component wiki content AND a Jira issue is linked (`state.jiraId` set), also post a humanizer-passed summary of the wiki content as a Jira comment so QA + PMs see the component docs inline. Independent of `reportChannels.jira` (which controls whether the main Jira comment runs). Set `false` to suppress only the wiki-summary comment."
         },
-        "figmaSource": {
-          "type": [
-            "object",
-            "null"
-          ],
-          "additionalProperties": false,
-          "description": "Upstream figma-to-component source for incremental sync (WS-9). Set manually by users who maintain a separate source project and want `/multi-agent:sync` to keep `pipeline/skills/figma-ios/` in step. Null = no sync, import was one-shot.",
-          "properties": {
-            "path": {
-              "type": "string",
-              "description": "Absolute path to the source project root (expects `.instructions/figma/` and `.claude/skills/` subtrees)."
-            },
-            "branch": {
-              "type": "string",
-              "default": "develop",
-              "description": "Source branch to pull from."
-            },
-            "lastSyncedAt": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "format": "date-time",
-              "description": "ISO timestamp of the most recent successful sync."
-            },
-            "lastCommit": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "description": "Source commit SHA captured at the most recent successful sync. Used as the floor for incremental diff."
-            }
-          }
-        },
         "promptLanguage": {
           "type": "string",
           "enum": [

package/pipeline/scripts/README.md

@@ -15,7 +15,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-figma-cross-cli-inventory.sh`  -  figma skill cross-CLI source-tree parity (39 assertions)
 
 ### Figma pipeline (see `pipeline/scripts/README-figma-smokes.md` for the full index)
-- `smoke-figma-android-parity.sh`, `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`, `smoke-figma-skill-import.sh`, `smoke-figma-sync.sh`
+- `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`
 
 ### Phase contracts
 - `smoke-phase-0-multi-repo.sh`  -  Phase 0 multi-repo mode fetch + worktree atomicity
@@ -78,8 +78,6 @@ Shell scripts invoked during pipeline execution.
 - `search-logs.sh`  -  backs `/multi-agent:search`
 - `scan-skills.sh`  -  backs `/multi-agent:scan`
 - `benchmark-phase-0.sh`  -  Phase 0 perf harness
-- `sync-figma-source.sh`  -  WS-9 source sync (figma)
-- `import-figma-skills.sh`  -  developer-only import harness (not run at runtime)
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
 - `sync-parity-check.sh`  -  manual parity verification helper
 

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,16 +1,17 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	92
+.claude/commands	42
 .claude/lib	24
 .claude/multi-agent-preferences.json	1
+.claude/multi-agent-refs	50
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	180
+.claude/scripts	177
 .claude/settings.json	1
-.claude/skills	572
+.claude/skills	428
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	24
 .copilot/schemas	23
-.copilot/scripts	180
-.copilot/skills	609
+.copilot/scripts	177
+.copilot/skills	465

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -97,7 +97,7 @@ const skipNote = skippedIds.length > 0
   ? `${modeLabel} mode does NOT TaskCreate phases ${skippedIds.join("/")}  -  those are not part of the ${modeLabel} phase set (\`${spec.phases.join(" ")}\`). Only register tiles for the active set.`
   : `${modeLabel} mode TaskCreates all 8 phases (no phase is skipped).`;
 
-const orderingNote = `**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. 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)".`;
+const orderingNote = `**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. 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)".`;
 
 const localCaveat = spec.local
   ? `\n> **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.\n`
@@ -109,7 +109,7 @@ const banner = spec.autopilot
 
 const out = `## 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).
 ${banner}${localCaveat}
 Two channels run in parallel at every phase boundary:
 
@@ -135,7 +135,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: