@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

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

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

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

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

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

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

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

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

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

@@ -31,7 +31,7 @@ Resume a paused or failed task from the last successful phase.
      - Phase 3 code → already in the worktree
    - Recent `git log --oneline -10` in the worktree grounds what was actually committed vs. claimed.
 
-4. **Rebuild the phase tiles**  -  load `tracker-state.json` for the task (never re-init it; `refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
+4. **Rebuild the phase tiles**  -  load `tracker-state.json` for the task (never re-init it; `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
    - Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
    - Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
 

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

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

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

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

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

@@ -1,5 +1,5 @@
 ---
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and remote-control."
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
 argument-hint: "[release] [--platform=<macos|linux|windows>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 ---
@@ -8,13 +8,13 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 
 **One command. Full ecosystem sync. No arguments needed.**
 
-When invoked, it synchronizes all 7 targets in order. It detects what changed, updates only the stale ones, and returns a result report. The host platform (macOS / Linux / Windows) is auto-detected; all dispatch commands stay platform-agnostic through `~/.claude/lib/credential-store.sh`.
+When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and returns a result report. The host platform (macOS / Linux / Windows) is auto-detected; all dispatch commands stay platform-agnostic through `~/.claude/lib/credential-store.sh`.
 
 **Input**: $ARGUMENTS (optional)
 
 | Arg | Meaning |
 |---|---|
-| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, remote-control. |
+| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website. |
 | `release` | Full sync + version bump + tag + npm publish + website deploy |
 | `--platform=<macos\|linux\|windows>` | Override automatic platform detection. For CI / cross-platform smoke. |
 | `"change description"` | Apply the description to every target at once |
@@ -23,12 +23,10 @@ When invoked, it synchronizes all 7 targets in order. It detects what changed, u
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 0 | Figma source (deprecated) | `prefs.global.figmaSource.path` | skip (see memory `feedback_figma_source_deprecated`) |
 | 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
-| 5 | Remote Control | `{owner}/remote-control` | <- pipeline references |
 
 ## Platform Support (macOS / Linux / Windows)
 
@@ -55,7 +53,6 @@ The sync skill must run on all three platforms. Commands go through the platform
 Run every step automatically:
 
 ```
-Step 0: FIGMA_SYNC  SKIP (deprecated  -  feedback_figma_source_deprecated)
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
 Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 36 sub-command skills)
@@ -63,38 +60,10 @@ Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scr
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
-Step 5: REMOTE      Pipeline references -> remote-control README
-Step 6: Commit      Commit + push all changed repos
-Step 7: Report      Summary: synced targets, platform, changed files, deploy status
+Step 5: Commit      Commit + push all changed repos
+Step 6: Report      Summary: synced targets, platform, changed files, deploy status
 ```
 
-### Step 0  -  Figma source sync (opt-in)
-
-If `prefs.global.figmaSource.path` is set, run a plan-driven figma sync BEFORE any other step:
-
-```bash
-# 1. Once plan:
-bash "$REPO_ROOT/pipeline/scripts/sync-figma-source.sh" --plan
-
-# 2. Review the plan (.last-figma-sync-plan.json), confirm overlay skips,
-#    and approve the figma-ios vs figma-common routing for new upstream skills.
-
-# 3. If approved, apply:
-bash "$REPO_ROOT/pipeline/scripts/sync-figma-source.sh"
-```
-
-- **Plan-driven flow**: `--plan` once rebuilds the "what would change" view  - 
-  upstream skill → local name (post-rename) → target tree (figma-ios vs
-  figma-common) → overlay-skip status. Writes `.last-figma-sync-plan.json`.
-  Apply mode (no flag) executes the plan.
-- Script is idempotent  -  incremental, uses the `lastCommit` watermark.
-- Updates the figma-ios / figma-common skills (transform + placeholder).
-- Files marked `local-overlay: true` are preserved (they appear as `overlaySkip: true` in the plan).
-- figma-android/ trees are NOT touched (no upstream source today).
-- Appends a `### Sync YYYY-MM-DD (@ sha)` block to CHANGELOG.md.
-- The output of this step is committed in Step 3 (REPO).
-- If `figmaSource.path` is unset, the step is silently skipped.
-
 If nothing is stale → report "All targets up to date" and stop.
 
 ## Special inputs
@@ -142,6 +111,7 @@ If nothing is stale → report "All targets up to date" and stop.
    ```
    ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
+   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
    ~/.claude/agents/*.md                  -> pipeline/agents/
    ```
@@ -150,6 +120,16 @@ If nothing is stale → report "All targets up to date" and stop.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
+   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** — these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
+     ```bash
+     # backstop: no local-only wrapper may exist in the synced target
+     grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
+     # backstop: no corporate marketplace/skill reference in the synced tree
+     grep -rniE "ai-ios-engineering-toolkit:(create-ui-component|evolve-ui-component|component-wiki|figma-setup|resource-utility)" \
+       ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
+     ```
 
 6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
    ```bash
@@ -233,23 +213,6 @@ git push origin main  # Vercel auto-deploy
 
 ---
 
-## Remote Control Sync (Step 5)
-
-```bash
-REMOTE_DIR="$HOME/remote-control"
-[ ! -d "$REMOTE_DIR" ] && gh repo clone {owner}/remote-control "$REMOTE_DIR"
-cd "$REMOTE_DIR" && git pull origin main
-```
-
-| File | What to sync |
-|-------|--------------|
-| `README.md` | Pipeline feature description |
-| `src/index.ts` | Help text / chip labels (if any) |
-
-Update only if the pipeline's public-facing features changed.
-
----
-
 ## Release Flow
 
 When invoked with the `release` argument:
@@ -262,9 +225,8 @@ When invoked with the `release` argument:
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags -> release.yml auto-publish
 7. WEBSITE       Version + features -> {website-host}
-8. REMOTE        Update remote-control references
-9. COPILOT       Copilot CLI instructions + skills sync
-10. Report        Summary: version, touched repos, deploy status
+8. COPILOT       Copilot CLI instructions + skills sync
+9. Report        Summary: version, touched repos, deploy status
 ```
 
 ---
@@ -275,7 +237,7 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
-| `~/.claude/commands/multi-agent/{cmd}.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
+| `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
 **36 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
@@ -287,7 +249,7 @@ local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review,
 scan, search, setup, stack, status, sync, test, update
 ```
 
-**NOT synced**: `refs/*`  -  lazy-load references, Claude Code specific
+**NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific
 
 **Claude -> Copilot**: add SKILL.md frontmatter (`name`, `description`, `user-invocable: true`, `argument-hint`)
 **Copilot -> Claude**: simplify the frontmatter (`description` + `allowed-tools`), add `$ARGUMENTS`

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

@@ -14,7 +14,7 @@ First step of every `multi-agent` flow **that touches a remote provider**.
 > repos, account-picker is bypassed and the state file's `accountId` is left
 > `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.
 
-> **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 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 payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
 
 ## Steps
 
@@ -28,7 +28,7 @@ First step of every `multi-agent` flow **that touches a remote provider**.
    - Bitbucket-based flow → `--providers bitbucket`
 
 3. **Picker UI**  -  show via AskUserQuestion (single-select):
-   - Breadcrumb (per `refs/picker-contract.md` Step narration): before the question, print the narrator line `<localized: "Step 1/N: account selection">` (`N` = total Phase 0 steps for the active flow).
+   - Breadcrumb (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): before the question, print the narrator line `<localized: "Step 1/N: account selection">` (`N` = total Phase 0 steps for the active flow).
    - `header`: "Account" (English chip)
    - `question`: `<localized: "Which account should this run use?">`
    - one option per account: `label` = account label (English), `description` = providers in `outputLanguage`

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

@@ -6,7 +6,7 @@ description: "Internal  -  dev context (extra repos) picker for multi-agent."
 
 Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
 
-> **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
 
@@ -34,7 +34,7 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
    - `editable`  -  `canPush=true` → picker options, pre-selected
    - `readonly`  -  `canPush=false` → printed as an advisory note; not selectable
 
-3. **AskUserQuestion (multiSelect=true)**. Print the breadcrumb narrator line first (per `refs/picker-contract.md` Step narration): `<localized: "Step N/N: extra dev repos">`.
+3. **AskUserQuestion (multiSelect=true)**. Print the breadcrumb narrator line first (per `$HOME/.claude/multi-agent-refs/picker-contract.md` Step narration): `<localized: "Step N/N: extra dev repos">`.
    ```
    [N/N] Extra editable dev repos (multi):
      [x] <submodule-a>  (suggestion: from .gitmodules)