@mmerterden/multi-agent-pipeline 12.5.0 → 12.6.0

package/pipeline/skills/shared/core/multi-agent-design-check/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: multi-agent-design-check
+language: en
+description: "Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a countable target set, build Debug in a worktree, launch in mock mode, fetch Figma variants, compare each pixel + px-spacing + typography + color, and export a side-by-side annotated report (HTML + PDF + Confluence) to ~/DesignChecks. A coverage gate fails the run when a target is neither audited nor skipped with a reason."
+user-invocable: true
+argument-hint: '[scope]  -  empty = whole module; screen name; screen@variant; Figma URL(s); --resume'
+---
+
+# multi-agent-design-check  -  Mock-mode vs Figma design audit
+
+Local, on-device design-conformance auditor. Runs the app in a **mock mode** on a simulator / emulator and compares each screen (and every mock variant the build exposes) against its Figma design at the **pixel + geometry + typography + color** level, then produces a detailed report.
+
+**Local-only**: no CI/CD, no cron, no commits, no PR. Read-only audit; writes a report to `~/DesignChecks/`. The worktree only isolates the Debug build.
+
+> **Language**: `promptLanguage=en` always (this spec stays English). `outputLanguage` applies to conversational lines and the human-readable report - pass it to `design_report` as `report.lang` (engine defaults to English, ships `en` + `tr` packs, per-key `report.labels` overrides). `ask_choice` labels/headers, branch names, paths, code identifiers stay English.
+
+## Scope  -  `$ARGUMENTS`
+
+The scope decides which **inventory targets** (Phase 0 step 5) the run must audit. It never changes how thoroughly each target is audited.
+
+| Form | Example | Scope |
+|------|---------|-------|
+| empty / `module` | (no argument) | Every target in the module's inventory |
+| screen name | `boarding-pass` | Every target whose `screen` matches (case/separator-insensitive) |
+| `screen@variant` | `boarding-pass@expired` | One target |
+| target id | `scenario-case:boardingpassoutcome-expired` | One target, exactly |
+| Figma URL(s) | `https://figma.com/design/…?node-id=1-2` | Only the frames those URLs name |
+| `--resume` | `--resume` | The unaudited remainder of the most recent run for this repo + module |
+| combinations | `seat-map summary@semi-success` | Union of the above, space- or newline-separated |
+
+A scope matching **no** inventory target is an error, not an empty run: print the closest inventory ids and halt.
+
+**Whole-module is the default, and it is meant to finish.** The inventory prices each target (`cost: relaunch | in-app`) and batches them into a run `plan`, so a 50-target module is typically about a dozen relaunches rather than fifty  -  a full audit is one sitting, not a project. Scope exists for resuming an interrupted run and for re-checking one screen after a fix, **not** for trimming an audit down to what feels affordable. The coverage gate applies to the **scoped** set, so a deliberate scoped run is never penalised for out-of-scope targets, and `--resume` closes the remainder.
+
+## Pipeline
+
+```
+Phase 0: Init & Gate  → repo + module picker, platform detect, MOCK FEASIBILITY GATE, SCENARIO INVENTORY, scope resolve, report dir, worktree
+Phase 1: Build & Launch → Debug build in worktree, boot device, install, launch in mock mode
+Phase 2: Figma          → fetch module frame tree, enumerate + map variants (ask when ambiguous)
+Phase 3: Drive & Compare → per plan batch: one launch → capture + flip in-app states → match → batch-ask → compare
+Phase 4: Report         → coverage gate + assemble + export HTML + PDF (+ Confluence) to ~/DesignChecks/
+```
+
+## Requirements
+
+- **iOS**: Xcode + Simulator. **Android**: Android SDK + emulator / device.
+- **MCP**: `dev-toolkit` (>= 2.8.0, for `design_scenario_inventory`, the `design_report` coverage gate, and `design_visual_compare` region alignment) + an authenticated Figma MCP (`mcp__claude_ai_Figma__*`).
+- The selected module must support a mock mode (Phase 0 gate). No mock support → halt.
+
+## Phase Tracker (mandatory)
+
+```bash
+bash $HOME/.copilot/scripts/phase-tracker.sh init "$TASK_ID"
+for p in "0:Init & Gate" "1:Build & Launch" "2:Figma" "3:Drive & Compare" "4:Report"; do
+  bash $HOME/.copilot/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+```
+Copilot / plain shell has no TaskList widget - after every state change call `phase-tracker.sh render` (prints a bordered ANSI card). Do NOT call TaskCreate here.
+
+## STOP-AND-CONFIRM
+
+Every Phase 0 / Phase 2 decision uses the `ask_choice` picker (`$HOME/.copilot/lib/ask-choice.sh`). Print a `Step <i>/<n>: <what it decides>` breadcrumb first. Confirmation required even with one option; state inheritance from a previous run is FORBIDDEN.
+
+---
+
+## Phase 0 - Init, Feasibility Gate & Inventory
+
+0. **MCP CURRENCY GATE (first, before anything expensive)** - an MCP stdio server publishes its tool list once at `initialize` and never re-reads the code, so a session bound to a process that started before the last update keeps serving the OLD tool list while still reporting "connected". Finding that out after a Debug build and a device drive wastes the run and yields a report missing the checks this spec depends on.
+
+   Assert both halves:
+
+   a. **Session** - `mcp__dev-toolkit__design_scenario_inventory` must be callable and `mcp__dev-toolkit__design_visual_compare` must accept `live_region`. Absent → the session holds a stale process.
+
+   b. **Disk** - probe the configured server, which reports what a fresh connection WOULD serve:
+   ```bash
+   printf '%s\n%s\n' \
+     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
+     '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+   | node "<dev-toolkit path>/index.js" 2>/dev/null | python3 -c "
+import sys,json
+for l in sys.stdin:
+    try: m=json.loads(l)
+    except: continue
+    if m.get('id')==1: print('version', m['result']['serverInfo']['version'])
+    if m.get('id')==2:
+        n=[t['name'] for t in m['result']['tools']]
+        print('tools', len(n), 'inventory', 'design_scenario_inventory' in n)"
+   ```
+
+   - **disk OK, session missing the tool** → **HALT**; the user must reconnect the MCP server (a stale build advertises one fewer `design_*` tool, which is the quickest tell). If a reconnect does not take, lingering server processes are the usual cause - compare `ps -o lstart=` start times against the code's mtime.
+   - **disk stale** → **HALT**; the checkout needs updating first.
+   - **both current** → continue.
+
+   Never substitute a local `node` call for a missing tool: the run would silently lose the coverage gate and region alignment, which is the exact failure this gate prevents.
+
+1. **Repo picker** - `$HOME/.copilot/multi-agent-refs/_repo-picker.md`. Account picker skipped (Figma token user-supplied) unless Confluence export needs a token.
+2. **Module picker** - `$HOME/.copilot/multi-agent-refs/_dev-context.md` (auto-suggest `.gitmodules` via `submodule-detector.sh`). Pick the module to audit (multi-module = audit each independently).
+3. **Platform detect** - `.xcodeproj`/`Package.swift`→iOS, `build.gradle*`→Android. Persist `state.platform`.
+4. **MOCK FEASIBILITY GATE** on the module path:
+   ```
+   mcp__dev-toolkit__design_mock_detect({ repo_path, platform, extra_keys })
+   ```
+   (`extra_keys` from `config mock.keys`.)
+   - `false` → **HALT** with `reason`; the module cannot be audited. Never fabricate a comparison.
+   - `"debug-only"` → warn via ask_choice (variants can't be toggled at launch; only default Debug state comparable), Continue / Cancel.
+   - `true` → persist `state.designCheck.mock` (mechanism, activation, variantsHint, evidence).
+5. **SCENARIO INVENTORY (this is the audit's target set)**:
+   ```
+   mcp__dev-toolkit__design_scenario_inventory({ repo_path, platform,
+     extra_launch_args: <config inventory.extraLaunchArgs>,
+     extra_targets:     <config inventory.extraTargets>,
+     ignore_targets:    <config inventory.ignoreTargets> })
+   ```
+   Returns `targets[]` - each `{ id, kind, label, screen, driver, cost, evidence }` - plus `plan[]`, `relaunchCount`, `groups[]`, `byKind`, `byCost`, `ignored[]`, `truncated`, `scanStrategy`. Kinds: `launch-arg`, `scenario-case`, **`prefix-code`** (a mock repository branching on the prefix of the reference the user types - usually the LARGEST group, and the one a selector-only search misses entirely), `code-scenario`, `fixture`, `deep-link`.
+
+   This list, not the agent's reading of the code and not what the UI happens to expose to tapping, is what the run is measured against. Persist verbatim to `state.designCheck.inventory`.
+   - `targetCount: 0` → warn that only the default launch state is auditable (a `debug-only` project legitimately lands here).
+   - `truncated: true` → the target set is INCOMPLETE. Say so now and pass `coverage.truncatedInventory: true` in Phase 4 so the gate fails instead of reporting a clean percentage of a partial denominator; narrow to a screen and work through the module in `--resume` steps.
+   - `ignored[]` non-empty → list what the config dropped, so a stale `ignoreTargets` cannot quietly shrink the audit.
+6. **Scope resolve** - intersect `$ARGUMENTS` with `inventory.targets`; persist `state.designCheck.scope = { argument, targetIds[] }`.
+
+   Print the resolved set grouped by screen **with its relaunch cost**: `<n> targets · <relaunchCount> relaunches`. Read the cost from `plan`, not from the target count - one relaunch serves every in-app target on that screen, so a 50-target module is typically a dozen relaunches. **Whole-module is the intended default**; ask_choice only when `relaunchCount` exceeds `config coverage.confirmAbove` (default 25), phrased as a cost estimate rather than an invitation to shrink the audit. Never offer a smaller scope as the easy path.
+7. **`--resume`** - read the most recent `~/DesignChecks/{repo}__{module}/*/run-state.json`; scope becomes that run's targets minus `covered` minus `skipped`. No previous run → say so and fall back to whole-module scope after confirmation.
+8. **Report dir** - create `~/DesignChecks/{repo}__{module}/{UTC-timestamp}/` (plus `assets/`) now and persist as `state.designCheck.reportDir`. Phase 3 writes captures, comparison images, and `run-state.json` into it, so it must exist before driving starts.
+9. **Worktree** - `{projectRoot}/{worktreeBasePath}/{taskId}` (default `.worktrees/DC-<shortId>`), never under $HOME. Prune stale locks + add `.worktrees/` to `.git/info/exclude` first.
+
+Persist `agent-state.json` (`mode: "design-check"`, platform, projectRoot, worktreePath, module, designCheck).
+
+## Phase 1 - Build & Launch (mock)
+
+1. **Debug build** in the worktree: iOS `mcp__dev-toolkit__ios_xcodebuild({ scheme, configuration: "Debug", action: "build" })`; Android `./gradlew :<module>:assembleDebug`.
+2. **Boot + install**: iOS list/boot device + `xcrun simctl install`; Android running emulator + `adb install -r`.
+3. **Deterministic state**: iOS `ios_status_bar({ preset: "clean" })`; fix appearance + locale.
+4. **Launch mock**: `mcp__dev-toolkit__design_mock_launch({ platform, bundle_id|package_name, launch_arg|intent_extra })` from Phase 0 activation. `debug-only` → just launch the Debug build. The build is installed once; Phase 3 relaunches it per target rather than rebuilding.
+
+## Phase 2 - Figma fetch & variant mapping (module-scoped)
+
+Figma **discovery** happens only here: the frame tree is fetched once and no later phase browses Figma for candidates. Phase 3 may fetch a specific node the user hands over in the 3.3 batch-ask - a targeted fetch of an already-identified frame, and the only Figma call allowed after this phase.
+
+1. Resolve the Figma URL (`$ARGUMENTS` or ask). Parse `fileKey` + `nodeId` (`-`→`:`).
+2. `mcp__claude_ai_Figma__get_metadata` → frame tree; direct child frames = candidate variants.
+3. Map each scoped target's `screen` + `label` (and `variantsHint`) → frames by similarity. Ambiguous/unmatched → deferred to the Phase 3.3 batch-ask (where the live capture can be shown); never guess. `debug-only` → single default variant.
+4. Per variant: `get_screenshot` (design PNG) + `get_design_context` (bbox, itemSpacing, paddings, fontSize/fontFamily, fills, CodeConnect name). Flatten to `figma_spec`; record `figmaFrame` size.
+
+Persist `state.designCheck.variants[]`.
+
+## Phase 3 - Drive every scoped target → capture → match → batch-ask → compare
+
+**This phase iterates `state.designCheck.scope.targetIds`  -  a finite list decided in Phase 0. It ends when every id is resolved, not when the UI stops offering new taps.** Tap-walking alone cannot reach a state needing a different launch argument, scenario case, or typed scenario code - which is exactly how a module's error / edge states go missing.
+
+### 3.1 Drive the inventory's plan, batch by batch
+
+**Follow `inventory.plan`, filtered to the scoped ids.** Each batch is one launch: the batch's relaunch target opens a screen, and every in-app target for that screen is flipped while the app is already there. Driving the plan is what makes full coverage affordable - target-by-target relaunching is what made earlier runs give up a third of the way in.
+
+Per batch: launch once with the batch's `launch` driver (or the plain mock activation for `(default launch)`) → navigate → capture the relaunch target → for each in-app target, flip its selector, let the screen re-render, capture. **No relaunch between in-app targets.**
+
+Per-target activation by `driver.type`:
+
+| `driver.type` | Activation |
+|---|---|
+| `launch-arg` | `design_mock_launch({ launch_arg: "<mock activation> <driver.launchArg>" })` - the mock switch AND the target's flag together |
+| `intent-extra` | `design_mock_launch({ intent_extra: "<mock extra> <driver.intentExtra>" })` |
+| `scenario` | Set `driver.enum` to `driver.case` through the build's debug scenario picker, then drive the flow that consumes it |
+| `code` (from `prefix-code`) | Type a reference beginning with `driver.code` at the entry field, then walk to `driver.appliesTo`. The prefix decides which fixture the mock repository returns - this is how most per-screen variants are reached |
+| `code` (from `code-scenario`) | Same entry field, flow-wide code not owned by one screen |
+| `fixture` | Activate the launch arg / scenario that reads `driver.file`; when nothing does → skip with reason "fixture not reachable from any driver" |
+| `deep-link` | `ios_open_url` / `android_open_url` with `driver.url` |
+| `manual` | Config-declared: follow the config's note, or skip with that note as the reason |
+
+While a target's state is on screen, also capture the **sub-states reachable from it by tapping** - overlays, bottom sheets, modals, popups, inline errors, QR / share sheets. These cost no relaunch and belong to the target that exposed them (`<id>#<sub-label>`).
+
+Per capture: `ios_screenshot`/`android_screenshot` (save PNG into the Phase 0 report dir) + `mcp__dev-toolkit__design_ui_geometry` → append to `state.designCheck.captured[]` with the target id and a human label. **Persist `state` and `run-state.json` after every capture** so a dying run resumes from where it stopped.
+
+Unreachable target → record `{ id, reason }` in `state.designCheck.skipped[]` with a concrete reason ("scenario picker not present in this build", "needs a live PNR", "crashes on launch: <symbol>"). "Requires a scenario / prefix / launch-arg" is **not** a reason - that describes the work, and the work is this phase's job.
+
+### 3.2 Match each capture → Figma frame (auto)
+
+Resolve each captured screen's frame from the Phase 2 tree; match by structure/content; accept only a **confident** match → `pairs[]`.
+
+### 3.3 Batch-ask the user for EVERYTHING unmatched (ONE prompt, WITH the visual)
+
+Collect ALL unmatched captures into a single list and ask ONCE - never guess, never show a wrong frame. **Show each unmatched screen's captured screenshot** (attach the PNG), name the screen, ask for the Figma node-id / URL in `outputLanguage`, optionally list best-guess candidates. Each answer becomes a confirmed pair; a declined screen is a skip with reason "no Figma frame supplied".
+
+### 3.4 Compare ALL pairs in one pass
+
+```
+mcp__dev-toolkit__design_visual_compare({ figma_png, live_png, out_dir, label,
+  figma_spec, live_geometry, figma_frame, live_screen,
+  crop_top_live, tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0 })
+```
+Collect findings (spacing/size/position px, color ΔE hex, typography), perceptualPct, images.
+
+**Bottom sheets, modals, and any partial overlay need region alignment.** Their Figma frame covers only the sheet while the capture is the whole screen; passing that pair as-is stretches a full screen onto a sheet-shaped frame, misplacing every element inside the sheet and burying the real defect in noise. For any capture whose frame is not full-screen add:
+
+```
+  live_region:     <the sheet container's {x,y,w,h} from design_ui_geometry>,
+  expected_region: <where the design puts that sheet, same units>
+```
+- `live_region` rebases the comparison onto the sheet's own box - read it from the `design_ui_geometry` element that IS the sheet container, never from a guess.
+- `expected_region` comes from the Figma frame's placement inside its parent screen frame; with it the engine emits an `inset` finding per edge.
+- `crop_top_live` is ignored when `live_region` is given (the region crop already excluded chrome).
+
+**Edge insets are defects, not tolerances.** A design showing a sheet flush to the screen edges is not satisfied by one floating in from them, and the reverse is equally wrong. Report every `inset` finding as a deviation with its px delta; never absorb a side gap as "close enough" and never raise `tolerance_px` to make one disappear. The sheet's internal content padding is measured by the normal element pairing once the region alignment is right.
+
+**Component reference** (best-effort): Code Connect atom → attach matching `*.figma.swift`/`*.figma.kt` component render.
+**Fix prompt**: compose a paste-ready developer prompt from the findings.
+
+### 3.5 Close the ledger
+
+Every scoped target id ends in exactly one bucket: **covered** (captured AND compared) or **skipped** (with a concrete reason from 3.1 / 3.3). Write `run-state.json` into the Phase 0 report dir with `{ targetIds, covered, skipped }` so `--resume` can pick up the remainder.
+
+Before leaving this phase, compare `covered.length + skipped.length` against `scope.targetIds.length`. A mismatch is a set of targets nobody decided about - go back and drive them, or record why they cannot be driven. Reaching Phase 4 with a mismatch is the worst of both worlds: the work is undone AND the run is marked incomplete.
+
+## Phase 4 - Report, coverage gate & export
+
+1. Output dir: `state.designCheck.reportDir`, already created in Phase 0, holding Phase 3's captures and comparison images. Do not mint a second timestamped dir.
+2. Assemble the report object:
+   ```
+   { project, module, platform, figmaUrl, figmaFileKey, timestamp, lang: <outputLanguage>,
+     coverage: { targets: <scoped target ids/objects>, covered: <audited ids>,
+                 skipped: [{ id, group, reason }],
+                 truncatedInventory: <inventory.truncated>,
+                 floor: <config coverage.floor, optional> },
+     variants: [{ name, figmaNodeId, perceptualPct, passed, compareSize, liveSize,
+                  images, findings, fixPrompt, componentRefs }] }
+   ```
+   Pass **ids**, not counts: the engine then names each unaccounted target instead of printing an anonymous tally. `compareSize` / `liveSize` come straight from the `design_visual_compare` result.
+3. Export:
+   ```
+   mcp__dev-toolkit__design_report({ report, out_dir: state.designCheck.reportDir,
+     formats: ["html","pdf"] (+ "confluence" if enabled) })
+   ```
+   HTML self-contained with the gate banner on top; PDF via Playwright (reports `pdfError` if unavailable); Confluence only if enabled (reuse `multi-agent-channels` adapter), else graceful skip.
+4. **COVERAGE GATE (blocking, not advisory)** - read `coverage` from the tool result and persist to `state.designCheck.coverage`:
+   - `gate: "pass"` → print per-variant PASS/FAIL + findings + report paths.
+   - `gate: "fail"` → the run is **INCOMPLETE**. Print `coverageError`, the `unaccountedIds`, and the command that closes the gap (`--resume`). Do not present an incomplete audit as finished, and never pad the covered list to make the gate pass.
+
+   The gate is a last line of defence, not the plan. If it fires, Phase 3 left work undone - drive the missing targets, then report.
+5. Remove the worktree unless asked to keep it. The report dir is never removed.
+
+## Notes
+
+- Feasibility is real - report honestly and stop when a module has no mock support; never fabricate a partial comparison.
+- **The inventory is the contract**: Phase 0 step 5 decides what "done" means. An audit that visits the linear happy path and lists the rest as "not visited" is the failure mode this pipeline exists to prevent; the gate makes it visible instead of polite.
+- **Chunk with scope, not with silence**: a 50-target module is a legitimate multi-run job. Scope it, close each run's gate, let `--resume` carry the remainder.
+- "Pixel perfect" is perceptual + geometric (scale normalized, chrome cropped); deltas reported in px/pt/hex with a tolerance.
+- The `design_*` engine is generic; project specifics (mock keys, extra launch args / targets, node overrides, status-bar crop, coverage floor, Confluence toggle) come from `design-check-config.json` / prefs, never hardcoded.

package/pipeline/skills/shared/core/multi-agent-help/SKILL.md

@@ -128,6 +128,17 @@ Manual Test (Phase 5 standalone  -  Xcode hint flow):
   /multi-agent:manual-test [#N]      Checkout task branch, print Xcode/SourceTree hints.
                                      (Renamed from :test in v5.7.4.)
 
+Design Check (mock-mode vs Figma, local-only  -  dev-toolkit-mcp design_* tools):
+
+  /multi-agent:design-check          Whole-module design audit: enumerate every state driver into a target set,
+  /multi-agent:design-check <scope>  drive each one in mock mode via idb, compare vs Figma (padding/width/spacing/
+  /multi-agent:design-check --resume font/color/component/localization), export HTML+PDF to ~/DesignChecks.
+                                     Scope: empty=module / screen / screen@variant / target-id / Figma URL(s).
+                                     COVERAGE GATE: a target is audited or skipped WITH a reason, else the run
+                                     is reported INCOMPLETE. --resume covers the remainder of the last run.
+                                     Unresolved frame → shows you the screenshot and asks for the node-id.
+  Drives dev-toolkit design_* : design_mock_detect / _scenario_inventory / _mock_launch / _ui_geometry / _visual_compare / _report.
+
 ------------------------------------------------------------
 
 Setup:
@@ -266,6 +277,17 @@ Manuel Test (Phase 5 standalone  -  Xcode hint akışı):
   /multi-agent:manual-test [#N]      Task branch'ine checkout, Xcode/SourceTree hint basar.
                                      (v5.7.4'te :test'ten :manual-test'e rename.)
 
+Design Check (mock-mod vs Figma, yalnızca lokal  -  dev-toolkit-mcp design_* tool'ları):
+
+  /multi-agent:design-check          Tüm modül tasarım denetimi: her state sürücüsünü hedef kümesine çıkar,
+  /multi-agent:design-check <scope>  her birini mock modda idb ile sür, Figma ile karşılaştır (padding/genişlik/
+  /multi-agent:design-check --resume spacing/font/renk/component/localization), HTML+PDF rapor ~/DesignChecks.
+                                     Kapsam: boş=modül / ekran / ekran@varyant / target-id / Figma URL(leri).
+                                     KAPSAM GEÇİDİ: hedef ya denetlenir ya da GEREKÇEYLE atlanır; aksi hâlde
+                                     koşu EKSİK raporlanır. --resume son koşunun kalanını kapatır.
+                                     Figma karşılığı bulunamazsa SANA screenshot'ı gösterip node-id sorar.
+  Sürdüğü dev-toolkit design_* : design_mock_detect / _scenario_inventory / _mock_launch / _ui_geometry / _visual_compare / _report.
+
 ------------------------------------------------------------
 
 Setup:

package/pipeline/skills/shared/core/multi-agent-refactor/SKILL.md

@@ -1,39 +1,41 @@
 ---
 name: multi-agent-refactor
 language: en
-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."
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync."
 user-invocable: true
-argument-hint: 'bugs | best-practices | drift | security | tests | performance | docs | ci | deps'
+argument-hint: 'bugs | best-practices | drift | dev-toolkit | security | tests | performance | docs | ci | deps'
 ---
 
 # Multi-Agent Refactor
 
-**One command. Best-practices + Bug hunt + Upstream drift -> Score -> Plan -> Approval -> Develop -> Sync.**
+**One command. Best-practices + Bug hunt + Upstream drift + Dev-toolkit -> 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, takes approval, applies the approved items, and asks about sync when done.
+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, researches the companion dev-toolkit MCP server against current MCP practice, scores everything, drafts a single prioritized plan, takes approval, applies the approved items, and asks about sync when done.
 
-**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", etc.)
+**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "dev-toolkit", 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 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion dev-toolkit repo -> plan band E
 Step 1:  SCAN            Scan 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 out of 10, total /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift), priority-ordered
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
 Step 5:  ASK             "Shall I start developing?"  -  take approval
 Step 6:  IMPLEMENT       Apply approved items in order (lint, test, commit)
 Step 7:  VERIFY          Confirm all tests + lint pass
 Step 8:  ASK SYNC        "Shall I run multi-agent-sync?"  -  take approval
 ```
 
-Plan bands (all four feed the single Step 4 table):
+Plan bands (all five 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.
+- **E - Dev-toolkit**: current-practice gaps in the companion dev-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
 
 ## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
@@ -94,6 +96,54 @@ Procedure:
 
 5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>". Do not auto-apply  -  it goes through Step 5 approval; after porting, bump the entry's `derivedFromVersion`.
 
+## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+
+The pipeline's device and browser hands are MCP tools served by a companion repo (`dev-toolkit-mcp`), and several pipeline skills declare a minimum toolkit version. This step researches current MCP practice and audits that repo against it.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit`: `{ enabled, label, localPath, mcpServerName, packageName, registry, repoUrl }`.
+2. If unset, auto-detect from the MCP registration: `mcpServers` in `~/.claude.json` (plus `projects[*].mcpServers`) and `~/.claude/settings.json`; for a stdio `node` entry take `dirname(args[0])`, and accept it only if that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. Neither resolves (or `enabled: false`) -> skip and report "no dev-toolkit configured". Never guess a path, never clone.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | features released since the pinned SDK that the server does not use: tool annotations, `outputSchema` + structured content, resource links, progress + cancellation, `tools/list_changed`, pagination |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs | description budget, tool-count ceilings, naming, output size limits, permission ergonomics |
+| 3 | Peer servers | GitHub search on the same domain + `stars:>50` | surfaces we lack, conventions peers converged on, what to discard |
+| 4 | Wrapped tooling | `simctl`, `idb`, `adb`, `xcodebuild`, Playwright notes, Apple ITMS + review guidelines | deprecated flags in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community | what server authors changed recently (transport, output-token diets, error shape) |
+
+**Audit the toolkit**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"; find "$DT/tools" -name "*.js" -exec node --check {} \;
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"   # stdout = JSON-RPC channel
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"                    # advertised count vs reality
+node -p "require('$DT/package.json').files.join('\n')"; ls -d "$DT"/tools/*/  # files[] covers runtime dirs
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool has a description + `inputSchema`; token-heavy results (screenshots, UI trees) are truncated or file-backed; failures return an error result, not a throw; `CHANGELOG.md`, CI and tests exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `multi-agent-sync` Step 3d.
+- A finding that changes the tool surface pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it.
+
 ## Step 1: SCAN
 
 ```
@@ -166,7 +216,7 @@ Each category is scored out of 10. Output format:
 
 ## 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).
+Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E dev-toolkit).
 
 ```
 | # | Priority | Band | Category | Item | Impact |
@@ -175,7 +225,8 @@ Merge all four bands into a single plan. Tag each row with its band (A best-prac
 | 2 | P0 | B | Testing | 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 |
+| 5 | P1 | E | Toolkit | Add read-only annotations to the dev-toolkit device tools | Medium |
+| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
 ```
 
 Priority levels:
@@ -187,13 +238,14 @@ Priority levels:
 
 After showing the plan, ask:
 
-> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, and upstream drift. Shall I start developing?"
+> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Shall I start developing?"
 
 Options:
 - "Yes, do all of them"
 - "Do only the P0 ones"
 - "Do only P0 + P1"
 - "Only the bugs (band B)"
+- "Only the dev-toolkit (band E)"
 - (the user can make a specific selection)
 
 **NEVER start developing without approval.**
@@ -204,6 +256,7 @@ Apply approved items in order:
 
 1. For each item:
    - Make the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion`)
+   - Band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, `tools/list` handshake, advertised tool count matching reality), commit there. Publishing is `multi-agent-sync` Step 3d.
    - Run the relevant tests
    - If successful, move to the next
    - If it fails, revert and notify the user
@@ -227,6 +280,8 @@ echo "Lint: PASS/FAIL"
 echo "Test: PASS/FAIL (X/Y passed)"
 ```
 
+If any band-E item was applied, verify the toolkit repo too: syntax-check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts match the count the server reports.
+
 ## Step 8: ASK SYNC
 
 After all approved items are applied, ask:
@@ -234,7 +289,7 @@ After all approved items are applied, ask:
 > "Development complete. Shall I run multi-agent-sync?"
 
 Options:
-- "Yes" -> run the `/sync` command (full ecosystem sync)
+- "Yes" -> run the `/sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
 - "No" -> report and finish
 - "Only commit + push" -> push only the current repo without sync
 
@@ -247,6 +302,7 @@ If $ARGUMENTS is specified, focus on that band/category only:
 | `bugs` | Bug hunt only (band B) |
 | `best-practices` | Field research + adapted plan only (band A) |
 | `drift` | Upstream derived-skill drift only (band D) |
+| `dev-toolkit` | Companion MCP toolkit research + audit only (band E) |
 | `security` | Security analysis only |
 | `tests` | Test coverage and quality only |
 | `performance` | Performance optimization only |

package/pipeline/skills/shared/core/multi-agent-review/SKILL.md

@@ -46,7 +46,7 @@ Skip Phase 0-3 and review a diff only. Input shapes: a PR (`#N`, `repo#N`, GitHu
 
    | Platform | Trigger files | Catalog to load |
    |---|---|---|
-   | iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  17 rules + ITMS refs |
+   | iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  18 rules + ITMS refs |
    | Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `pipeline/skills/shared/core/google-play-compliance/SKILL.md`  -  21 rules + Play policy refs |
 
    It appends the catalog's `ruleID` + the Apple ITMS / Play policy ref to each finding:

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: multi-agent-sync
 language: en
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server."
 user-invocable: true
-argument-hint: 'release | "change description"'
+argument-hint: 'release | dev-toolkit | "change description"'
 ---
 
 # Multi-Agent Sync
@@ -22,6 +22,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | 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 | dev-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
 
 ## Default Behavior (no argument)
 
@@ -29,11 +30,12 @@ Run all steps automatically:
 
 ```
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 42 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
+Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
-Step 6: Report      Summary: synced targets, changed files, deploy status
+Step 6: Report      Summary: synced targets, changed files, deploy status, dev-toolkit version
 ```
 
 If nothing is stale -> report "All targets up to date" and stop.
@@ -44,6 +46,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 |-------|----------|
 | (no argument) | Full ecosystem sync (default) |
 | `release` | Full sync + version bump + tag + npm publish + website deploy |
+| `dev-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `"change description"` | Apply the description to ALL targets at once |
 
 
@@ -90,6 +93,43 @@ If nothing is stale -> report "All targets up to date" and stop.
    - `~/.claude/settings.json`
 
 
+## Dev-Toolkit Sync (Step 3d)
+
+The companion MCP server (`dev-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship.
+
+**Resolution**: identical to `multi-agent-refactor` Step 0c  -  `prefs.global.devToolkit` first, then the `mcpServers` registration, then skip.
+
+**Detect movement**: dirty working tree, unpushed commits, or no `v<version>` tag for the version in `package.json`. Nothing moved -> report "up to date" and continue.
+
+**Ship gates** (a failure aborts this step only, with file + line; the rest of the sync continues).
+When the toolkit ships its own gate script (`npm run gates` / `scripts/gates.sh`), run that instead of the list below - the repo owns the definition, this skill owns the requirement. The list is the fallback, and the coverage the script must have:
+
+1. `node --check index.js` plus every `tools/**/*.js`.
+2. stdio handshake (`initialize` -> `notifications/initialized` -> `tools/list`) must answer with a non-zero tool count.
+3. That count must match every advertised count (`package.json` description, README header and per-family rows). Fix the docs, never the gate.
+4. `npm pack --dry-run` must list every `tools/*/` directory the server loads  -  a missing `files[]` entry publishes a broken package.
+5. `grep -rn "console\.log(" index.js tools/` must be empty: stdout carries the JSON-RPC frames, diagnostics go to `console.error`.
+6. Personal-data scan: no absolute `/Users/<name>` paths, no tokens, no corporate hostnames.
+7. Version contract: every pipeline-side minimum version must be satisfied by what is about to ship; a new tool a pipeline skill now needs -> bump that minimum in the same sync.
+
+**Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool.
+
+**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry: `npm.pkg.github.com` needs a GitHub PAT with `write:packages` (logical key `github`), `registry.npmjs.org` needs the `npm` key.
+
+```bash
+NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
+REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
+HOST=${REG#https://}; HOST=${HOST%/}
+case "$HOST" in npm.pkg.github.com*) KEY=github ;; *) KEY=npm ;; esac
+TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
+[ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
+printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
+npm publish --userconfig "$NPMRC"
+```
+
+**Approval**: outside autopilot and outside `release`, ask first: commit + push / commit + push + publish / skip. Never ship unapproved band-E work from `multi-agent-refactor` silently.
+
+
 ## Website Sync (Step 4)
 
 Propagate the pipeline version, phase count, model count, and feature descriptions to the website.
@@ -124,9 +164,10 @@ When invoked with the `release` argument:
 4. VERSION       package.json version bump (patch/minor/major)
 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. COPILOT       Copilot CLI instructions + skills sync
-9. Report        Summary: version, touched repos, deploy status
+7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
+8. WEBSITE       Version + features -> {website-host}
+9. COPILOT       Copilot CLI instructions + skills sync
+10. Report       Summary: version, touched repos, deploy status
 ```
 
 
@@ -136,10 +177,10 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**42 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
@@ -159,6 +200,7 @@ routines, save, scan, search, setup, stack, status, sync, test, uninstall, updat
 | `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
 | `gh` CLI (work) | `${USER}_{work-gh-alias}` gh auth (Keychain) |
 | npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
+| dev-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
 
 ```bash
 gh auth switch --user {owner}  # for personal repos

package/pipeline/skills/shared/core/multi-agent-test/SKILL.md

@@ -39,6 +39,6 @@ Pass `$ARGUMENTS` through verbatim  -  the target doc picks the right test matri
 
 - **iOS**: Xcode + booted Simulator (`xcrun simctl list | grep Booted`)
 - **Android**: Android SDK + running emulator or USB device (`adb devices`)
-- **MCP**: `dev-toolkit` MCP server registered (tool names start with `mcp__dev_toolkit__*`)
+- **MCP**: `dev-toolkit` MCP server registered (tool names start with `mcp__dev-toolkit__*`)
 
 For the Phase 5 manual test mode (branch checkout + Xcode hint), use `multi-agent-manual-test` instead.