@mmerterden/multi-agent-pipeline 20.13.0 → 20.15.0

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

@@ -11,16 +11,17 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # /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, 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. 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.
+**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 from 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` `header` chips, branch names, file paths, code identifiers, log lines. Option `label`s follow `outputLanguage` like the rest of the picker copy. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: `prefs.global.promptLanguage` is always `en` - this spec and every instruction to the LLM stay English. `prefs.global.outputLanguage` applies to conversational lines and the human-readable parts of the report; pass it to `design_report` as `report.lang` (engine defaults to English, ships `en` + `tr` label packs, per-key `report.labels` overrides). `AskUserQuestion` `header` chips, branch names, file paths, code identifiers and log lines stay English; option `label`s follow `outputLanguage`. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+
+## Gotchas
+
+- A scope that matches no inventory target is an error, not an empty run; print the closest ids and stop.
+- The coverage gate fails the run when a target was neither audited nor skipped with a reason. "Not reached" is not "passed".
+- A Figma variant with no matching mock state is a finding about the mock, not a pass for the screen.
 
 ## Scope  -  `$ARGUMENTS`
 
@@ -33,7 +34,7 @@ The scope decides which **inventory targets** (Phase 0 step 5) the run must audi
 | `screen@variant` | `order-status@expired` | One target |
 | target id | `scenario-case:orderstatusoutcome-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 |
+| `--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 that matches **no** inventory target is an error, not an empty run: print the closest inventory ids and halt.
@@ -77,104 +78,38 @@ Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker per `pic
 
 ## 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". Finding that out after a Debug build wastes the whole run.
-
-   Assert both halves before continuing:
-
-   a. **Session** - `mcp__multi-agent-toolkit__design_scenario_inventory` must be present in the tools available to you, and `mcp__multi-agent-toolkit__design_visual_compare` must accept `live_region`. Absent → the session is bound to a stale process.
-
-   b. **Disk** - probe what a fresh connection WOULD serve. Launch it as registered; under npx `args[0]` is `-y`, not a path.
-   ```bash
-   MA_MCP_CMD=$(python3 -c "import json,os,shlex;e=json.load(open(os.path.expanduser('~/.claude.json')))['mcpServers']['multi-agent-toolkit'];print(shlex.join([e['command']]+e.get('args',[])))")
-   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":{}}' \
-   | eval "$MA_MCP_CMD" 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` → `multi-agent-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 multi-agent-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.designCheck.platform`.
-4. **MOCK FEASIBILITY GATE** - run against the selected module path:
-   ```
-   mcp__multi-agent-toolkit__design_mock_detect({ repo_path: "<module path>", platform: "<ios|android>",
-     extra_keys: <design-check-config mock.keys, if any> })
-   ```
-   Branch on `supported`:
-   - **`false`** → try the **snapshot lane** before halting: a screen renderable from its own view model (filled, flow-advanced, no backend) is auditable without a runtime mock switch. Ask via `AskUserQuestion`, persist `state.designCheck.captureLane = "snapshot"`. State the trade: snapshots reach modules mocks cannot and cannot flip an in-app variant, so the target set is whatever the view model can be built into. Declined or not renderable → **HALT** with `reason`. Never 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 + description in `outputLanguage`): option 1 semantically "Continue"  -  audit the single default Debug state only; option 2 semantically "Cancel"  -  stop.
-   - **`true`** → continue. Persist `state.designCheck.mock = <detect result>` (mechanism, activation, variantsHint, evidence).
-5. **SCENARIO INVENTORY (this is the audit's target set)**:
-   ```
-   mcp__multi-agent-toolkit__design_scenario_inventory({ repo_path: "<module path>", platform,
-     targets_file:      <config inventory.targetsFile>,
-     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 or what the UI exposes 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 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.
+0. **MCP CURRENCY GATE (first, before anything expensive)** - a session started before the last update serves the OLD tool list while reporting "connected". Check both halves before the Debug build: (a) **session** - `design_scenario_inventory` is available and `design_visual_compare` accepts `live_region`; (b) **disk** - probe what a fresh connection would serve. Disk OK but session stale → **HALT**, tell the user to reconnect (`/mcp` → `multi-agent-toolkit` → Reconnect). Disk stale → **HALT**, the checkout needs updating. Both current → continue. Never substitute a local `node` call for a missing tool: the run would silently lose the coverage gate and region alignment. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/mcp-currency-gate.md`. Read it for Phase 0 step 0.
+1. **Repo picker** - `$HOME/.claude/multi-agent-refs/_repo-picker.md`. Account picker skipped unless Confluence export is enabled.
+2. **Module / dev-context picker** - `$HOME/.claude/multi-agent-refs/_dev-context.md`; multi-module allowed, each audited independently.
+3. **Platform detect** - persist `state.designCheck.platform`.
+4. **MOCK FEASIBILITY GATE** - `mcp__multi-agent-toolkit__design_mock_detect` on the selected module path. Branch on `supported`:
+   - **`false`** → try the **snapshot lane** before halting: a screen renderable from its own view model is auditable without a runtime mock switch. Ask via `AskUserQuestion`, persist `state.designCheck.captureLane = "snapshot"`, and state the trade (no in-app variant flips). Declined or not renderable → **HALT** with `reason`. Never fabricate a comparison.
+   - **`"debug-only"`** → `AskUserQuestion` warning: variants cannot be toggled at launch, only the default Debug state is comparable. Continue / Cancel.
+   - **`true`** → continue; persist `state.designCheck.mock`.
+5. **SCENARIO INVENTORY (this is the audit's target set)** - `mcp__multi-agent-toolkit__design_scenario_inventory` with the config's inventory overrides. This list, not the agent's reading of the code or what the UI exposes 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 only the default launch state can be audited; a `debug-only` project lands here.
+   - `truncated: true` → 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[] }`.
+6. **Scope resolve** - intersect `$ARGUMENTS` with `inventory.targets`; persist `state.designCheck.scope = { argument, targetIds[] }`. Print the set grouped by screen as `<n> targets · <relaunchCount> relaunches` (cost from `plan`, not the target count). Ask for confirmation only when `relaunchCount` exceeds `config coverage.confirmAbove` (default 25), as a cost estimate; never propose a smaller scope as the easy path.
+7. **`--resume`** - scope = the latest `run-state.json` targets minus `covered` minus `skipped`. No previous run → tell the user and fall back to whole-module scope after confirmation.
+8. **Report dir** - create `~/DesignChecks/{repo}__{module}/{UTC-timestamp}/` (+ `assets/`) now, persist `state.designCheck.reportDir`; it exists before driving starts.
+9. **Worktree** - `{projectRoot}/.worktrees/{taskId}`, `taskId` = `DC-<shortId>`, **never under $HOME**; prune stale locks and add the residue guard first. Local mode is not offered.
 
-   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 the `phase-0-init.md` Step 6 worktree location convention exactly: `{projectRoot}/.worktrees/{taskId}` with `taskId` = `DC-<shortId>`, **never under $HOME** (the `.worktrees` segment is fixed, not a preference). 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"`, `projectRoot`, `worktreePath` and `designCheck` (which carries `module` and `platform`).
+Then persist `agent-state.json`. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/init-inventory.md`. Read it for Phase 0 steps 1-9.
 
 ## Phase 1 - Build & Launch (mock)
 
-1. **Debug build** in the worktree (mock activation requires the Debug configuration):
-   - iOS: `mcp__multi-agent-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__multi-agent-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.
+Debug build in the worktree (mocks need Debug), boot, install once, fix status bar / appearance / locale, launch via `design_mock_launch` with the Phase 0 activation (`debug-only`: plain launch). Phase 3 relaunches, never rebuilds. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/build-launch.md`. Read it for Phase 1.
 
 ## 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[]`.
+Fetch the frame tree, map each scoped target to a frame, fetch screenshot + design context per variant, persist `state.designCheck.variants[]`. **Ambiguous or unmatched → defer to the Phase 3.3 batch-ask. Never guess silently.** Full procedure: `$HOME/.claude/multi-agent-refs/design-check/figma-mapping.md`. Read it for Phase 2.
 
 ## 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.
+**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, scenario case, or typed scenario code - which is how a module's error / edge states go missing.
 
 ### 3.0 What every capture is compared against
 
@@ -182,69 +117,23 @@ Persist the variant list + spec + PNG paths to `state.designCheck.variants[]`.
 
 ### 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 |
+**Follow `inventory.plan`, filtered to the scoped ids.** Each batch is one launch: the relaunch target opens a screen, then every in-app target for that screen is flipped while the app sits there - **no relaunch between them**. Driving the plan is what makes full coverage affordable. Activate each target by its `driver.type`, and capture the tap-reachable sub-states (sheets, modals, inline errors) under `<id>#<sub-label>`. Each capture (screenshot + `design_ui_geometry`) goes to `state.designCheck.captured[]`. **Persist `state` and `run-state.json` after every capture**, so a run that dies mid-way resumes from where it stopped. Full procedure (driver table, capture mechanics): `$HOME/.claude/multi-agent-refs/design-check/drive-capture.md`. Read it for Phase 3.1.
 
-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__multi-agent-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 order", "crashes on launch: <symbol>"). "Requires a scenario / prefix / launch-arg" is **not** a reason - it describes the work, which is this phase's job.
+An unreachable target is recorded immediately as `{ id, reason }` in `state.designCheck.skipped[]` with a concrete reason. "Requires a scenario / prefix / launch-arg" is **not** a reason - it describes the work, which 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[]`.
+Accept only a **confident** match against the Phase 2 tree; 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".
+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**, name the screen, and ask for the Figma node-id / URL (in `outputLanguage`). Each answer 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__multi-agent-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__multi-agent-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`.
+`design_visual_compare` per pair (matched + user-supplied) with `tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0`. **Bottom sheets, modals, and any partial overlay need region alignment** (`live_region` from the sheet container in `design_ui_geometry`, never a guess, plus `expected_region` from the Figma placement). Attach Code Connect refs (best-effort); compose a paste-ready fix prompt. Full procedure (match, batch-ask mechanics, compare call, region alignment): `$HOME/.claude/multi-agent-refs/design-check/compare.md`. Read it for Phase 3.2-3.4.
 
-**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.
+**Edge insets are defects, not tolerances.** 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.
 
 ### 3.5 Close the ledger
 
@@ -255,48 +144,24 @@ Every scoped target id must end in exactly one bucket:
 
 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.
+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 - 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,
-                   walk: { components: <inventoried>, converged: <count>,
-                           didNotConverge: [ { component, attempts } ],
-                           notVerified: [ { item, tag, reason } ] } } ] }
-   ```
-
-   `walk` separates a checked screen from a viewed one. An empty `notVerified` on a run that never captured a dark or mirrored pass is a false clean - list the skip. Field definitions: `features/design-conformance.md`.
-   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__multi-agent-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.
+1. **Output dir**: `state.designCheck.reportDir` from Phase 0; never a second timestamped dir.
+2. **Assemble** the report object: `coverage` (scoped `targets`, `covered`, `skipped` with reasons, `truncatedInventory`, optional `floor`) and per-variant results with a `walk` block (`components`, `converged`, `didNotConverge`, `notVerified`). `walk` separates a checked screen from a viewed one: an empty `notVerified` on a run that never captured a dark or mirrored pass is a false clean - list the skip. Pass **ids**, not counts.
+3. **Render + export** with `design_report` (`html` + `pdf`, + `confluence` only when enabled; disabled → graceful skip). Full procedure (report object, export formats, cleanup): `$HOME/.claude/multi-agent-refs/design-check/export.md`. Read it for Phase 4.
 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.
+5. Remove the worktree 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.
+- **Feasibility is real**: a project with no launchable app or no runtime switch cannot be audited. 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.
+- **"Pixel perfect" is perceptual + geometric**: scale normalized, chrome cropped; findings carry px / pt / hex deltas and a tolerance.
+- The `design_*` engine is project-agnostic; project specifics (mock keys, launch args / targets, node overrides, status-bar crop, coverage floor, Confluence toggle) come from `design-check-config.json` / prefs, never hardcoded.

package/pipeline/commands/multi-agent/diff-explain/SKILL.md

@@ -6,6 +6,8 @@ parameters: [{"name":"task","kind":"run-id"},{"name":"--triage","kind":"path"},{
 gui: form
 destructive: false
 confirm: none
+context: fork
+agent: Explore
 ---
 
 # multi-agent diff-explain  -  Phase 4 Triage to Diff Bridge

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

@@ -0,0 +1,65 @@
+---
+description: "Estimate new work from similar closed Jira work: a P25-P75 range per role from logged time, with the tickets behind it and the modules touched. Read-only; never a single number, none below three samples. Use when a story, analysis or request needs an effort range."
+description-tr: "Yeni işi ona benzeyen kapanmış işlerden tahmin eder: benzer bitmiş Jira kayıtlarını bulur, onlara ve rol alt görevlerine girilen süreyi okur, rol başına P25-P75 aralığını dayandığı ticket'larla ve işin dokunduğu modüllerle raporlar. Salt-okunur; asla tek sayı vermez, üç örneğin altında hiç sayı vermez."
+allowed-tools: Bash, Read, Grep, AskUserQuestion
+argument-hint: "<analysis.md | \"free text\"> [--project KEY]"
+parameters: [{"name":"input","kind":"text","required":true},{"name":"--project","kind":"text"}]
+gui: form
+destructive: false
+confirm: none
+not-for: analysis, analysis-jira
+---
+
+# multi-agent estimate
+
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
+**Input**: $ARGUMENTS
+
+Turns history into a range. The query and the reading of the work are yours;
+the arithmetic and the minimum-sample rule are the script's. Nothing is written
+to Jira or anywhere else.
+
+Script: `$HOME/.claude/scripts/estimate.mjs`.
+
+## Gotchas
+
+- The query must say `statusCategory = Done`; the script refuses anything else, because open work has no final time.
+- Logged time is only as good as the team's logging. A role with sub-tasks but no `timespent` has no samples; say that rather than reading it as zero effort.
+- Similar means similar work, not similar words: narrow by component or label first, then by text. A query that returns fifty unrelated issues gives a confident-looking range about nothing.
+- Fewer than three samples gives no number for that row. Do not fill it in from judgement.
+
+## Step 1 - What is being estimated
+
+From an analysis document, read its feature name, the components or channels it
+names and its story count; from free text, its nouns. Map the modules it
+touches with the repo map when a repository is at hand:
+
+```bash
+node "$HOME/.claude/scripts/repo-map.mjs" --root "<repo>" --budget 800
+```
+
+## Step 2 - The query
+
+Build one JQL from the project (`--project`, else `prefs.global.issueTree.projectKey`),
+`statusCategory = Done`, the components or labels found above, and at most two
+`text ~` terms. Show it and let the user edit it with one `AskUserQuestion`
+(**Run it** / **Edit the query** / **Cancel**).
+
+## Step 3 - Run
+
+```bash
+node "$HOME/.claude/scripts/estimate.mjs" --jql "<jql>" \
+  --roles "$(jq -r '.global.issueTree.subtaskRoles // [] | join(",")' "$HOME/.claude/multi-agent-preferences.json")"
+```
+
+With no roles configured the report has the total and story-point rows only.
+
+## Step 4 - Report
+
+Print the table verbatim, then the modules from Step 1. Say which rows had too
+little history, how many issues were sampled, and that the range describes the
+past work the query found: the choice of query is judgement, the numbers are
+arithmetic over it.
+
+**Stop. No ticket is created or edited.**