@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -17,11 +17,11 @@ pipeline/scripts/phase-tracker.sh update 0 in_progress
 
 If `INPUT_TASK_ID` isn't known yet (free-text, project not selected), use a placeholder; rename later via `mv` once parsed in Step 1.
 
-Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress` on entry and `phase-tracker.sh update <N> completed|failed|skipped` on exit. Sub-phase milestones use `phase-tracker.sh sub <N> <subN> "<name>" <status>`. See `commands/multi-agent/refs/phases.md` "Visual Phase Tracker" for the full contract.
+Every subsequent phase (1-7) MUST call `phase-tracker.sh update <N> in_progress` on entry and `phase-tracker.sh update <N> completed|failed|skipped` on exit. Sub-phase milestones use `phase-tracker.sh sub <N> <subN> "<name>" <status>`. See `$HOME/.claude/multi-agent-refs/phases.md` "Visual Phase Tracker" for the full contract.
 
 ##### TaskCreate ordering on Claude Code (strict)
 
-On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate`. Full contract: `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+On Claude Code, fire all `TaskCreate` calls in strict phase-number order (0 → 7) BEFORE any `TaskUpdate`. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ---
 
@@ -35,9 +35,9 @@ Read preferences: `PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"` (if
 OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null || echo en)
 ```
 
-From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
+From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `$HOME/.claude/multi-agent-refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
 
-**Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `refs/features/model-fallback.md` - `preferredModel` personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
+**Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `$HOME/.claude/multi-agent-refs/features/model-fallback.md` - `preferredModel` personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
 
 **First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults  -  setup never ran), show:
 ```
@@ -132,7 +132,7 @@ Results are cached in `global.serviceStatus` (existing TTL contract, default 300
    - **Continue degraded**  -  proceed on Tier 2 (REST PAT) for this run; log the downgrade.
 3. **Autopilot**: silent renewal only; if it fails, log `→ figma mcp token expired (autopilot: continuing on tier 2)` and continue degraded  -  never prompt.
 
-**Other tokens expired / rejected** → run the Expired-token decision from `refs/keychain.md` Rule 1 HERE at init (Regenerate / Use a different token / Skip and continue) instead of waiting for the first mid-run 401. A token that is structurally required for the input (e.g. the Jira PAT for a Jira-ID input) halts on skip, since Step 1 cannot fetch without it. Autopilot: skip-and-degrade semantics per Rule 1, halt only on structurally required tokens.
+**Other tokens expired / rejected** → run the Expired-token decision from `$HOME/.claude/multi-agent-refs/keychain.md` Rule 1 HERE at init (Regenerate / Use a different token / Skip and continue) instead of waiting for the first mid-run 401. A token that is structurally required for the input (e.g. the Jira PAT for a Jira-ID input) halts on skip, since Step 1 cannot fetch without it. Autopilot: skip-and-degrade semantics per Rule 1, halt only on structurally required tokens.
 
 Probe failures caused by network (timeout, DNS) are NOT treated as expiry  -  log and continue; the mid-run 401 path still exists as the safety net.
 
@@ -146,7 +146,7 @@ Classify and fetch external data:
 
 1. Extract org, repo, issueNumber from URL
 2. `gh issue view {N} -R {org}/{repo} --json title,body,labels,assignees`
-3. Scan body for Jira ID (`{JIRA_KEY}-XXXXX`) → store as jiraId. Multiple → use FIRST. **No Jira ID** → apply the **GitHub-issue Jira auto-create** policy below; result is either a newly created Jira (`jiraId` stored + GitHub issue body updated with the link) or an explicit "no Jira" decision (branch uses `feature/GH{issueNo}-{kebab}`). See `refs/issue-jira-triad.md` for the full policy, including autopilot behaviour and the `prefs.global.autoJiraFromGithubIssue` preference.
+3. Scan body for Jira ID (`{JIRA_KEY}-XXXXX`) → store as jiraId. Multiple → use FIRST. **No Jira ID** → apply the **GitHub-issue Jira auto-create** policy below; result is either a newly created Jira (`jiraId` stored + GitHub issue body updated with the link) or an explicit "no Jira" decision (branch uses `feature/GH{issueNo}-{kebab}`). See `$HOME/.claude/multi-agent-refs/issue-jira-triad.md` for the full policy, including autopilot behaviour and the `prefs.global.autoJiraFromGithubIssue` preference.
 4. Scan body for Figma URL (`figma.com/design/...`) → store as figmaUrl
 5. Auto-detect project: check `$HOME/{repo}` exists → skip Step 2
 
@@ -200,7 +200,7 @@ Sequential prompts (standard UX pattern with Recent suggestion): Project Key →
 
 #### Step 1b  -  URL Enrichment (catalogue + targeted deep fetches)
 
-After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `refs/channels/*.md`.
+After Step 1 fetches the Jira description (or free-text input), every URL in the text gets classified and catalogued. Targeted deep fetches (Crashlytics, Fortify) run when the matching link type is present; the rest (Swagger, Confluence, Figma, generic doc) are catalogued so Phase 1 (Analysis) can consume them via the typed fetchers documented in `$HOME/.claude/multi-agent-refs/channels/*.md`.
 
 ##### Step 1b.0  -  Extract context links (always runs)
 
@@ -517,7 +517,7 @@ Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
 
 | Phase   | Behavior change                                                                                          |
 | ------- | -------------------------------------------------------------------------------------------------------- |
-| Phase 3 | `component` → delegate to `pipeline/skills/figma-ios/figma-to-component` (orchestrator runs 3.0-3.8 internally); else standard TDD |
+| Phase 3 | `component` → dispatch to the enabled `ai-<platform>-engineering-toolkit` plugin's `create-component` skill (fallback `create-ui-component`); else standard TDD |
 | Phase 4 | `bugfix` → test coverage; `component` → accessibility+tokens; `refactor` → behavior preservation         |
 | Phase 6 | `bugfix`/`hotfix` → `fix(...)` prefix; `feature`/`component` → `feat(...)`; `refactor` → `refactor(...)` |
 | Phase 7 | `component` → includes SubPhase breakdown                                                                |
@@ -533,7 +533,7 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 3. If `clarityScore >= prefs.clarifyAmbiguous.minScoreToProceed` (default 6) or `stopAndAsk == false` → write `state.clarification` (score + rationale, no questions), proceed to Phase 1 silently.
 4. If `stopAndAsk == true`:
 
-   - **Interactive runs:** render the questions via `AskUserQuestion` (label + header per `refs/rules.md` Language Application matrix; `outputLanguage` for `question` + `option.description`, English for `label` + `header`). Up to `maxQuestions` questions, each with the recommended option flagged. Persist the user's answers under `state.clarification.userAnswers`.
+   - **Interactive runs:** render the questions via `AskUserQuestion` (label + header per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix; `outputLanguage` for `question` + `option.description`, English for `label` + `header`). Up to `maxQuestions` questions, each with the recommended option flagged. Persist the user's answers under `state.clarification.userAnswers`.
    - **Autopilot runs:** follow `clarifyAmbiguous.autopilotMode`:
 
      | Mode  | Behavior |
@@ -564,6 +564,6 @@ Phase 7 cost rollup carries this as a `phase 0` line item so the user sees ambig
 
 <!-- progress-contract: applied -->
 
-**Progress (per `refs/progress-contract.md`):** emit one `→ <verb> <object>` line for each of: `→ parsing input`, `→ checking token <service>`, `→ scanning project <root>`, `→ creating worktree <repo>`, `→ binding identity <name>`, `→ writing state`. When `clarifyAmbiguous.enabled`, also emit `→ scoring task ambiguity` before Step 8 and `→ asking clarifying questions <N>` when `stopAndAsk` fires.
+**Progress (per `$HOME/.claude/multi-agent-refs/progress-contract.md`):** emit one `→ <verb> <object>` line for each of: `→ parsing input`, `→ checking token <service>`, `→ scanning project <root>`, `→ creating worktree <repo>`, `→ binding identity <name>`, `→ writing state`. When `clarifyAmbiguous.enabled`, also emit `→ scoring task ambiguity` before Step 8 and `→ asking clarifying questions <N>` when `stopAndAsk` fires.
 
 **Save preferences**: Write updated prefs to `$HOME/.claude/multi-agent-preferences.json` with all Phase 0 selections.

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

@@ -3,11 +3,11 @@
 > **TLDR**  -  Fable-driven codebase exploration (Opus when the fallback ladder engages). Detects if the issue is already fixed (git blame, closed PRs), then launches parallel Explore sub-agents to map the affected code paths. Outputs: impact analysis, stack detection (auto-selects platform guide), relevant files, risk areas. Feeds Phase 2 planning.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for each Explore dispatch, each finish, analyst synthesis start, `analysis.json` write.
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for each Explore dispatch, each finish, analyst synthesis start, `analysis.json` write.
 
 #### Step 0  -  Prior Fix Detection
 
-Before any analysis, check if this issue was already fixed by someone else. Three signals (git commit grep on issue ID over 8 weeks, recent file-path history over 4 weeks, Jira/issue comments). On hit → prompt: Verify (cherry-pick path) / Stop (cleanup + `stopped_already_fixed` state) / Continue. Miss → Step 1. Full check commands, prompt block, and cleanup commands: `refs/features/prior-fix-detection.md`.
+Before any analysis, check if this issue was already fixed by someone else. Three signals (git commit grep on issue ID over 8 weeks, recent file-path history over 4 weeks, Jira/issue comments). On hit → prompt: Verify (cherry-pick path) / Stop (cleanup + `stopped_already_fixed` state) / Continue. Miss → Step 1. Full check commands, prompt block, and cleanup commands: `$HOME/.claude/multi-agent-refs/features/prior-fix-detection.md`.
 
 #### Step 1  -  Knowledge Injection (cached context)
 
@@ -75,7 +75,7 @@ Progress lines:
 
 #### Step 1.5  -  External Context Injection (`state.contextLinks[]`)
 
-Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `refs/features/external-context-injection.md`.
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
 
 **Log line shape** (progress contract):
 
@@ -107,7 +107,7 @@ This informs:
 
 #### Step 2.5  -  Repo Map Injection (advisory, opt-in)
 
-Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `pipeline/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `refs/features/repo-map.md`.
+Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `pipeline/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
 
 #### Step 3  -  Codebase Exploration
 
@@ -155,7 +155,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 1 anal
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83` for the canonical contract.
+Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83` for the canonical contract.
 
 #### Prior-Art Enrichment (advisory)
 
@@ -178,6 +178,6 @@ After every LLM call in this phase (analysis, plan generation, code/diff write,
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 1 <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 1  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 1  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-2-planning.md

@@ -3,7 +3,7 @@
 > **TLDR**  -  Fable decomposes the analysis (Opus when the fallback ladder engages) into concrete tasks with file-level targets, risk grading, and architecture review. Before Phase 3 a **Plan Approval Gate** runs in normal mode: if the Jira/issue description is ambiguous the orchestrator asks the user structured clarification questions (max 2 rounds)  -  once scope is clear it renders the plan and loops on free-text edit requests until the user approves or aborts. The gate is **skipped entirely** for `--dev`, `autopilot`, and `--dev autopilot` (their speed/zero-interaction contracts are preserved).
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md`  -  lines for plan-draft start, clarification-ask, clarification-answer, plan render, plan-edit-request, plan-approved, plan-aborted.
+Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -  lines for plan-draft start, clarification-ask, clarification-answer, plan render, plan-edit-request, plan-approved, plan-aborted.
 
 ## Phase 2 Pre-flight (BLOCKING, v9.0.0)
 
@@ -313,7 +313,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 2 plan
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
 ```
 
-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`.
 
 ---
 
@@ -325,6 +325,6 @@ After every LLM call in this phase (analysis, plan generation, code/diff write,
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <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 2  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 2  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-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)