@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.0

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-autopilot
 language: en
-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."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, or free-text'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-local
 language: en
-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."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-dev-local-autopilot
 language: en
-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."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-diff-explain
 language: en
-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."
 user-invocable: true
 argument-hint: "[#task-id | --triage <path> | --state <path>] [--branch <name>] [--base <name>]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-finish
 language: en
-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."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-forget
 language: en
-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."
 user-invocable: true
 argument-hint: "[name]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-garbage-collect
 language: en
-description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before deleting."
+description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out."
 user-invocable: true
 argument-hint: "[--older-than=<minutes>] [--yes]  -  dry-run unless confirmed"
 ---

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-issue
 language: en
-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."
 user-invocable: true
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-jira
 language: en
-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."
 user-invocable: true
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-kill
 language: en
-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."
 user-invocable: true
 argument-hint: "#id  -  task ID to delete (e.g. #2)"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-language
 language: en
-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."
 user-invocable: true
 argument-hint: "[en|tr]  -  sets outputLanguage; omit for interactive picker; use 'output en|tr' for explicit form"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-local
 language: en
-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."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-local-autopilot
 language: en
-description: "Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch."
+description: "Full pipeline + local + autopilot  -  no worktree, no confirmations, all 8 phases run end-to-end on the current branch. Use when the full pipeline should run on the current branch with no worktree and no prompts."
 user-invocable: true
 argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-log
 language: en
-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."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID (e.g. #3). If omitted, the most recent task is used."
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-manual-test
 language: en
-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."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID. Defaults to the latest task if omitted"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-prune-logs
 language: en
-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."
 user-invocable: true
 argument-hint: "[--older-than=<days>] [--project=<name>] [--task=<id>] [--yes]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-purge
 language: en
-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."
 user-invocable: true
 ---
 

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

@@ -1,39 +1,41 @@
 ---
 name: multi-agent-refactor
 language: en
-description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, draft one plan, take approval, develop, then ask whether to sync."
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync. Use when asked to review a project for bugs, gaps or improvements, or to check whether derived skills have drifted from upstream."
 user-invocable: true
-argument-hint: 'bugs | best-practices | drift | security | tests | performance | docs | ci | deps'
+argument-hint: 'bugs | best-practices | drift | dev-toolkit | security | tests | performance | docs | ci | deps'
 ---
 
 # Multi-Agent Refactor
 
-**One command. Best-practices + Bug hunt + Upstream drift -> Score -> Plan -> Approval -> Develop -> Sync.**
+**One command. Best-practices + Bug hunt + Upstream drift + Dev-toolkit -> Score -> Plan -> Approval -> Develop -> Sync.**
 
-Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, scores everything, drafts a single prioritized plan, takes approval, applies the approved items, and asks about sync when done.
+Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, researches the companion dev-toolkit MCP server against current MCP practice, scores everything, drafts a single prioritized plan, takes approval, applies the approved items, and asks about sync when done.
 
-**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", etc.)
+**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "dev-toolkit", etc.)
 
 ## Flow
 
 ```
 Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
+Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion dev-toolkit repo -> plan band E
 Step 1:  SCAN            Scan the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
 Step 3:  SCORE           Each category out of 10, total /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift), priority-ordered
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
 Step 5:  ASK             "Shall I start developing?"  -  take approval
 Step 6:  IMPLEMENT       Apply approved items in order (lint, test, commit)
 Step 7:  VERIFY          Confirm all tests + lint pass
 Step 8:  ASK SYNC        "Shall I run multi-agent-sync?"  -  take approval
 ```
 
-Plan bands (all four feed the single Step 4 table):
+Plan bands (all five feed the single Step 4 table):
 - **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
 - **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
 - **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
 - **D - Drift**: upstream updates to skills we derived from an external source.
+- **E - Dev-toolkit**: current-practice gaps in the companion dev-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
 
 ## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
@@ -71,19 +73,27 @@ The upstream mapping is **configuration, never hardcoded** (it can reference pri
   "upstreamPlugin": "<plugin name>",
   "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
   "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
-  "upstreamRepoUrl": "<optional https url>"                // used only if the marketplace is not installed locally
+  "upstreamVersionSource": "marketplace.json",             // which manifest is authoritative; default marketplace.json
+  "upstreamLocalClone": "<optional path>",                 // working copy of the upstream repo, preferred over the cache
+  "upstreamRepoUrl": "<optional https url>"                // used when neither a clone nor the marketplace is available
 }
 ```
 
+**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` holds only what the last `claude marketplace update` fetched. Treating it as the current upstream version is how this step reported "up to date" while the derivation was four releases behind: the cache sat at 0.2.1 and upstream was at 0.4.1. Resolve in the order below, and never let the cache alone produce an "up to date" verdict.
+
+**Which manifest carries the version** is `upstreamVersionSource`, default `marketplace.json` - that is what a marketplace consumer resolves. Some upstreams keep per-plugin `plugin.json` versions deliberately unused, so reading those records a version nobody ships. One entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG said plainly that `plugin.json` is not used.
+
 Procedure:
 1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured". Never invent a source.
-2. For each entry, resolve the current upstream version:
-   - **Preferred**: read the newest installed version under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/` (its `.claude-plugin/plugin.json` `version`), plus that version's `CHANGELOG.md`.
-   - **Fallback**: if the marketplace is not installed locally and `upstreamRepoUrl` is set, `WebFetch` the upstream `plugin.json` + `CHANGELOG.md`.
-   - If neither is reachable, record "upstream unreachable" and move on (do not fail the run).
+2. For each entry, resolve the current upstream version, stopping at the first source that answers:
+   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`, and report when the clone is itself behind its remote so a stale working copy is not silently trusted.
+   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the active account even though it exists; that is unreachable, not "no drift".
+   - **Plugin cache**: last resort. When it is the only source that answered, report **`unverified (cache only)`**, never "up to date", and add a plan item to configure `upstreamLocalClone`.
+   - If nothing is reachable, record "upstream unreachable" and move on (do not fail the run).
 3. Compare the resolved upstream version to `derivedFromVersion`:
-   - equal -> "up to date" (no drift)
-   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ templates) against our `localPath` copy. Summarize what changed.
+   - equal, from an authoritative source -> "up to date" (no drift)
+   - equal, from the cache only -> "unverified (cache only)"
+   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ templates) against our `localPath` copy. Summarize what changed, ignoring entries that touch only skills outside `upstreamSkills`.
 4. Emit the drift table (plan band D):
 
 ```
@@ -94,6 +104,54 @@ Procedure:
 
 5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>". Do not auto-apply  -  it goes through Step 5 approval; after porting, bump the entry's `derivedFromVersion`.
 
+## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+
+The pipeline's device and browser hands are MCP tools served by a companion repo (`dev-toolkit-mcp`), and several pipeline skills declare a minimum toolkit version. This step researches current MCP practice and audits that repo against it.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit`: `{ enabled, label, localPath, mcpServerName, packageName, registry, repoUrl }`.
+2. If unset, auto-detect from the MCP registration: `mcpServers` in `~/.claude.json` (plus `projects[*].mcpServers`) and `~/.claude/settings.json`; for a stdio `node` entry take `dirname(args[0])`, and accept it only if that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. Neither resolves (or `enabled: false`) -> skip and report "no dev-toolkit configured". Never guess a path, never clone.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | features released since the pinned SDK that the server does not use: tool annotations, `outputSchema` + structured content, resource links, progress + cancellation, `tools/list_changed`, pagination |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs | description budget, tool-count ceilings, naming, output size limits, permission ergonomics |
+| 3 | Peer servers | GitHub search on the same domain + `stars:>50` | surfaces we lack, conventions peers converged on, what to discard |
+| 4 | Wrapped tooling | `simctl`, `idb`, `adb`, `xcodebuild`, Playwright notes, Apple ITMS + review guidelines | deprecated flags in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community | what server authors changed recently (transport, output-token diets, error shape) |
+
+**Audit the toolkit**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"; find "$DT/tools" -name "*.js" -exec node --check {} \;
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"   # stdout = JSON-RPC channel
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"                    # advertised count vs reality
+node -p "require('$DT/package.json').files.join('\n')"; ls -d "$DT"/tools/*/  # files[] covers runtime dirs
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool has a description + `inputSchema`; token-heavy results (screenshots, UI trees) are truncated or file-backed; failures return an error result, not a throw; `CHANGELOG.md`, CI and tests exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `multi-agent-sync` Step 3d.
+- A finding that changes the tool surface pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it.
+
 ## Step 1: SCAN
 
 ```
@@ -166,7 +224,7 @@ Each category is scored out of 10. Output format:
 
 ## Step 4: PLAN  -  one merged, prioritized table
 
-Merge all four bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift).
+Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E dev-toolkit).
 
 ```
 | # | Priority | Band | Category | Item | Impact |
@@ -175,7 +233,8 @@ Merge all four bands into a single plan. Tag each row with its band (A best-prac
 | 2 | P0 | B | Testing | Fix nil-deref on empty response (src/y:42) | High |
 | 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
 | 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
-| 5 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
+| 5 | P1 | E | Toolkit | Add read-only annotations to the dev-toolkit device tools | Medium |
+| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
 ```
 
 Priority levels:
@@ -187,13 +246,14 @@ Priority levels:
 
 After showing the plan, ask:
 
-> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, and upstream drift. Shall I start developing?"
+> "I found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Shall I start developing?"
 
 Options:
 - "Yes, do all of them"
 - "Do only the P0 ones"
 - "Do only P0 + P1"
 - "Only the bugs (band B)"
+- "Only the dev-toolkit (band E)"
 - (the user can make a specific selection)
 
 **NEVER start developing without approval.**
@@ -204,6 +264,7 @@ Apply approved items in order:
 
 1. For each item:
    - Make the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion`)
+   - Band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, `tools/list` handshake, advertised tool count matching reality), commit there. Publishing is `multi-agent-sync` Step 3d.
    - Run the relevant tests
    - If successful, move to the next
    - If it fails, revert and notify the user
@@ -227,6 +288,8 @@ echo "Lint: PASS/FAIL"
 echo "Test: PASS/FAIL (X/Y passed)"
 ```
 
+If any band-E item was applied, verify the toolkit repo too: syntax-check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts match the count the server reports.
+
 ## Step 8: ASK SYNC
 
 After all approved items are applied, ask:
@@ -234,7 +297,7 @@ After all approved items are applied, ask:
 > "Development complete. Shall I run multi-agent-sync?"
 
 Options:
-- "Yes" -> run the `/sync` command (full ecosystem sync)
+- "Yes" -> run the `/sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
 - "No" -> report and finish
 - "Only commit + push" -> push only the current repo without sync
 
@@ -247,6 +310,7 @@ If $ARGUMENTS is specified, focus on that band/category only:
 | `bugs` | Bug hunt only (band B) |
 | `best-practices` | Field research + adapted plan only (band A) |
 | `drift` | Upstream derived-skill drift only (band D) |
+| `dev-toolkit` | Companion MCP toolkit research + audit only (band E) |
 | `security` | Security analysis only |
 | `tests` | Test coverage and quality only |
 | `performance` | Performance optimization only |

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-resume
 language: en
-description: "Resume a stopped or failed task from the phase where it left off."
+description: "Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left off."
 user-invocable: true
 argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review
 language: en
-description: "Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select."
+description: "Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select. Use when a branch diff or a pull request needs reviewing before it merges."
 user-invocable: true
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  PR by number/URL, repo+number, or branch (GitHub + Bitbucket Server). If omitted: interactive PR picker, else current branch."
 ---
@@ -46,7 +46,7 @@ Skip Phase 0-3 and review a diff only. Input shapes: a PR (`#N`, `repo#N`, GitHu
 
    | Platform | Trigger files | Catalog to load |
    |---|---|---|
-   | iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  17 rules + ITMS refs |
+   | iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  18 rules + ITMS refs |
    | Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `pipeline/skills/shared/core/google-play-compliance/SKILL.md`  -  21 rules + Play policy refs |
 
    It appends the catalog's `ruleID` + the Apple ITMS / Play policy ref to each finding:

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review-issue
 language: en
-description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code."
+description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code. Use when deciding whether a GitHub issue is specified well enough to hand to development."
 user-invocable: true
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-review-jira
 language: en
-description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code."
+description: "Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as a Jira comment. Read-only on code. Use when deciding whether a Jira issue is specified well enough to hand to development."
 user-invocable: true
 argument-hint: "[JIRA-KEY | Jira URL]  -  optional; with no argument, pick from your open Jira issues"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-routines
 language: en
-description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which saved routines exist or what one of them does."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-save
 language: en
-description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; stored local-only, never synced."
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; stored local-only, never synced. Use when a job keeps recurring and should become its own reusable command."
 user-invocable: true
 argument-hint: "[name]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-scan
 language: en
-description: Skill security scan: walks local skill directories against a tiered pattern catalog.
+description: "Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsafe or unexpected content."
 user-invocable: true
 argument-hint: "[--strict] [--target <path>]  -  optional: --strict enables CI failure mode, --target picks a custom directory"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-search
 language: en
-description: Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus.
+description: "Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when something has to be found across past task logs."
 user-invocable: true
 argument-hint: "<query> [--project <slug>] [--since 7d|YYYY-MM-DD] [--phase <N>] [--semantic] [--json|--tsv]"
 ---

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-setup
 language: en
-description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation."
+description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding."
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-stack
 language: en
-description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all)."
+description: "Select the active stack for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json (ios/android/mobile/backend/frontend/fullstack/all). Use when a repo's stack changed or the wrong plugins are enabled for it."
 user-invocable: true
 ---
 
@@ -9,7 +9,7 @@ user-invocable: true
 
 Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. The `ai-common-engineering-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
 
-This replaces the old `stack-swap.sh` mechanic that physically moved skill directories. No SessionStart hook, no directory shuffling — enablement is declarative, per-repo, and versioned.
+This replaces the old `stack-swap.sh` mechanic that physically moved skill directories. No SessionStart hook, no directory shuffling - enablement is declarative, per-repo, and versioned.
 
 ## Usage
 
@@ -44,7 +44,7 @@ multi-agent-stack all              # all four stack toolkits + common
 
 ## Notes
 
-- Enablement is per-repo and declarative — commit `.claude/settings.json` so teammates get the same stack.
+- Enablement is per-repo and declarative - commit `.claude/settings.json` so teammates get the same stack.
 - Restart the conversation to pick up newly enabled plugins.
 - Pipeline Phase 1 stack detection is independent (it reads project files); `stack` only sets which plugin skill set is active.
 - The old `stack-swap.sh` skill-dir swap has been removed; stack selection is entirely plugin enablement.

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

@@ -1,7 +1,7 @@
 ---
 name: multi-agent-status
 language: en
-description: "Show every multi-agent task's ID, phase, branch, and status."
+description: "Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task."
 user-invocable: true
 ---