@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.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/dev/SKILL.md

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Hızlı geliştirme modu: Init → Dev (Opus) → Test → Commit → Report. Analiz, planlama ve review fazları atlanır."
 ---
 

package/pipeline/commands/multi-agent/dev-autopilot/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Fastest mode: Dev (Opus) plus Autopilot. Init → Dev → Commit → Report with zero confirmations."
+description: "Fastest mode: Dev (Opus) plus Autopilot. Init → Dev → Commit → Report with zero confirmations. Use when a change is well understood and should go from start to commit with no questions asked."
 description-tr: "En hızlı mod: Dev (Opus) + Autopilot. Init → Dev → Commit → Report, sıfır onay."
 ---
 

package/pipeline/commands/multi-agent/dev-local/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Fast mode + local  -  Init → Dev(Opus) → Commit → Report, no worktree."
+description: "Fast mode + local  -  Init → Dev(Opus) → Commit → Report, no worktree. Use when a change should be developed on the current branch without creating a worktree."
 description-tr: "Hızlı mod + lokal - Init → Dev(Opus) → Commit → Report, worktree yok."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, Skill
 ---

package/pipeline/commands/multi-agent/dev-local-autopilot/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction."
+description: "Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction. Use when a change should be developed on the current branch with no worktree and no prompts."
 description-tr: "En hızlı + lokal - Dev(Opus) + autopilot, worktree yok, sıfır etkileşim."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, WebFetch, Skill
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which code change'."
+description: "Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which code change'. Use when a review finding has to be traced to the exact lines that caused it."
 description-tr: "Faz 4 triyaj bulgularını branch diff satırlarına eşler. Review sonrası kullanılan salt-okunur komut: hangi bulgu hangi kod değişikliğine denk geliyor sorusunu cevaplar."
 argument-hint: "[#task-id | --triage <path> | --state <path>] [--branch <name>] [--base <name>]"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenario comment). No dev phase."
+description: "Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenario comment). No dev phase. Use when local work is already done and only review, build, commit and reporting remain."
 description-tr: "Halihazırda bitmiş LOKAL işi pipeline kuyruğundan geçirir: Review → Build+Test → Commit/PR → Report (teknik analiz + Jira test-senaryosu yorumu). Dev fazı yok."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, Skill
 ---
@@ -52,12 +52,12 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `finish` treats
 
 ## Phase execution (reuse the existing phase contracts)
 
-- **Phase 4 Review** — run per `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
+- **Phase 4 Review** - run per `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
   - interactive: present them and ask (`AskUserQuestion`) whether to fix now (loop back through a minimal Phase-3-style TDD fix) or proceed;
   - `autopilot` (or `prefs.global.finish.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
-- **Phase 5 Build+Test** — the **automated success gate** (this is what "build+test success" means here; the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/frontend build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" — never fabricate test results.**
-- **Phase 6 Commit/PR** — per `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/multi-agent-refs/pipeline-output-formatting` and `rules/git-conventions` — `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
-- **Phase 7 Report** — per `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content for `finish`: a Jira **comment** carrying the technical analysis + the test scenarios (and, when the PR was opened, the PR description). Every body runs through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
+- **Phase 5 Build+Test** - the **automated success gate** (this is what "build+test success" means here; the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/frontend build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" - never fabricate test results.**
+- **Phase 6 Commit/PR** - per `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/multi-agent-refs/pipeline-output-formatting` and `rules/git-conventions` - `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- **Phase 7 Report** - per `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content for `finish`: a Jira **comment** carrying the technical analysis + the test scenarios (and, when the PR was opened, the PR description). Every body runs through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
 
 ## Modes
 
@@ -103,6 +103,6 @@ No TaskList widget. After every state change call `bash $HOME/.claude/scripts/ph
 
 ```bash
 /multi-agent:dev-local "PROJ-12345"     # develop locally (Init→Dev→Commit→Report, no review/test)
-# … you inspect / hand-test the change …
+# ... you inspect / hand-test the change ...
 /multi-agent:finish                        # now: review + build/test + PR + Jira analysis & test scenarios
 ```

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

@@ -1,5 +1,5 @@
 ---
-description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms."
+description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms. Use when a saved routine is no longer wanted and should be removed."
 description-tr: "Kaydedilmiş bir /multi-agent rutinini (/multi-agent:save ile oluşturulan) siler: local-only komutunu ve registry kaydını kaldırır. Hangisini soracak ve onay alacak."
 argument-hint: "[name]  -  routine to remove; asked if omitted"
 allowed-tools: Bash, Read, AskUserQuestion

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) and worktree residue (orphan .worktrees dirs, gitlink index entries) from past runs. Dry-run first; confirms before deleting."
+description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) and worktree residue (orphan .worktrees dirs, gitlink index entries) from past runs. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out."
 description-tr: "Geçmiş çalışmalardan kalan /tmp scratch'ini (picker durumu, review diff'leri, kanal payload'ları, analiz taslakları) ve worktree kalıntılarını (sahipsiz .worktrees klasörleri, gitlink index kayıtları) süpürür. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<minutes>] [--yes]  -  dry-run unless confirmed"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatibility)."
+description: "Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatibility). Use when asked what the pipeline can do, which mode to pick, or what a command means."
 description-tr: "Multi-agent pipeline kullanım kılavuzu - prefs.global.outputLanguage'e göre EN veya TR render edilir (geriye uyumluluk için promptLanguage'e düşer)."
 ---
 
@@ -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/issue/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline."
+description: "List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline. Use when a GitHub issue should be picked up and started without knowing its number in advance."
 description-tr: "Atanmamış GitHub issue'larını listeler, birini seçtirir, otomatik atar ve multi-agent pipeline'ı başlatır."
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "List open Jira issues, pick one, and launch the multi-agent pipeline."
+description: "List open Jira issues, pick one, and launch the multi-agent pipeline. Use when a Jira issue should be picked up and started without knowing its key in advance."
 description-tr: "Açık Jira issue'larını listeler, birini seçtirir ve multi-agent pipeline'ı başlatır."
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Stop the given task, then remove its worktree and branch. Asks for confirmation."
+description: "Stop the given task, then remove its worktree and branch. Asks for confirmation. Use when a running or stuck task should be stopped and its worktree removed."
 description-tr: "Verilen görevi durdurur, ardından worktree'sini ve branch'ini kaldırır. Onay ister."
 argument-hint: "#id  -  task ID to delete (e.g. #2)"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English."
+description: "Toggle outputLanguage (assistant explanations). promptLanguage is fixed to English. External payloads stay English. Use when the assistant should explain itself in a different language."
 description-tr: "outputLanguage'i değiştirir (asistan açıklamaları). promptLanguage İngilizce sabittir. Dış payload'lar İngilizce kalır."
 argument-hint: "[en|tr]  -  sets outputLanguage; omit for interactive picker; use 'output en|tr' for explicit form"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Full pipeline in local mode  -  no worktree, runs directly on the current branch."
+description: "Full pipeline in local mode  -  no worktree, runs directly on the current branch. Use when the full pipeline should run on the current branch without creating a worktree."
 description-tr: "Tam pipeline lokal modda - worktree yok, doğrudan mevcut branch üzerinde çalışır."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, Skill
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Full pipeline + local + autopilot  -  no worktree, no confirmations; runs 7 phases (User Test skipped) end-to-end on the current branch."
+description: "Full pipeline + local + autopilot  -  no worktree, no confirmations; runs 7 phases (User Test skipped) end-to-end on the current branch. Use when the full pipeline should run on the current branch with no worktree and no prompts."
 description-tr: "Tam pipeline + lokal + autopilot - worktree yok, onay yok; 7 fazı (Kullanıcı Testi atlanır) mevcut branch üzerinde uçtan uca koşar."
 argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, Skill

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

@@ -1,5 +1,5 @@
 ---
-description: "Show the agent-log.md for the given task. With no ID, shows the most recent task."
+description: "Show the agent-log.md for the given task. With no ID, shows the most recent task. Use when asked what a task did, or to read its log."
 description-tr: "Verilen görevin agent-log.md dosyasını gösterir. ID verilmezse en son görevi gösterir."
 argument-hint: "[#id]  -  optional: task ID (e.g. #3). If omitted, the most recent task is used."
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at /multi-agent:test)."
+description: "Switch to the active task's branch and prepare it for manual testing in Xcode. Phase 5 standalone (the UI Bug Hunter lives at /multi-agent:test). Use when a finished change needs trying by hand on a device or simulator."
 description-tr: "Aktif görevin branch'ine geçer ve Xcode'da manuel test için hazırlar. Faz 5'in bağımsız hali (UI Bug Hunter /multi-agent:test'te)."
 ---
 

package/pipeline/commands/multi-agent/prune-logs/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting."
+description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting. Use when task logs have built up and need trimming by age, project or task."
 description-tr: "~/.claude/logs/multi-agent altındaki görev bazlı proje loglarını siler (yaş/proje/görev filtresi). Denetim izi + metrikler korunur. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<days>] [--project=<name>] [--task=<id>] [--yes]"
 ---

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

@@ -1,5 +1,5 @@
 ---
-description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation."
+description: "⚠️ Wipes every worktree, branch, log, and state file. Irreversible; asks for double confirmation. Use when every worktree, branch, log and state file should be wiped and the pipeline reset."
 description-tr: "⚠️ Tüm worktree, branch, log ve state dosyalarını siler. Geri alınamaz; çift onay ister."
 ---