@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

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

@@ -6,7 +6,7 @@ description: "Internal  -  multi-select repo picker for multi-agent."
 
 Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
 
-> **Language**: Per `refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: 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`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
 
 ## Steps
 
@@ -30,7 +30,7 @@ Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
    Local rows expose `localPath` (filesystem path) and a redacted `remoteUrl`
    (credentials stripped at cache time).
 
-2. **Show list** via AskUserQuestion (multiSelect=true). Print the breadcrumb narrator line first (per `refs/picker-contract.md` Step narration): `<localized: "Step 2/N: repo selection">`.
+2. **Show list** via AskUserQuestion (multiSelect=true). Print the breadcrumb narrator line first (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): `<localized: "Step 2/N: repo selection">`.
    ```
    [2/N] Select repos (multi):
      [ ] <repo-a>      (github)

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

@@ -1,6 +1,6 @@
 ## Android/Kotlin Component Generation Guide
 
-> **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 Composable 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 Composable 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 an Android UI component (Jetpack Compose), follow this architecture.
 

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

@@ -116,7 +116,7 @@ The dispatch summary line includes the comment URL with `?focusedCommentId=...`
 
 ## Wiki → Jira auto-link triad
 
-When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJiraComment === true`, the Wiki adapter also posts a humanizer-passed Jira comment summarizing wiki pages (component name + variant count + wiki URL). That secondary comment is independent of this adapter  -  both can coexist on the same issue. Full contract: `refs/issue-jira-triad.md`.
+When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJiraComment === true`, the Wiki adapter also posts a humanizer-passed Jira comment summarizing wiki pages (component name + variant count + wiki URL). That secondary comment is independent of this adapter  -  both can coexist on the same issue. Full contract: `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`.
 
 ## Hard rules (must not regress)
 

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

@@ -1,6 +1,6 @@
 # Channel adapter  -  Wiki
 
-> Detailed contract for the `wiki` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here. Full Case A/Case B handling lives in `refs/wiki-capture.md`.
+> Detailed contract for the `wiki` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here. Full Case A/Case B handling lives in `$HOME/.claude/multi-agent-refs/wiki-capture.md`.
 
 The Wiki adapter generates component documentation pages  -  main page, platform sub-pages (iOS / Android), screenshots, and index updates. It is the only channel gated by **task type** (`component` only) and the only one that writes to a separate repo (the wiki repo configured in `figma-config.json`).
 
@@ -11,7 +11,7 @@ state.taskType === "component"  AND  figmaConfig.wiki.enabled === true
 ```
 
 If both are met → **Case A** (preconditions met)  -  proceed to scope multi-select.
-Otherwise → **Case B** (preconditions missing)  -  show the menu from `refs/wiki-capture.md` (setup / skip / disable / manual-note).
+Otherwise → **Case B** (preconditions missing)  -  show the menu from `$HOME/.claude/multi-agent-refs/wiki-capture.md` (setup / skip / disable / manual-note).
 
 In multi-repo tasks, wiki scope is the **primary** repo's `figma-config.wikiRepo` (single repo). Extras are not written to wiki  -  their PRs link back via the `## Related PRs` block injected by the PR adapter.
 
@@ -34,17 +34,17 @@ The selected scope routes to a platform skill:
 
 | Platform | Skill | Notes |
 |---|---|---|
-| iOS / SwiftUI | `pipeline/skills/figma-ios/figma-component-wiki` | Reads `Configuration` + `+Modifiers` from the source, captures Figma screenshots via MCP / REST, runs Snapshot tests for iOS dark/light/RTL. |
-| Android / Compose | `pipeline/skills/figma-android/figma-component-wiki` | Reads Compose composables + previews, runs Paparazzi screenshots if available, otherwise generates from layout inspector. |
-| Generic | `pipeline/skills/figma-common/figma-component-wiki` | Used when `state.platform` is unknown (fallback path  -  typically a flag). |
+| iOS / SwiftUI | `ai-ios-engineering-toolkit:figma-component-wiki` | Reads `Configuration` + `+Modifiers` from the source, captures Figma screenshots via MCP / REST, runs Snapshot tests for iOS dark/light/RTL. |
+| Android / Compose | `ai-android-engineering-toolkit:figma-component-wiki` | Reads Compose composables + previews, runs Paparazzi screenshots if available, otherwise generates from layout inspector. |
+| Generic | `ai-ios-engineering-toolkit:figma-component-wiki` (fallback) | Used when `state.platform` is unknown (fallback path  -  typically a flag). |
 
-Full per-skill contract: `refs/wiki-capture.md`.
+Full per-skill contract: `$HOME/.claude/multi-agent-refs/wiki-capture.md`.
 
 ## Wiki → Jira auto-link triad
 
 When the adapter writes pages **AND** `state.jiraId` is set **AND** `prefs.global.wikiToJiraComment === true`, the adapter posts a humanizer-passed summary as an additional Jira comment (component name + variant count + wiki URL).
 
-This comment is **independent** of the main `jira` channel comment  -  both can coexist on the same issue. Full triad contract: `refs/issue-jira-triad.md`.
+This comment is **independent** of the main `jira` channel comment  -  both can coexist on the same issue. Full triad contract: `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`.
 
 ## Wiki adapter modes (figma-config.wiki.mode)
 

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

@@ -0,0 +1,92 @@
+# Component Dispatch (Phase 3 short-circuit)
+
+> **TLDR**  -  When `taskType === "component"` (Figma URL in task description or instruction-driven figma workflow), multi-agent Phase 3 **does not run the TDD loop**. It delegates the entire phase to the enabled `ai-<platform>-engineering-toolkit` **marketplace plugin's** component skill (`create-component`, falling back to `create-ui-component`) via the Skill tool. Implementation lives in the plugin; multi-agent's job is classification, dispatch, and state report. The pipeline no longer bundles its own `figma-to-component` orchestrator  -  component skills live in one place, the plugin marketplace.
+
+This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md`. Keeping it separate lets `phase-3-dev.md` remain tight (it's already the largest phase doc) and gives the orchestrator-report contract a stable URL for both Claude-side and Copilot-side implementations.
+
+## Entry conditions
+
+Phase 3 checks, in order:
+
+1. `agent-state.json` has `taskType: "component"` (set by Phase 0 Step 7).
+2. `agent-state.json` has a non-null `figmaUrl`.
+
+Either missing → log the anomaly to `agent-log.md` ("component dispatch expected but state incomplete"), fall through to the standard TDD path. Never silently skip the Figma work.
+
+## Plugin skill resolution
+
+```
+project.platform  → component skill (enabled marketplace plugin, Claude Code)
+──────────────────────────────────────────────────────────────────────────────
+ios               → Skill: ai-ios-engineering-toolkit:create-component
+                            (fallback: ai-ios-engineering-toolkit:create-ui-component)
+android           → Skill: ai-android-engineering-toolkit:create-component
+                            (fallback: ai-android-engineering-toolkit:create-ui-component)
+web, multi-*      → HALT with clear error (no web target)
+```
+
+**Dual-name resolution.** The public (`multi-agent-plugins`) and a corporate/private marketplace named the same skill differently  -  `create-component` vs `create-ui-component`. Dispatch tries `create-component` first; if it is not available in the current repo, tries `create-ui-component`. (Same dual-name rule applies when `taskType` maps to evolve → `evolve-component`/`evolve-ui-component`, or fix → `fix-bug`.)
+
+If **neither** resolves, the platform's `ai-<platform>-engineering-toolkit` plugin is not enabled in this repo. **Halt with a user-visible error**: "component task requires the ai-<platform>-engineering-toolkit plugin enabled in this repo (`.claude/settings.local.json`)." Do not silently fall back to TDD  -  a component task ran through the bugfix path would produce wrong artefacts.
+
+## Dispatch call
+
+Emit `→ dispatching create-component <componentName>` via the progress contract, then invoke the resolved plugin skill via the **Skill tool** with:
+
+- `figmaUrl`  -  primary argument (the plugin skill's `<figma-url>`)
+- the component name + the analysis Section 6 (Bileşen Envanteri) row + Section 13.1 conventions as context (the plugin skill does not re-read the pipeline's analysis doc on its own  -  pass what it needs)
+- `mode`  -  `"dev"` vs `"full"` communicated so the plugin can elide tests/wiki on `--dev`
+
+Plugin skills are user-facing lifecycle skills; they do **not** accept an `agentState` path and do **not** write `agent-state.json`. State tracking therefore moves to the dispatch layer (next section).
+
+## Subphase contract (dispatch-layer owned)
+
+Because the plugin skill does not write pipeline state, **multi-agent's dispatch layer owns `state.phases["3"].subphases[]`**, not the skill. On dispatch, seed one coarse component-build subphase; on return, finalize it:
+
+```json
+{
+  "id": "3.component",
+  "name": "component-build (plugin: create-component)",
+  "status": "done",
+  "startedAt": "2026-04-16T18:12:02Z",
+  "endedAt":   "2026-04-16T18:13:47Z",
+  "buildStatus": "green",
+  "testStatus": "green"
+}
+```
+
+This is the accepted behavioral change from the old bundled orchestrator: subphase granularity is coarse (one component-build row) rather than the former 3.0-3.8 breakdown, because the plugin reports at its own granularity. If the plugin emits structured progress, the dispatch layer MAY map it to finer subphase rows, but coarse is the contract floor. Multi-agent's `phase-tracker` reads the array unchanged.
+
+## Multi-repo report
+
+When multi-repo mode is active (`state.projects.length > 1`), the dispatch layer passes `state.projects[]` to the plugin skill and sequences writes across the repo graph:
+
+- Tokens, accessibility metadata, testing identifiers, localisation keys → `repos.common`
+- View / Configuration / Modifiers / Preview → `repos.components`
+- Wiki markdown → `repos.wiki` (if `wiki.mode === submodule` or `separate-repo`) or `repos.components/.wiki/components/` (if `wiki.mode === in-repo`)
+
+Multi-agent does **not** split the component task into per-repo Phase 3 runs  -  the dispatch layer sequences the plugin invocation so token writes to `common` precede component reads in `components`. If the plugin skill is not repo-graph aware, dispatch runs it against `repos.components` and performs the `common` token/key writes itself around the call.
+
+## Failure + resume
+
+On failure (the plugin skill returns an unrecoverable build/test error, or the dispatch hits retry cap):
+
+1. The dispatch layer persists `{error, buildLog, testLog}` to `state.phases["3"].errors[]`.
+2. Multi-agent increments `state.phases["3"].retryCount`.
+3. Retry re-invokes the plugin skill (it is idempotent on an existing component; it reconciles rather than duplicating). There is no bundled `phase-<N>` resume anymore.
+4. Hard kill at `retryCount === 3` → surface the errors to the user, halt Phase 3. Do not loop indefinitely.
+
+## `--dev` mode behaviour
+
+When multi-agent is invoked with `--dev` (fast path: Init → Dev → Commit → Report), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
+
+Phase 4 reviewer-skipping is **not** Phase 3's concern  -  Phase 4 decides based on `mode: "dev"` itself.
+
+## Cross-CLI behaviour (intentional divergence)
+
+Component dispatch is **no longer byte-identical across CLIs** and that is by design (see `cross-cli-contract.md` §1.1):
+
+- **Claude Code**: dispatches to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin via the Skill tool (this doc).
+- **Copilot CLI**: has no plugin loader; it continues to use its standalone `~/.copilot/skills/figma-*` skill copies (frozen fallback). Copilot's resolution + progress lines follow those local skills.
+
+What still MUST match across CLIs: the `taskType === "component"` classification, the `state.phases["3"].subphases[]` shape the dispatch layer writes, and `--dev` elision semantics. Figma-skill *inventory* parity is no longer enforced. `smoke-cross-cli-behavior.sh` asserts only the classification + state-shape axis for components.

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

@@ -28,65 +28,13 @@ Categories:
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 
-### 1.1 Figma component subphase skills
+### 1.1 Figma / component work (plugin-based on Claude Code; NOT parity-enforced)
 
-In addition to the 36 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
+Component work is **no longer a bundled pipeline skill set**. Claude Code dispatches `taskType === "component"` to the enabled `ai-<platform>-engineering-toolkit` **marketplace plugin** (`create-component`, fallback `create-ui-component`) via the Skill tool  -  full contract in `$HOME/.claude/multi-agent-refs/component-dispatch.md`. The pipeline no longer ships `pipeline/skills/figma-ios|figma-android|figma-common`; the pipeline-unique component skills (iterate loops, performance harness, validate/review, commit, adapters, wiki) were absorbed into the `ai-ios-engineering-toolkit` plugin so component skills live in one place.
 
-| Location | Skill count | Purpose |
-|---|---|---|
-| `pipeline/skills/figma-ios/` | 5 | iOS-only Phase 3 sub-skills (SwiftUI-specific) |
-| `pipeline/skills/figma-android/` | 5 | Android-only Phase 3 sub-skills (Jetpack Compose-specific) |
-| `pipeline/skills/figma-common/` | 31 | Platform-agnostic helpers (iterate / commit / wiki setup / MCP auth / performance harness / cross-cutting integration adapters / etc.) |
-
-Both Claude Code and Copilot CLI MUST expose every skill with identical argument shape, identical progress-line emission, and identical state writes. Inventory divergence (skill exists on one side but not the other) is a contract violation and blocks merge.
-
-**iOS and Android parallel set** (same 5 skill names under each platform dir):
-
-| Skill | Scope | iOS path | Android path |
-|---|---|---|---|
-| `figma-to-component` | Orchestrator (3.0-3.8) | `pipeline/skills/figma-ios/figma-to-component/` | `pipeline/skills/figma-android/figma-to-component/` |
-| `figma-component-implement` | 3.4 code gen | `pipeline/skills/figma-ios/figma-component-implement/` | `pipeline/skills/figma-android/figma-component-implement/` |
-| `figma-component-test` | 3.5 tests | `pipeline/skills/figma-ios/figma-component-test/` | `pipeline/skills/figma-android/figma-component-test/` |
-| `figma-component-code-connect` | 3.6 mapping publish | `pipeline/skills/figma-ios/figma-component-code-connect/` | `pipeline/skills/figma-android/figma-component-code-connect/` |
-| `figma-component-wiki` | 3.7 wiki (4 adapters) | `pipeline/skills/figma-ios/figma-component-wiki/` | `pipeline/skills/figma-android/figma-component-wiki/` |
-
-**Common pool** (all 31 skills under `pipeline/skills/figma-common/`  -  platform-agnostic, dispatched regardless of iOS/Android):
+**Intentional cross-CLI divergence.** Copilot CLI has no marketplace-plugin loader, so it retains its own standalone `~/.copilot/skills/figma-*` copies as a frozen fallback. Component/figma dispatch is therefore **not** byte-identical across CLIs, and figma-skill *inventory* parity is **no longer enforced**  -  this is a deliberate exception to the parity rule, not drift.
 
-| Skill | Scope |
-|---|---|
-| `figma-component-start` | Issue → branches |
-| `figma-component-confluence-sync` | 7b confluence XHTML |
-| `figma-component-status-update` | Confluence dashboard refresh |
-| `figma-commit` | 14-item review + PR |
-| `figma-iteration-commit` | Iteration/develop commit |
-| `figma-issue` | Issue + Jira auto-create |
-| `figma-iterate` | Auto batch loop |
-| `figma-cli-iterate` | CLI iterate (all phases) |
-| `figma-cli-lean-iterate` | CLI iterate (skip test+wiki) |
-| `figma-cli-iterate-mend` | Re-implement discarded |
-| `figma-cli-skip` | Mark skipped |
-| `figma-fix` | Targeted bug fix |
-| `figma-mend` | Re-implement from scratch |
-| `figma-review` | Interactive review |
-| `figma-validate` | Pre-impl validation |
-| `figma-setup` | Env wizard |
-| `figma-remote-mcp-auth` | Figma MCP OAuth |
-| `figma-ui-patterns` | Pattern index |
-| `figma-utility` | Figma data fetch |
-| `figma-skip` | Skip + update Confluence |
-| `figma-form-integration` | Form protocol adapter |
-| `figma-price-integration` | Price protocol adapter |
-| `figma-navigation` | Navigation pattern adapter (native-first / `ui.navigationSystem`) |
-| `figma-overlays` | Overlay pattern adapter (native-first / `ui.overlaySystem`) |
-| `figma-bottom-sheets` | Bottom-sheet/detent adapter (native-first / `ui.sheetSystem`) |
-| `figma-evolve-component` | Reconcile drift + additive extend (human-gated) |
-| `performance-start` | Perf-tracked component start |
-| `performance-swiftui` | Perf-optimized pipeline |
-| `performance-tour` | Batch produce components |
-| `performance-review-next` | Interactive batch review |
-| `performance-iteration-commit-all` | Batch validate + push all |
-
-Total figma skill count: **41** (5 iOS + 5 Android + 31 Common).
+What still MUST match across CLIs for component tasks: the `taskType === "component"` classification, the `state.phases["3"].subphases[]` shape the dispatch layer writes, and `--dev` elision semantics. Resolution/routing is Claude-plugin vs Copilot-local-copy by design.
 
 ### 1.2 Store-compliance skills
 
@@ -99,24 +47,9 @@ Two parallel shared/core skills under `pipeline/skills/shared/core/` wrap extern
 
 Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 4 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh` (46 assertions).
 
-### 1.2 Figma-skill routing from multi-agent
-
-Multi-agent Phase 3 resolves the orchestrator via `figmaConfig.project.platform`:
-
-- `"ios"` → `pipeline/skills/figma-ios/figma-to-component/SKILL.md`
-- `"android"` → `pipeline/skills/figma-android/figma-to-component/SKILL.md`
-- anything else → halt with a clear error
-
-Resolution logic MUST be byte-identical across CLIs. The full routing contract lives in `refs/component-dispatch.md`.
-
-### 1.3 Figma skill frontmatter MUST carry (platform-specific skills only)
-
-- `name` matching the directory name
-- `status: wip-v5` (or `stable`/`deprecated` once released)
-- `sourced-from: upstream/<orig>` or `sourced-from: derived-from/<peer-path>` for platform-specific peers
-- `platform: ios` or `platform: android` when the skill is platform-specific
+### 1.3 Figma-skill routing from multi-agent (superseded)
 
-Enforced by `smoke-figma-skill-import.sh` (iOS), `smoke-figma-android-parity.sh` (Android), `smoke-cross-cli-behavior.sh` (cross-platform inventory parity).
+Superseded by §1.1: Claude Code resolves component dispatch to the marketplace plugin (dual-name `create-component`/`create-ui-component`; full contract in `$HOME/.claude/multi-agent-refs/component-dispatch.md`); Copilot CLI uses its local `~/.copilot/skills/figma-*` copies. No shared filesystem-path routing table or figma-skill frontmatter/inventory parity remains under enforcement.
 
 ---
 
@@ -182,7 +115,7 @@ The top-level orchestrator has two deliberately different shapes on the two CLIs
 
 | Surface | File | Shape | Why |
 |---|---|---|---|
-| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines  -  thin dispatcher that routes to `refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
+| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines  -  thin dispatcher that routes to `$HOME/.claude/multi-agent-refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
 | Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
 
 **What must stay identical** (byte-level) across the two files:
@@ -293,7 +226,7 @@ Modifier flags are orthogonal and compose:
 
 ## 7. Platform Guards (macOS / Linux / WSL)
 
-Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/figma-common/` command files must be portable.
+Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
 
 For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
 
@@ -304,7 +237,7 @@ For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (
 | Clipboard read |  -  (still needs a per-platform branch  -  there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
 | Clipboard clear |  -  | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
 
-For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in figma skill bash blocks.
+For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in skill bash blocks.
 
 ---
 
@@ -316,7 +249,7 @@ This contract is validated by:
 - `smoke-commands-skills-parity.sh` (50 assertions)  -  enforces colon-form command ↔ dash-form skill directory parity
 - `smoke-compliance-skills.sh` (45 assertions)  -  enforces store-compliance skill catalog + 4 consumer wiring
 - `smoke-personal-data.sh`  -  extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs
-- `pre-push-check.sh`  -  runs both smoke tests before any push that touches `pipeline/skills/figma-common/` commands
+- `pre-push-check.sh`  -  runs the cross-CLI + personal-data smoke tests before any push that touches `pipeline/skills/shared/core/` commands
 - `sync.md` (Section 2 REPO step)  -  genericization lookup table MUST match Section 2 of this contract
 
 ---

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/features/verify-by-test.md

@@ -38,4 +38,4 @@ Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock c
 
 ## Reference
 
-Wiring: `refs/phases/phase-4-review.md` Step 3.7. Schema: `pipeline/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `pipeline/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `pipeline/schemas/prefs.schema.json`.
+Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `pipeline/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `pipeline/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `pipeline/schemas/prefs.schema.json`.

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

@@ -11,7 +11,7 @@ Consumed by `generate.md`. This ref is never invoked directly.
 - **Standard template is the baseline.** The description structure comes from the type's standard template (see [7/12]), not from a mined heading set. Mining informs summary prefix, labels, components, priority norm, sprint placement, and test-scenario style  -  never replaces the standard section skeleton.
 - **Auto-sizing.** A conditional section renders only when its trigger is present. No empty placeholder headings  -  if there is nothing to put in a conditional section, it does not appear.
 - **Issue content language follows `prefs.global.outputLanguage`.** Summary and description are written in the user's output language (intentional exception to the "external payloads stay English" default  -  the issue is authored FOR the user's team). Code identifiers, file paths, and URLs stay verbatim. AskUserQuestion `question`/`description` also follow `outputLanguage`; `label`/`header` stay English.
-- **UTF-8 verbatim POST path** (same as `refs/channels/jira.md`): description body goes to a file, `jq -n --rawfile` builds the payload, `curl --data-binary @file` ships it. Never round-trip through `unicode_escape`/`latin-1`, never hand-roll a re-encoding helper. Jira wiki markup (`h3.` headings, `[text|url]` links), real newlines, no HTML entities.
+- **UTF-8 verbatim POST path** (same as `$HOME/.claude/multi-agent-refs/channels/jira.md`): description body goes to a file, `jq -n --rawfile` builds the payload, `curl --data-binary @file` ships it. Never round-trip through `unicode_escape`/`latin-1`, never hand-roll a re-encoding helper. Jira wiki markup (`h3.` headings, `[text|url]` links), real newlines, no HTML entities.
 - **Humanizer pass** on the description body after composition, before the preview render.
 - **Read-only until approval.** Steps 1-9 perform only GET requests. The first write of any kind is the `POST /rest/api/2/issue` in step [10/12].
 
@@ -65,7 +65,7 @@ TOKEN=$(~/.claude/lib/credential-store.sh get "$ACCOUNT_JIRA_TOKEN_KEY")
 
 ### [2/12] Resolve project key
 
-Fallback chain (same as `refs/issue-jira-triad.md` Create path):
+Fallback chain (same as `$HOME/.claude/multi-agent-refs/issue-jira-triad.md` Create path):
 1. `figmaConfig.jira.projectKey` (per-project config, when running inside a configured repo)
 2. `prefs.global.defaultJiraKey`
 3. Fetch and ask:

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/issue-jira-triad.md

@@ -2,7 +2,7 @@
 
 > **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
-This doc is referenced from `refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
+This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
 
 ## The triad at a glance
 

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

@@ -21,7 +21,7 @@ When a token resolves but the service rejects it (401 / 403), do not silently sk
 
 The question asks a *choice*; the replacement value still flows through the clipboard, never chat. `smoke-no-token-prompt.sh` greps for value-prompts (`enter token`, `paste token`, `API key:`) - decision labels like `Regenerate` / `Skip and continue` do not trip it.
 
-Expiry is also checked **proactively at init**: Phase 0 Step 0.7 (`refs/phases/phase-0-init.md`) probes every token the run will need with one cheap call each (cached via `global.serviceStatus`, TTL 300s) and runs this same decision at init instead of waiting for the first mid-run 401. The mid-run 401 path stays as the safety net.
+Expiry is also checked **proactively at init**: Phase 0 Step 0.7 (`$HOME/.claude/multi-agent-refs/phases/phase-0-init.md`) probes every token the run will need with one cheap call each (cached via `global.serviceStatus`, TTL 300s) and runs this same decision at init instead of waiting for the first mid-run 401. The mid-run 401 path stays as the safety net.
 
 #### Figma MCP token lifecycle (critical)
 

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

@@ -75,7 +75,7 @@ Verdict: unverified (2 reviewers)
 
 ## Handoff - end of Phase {N} ({name}) - {ISO timestamp}
 
-(v10.8.0, appended chronologically by the phase-boundary checkpoint  -  one block per phase transition, the LATEST block is authoritative. Written by the orchestrator from state it already holds; no LLM call, ~15 lines max. `resume.md` Step 3 and post-`/compact` re-grounding read this block FIRST. Format spec: `refs/phases/operations.md`.)
+(v10.8.0, appended chronologically by the phase-boundary checkpoint  -  one block per phase transition, the LATEST block is authoritative. Written by the orchestrator from state it already holds; no LLM call, ~15 lines max. `resume.md` Step 3 and post-`/compact` re-grounding read this block FIRST. Format spec: `$HOME/.claude/multi-agent-refs/phases/operations.md`.)
 
 - Done: {up to 3 bullets of completed outcomes}
 - Remaining: {ordered list of remaining phases / sub-steps}

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

@@ -35,7 +35,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 - Phase 4 Review -> if blocking finding, returns to Phase 3, auto fix + rebuild (safety)
 - Kill/Purge confirmations -> destructive operations always ask
 - Build fail -> auto fix + rebuild (max 3 retries). After 3 retries still failing -> pause, ask user
-- **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
+- **Circuit-breaker** -> autopilot halts (records reason, waits for `resume`) on a no-progress stall, an identical repeated failure, a rework storm, cost drift past the `costBudget` ceiling, or a merge/rebase conflict. Full wiring: `$HOME/.claude/multi-agent-refs/features/autopilot-circuit-breaker.md`. This is the sanctioned autopilot pause  -  continuing unattended off the happy path is the less safe choice.
 - **Phase 7 channels dispatch** -> always pauses for multi-select. Rationale: Jira/Confluence are externally visible; silently posting wrong-tone content leaks team-visible artifacts. See below.
 
 **State tracking**: `agent-state.json` gets `"autopilot": true`. Autopilot continues on resume as well.
@@ -53,7 +53,7 @@ The generic "zero-interaction" contract covers Phases 0-6 only. Phase 7 channels
   - Resume: `/multi-agent:resume <task-id>` re-opens menu with same inputs.
 - Post-hoc `/multi-agent:channels <task>` never times out  -  user invoked it explicitly.
 
-Full contract: `refs/phases/phase-7-report.md` (Autopilot pause contract) + `commands/multi-agent/channels.md`.
+Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (Autopilot pause contract) + `commands/multi-agent/channels/SKILL.md`.
 
 ---
 

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

@@ -107,7 +107,7 @@ This keeps orchestrator context lean and enables programmatic routing.
 - Next: Phase {N+1} {name}, subStep {token or "start"}
 ```
 
-Full `agent-log.md` shape: `refs/phases/log-format.md`. Resume-side consumption: `resume.md` Step 3 reads the latest handoff FIRST, then falls back to per-phase findings for logs written before v10.8.
+Full `agent-log.md` shape: `$HOME/.claude/multi-agent-refs/phases/log-format.md`. Resume-side consumption: `resume.md` Step 3 reads the latest handoff FIRST, then falls back to per-phase findings for logs written before v10.8.
 
 **Sub-step checkpoints (long phases)**: Phase 3 (dev/TDD cycles) and Phase 7 (report/channels) can run many minutes; a crash mid-phase loses everything since the last phase boundary and forces a full phase re-run on resume. For these phases, also record `state.phases[<n>].subStep` (a short token: `red`, `green`, `build`, `pr-opened`, `confluence-synced`, ...) and the `files[]` written so far after each meaningful unit of work. On resume, re-enter the phase but skip units whose `subStep` is already recorded and whose `files[]` exist in the worktree  -  re-do only the unfinished tail, never the whole phase.
 

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.