@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.0

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent
 language: en
-description: "Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable + Sonnet on Claude Code, GPT + Opus + Sonnet on Copilot CLI) → commit → log. Every step is written to agent-log.md."
+description: "Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable + Sonnet on Claude Code, GPT + Opus + Sonnet on Copilot CLI) → commit → log. Every step is written to agent-log.md. Use when given a Jira ID, a GitHub issue or a free-text task and the whole pipeline should run."
 user-invocable: true
 argument-hint: '"PROJ-12345" "feature/PROJ-12345-flight-filter" | "https://github.com/.../issues/316" | status | log #1 | resume #1 | kill #1 | clear-logs | purge | review'
 ---
@@ -281,6 +281,14 @@ When `dynamicSkillLoading=true` AND the target install is index-only, subagent p
 Run phases sequentially. Log every step to `agent-log.md`.
 If any phase fails, mark task as `paused` and stop  -  user can `resume` later.
 
+**The blocks below are the routing summary, not the specification.** Each phase's
+full contract lives in `$HOME/.claude/multi-agent-refs/phases/phase-{n}-{name}.md`
+(3200 lines across the set) and is read when that phase actually starts. Modes are
+in `phases/modes.md`, operations in `phases/operations.md`, the log shape in
+`phases/log-format.md`. Where a summary here and a ref disagree, the ref wins and
+the summary is the bug: this file used to carry its own copy of the log format,
+and the copy named a path the code had stopped using.
+
 ### Canonical phase labels (TaskCreate + banner)
 
 Every user-facing phase title  -  TaskCreate cards, `phase-banner.sh` headers, and any status line rendered to the terminal  -  MUST come from this table. Labels are always English (`promptLanguage` is locked to `en`):
@@ -570,206 +578,24 @@ Skip this sub-step if the task is NOT a component implementation (e.g., bug fix,
 
 ## Log File Format
 
-Create at `.worktrees/PROJ-{id}/agent-log.md`:
-
-```markdown
-# PROJ-{id}  -  {Task Title}
-**Branch**: {branch-name}
-**Project**: {my-ios-app | my-figma-app}
-**Started**: {YYYY-MM-DD HH:mm}
-**Finished**: {YYYY-MM-DD HH:mm}
-**Total Duration**: {Xm Ys}
-**Status**: 🔄 In Progress | ✅ Complete | ⏸️ Paused | ❌ Failed
-
-## Timeline
-
-| # | Phase | Agent | Model | Duration | Tokens (in/out) | Status | Detail |
-|---|-------|-------|-------|----------|-----------------|--------|--------|
-
-> `Tokens (in/out)` is fed per row from the `phase-tracker.sh tokens` accumulator. If there is no token telemetry, the cell is printed as ` - `.
-
-## Agent Activity Report
-
-### Agent Usage
-| Agent | Call Count | Total Duration | Model(s) | Skill Count |
-|-------|-------------|-------------|------------|-------------|
-| explore | 3 | 12s | haiku | 0 |
-| ios-architect | 1 | 8s | opus | 6 |
-| code-reviewer | 3 | 37s | opus, gpt-5.4, sonnet | 5 each |
-| security-auditor | 1 | 6s | sonnet | 4 |
-| task (build) | 4 | 2m 15s | haiku | 0 |
-| **TOTAL** | **12** | **3m 18s** | | |
-
-### Token Estimate
-| Category | Amount |
-|----------|--------|
-| Main agent (orchestrator) | ~{N}K tokens |
-| Sub-agents (total) | ~{N}K tokens |
-| **Total estimate** | **~{N}K tokens** |
-| Premium request count | ~{N} |
-
-> Token amounts are estimates. For exact usage, run the `/usage` command.
-
-### Per-Phase Time Distribution
-```
-Phase 0: Init       ████░░░░░░░░░░░░  5s
-Phase 1: Analysis   ██████░░░░░░░░░░  12s
-Phase 2: Planning   █████░░░░░░░░░░░  8s
-Phase 3: Dev        ████████████████  2m 35s  ← longest
-Phase 4: Review     ████████░░░░░░░░  37s
-Phase 5: Test  ██░░░░░░░░░░░░░░  (waiting on user)
-Phase 6: Commit     ██░░░░░░░░░░░░░░  3s
-Phase 7: Report    ███░░░░░░░░░░░░░  17s  ← Jira + Wiki + Confluence + Log + Knowledge
-```
-
-### Review Iterations
-| Iteration | Blocking | Important | Suggestion | Decision |
-|-----------|----------|-----------|------------|-------|
-| R1 | 0 | 1 | 2 | 🟡 fix + re-review |
-| R2 | 0 | 0 | 1 | 🟢 pass |
-
-## Files Changed
-
-## Review Consensus
-
-## Cost Breakdown
-
-(Printed in Phase 7 via `pipeline/scripts/render-agent-log-cost.sh <task-id>`. If there is no token data in the tracker, the renderer returns exit 2 and this section is silently skipped.)
-
-| Phase | Model | Tokens in | Tokens out | Est. USD |
-|-------|-------|-----------|------------|----------|
-
-## Test Scenarios (Jira)
-```
-
-### Cost Breakdown  -  emit contract
-
-The Phase 7 agent-log compose step always attempts this render:
-
-```bash
-COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
-  printf '\n%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
-```
-
-Independent of `reportContent.costSummary`  -  agent-log always carries it, PR/Jira bodies are opt-in. The renderer uses `cost-table.json`; a price update flows from a single point to both surfaces at once.
-
----
-
-## SwiftUI Component Generation Guide (Generic)
-
-When the task involves creating a SwiftUI component (any project, not just figma), follow this architecture:
-
-### Component Architecture: Configuration / View / Modifiers
+Canonical shape, and the path the code actually uses, live in
+`$HOME/.claude/multi-agent-refs/phases/log-format.md`. Read it when writing
+the log; do not re-derive the format here.
 
-Every component produces up to 5 files:
+This section used to carry its own copy of the whole template, and the copy
+had gone stale in a way that mattered: it said the log lives at
+`.worktrees/PROJ-{id}/agent-log.md`, while `prune-logs.sh` and the phase
+tracker both use `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`. Two
+answers for one path, and the wrong one was the one loaded on every run.
 
-| File | When | Content |
-|------|------|---------|
-| `{Name}Configuration.swift` | Complex (>3 props) | Pure value type, all declarative properties |
-| `{Name}View.swift` | Always | SwiftUI view, renders Configuration |
-| `{Name}+Modifiers.swift` | Complex | Fluent modifier API chain |
-| `{Name}Preview.swift` | Always | All meaningful variant previews |
-| `{Name}Tests.swift` | Always | ViewInspector + Unit tests |
+## Component Generation
 
-### Configuration Purity Rule
+Generic guide: `$HOME/.claude/multi-agent-refs/component-generation.md`.
+Dispatch (which plugin skill handles it per CLI):
+`$HOME/.claude/multi-agent-refs/component-dispatch.md`.
 
-Configuration structs hold ONLY declarative, value-type properties:
-
-```swift
-// ✅ CORRECT  -  pure value type
-struct ButtonConfiguration {
-    var title: String = ""
-    var style: ButtonStyle = .primary
-    var isEnabled: Bool = true
-    var icon: Image? = nil
-}
-
-// ❌ WRONG  -  these do NOT belong in Configuration
-// Closures → View property
-// @Binding → View property
-// @State → View property
-// AnyView / @ViewBuilder → View generic parameter
-```
-
-### View Implementation
-
-```swift
-struct ButtonView: View {
-    let configuration: ButtonConfiguration
-    private var action: (() -> Void)?  // closure lives in View, not Config
-
-    var body: some View {
-        Button(action: { action?() }) {
-            HStack(spacing: .Spacing.spacing8) {
-                if let icon = configuration.icon { icon }
-                Text(configuration.title)
-                    .typographyStyle(.body1)
-            }
-        }
-        .disabled(!configuration.isEnabled)
-    }
-}
-```
-
-### Modifier Pattern
-
-```swift
-extension ButtonView {
-    func title(_ value: String) -> ButtonView {
-        var config = configuration
-        config.title = value
-        return ButtonView(configuration: config)
-    }
-    func style(_ value: ButtonStyle) -> ButtonView {
-        var config = configuration
-        config.style = value
-        return ButtonView(configuration: config)
-    }
-    func onTap(_ action: @escaping () -> Void) -> ButtonView {
-        var view = self
-        view.action = action
-        return view
-    }
-}
-```
-
-### Simple vs Complex Decision
-
-| Criteria | Simple | Complex |
-|----------|--------|---------|
-| Properties | ≤3 | >3 |
-| Configuration file | No  -  props in View directly | Yes  -  separate struct |
-| +Modifiers file | No | Yes |
-| View file | All-in-one | Renders Configuration |
-
-### 3-Layer Test Strategy
-
-| Layer | Tool | What It Validates |
-|-------|------|-------------------|
-| Structural | ViewInspector | Hierarchy, subview existence, applied modifiers |
-| Visual | Snapshot Tests | Pixel-correct render: light/dark, RTL/LTR |
-| Behavioral | Unit Tests | State changes, closures, configuration mutations |
-
-### Component Checklist (Before Commit)
-
-1. No magic numbers  -  all values are design tokens or named constants
-2. Configuration purity  -  no side-effects or view logic in Config
-3. Modifier correctness  -  fluent API valid, paired modifiers live in the View
-4. Accessibility  -  accessibility label/trait on every interactive element
-5. Preview  -  all meaningful variants in the preview
-6. Test  -  structural + unit tests written
-7. Dark mode  -  renders correctly in both color schemes
-8. Dynamic Type  -  text scales at large sizes without breaking the layout
-
-### When a Figma URL Is Provided
-
-If the user provides a Figma URL:
-1. Fetch the design data with Figma MCP tools (get_design_context, get_screenshot)
-2. Map the design's colors, spacing, and typography onto the project's token system
-3. Apply the Configuration/View/Modifiers pattern above
-4. Use the screenshot as a reference, do not copy it  -  adapt to the project's existing components
-
----
+Loaded only for a task that generates a component from a design, which is
+what it is for. It was previously inline and paid for on every run.
 
 ## Rules
 
@@ -868,85 +694,6 @@ When `multi-agent status` is called, show:
 
 ## Help Display
 
-When called with no args or `help`, detect project and show relevant usage with pipeline explanation:
-
-First show how it works:
-```
-🤖 How it works (8 phases):
-  0. Init       -  Project detection, worktree creation, state file
-  1. Analysis   -  Codebase scan (parallel explore agents, Fable)
-  2. Planning   -  Task breakdown, architecture review, user approval
-  3. Dev        -  TDD loop: write test → write code → build (Sonnet)
-  4. Review     -  Parallel review + Fable triage. Reviewer set by CLI:
-                 • Claude Code → Fable + Sonnet (2 parallel)
-                 • Copilot CLI → GPT-5.4 + Opus + Sonnet (3 parallel)
-  5. Test  -  Optional: switch to the branch, manual test in Xcode
-  6. Commit     -  Commit + push + PR + issue body update (PR links + progress flags)
-  7. Report     -  A single logical phase (5 steps):
-                 1) Jira comment (humanized analysis + test scenarios)
-                 2) Component wiki + Figma screenshot + wiki push (for component tasks)
-                 3) Optional Confluence page update
-                 4) Detailed report into agent-log.md + Quality & Metrics + telemetry
-                 5) Knowledge capture (architecture, patterns, gotchas) + memory
-
-Every step is logged to agent-log.md. An error in any phase → pause.
-resume continues from where it left off.
-```
-
-Then show project-specific usage:
-
-**my-ios-app:**
-```
-🤖 Multi-Agent Task Orchestrator (my-ios-app)
-
-Usage:
-  multi-agent "PROJ-XXX" "branch-name"   → Full pipeline → assigns #ID
-  multi-agent status                        → All tasks with #ID, phase, status
-  multi-agent log [#id]                     → View task log
-  multi-agent resume [#id]                  → Resume paused task
-  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
-  multi-agent clear-logs                    → Delete all logs, keep worktrees
-  multi-agent purge                         → ⚠️ Full reset: delete everything
-  multi-agent review                        → Review current diff only
-
-Example: multi-agent "PROJ-12345" "feature/PROJ-12345-flight-filter"
-```
-
-**my-figma-app:**
-```
-🤖 Multi-Agent Task Orchestrator (figma)
-
-Usage:
-  multi-agent "github-issue-url"            → Full pipeline from issue
-  multi-agent status                        → All tasks with #ID, phase, status
-  multi-agent log [#id]                     → View task log
-  multi-agent resume [#id]                  → Resume paused task
-  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
-  multi-agent clear-logs                    → Delete all logs, keep worktrees
-  multi-agent purge                         → ⚠️ Full reset: delete everything
-  multi-agent review                        → Review current diff only
-
-Example: multi-agent "https://github.com/my-org/my-figma-app/issues/316"
-```
-
-**generic (any iOS project):**
-```
-🤖 Multi-Agent Task Orchestrator (generic)
-
-Usage:
-  multi-agent "bug/feature description"     → Full pipeline from free-text
-  multi-agent "github-issue-url"            → Full pipeline from issue
-  multi-agent "PROJ-XXX" "branch-name"   → Full pipeline with Jira
-  multi-agent status                        → All tasks with #ID, phase, status
-  multi-agent log [#id]                     → View task log
-  multi-agent resume [#id]                  → Resume paused task
-  multi-agent kill [#id]                    → Stop + delete worktree/branch/logs
-  multi-agent clear-logs                    → Delete all logs, keep worktrees
-  multi-agent purge                         → ⚠️ Full reset: delete everything
-  multi-agent review                        → Review current diff only
-
-Example: multi-agent "In LoginView the button color is invisible in dark mode"
-```
-
-Pipeline: Init → Analysis → Planning → Development → Review → User Test → Commit → Wiki → Report
-Each step logged to: .worktrees/{task-id}/agent-log.md
+Rendered by the `multi-agent-help` skill (`/multi-agent:help`), which owns
+the full text in both languages. It used to be duplicated here in English
+only, on a path this skill takes for exactly one input.

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-analysis
 language: en
-description: "Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B render. 23 main sections + 3 footer in Full mode; 7 sections in Lite mode (auto for small features). Collects Figma / Swagger / Confluence / Jira / Standards / Firebase / repo inputs, then stops. Does not chain into dev or create branches."
+description: "Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B render. 23 main sections + 3 footer in Full mode; 7 sections in Lite mode (auto for small features). Collects Figma / Swagger / Confluence / Jira / Standards / Firebase / repo inputs, then stops. Does not chain into dev or create branches. Use when a feature needs a written specification before any code, from Figma, Swagger, Confluence, Jira or repo inputs."
 user-invocable: true
 argument-hint: "[\"<analysis-name>\"] [--lite | --full] [--no-cache] [--preview-conventions]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-analysis-resolve
 language: en
-description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a changelog bump. Companion to multi-agent-analysis."
+description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a changelog bump. Companion to multi-agent-analysis. Use when an analysis document's open questions and risks need answering row by row before development starts."
 user-invocable: true
 argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-autopilot
 language: en
-description: "Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously."
+description: "Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously. Use when a task should run end to end with no confirmation prompts."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-build-optimize
 language: en
-description: "Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan in .build-benchmark/, and re-benchmarks after the developer approves changes. Fails fast on non-iOS stacks."
+description: "Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analyzers, produces a recommend-first optimization plan in .build-benchmark/, and re-benchmarks after the developer approves changes. Fails fast on non-iOS stacks. Use when an iOS build is slow and needs measuring before anything is changed."
 user-invocable: true
 argument-hint: "(none - operates on current repo)"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-create-jira
 language: en
-description: "Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with auto-sizing sections, full preview + explicit approval before create."
+description: "Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with auto-sizing sections, full preview + explicit approval before create. Use when a Jira Task, Bug or Story has to be written to the project's own conventions."
 user-invocable: true
 argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all optional, asked interactively when missing"
 ---

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev
 language: en
-description: "Fast development mode: Init → Dev (Opus) → Test → Commit → Report. Analysis, planning, and review phases are skipped."
+description: "Fast development mode: Init → Dev (Opus) → Test → Commit → Report. Analysis, planning, and review phases are skipped. Use when the work is already scoped and only development, test and commit are needed."
 user-invocable: true
 argument-hint: '"task" [autopilot]  -  issue URL, Jira ID, or free-text + optional autopilot'
 ---