@mmerterden/multi-agent-pipeline 12.4.0 → 12.6.0

package/pipeline/commands/multi-agent/design-check/SKILL.md

@@ -0,0 +1,287 @@
+---
+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."
+description-tr: "Mock-mod vs Figma tasarım denetimi (iOS / Android, yalnızca lokal). Repo + modül seç, mock desteğini geçitle, her state sürücüsünü sayılabilir bir hedef kümesine çıkar, worktree'de Debug derle, mock modda aç, Figma varyantlarını çek, her varyantı piksel + px-boşluk + tipografi + renk düzeyinde karşılaştır, yan yana annotasyonlu raporu (HTML + PDF + Confluence) ~/DesignChecks altına aktar. Bir hedef ne denetlenmiş ne de gerekçeyle atlanmışsa kapsam geçidi koşuyu başarısız sayar."
+argument-hint: '[scope]  -  empty = whole module; screen name; screen@variant; Figma URL(s); --resume'
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__claude_ai_Figma__get_metadata, mcp__claude_ai_Figma__get_design_context, mcp__claude_ai_Figma__get_screenshot, mcp__dev-toolkit__design_mock_detect, mcp__dev-toolkit__design_scenario_inventory, mcp__dev-toolkit__design_mock_launch, mcp__dev-toolkit__design_ui_geometry, mcp__dev-toolkit__design_visual_compare, mcp__dev-toolkit__design_report, mcp__dev-toolkit__ios_list_devices, mcp__dev-toolkit__ios_boot_device, mcp__dev-toolkit__ios_launch_app, mcp__dev-toolkit__ios_terminate_app, mcp__dev-toolkit__ios_screenshot, mcp__dev-toolkit__ios_tap, mcp__dev-toolkit__ios_swipe, mcp__dev-toolkit__ios_type_text, mcp__dev-toolkit__ios_open_url, mcp__dev-toolkit__ios_get_ui_tree, mcp__dev-toolkit__ios_status_bar, mcp__dev-toolkit__ios_set_appearance, mcp__dev-toolkit__ios_set_locale, mcp__dev-toolkit__ios_xcodebuild, mcp__dev-toolkit__ios_xcresult, mcp__dev-toolkit__android_list_devices, mcp__dev-toolkit__android_screenshot, mcp__dev-toolkit__android_tap, mcp__dev-toolkit__android_swipe, mcp__dev-toolkit__android_type_text, mcp__dev-toolkit__android_open_url, mcp__dev-toolkit__android_launch_app, mcp__dev-toolkit__android_stop_app
+---
+
+# /multi-agent:design-check  -  Mock-mode vs Figma design audit
+
+Local, on-device design-conformance auditor. It 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. It is a read-only audit that writes a report to `~/DesignChecks/`. The worktree exists only to build the Debug app without touching the user's working tree.
+
+> **Language (read FIRST)**: Two independent axes.
+>
+> 1. **`prefs.global.promptLanguage` is always `en`**  -  this spec and every instruction to the LLM stay English.
+> 2. **`prefs.global.outputLanguage` is user-selectable**  -  applies to conversational lines and the human-readable parts of the report. Pass it to `design_report` as `report.lang`; the engine defaults to English and ships an `en` + `tr` label pack, plus per-key `report.labels` overrides.
+>
+> Regardless of `outputLanguage`, these stay English: `AskUserQuestion` labels/headers, branch names, file paths, code identifiers, log lines. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+
+## 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` | `/multi-agent:design-check` | 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` | `/multi-agent:design-check --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 |
+
+Multiple forms may be combined. A scope that matches **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** target 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 + an available Simulator. **Android**: Android SDK + a running emulator / device.
+- **MCP**: the `dev-toolkit` MCP server (>= 2.8.0, for `design_scenario_inventory`, the `design_report` coverage gate, and `design_visual_compare` region alignment). The Figma MCP (`mcp__claude_ai_Figma__*`) must be authenticated - the user supplies the Figma URL.
+- The selected module must support a **mock mode** (Phase 0 gate decides this). No mock support → the command halts.
+
+## Phase Tracker Contract (mandatory)
+
+Register one tile per phase in strict order BEFORE any update, on both channels. Full spec: `$HOME/.claude/multi-agent-refs/tracker-contract.md`.
+
+```bash
+bash $HOME/.claude/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/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+```
+
+In Claude Code also drive the native TaskList widget: fire all `TaskCreate` calls in phase order (0→1→2→3→4) first, persist each `taskId` via `phase-tracker.sh meta <N> tasklist_id`, then flip status with `TaskUpdate` + `phase-tracker.sh update` at every boundary. On Copilot / plain shell call `phase-tracker.sh render` instead (no TaskCreate).
+
+## STOP-AND-CONFIRM format
+
+Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker (numbered text menus are forbidden - `feedback_native_picker_ui`). Print a `Step <i>/<n>: <what it decides>` breadcrumb before each picker. Confirmation is required even with a single 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 connected to a server process that started before the last update keeps serving the OLD tool list while still reporting "connected". Discovering that after a Debug build and a device drive wastes the whole run and produces a report missing the very checks this spec relies on.
+
+   Assert both halves before continuing:
+
+   a. **Session** - `mcp__dev-toolkit__design_scenario_inventory` must be present in the tools available to you, and `mcp__dev-toolkit__design_visual_compare` must accept `live_region`. Absent → the session is bound to a stale process.
+
+   b. **Disk** - probe the configured server directly, which reports what a fresh connection WOULD serve:
+   ```bash
+   cd "$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.claude.json')))['mcpServers']['dev-toolkit']['args'][0].rsplit('/',1)[0])")" && \
+   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 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)"
+   ```
+
+   Branch on the two results:
+   - **disk OK, session missing the tool** → **HALT** and tell the user to reconnect: `/mcp` → `dev-toolkit` → Reconnect. Note the tool-count tell (a stale build advertises one fewer `design_*` tool). If a reconnect does not take, stale server processes may be lingering - `pgrep -f dev-toolkit-mcp/index.js` with `ps -o lstart=` shows their start times, and any that predate the code's mtime cannot serve the current tools.
+   - **disk itself stale** (older version, or `inventory False`) → **HALT**: the checkout needs updating before a reconnect can help.
+   - **both current** → continue.
+
+   Never work around a stale server by substituting a local `node` call for the missing tool: the run would silently lose the coverage gate and region alignment, which is exactly the failure this gate exists to prevent.
+
+1. **Repo picker** - reuse `$HOME/.claude/multi-agent-refs/_repo-picker.md`. The account picker is skipped (Figma token is user-supplied, no Jira/GitHub fetch happens) unless Confluence export is enabled, in which case resolve the Confluence token via `account-resolver.sh`.
+2. **Module / dev-context picker** - reuse `$HOME/.claude/multi-agent-refs/_dev-context.md`. Auto-suggest submodules from `.gitmodules` (`submodule-detector.sh`); the user selects the single module to audit (multi-module allowed - each is audited independently).
+3. **Platform detect** - `.xcodeproj` / `Package.swift` → iOS; `build.gradle*` → Android (same markers as `phase-0-init.md`). Persist `state.platform`.
+4. **MOCK FEASIBILITY GATE** - run against the selected module path:
+   ```
+   mcp__dev-toolkit__design_mock_detect({ repo_path: "<module path>", platform: "<ios|android>",
+     extra_keys: <design-check-config mock.keys, if any> })
+   ```
+   Branch on `supported`:
+   - **`false`** → **HALT**. Show `reason` + that no runtime mock switch / launchable app / mock fixtures were found. Tell the user this module cannot be audited by design-check and stop. Do not fabricate a comparison.
+   - **`"debug-only"`** → surface an `AskUserQuestion` warning: mocks are compiled into the Debug build via `#if DEBUG` DI, so **variants cannot be toggled at launch** - only the default Debug state is comparable. Options: `{ label: "Continue", description: "Audit the single default Debug state only" }`, `{ label: "Cancel", description: "Stop" }`.
+   - **`true`** → continue. Persist `state.designCheck.mock = <detect result>` (mechanism, activation, variantsHint, evidence).
+5. **SCENARIO INVENTORY (this is the audit's target set)**:
+   ```
+   mcp__dev-toolkit__design_scenario_inventory({ repo_path: "<module 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 no state driver was found and that only the default launch state can be audited; a `debug-only` project legitimately lands here.
+   - `truncated: true` → the inventory hit its cap, so the target set is INCOMPLETE. Say so now, and pass `coverage.truncatedInventory: true` in Phase 4 so the gate fails rather than reporting a clean percentage of a partial denominator. Narrow the scope 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` (grammar above) 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, not fifty. **Whole-module is the intended default**; only ask for confirmation when `relaunchCount` exceeds `config coverage.confirmAbove` (default 25), and phrase it as a cost estimate, not as an invitation to shrink the audit. Never propose a smaller scope as the easy path - a scoped run is for resuming or for a focused re-check, not for avoiding work.
+7. **`--resume`** - read the most recent `~/DesignChecks/{repo}__{module}/*/run-state.json`; the scope becomes that run's targets minus its `covered` and minus its `skipped` entries. Skips carry a reason and are honoured, so a resume covers the genuinely unaudited remainder. No previous run → tell the user and fall back to whole-module scope after confirmation.
+8. **Report dir** - create `~/DesignChecks/{repo}__{module}/{UTC-timestamp}/` (and `assets/` inside it) now, and persist it as `state.designCheck.reportDir`. Phase 3 writes captures, comparison images, and `run-state.json` into it, so it must exist before driving starts - not at export time. This is report output, not a worktree; $HOME is intended here.
+9. **Worktree** - build the Debug app in an isolated worktree so the user's tree is untouched. Follow `phase-0-init.md` Step 8 convention exactly: `{projectRoot}/{worktreeBasePath}/{taskId}` (default `.worktrees/DC-<shortId>`), **never under $HOME** (`feedback_worktree_path_convention`). Stale-lock heal (`git worktree prune`) + residue guard (`.worktrees/` in `.git/info/exclude`) first. Local mode is not offered - the audit always uses a worktree checkout of the current branch's HEAD (no fetch/push).
+
+Persist `agent-state.json` with `taskId`, `mode: "design-check"`, `platform`, `projectRoot`, `worktreePath`, `module`, `designCheck`.
+
+## Phase 1 - Build & Launch (mock)
+
+1. **Debug build** in the worktree (mock activation requires the Debug configuration):
+   - iOS: `mcp__dev-toolkit__ios_xcodebuild({ workspace|project, scheme, configuration: "Debug", action: "build", destination: "generic/platform=iOS Simulator" })`. Drill failures via `ios_xcresult`.
+   - Android: `./gradlew :<module>:assembleDebug` (or `installDebug`) via Bash.
+2. **Boot device + install**: iOS `ios_list_devices` → `ios_boot_device` → install the built `.app` (`xcrun simctl install`). Android: ensure an emulator is running, `adb install -r <apk>`.
+3. **Deterministic state**: iOS `ios_status_bar({ preset: "clean" })` (09:41 / full battery); set a fixed appearance + locale so captures are stable across runs.
+4. **Launch in mock mode** using the activation from Phase 0:
+   ```
+   mcp__dev-toolkit__design_mock_launch({ platform, bundle_id|package_name,
+     launch_arg: state.designCheck.mock.activation.launchArg,      // iOS, e.g. "-debugMockMode YES"
+     intent_extra: state.designCheck.mock.activation.intentExtra }) // Android
+   ```
+   For `debug-only` there is no switch - just launch the Debug build. The build is installed once and stays installed: 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 looking for candidates. Phase 3 may still fetch a specific node the user hands over in the 3.3 batch-ask - that is a targeted fetch of an already-identified frame, not discovery, and it is the only Figma call allowed after this phase.
+
+1. Resolve the Figma URL (`$ARGUMENTS` or ask via `AskUserQuestion`). Parse `fileKey` + `nodeId` (`figma.com/design/{fileKey}/...?node-id={id}`; convert `-`→`:` in node ids).
+2. `mcp__claude_ai_Figma__get_metadata({ fileKey, nodeId })` → the frame tree. Treat direct child frames as **candidate variants**.
+3. **Map inventory targets → Figma frames**: match each scoped target's `screen` + `label` (and `state.designCheck.mock.variantsHint`) to frame names by similarity.
+   - Confident 1:1 match → accept.
+   - **Ambiguous or unmatched** → deferred to the Phase 3.3 batch-ask, where the live capture can be shown alongside the question. Never guess silently.
+   - `debug-only` projects → a single variant (the default state) mapped to the primary frame.
+4. For each mapped variant: `mcp__claude_ai_Figma__get_screenshot` (the design render PNG, download locally) and `mcp__claude_ai_Figma__get_design_context` (node geometry: `absoluteBoundingBox`, `itemSpacing`, paddings, text `fontSize`/`fontFamily`, `fills` colors, and any `CodeConnectSnippet` component name). Flatten the node subtree with the geometry helper into a `figma_spec` element list. Record the Figma frame size (`figmaFrame`).
+
+Persist the variant list + spec + PNG paths to `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 that needs a different launch argument, a different scenario case, or a 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 same screen is then flipped while the app is already sitting 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.
+
+For each batch:
+1. Launch once with the batch's `launch` driver (or the plain mock activation for the `(default launch)` batch).
+2. Navigate to the screen (`ios_tap` / `ios_swipe` / `ios_type_text` route through idb).
+3. Capture the batch's relaunch target.
+4. For each in-app target in the batch: flip its selector (scenario case / scenario code), let the screen re-render, capture. **No relaunch between these.**
+
+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 (navigate to it, select, return), then drive the flow that consumes it |
+| `code` (from `prefix-code`) | Type a reference beginning with `driver.code` at the entry field the flow starts from, then walk to `driver.appliesTo`. The prefix decides which fixture the mock repository returns, so this is how most per-screen variants are reached |
+| `code` (from `code-scenario`) | Same entry field, but the code is flow-wide rather than owned by one screen |
+| `fixture` | Activate the launch arg / scenario that reads `driver.file`; when nothing does, the target is a 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; record them as additional captures under that target id (`<id>#<sub-label>`).
+
+For each capture: `ios_screenshot` (save PNG into the Phase 0 report dir) + `mcp__dev-toolkit__design_ui_geometry` (live boxes + screen size) → append to `state.designCheck.captured[]` with the target id and a human label. **Persist `state` and `run-state.json` after every capture**, so a run that dies mid-way resumes from where it stopped instead of starting over.
+
+If a target cannot be reached, record it immediately as `{ 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 is a description of the work, and the work is this phase's job.
+
+### 3.2 Match each capture → Figma frame (auto)
+
+For each captured screen, resolve its Figma frame: drill the relevant board (`get_metadata` result from Phase 2), match by structure/content; accept only a **confident** match. Add matched → `pairs[]`.
+
+### 3.3 Batch-ask the user for EVERYTHING unmatched (ONE prompt, WITH the visual)
+
+Collect ALL captures with no confident Figma match into a single list and ask the user ONCE - never guess, never show a wrong frame. **For each unmatched screen you MUST SHOW its captured live screenshot** (render/attach the PNG so they see exactly which visual you mean), name the screen, and ask for the Figma node-id / URL (in `outputLanguage`). Optionally list your best-guess candidate frame names. The user supplies the node-id/URL per shown screenshot; each becomes a confirmed pair. A screen the user declines to map is a skip with reason "no Figma frame supplied".
+
+### 3.4 Compare ALL pairs in one pass
+
+For each pair (matched + user-supplied), fetch `get_screenshot` + `get_design_context`, then:
+   ```
+   mcp__dev-toolkit__design_visual_compare({
+     figma_png, live_png, out_dir: "<report dir>/assets", label: "<variant>",
+     figma_spec, live_geometry, figma_frame, live_screen,
+     crop_top_live: <status-bar px>,       // strip device chrome the Figma frame lacks
+     tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0 })
+   ```
+   Collect `findings` (spacing / size / position in px, color ΔE with hex, typography), `perceptualPct`, and the written image paths (figma / live / diff / overlay / side-by-side).
+
+**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, which misplaces every element inside the sheet and buries the real defect in noise. So for any capture whose frame is not full-screen:
+
+   ```
+   mcp__dev-toolkit__design_visual_compare({ ...as above,
+     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. Take it from the `design_ui_geometry` element that is the sheet container (the outermost element whose height is well under the screen's and which holds the sheet's content), NOT from a guess.
+   - `expected_region` comes from the Figma frame's own 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 has already excluded device chrome.
+
+**Edge insets are defects, not tolerances.** A design that shows 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", never raise `tolerance_px` to make one disappear. The same applies to the sheet's internal content padding, which the normal element pairing measures once the region alignment is right.
+
+**Component reference (best-effort)**: if a Figma atom carries a Code Connect component name and the repo has a matching `*.figma.swift` / `*.figma.kt`, attach that component's reference render to the variant's `componentRefs`.
+
+**Fix prompt**: from the findings, compose a ready-to-paste developer prompt (target file/screen + each deviation with expected vs actual token/value) so the user can hand it straight to an agent to apply the fix.
+
+### 3.5 Close the ledger
+
+Every scoped target id must end in exactly one bucket:
+
+- **covered** - captured AND compared (or captured and explicitly awaiting a Figma frame the user declined to supply, which is a skip)
+- **skipped** - with a concrete reason recorded in 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. An id in neither bucket is a bug in this phase, and Phase 4's gate will fail the run for it.
+
+Before leaving this phase, compare `covered.length + skipped.length` against `scope.targetIds.length`. If they differ, the difference 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 and letting the gate report it 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 - Phase 3's captures and comparison images are already inside it. Do not mint a second timestamped dir here.
+2. Assemble the report object:
+   ```
+   { project, module, platform, figmaUrl, figmaFileKey, timestamp,
+     lang: <prefs.global.outputLanguage>,
+     coverage: { targets: <scoped inventory targets, as the id array or the target objects>,
+                 covered: <audited id array>,
+                 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 in the report instead of printing an anonymous tally. `compareSize` and `liveSize` come straight from the `design_visual_compare` result.
+3. **Render + export**:
+   ```
+   mcp__dev-toolkit__design_report({ report, out_dir: state.designCheck.reportDir,
+     formats: ["html", "pdf"] + (confluence enabled ? ["confluence"] : []) })
+   ```
+   - HTML: self-contained (base64 images, CSS-positioned annotations over the live capture, stacked findings, fix prompt), with the coverage gate banner at the top.
+   - PDF: via Playwright if present; if unavailable the tool returns `pdfError` - report it and note the HTML can be printed manually.
+   - **Confluence**: only if `figmaConfig.confluence.enabled` (or prefs). Reuse the pipeline's Confluence adapter (`/multi-agent:channels` storage-format upload) with the report HTML as the page body + PNGs as attachments. Disabled → graceful skip with a one-line note.
+4. **COVERAGE GATE (blocking, not advisory)** - read `coverage` from the tool result and persist it to `state.designCheck.coverage`:
+   - `gate: "pass"` → report per-variant PASS/FAIL + findings count + report paths.
+   - `gate: "fail"` → the run is **INCOMPLETE**. Print `coverageError`, the `unaccountedIds`, and the exact command that closes the gap: `/multi-agent:design-check --resume`. Do not present an incomplete audit as a finished one, do not bury the miss in a footnote, 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 - the correct response is to drive the missing targets, and only then to report.
+5. Clean up the worktree (`git worktree remove --force`) unless the user asked to keep the built app. The report dir is never removed.
+
+## Notes
+
+- **Feasibility is real**: many projects legitimately cannot be audited (no launchable app, no runtime switch). Report that honestly and stop - never substitute a fabricated or 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, finish each run's gate cleanly, and let `--resume` carry the remainder.
+- **"Pixel perfect" is perceptual + geometric**: a Figma render never matches device dimensions 1:1, so the engine normalizes scale and crops chrome. Findings are reported with explicit px / pt / hex deltas and a tolerance, not as strict pixel equality.
+- The engine (`design_*` tools) is generic and project-agnostic; all project specifics (mock switch keys, extra launch args / targets, variant→node overrides, status-bar crop, coverage floor, Confluence toggle) come from `design-check-config.json` / prefs, never hardcoded.

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

@@ -118,14 +118,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
-  /multi-agent:refactor       Adapted best-practices + bug hunt + upstream-drift check -> one plan, approval, dev + sync
+  /multi-agent:refactor       Adapted best-practices + bug hunt + upstream-drift + dev-toolkit MCP research -> one plan, approval, dev + sync
 
 Setup & Maintenance:
 
   /multi-agent:setup          First-run wizard  -  Keychain tokens + Git identity + language
   /multi-agent:language [en|tr]   Show or set outputLanguage (promptLanguage stays English)
   /multi-agent:stack <id>     Select stack by enabling the matching marketplace plugin(s) (ios / android / mobile / backend / frontend / fullstack / all)
-  /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website)
+  /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website + dev-toolkit MCP)
   /multi-agent:update         Pull latest pipeline + reinstall + run migrations
   /multi-agent:uninstall      Uninstall pipeline from every CLI (--all-data also clears settings + logs; Keychain tokens always intact, double confirm)
 
@@ -170,6 +170,26 @@ Manual Test (Phase 5 standalone  -  Xcode hint flow):
   /multi-agent:manual-test           Checkout task branch, print Xcode/SourceTree hints,
   /multi-agent:manual-test #N        wait for your "ok" / "fix: ..." verdict.
 
+Design Check (mock-mode vs Figma, local-only  -  powered by dev-toolkit-mcp design_* tools):
+
+  /multi-agent:design-check                Whole-module design audit: pick repo+module, gate on mock support,
+                                           enumerate every state driver (launch args, scenario cases, scenario codes,
+                                           fixtures, deep links) into a countable target set, build Debug in a worktree,
+                                           drive each target in mock mode via idb, compare each vs its Figma frame
+                                           (padding/width/spacing/font/color/component/localization), and export a
+                                           report (HTML+PDF, ~/DesignChecks).
+  /multi-agent:design-check <screen>       Scope to one screen's targets (e.g. boarding-pass).
+  /multi-agent:design-check <screen@var>   Scope to a single variant (e.g. boarding-pass@expired).
+  /multi-agent:design-check <figma-url…>   Scope to the frame(s) those URLs name.
+  /multi-agent:design-check --resume       Audit the unaudited remainder of the last run for this repo+module.
+  # COVERAGE GATE: every target is either audited or skipped WITH a concrete reason. Anything else fails the
+  # gate and the run is reported INCOMPLETE with the missing target ids  -  a partial audit never reads as clean.
+  # "Requires a scenario / prefix / launch-arg" is not a reason; reaching those states is the run's job.
+  # When a live screen has no confident Figma match, it SHOWS you the screenshot and asks for the node-id.
+
+  dev-toolkit-mcp design_* tools it drives: design_mock_detect, design_scenario_inventory, design_mock_launch,
+  design_ui_geometry, design_visual_compare, design_report (+ ios_* / android_* device control).
+
 ------------------------------------------------------------
 
 Setup:
@@ -195,7 +215,7 @@ Key Features:
   Multi-Repo       Per-repo worktrees, per-repo identity, integration build before commit
   Identity Routing Git identity auto-picked from repo origin URL (corporate vs personal)
   Issue Safety     Never auto-closes issues (4 approvals required, GitHub + Jira)
-  Store Compliance /multi-agent:test "store-ready" runs 17-rule iOS audit (ITMS / Privacy Manifest /
+  Store Compliance /multi-agent:test "store-ready" runs 18-rule iOS audit (ITMS / Privacy Manifest /
                    code signing / debug-tool leak / IPv6 / SDK list / etc.) and 21-rule Android audit
   Bilingual        EN + TR  -  outputLanguage toggles assistant explanations; promptLanguage is locked en
 
@@ -341,14 +361,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
-  /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift kontrolü -> tek plan, onay, dev + sync
+  /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift + dev-toolkit MCP araştırması -> tek plan, onay, dev + sync
 
 Setup & Maintenance:
 
   /multi-agent:setup              İlk kurulum sihirbazı  -  Keychain token + Git kimliği + dil
   /multi-agent:language [en|tr]   outputLanguage'ı göster veya ayarla (promptLanguage İngilizce kalır)
   /multi-agent:stack <id>         Stack'i eşleşen marketplace plugin'i etkinleştirerek seç (ios / android / mobile / backend / frontend / fullstack / all)
-  /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website)
+  /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website + dev-toolkit MCP)
   /multi-agent:update             En son pipeline'ı çek + reinstall + migration çalıştır
   /multi-agent:uninstall          Pipeline'ı tüm CLI'lerden kaldır (--all-data ayar + logları da siler; Keychain token her zaman dokunulmaz, çift onay)
 
@@ -393,6 +413,26 @@ Manuel Test (Phase 5 standalone  -  Xcode hint akışı):
   /multi-agent:manual-test           Task branch'ine checkout, Xcode/SourceTree hint basar,
   /multi-agent:manual-test #N        "ok" / "fix: ..." yanıtını bekler.
 
+Design Check (mock-mod vs Figma, yalnızca lokal  -  dev-toolkit-mcp design_* tool'larıyla):
+
+  /multi-agent:design-check                Tüm modül tasarım denetimi: repo+modül seç, mock desteğini geçitle,
+                                           her state sürücüsünü (launch arg, senaryo case'leri, senaryo kodları,
+                                           fixture'lar, deep link'ler) sayılabilir bir hedef kümesine çıkar,
+                                           worktree'de Debug derle, her hedefi mock modda idb ile sür, her birini
+                                           Figma frame'iyle karşılaştır (padding/genişlik/spacing/font/renk/
+                                           component/localization), rapor çıkar (HTML+PDF, ~/DesignChecks).
+  /multi-agent:design-check <ekran>        Tek ekranın hedeflerine kapsa (örn. boarding-pass).
+  /multi-agent:design-check <ekran@varyant> Tek varyanta kapsa (örn. boarding-pass@expired).
+  /multi-agent:design-check <figma-url…>   URL'lerin işaret ettiği frame'lere kapsa.
+  /multi-agent:design-check --resume       Bu repo+modül için son koşunun denetlenmemiş kalanını denetle.
+  # KAPSAM GEÇİDİ: her hedef ya denetlenir ya da SOMUT bir gerekçeyle atlanır. Başka her durum geçidi
+  # düşürür ve koşu eksik hedef id'leriyle EKSİK raporlanır  -  kısmi denetim asla temiz görünmez.
+  # "Senaryo / prefix / launch-arg gerektirir" gerekçe değildir; o state'lere ulaşmak koşunun işidir.
+  # Canlı ekranın Figma karşılığı kesin bulunamazsa SANA screenshot'ı gösterip node-id sorar.
+
+  Sürdüğü dev-toolkit-mcp design_* tool'ları: design_mock_detect, design_scenario_inventory, design_mock_launch,
+  design_ui_geometry, design_visual_compare, design_report (+ ios_* / android_* cihaz kontrolü).
+
 ------------------------------------------------------------
 
 Setup:

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

@@ -1,37 +1,39 @@
 ---
-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-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch
+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."
+description-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, dev-toolkit MCP sunucusunu güncel MCP pratiklerine göre araştırır, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch, WebSearch
 ---
 
 # 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, asks the user for approval, applies the approved items, and asks about sync at the end.
+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, 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.)
+**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            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 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
 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):
+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
 
@@ -96,6 +98,78 @@ Procedure:
 
 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 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+
+The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
+
+**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 | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
+
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness 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 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | 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 (new / renamed / removed tool) 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  -  never report the same finding twice.
+
 ## Step 1: SCAN
 
 ```
@@ -168,7 +242,7 @@ Each category is scored out of 10. Output:
 
 ## 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.
+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) so the source is visible.
 
 ```
 | # | Priority | Band | Category | Item | Impact |
@@ -177,7 +251,8 @@ Merge all four bands into a single plan. Tag each row with its band (A best-prac
 | 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 |
+| 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:
@@ -189,13 +264,14 @@ Priority levels:
 
 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?"
+> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Should I start the work?"
 
 Options:
 - "Yes, do all"
 - "Only P0"
 - "P0 + P1 only"
 - "Only bugs (band B)"
+- "Only the dev-toolkit (band E)"
 - (the user may pick specific items)
 
 **Never start the work without approval.**
@@ -206,6 +282,7 @@ 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)
+   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d  -  do not publish from this step.
    - run the relevant tests
    - on success, move to the next
    - on failure, roll back and notify the user
@@ -229,6 +306,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 (README header, `package.json` description) match the count the server reports.
+
 ## Step 8: ASK SYNC
 
 After every approved item is applied, ask:
@@ -236,7 +315,7 @@ 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)
+- "Yes" -> run the `/multi-agent:sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
 - "No" -> emit a report and stop
 - "Commit + push only" -> push the current repo without sync
 
@@ -249,6 +328,7 @@ If $ARGUMENTS is set, 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 optimisation only |

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

@@ -192,7 +192,7 @@ When release-relevant iOS/Android files change, load the matching catalog:
 
 | Platform | Trigger files | Catalog |
 |---|---|---|
-| 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 |
 
 Each finding gets the `ruleID` from the catalog plus the platform policy ref: