@mmerterden/multi-agent-pipeline 12.5.0 → 12.6.0

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

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

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

@@ -1,37 +1,39 @@
 ---
-description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, draft one plan, take approval, develop, then ask whether to sync."
-description-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch
+description: "Analyse the project: extract adapted best-practices, hunt real bugs + improvement areas, check upstream drift of derived skills, research the companion dev-toolkit MCP server against current MCP practice, draft one plan, take approval, develop, then ask whether to sync."
+description-tr: "Projeyi analiz eder: uyarlanmış best-practice'leri çıkarır, gerçek bug + iyileştirme alanlarını avlar, türetilmiş skill'lerin upstream drift'ini kontrol eder, dev-toolkit MCP sunucusunu güncel MCP pratiklerine göre araştırır, tek plan taslağı çıkarır, onay alır, geliştirir, sonra sync isteyip istemediğini sorar."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, WebFetch, WebSearch
 ---
 
 # Multi-Agent Refactor
 
-**One command. Best-practices + Bug hunt + Upstream drift -> Score -> Plan -> Approval -> Develop -> Sync.**
+**One command. Best-practices + Bug hunt + Upstream drift + Dev-toolkit -> Score -> Plan -> Approval -> Develop -> Sync.**
 
-Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, scores everything, drafts a single prioritized plan, asks the user for approval, applies the approved items, and asks about sync at the end.
+Deep-analyses the current project, extracts the global best-practices worth adopting (adapted to our stack), hunts real bugs and improvement areas, checks whether any skills we derived from an upstream source have drifted, researches the companion dev-toolkit MCP server against current MCP practice, scores everything, drafts a single prioritized plan, asks the user for approval, applies the approved items, and asks about sync at the end.
 
-**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", etc.)
+**Input**: $ARGUMENTS (optional  -  area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "dev-toolkit", etc.)
 
 ## Flow
 
 ```
 Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT them to our stack -> plan band A
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
+Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion dev-toolkit repo -> plan band E
 Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
 Step 3:  SCORE           Each category /10, overall /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift), priority-ordered
+Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (dev-toolkit)
 Step 5:  ASK             "Start the work?"  -  wait for user approval
 Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
 Step 7:  VERIFY          Confirm every test + lint passes
 Step 8:  ASK SYNC        "Run /multi-agent:sync?"  -  wait for user approval
 ```
 
-Plan bands (all four feed the single Step 4 table):
+Plan bands (all five feed the single Step 4 table):
 - **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
 - **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
 - **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
 - **D - Drift**: upstream updates to skills we derived from an external source.
+- **E - Dev-toolkit**: current-practice gaps in the companion dev-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
 
 ## Step 0: BEST-PRACTICES  -  research the field, adapt to us
 
@@ -96,6 +98,78 @@ Procedure:
 
 5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>", with the specific skills to update. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
+## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+
+The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
+
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
+- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+
 ## Step 1: SCAN
 
 ```
@@ -168,7 +242,7 @@ Each category is scored out of 10. Output:
 
 ## Step 4: PLAN  -  one merged, prioritized table
 
-Merge all four bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift) so the source is visible.
+Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E dev-toolkit) so the source is visible.
 
 ```
 | # | Priority | Band | Category | Item | Impact |
@@ -177,7 +251,8 @@ Merge all four bands into a single plan. Tag each row with its band (A best-prac
 | 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
 | 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
 | 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
-| 5 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
+| 5 | P1 | E | Toolkit | Add read-only annotations to the dev-toolkit device tools | Medium |
+| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
 ```
 
 Priority levels:
@@ -189,13 +264,14 @@ Priority levels:
 
 After showing the plan, ask:
 
-> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, and upstream drift. Should I start the work?"
+> "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and dev-toolkit practice. Should I start the work?"
 
 Options:
 - "Yes, do all"
 - "Only P0"
 - "P0 + P1 only"
 - "Only bugs (band B)"
+- "Only the dev-toolkit (band E)"
 - (the user may pick specific items)
 
 **Never start the work without approval.**
@@ -206,6 +282,7 @@ Apply the approved items one by one:
 
 1. For each item:
    - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
+   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d  -  do not publish from this step.
    - run the relevant tests
    - on success, move to the next
    - on failure, roll back and notify the user
@@ -229,6 +306,8 @@ echo "Lint: PASS/FAIL"
 echo "Test: PASS/FAIL (X/Y passed)"
 ```
 
+If any band-E item was applied, verify the toolkit repo too  -  syntax check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts (README header, `package.json` description) match the count the server reports.
+
 ## Step 8: ASK SYNC
 
 After every approved item is applied, ask:
@@ -236,7 +315,7 @@ After every approved item is applied, ask:
 > "Work is complete. Should I run /multi-agent:sync?"
 
 Options:
-- "Yes" -> run the `/multi-agent:sync` command (full ecosystem sync)
+- "Yes" -> run the `/multi-agent:sync` command (full ecosystem sync  -  its Step 3d ships any band-E work in the toolkit repo)
 - "No" -> emit a report and stop
 - "Commit + push only" -> push the current repo without sync
 
@@ -249,6 +328,7 @@ If $ARGUMENTS is set, focus on that band/category only:
 | `bugs` | Bug hunt only (band B) |
 | `best-practices` | Field research + adapted plan only (band A) |
 | `drift` | Upstream derived-skill drift only (band D) |
+| `dev-toolkit` | Companion MCP toolkit research + audit only (band E) |
 | `security` | Security analysis only |
 | `tests` | Test coverage and quality only |
 | `performance` | Performance optimisation only |

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

@@ -192,7 +192,7 @@ When release-relevant iOS/Android files change, load the matching catalog:
 
 | Platform | Trigger files | Catalog |
 |---|---|---|
-| iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  17 rules + ITMS refs |
+| iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `pipeline/skills/shared/core/apple-archive-compliance/SKILL.md`  -  18 rules + ITMS refs |
 | Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `pipeline/skills/shared/core/google-play-compliance/SKILL.md`  -  21 rules + Play policy refs |
 
 Each finding gets the `ruleID` from the catalog plus the platform policy ref:

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

@@ -1,7 +1,7 @@
 ---
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
-description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo ve website."
-argument-hint: "[release] [--platform=<macos|linux|windows>]"
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server."
+description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo, website ve dev-toolkit MCP sunucusu."
+argument-hint: "[release] [dev-toolkit] [--platform=<macos|linux|windows>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 ---
 
@@ -15,8 +15,9 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | Arg | Meaning |
 |---|---|
-| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website. |
-| `release` | Full sync + version bump + tag + npm publish + website deploy |
+| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, dev-toolkit MCP server. |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (includes the dev-toolkit ship path) |
+| `dev-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `--platform=<macos\|linux\|windows>` | Override automatic platform detection. For CI / cross-platform smoke. |
 | `"change description"` | Apply the description to every target at once |
 
@@ -28,6 +29,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
+| 5 | dev-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
 
 ## Platform Support (macOS / Linux / Windows)
 
@@ -56,13 +58,14 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 42 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
+Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
-Step 6: Report      Summary: synced targets, platform, changed files, deploy status
+Step 6: Report      Summary: synced targets, platform, changed files, deploy status, dev-toolkit version
 ```
 
 If nothing is stale → report "All targets up to date" and stop.
@@ -73,6 +76,7 @@ If nothing is stale → report "All targets up to date" and stop.
 |-------|----------|
 | (no args) | Full ecosystem sync (default) |
 | `release` | Full sync + version bump + tag + npm publish + website deploy |
+| `dev-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `"change description"` | Apply the description to EVERY target at once |
 
 ---
@@ -207,6 +211,107 @@ Never author skills directly in the plugins repo's `knowledge/` — they will be
 
 ---
 
+## Dev-Toolkit Sync (Step 3d)
+
+The companion MCP server (`dev-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship  -  otherwise the pipeline documents a tool no consumer has.
+
+**Resolution**: identical to `/multi-agent:refactor` Step 0c  -  `prefs.global.devToolkit` first, then auto-detect from the `mcpServers` registration (`~/.claude.json`, `~/.claude/settings.json`), then skip. `enabled: false` skips.
+
+**Detect movement**:
+
+```bash
+DT="<resolved localPath>"; cd "$DT"
+git fetch origin --quiet 2>/dev/null || true
+DIRTY=$(git status --porcelain)
+AHEAD=$(git log --oneline @{u}..HEAD 2>/dev/null | wc -l | tr -d ' ')
+VER=$(node -p "require('./package.json').version")
+TAGGED=$(git tag --list "v$VER")
+```
+
+Moved = `DIRTY` non-empty, or `AHEAD` > 0, or no tag for `VER`. Nothing moved -> report `dev-toolkit: up to date (v$VER)` and continue with the sync.
+
+**Ship gates**  -  all must pass before commit or publish. A gate failure aborts THIS step only, reported with file + line; the rest of the sync continues.
+
+**Prefer the repo's own gate script.** When the toolkit ships one (`npm run gates`, or `scripts/gates.sh`), run THAT and skip the inline list below - the repo owns the definition, this skill only owns the requirement. The inline gates are the fallback for a repo that has none, and the checklist the gate script itself must cover.
+
+```bash
+cd "$DT"
+if node -e "process.exit(require('./package.json').scripts?.gates ? 0 : 1)" 2>/dev/null; then
+  npm run gates || echo "ABORT: dev-toolkit gates failed"
+elif [ -f scripts/gates.sh ]; then
+  bash scripts/gates.sh || echo "ABORT: dev-toolkit gates failed"
+else
+  : # run the inline gates below
+fi
+```
+
+1. **Syntax**: `node --check index.js` plus every `tools/**/*.js`.
+2. **Boot + inventory**: handshake the server over stdio and count the registered tools.
+
+```bash
+TOOLS=$(printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"sync","version":"1"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | node index.js 2>/dev/null \
+  | node -e 'let b="";process.stdin.on("data",d=>b+=d).on("end",()=>{const m=b.split("\n").filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).find(x=>x&&x.id===2&&x.result&&x.result.tools);console.log(m?m.result.tools.length:0)})')
+[ "${TOOLS:-0}" -gt 0 ] || echo "ABORT: the toolkit served 0 tools"
+```
+
+3. **Advertised-count match**: `$TOOLS` must equal every advertised count (`package.json` `description`, the `README.md` header and its per-family rows). Fix the docs, never the gate  -  a stale count has shipped before.
+4. **Packaging**: every directory the server loads at runtime must be inside `files[]`. A missing entry publishes a broken package (this has already caused one patch release).
+
+```bash
+PACK=$(npm pack --dry-run 2>&1)
+for d in tools/*/; do printf '%s' "$PACK" | grep -q "$d" || echo "ABORT: $d missing from files[]"; done
+```
+
+5. **stdout hygiene**: `grep -rn "console\.log(" index.js tools/` must be empty  -  stdout carries the JSON-RPC frames, diagnostics belong on `console.error`.
+6. **Personal-data scan**: no absolute `/Users/<name>` paths, no tokens, no corporate hostnames in the shipped files.
+7. **Version contract**: every pipeline-side minimum (the `cross-cli-contract.md` tool table, `design-check`'s MCP requirement, `apple-archive-compliance`) must be satisfied by the version about to ship. A newly added tool that a pipeline skill now needs -> bump that declared minimum in the pipeline during this same sync.
+
+**Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool (pipeline minimums depend on the surface).
+
+**Ship**:
+
+```bash
+gh auth switch --user {owner}
+git add -A
+git commit -m "{type}(v$NEW): {what changed}"    # that repo's own commit convention
+git tag "v$NEW" && git push origin main --tags
+```
+
+Publish to the registry declared in `publishConfig` through a throwaway userconfig. Never edit `~/.npmrc`, and never a bare `npm publish`  -  it lands on whichever registry the ambient config happens to name.
+
+**The token depends on the registry**: `npm.pkg.github.com` authenticates with a GitHub PAT carrying `write:packages` (logical key `github`), `registry.npmjs.org` with an npm token (logical key `npm`). Picking the wrong one fails with a 401 that reads like a missing package.
+
+```bash
+NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
+REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
+HOST=${REG#https://}; HOST=${HOST%/}
+case "$HOST" in npm.pkg.github.com*) KEY=github ;; *) KEY=npm ;; esac
+TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
+[ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
+printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
+npm publish --userconfig "$NPMRC"
+```
+
+Verify the publish landed: on GitHub Packages `npm view <package> version --userconfig "$NPMRC"`; on npmjs read the registry directly (`curl -s https://registry.npmjs.org/<package>/latest`) rather than `npm view`, which can answer from a stale cache.
+
+**Approval**: outside autopilot and outside `release`, ask before shipping.
+
+> "dev-toolkit moved (N changed files, M unpushed commits, v$VER). What should I do?"
+
+- Commit + push (no publish)
+- Commit + push + publish v$NEW
+- Skip this step
+
+With `release`, or in autopilot, run the full ship path without asking. If the working copy holds band-E work from `/multi-agent:refactor` that was never approved, do not ship it silently  -  report it and ask.
+
+**Consumer note**: a path-based stdio registration (`node <localPath>/index.js`) picks the change up on the next MCP restart with no reinstall; a packaged registration (`npx <package>`) needs the published version. State which one the resolved config uses in the Step 6 report.
+
+---
+
 ## Website Sync (Step 4)
 
 Propagate pipeline version, phase count, model count, and feature descriptions to the website.
@@ -242,9 +347,10 @@ When invoked with the `release` argument:
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags -> release.yml auto-publish
-7. WEBSITE       Version + features -> {website-host}
-8. COPILOT       Copilot CLI instructions + skills sync
-9. Report        Summary: version, touched repos, deploy status
+7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
+8. WEBSITE       Version + features -> {website-host}
+9. COPILOT       Copilot CLI instructions + skills sync
+10. Report       Summary: version, touched repos, deploy status
 ```
 
 ---
@@ -257,10 +363,10 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**42 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
@@ -281,6 +387,7 @@ routines, save, scan, search, setup, stack, status, sync, test, uninstall, updat
 | `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
 | `gh` CLI (work) | `{user}_<work-label>` gh auth (Keychain)  -  see `prefs.global.accounts[]` |
 | npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
+| dev-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
 
 ```bash
 gh auth switch --user {owner}  # for personal repos

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

@@ -35,6 +35,6 @@ Pass `$ARGUMENTS` through verbatim  -  sim-test.md decides which test matrix to
 
 - **iOS**: Xcode + a booted Simulator (`xcrun simctl list | grep Booted`)
 - **Android**: Android SDK + a running emulator or USB device (`adb devices`)
-- **MCP**: the `dev-toolkit` MCP server must be installed (tool names start with `mcp__dev_toolkit__`)
+- **MCP**: the `dev-toolkit` MCP server must be installed (tool names start with `mcp__dev-toolkit__`)
 
 For manual-test mode (checkout the task branch + Xcode-open hint), see `/multi-agent:manual-test`.

package/pipeline/commands/sim-test.md

@@ -1,6 +1,6 @@
 ---
 description: "Mobile UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb)  -  auto-detects platform"
-allowed-tools: Agent, Bash, Read, Write, Edit, TaskCreate, TaskUpdate, TaskList, TaskGet, mcp__dev_toolkit__ios_list_devices, mcp__dev_toolkit__ios_boot_device, 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_launch_app, mcp__dev_toolkit__ios_terminate_app, mcp__dev_toolkit__ios_list_apps, mcp__dev_toolkit__ios_go_home, mcp__dev_toolkit__ios_set_appearance, mcp__dev_toolkit__ios_set_content_size, mcp__dev_toolkit__ios_set_locale, mcp__dev_toolkit__ios_open_url, mcp__dev_toolkit__ios_status_bar, mcp__dev_toolkit__ios_push_notification, mcp__dev_toolkit__ios_grant_permission, mcp__dev_toolkit__ios_revoke_permission, mcp__dev_toolkit__ios_reset_permissions, mcp__dev_toolkit__ios_set_location, mcp__dev_toolkit__ios_clear_location, mcp__dev_toolkit__ios_set_increase_contrast, mcp__dev_toolkit__ios_record_video, mcp__dev_toolkit__ios_add_media, mcp__dev_toolkit__ios_keychain_reset, mcp__dev_toolkit__ios_get_app_container, mcp__dev_toolkit__ios_erase_device, mcp__dev_toolkit__ios_get_ui_tree, 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_key_event, mcp__dev_toolkit__android_launch_app, mcp__dev_toolkit__android_stop_app, mcp__dev_toolkit__android_list_packages, mcp__dev_toolkit__android_go_home, mcp__dev_toolkit__android_go_back, mcp__dev_toolkit__android_get_ui_tree, mcp__dev_toolkit__android_set_dark_mode, mcp__dev_toolkit__android_set_font_scale, mcp__dev_toolkit__android_set_locale, mcp__dev_toolkit__android_set_location, mcp__dev_toolkit__android_grant_permission, mcp__dev_toolkit__android_revoke_permission, mcp__dev_toolkit__android_record_screen, mcp__dev_toolkit__android_install_apk, mcp__dev_toolkit__android_uninstall_app, mcp__dev_toolkit__android_logcat, mcp__dev_toolkit__android_get_screen_size, mcp__dev_toolkit__android_open_url, mcp__dev_toolkit__android_clear_app_data
+allowed-tools: Agent, Bash, Read, Write, Edit, TaskCreate, TaskUpdate, TaskList, TaskGet, mcp__dev-toolkit__ios_list_devices, mcp__dev-toolkit__ios_boot_device, 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_launch_app, mcp__dev-toolkit__ios_terminate_app, mcp__dev-toolkit__ios_list_apps, mcp__dev-toolkit__ios_go_home, mcp__dev-toolkit__ios_set_appearance, mcp__dev-toolkit__ios_set_content_size, mcp__dev-toolkit__ios_set_locale, mcp__dev-toolkit__ios_open_url, mcp__dev-toolkit__ios_status_bar, mcp__dev-toolkit__ios_push_notification, mcp__dev-toolkit__ios_grant_permission, mcp__dev-toolkit__ios_revoke_permission, mcp__dev-toolkit__ios_reset_permissions, mcp__dev-toolkit__ios_set_location, mcp__dev-toolkit__ios_clear_location, mcp__dev-toolkit__ios_set_increase_contrast, mcp__dev-toolkit__ios_record_video, mcp__dev-toolkit__ios_add_media, mcp__dev-toolkit__ios_keychain_reset, mcp__dev-toolkit__ios_get_app_container, mcp__dev-toolkit__ios_erase_device, mcp__dev-toolkit__ios_get_ui_tree, 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_key_event, mcp__dev-toolkit__android_launch_app, mcp__dev-toolkit__android_stop_app, mcp__dev-toolkit__android_list_packages, mcp__dev-toolkit__android_go_home, mcp__dev-toolkit__android_go_back, mcp__dev-toolkit__android_get_ui_tree, mcp__dev-toolkit__android_set_dark_mode, mcp__dev-toolkit__android_set_font_scale, mcp__dev-toolkit__android_set_locale, mcp__dev-toolkit__android_set_location, mcp__dev-toolkit__android_grant_permission, mcp__dev-toolkit__android_revoke_permission, mcp__dev-toolkit__android_record_screen, mcp__dev-toolkit__android_install_apk, mcp__dev-toolkit__android_uninstall_app, mcp__dev-toolkit__android_logcat, mcp__dev-toolkit__android_get_screen_size, mcp__dev-toolkit__android_open_url, mcp__dev-toolkit__android_clear_app_data
 ---
 
 # Mobile UI Bug Hunter
@@ -22,8 +22,8 @@ Auto-detects platform: iOS (simctl) or Android (adb). No external apps needed.
 5. If argument contains "android" or "ios" -> use that
 ```
 
-For iOS: use `mcp__dev_toolkit__ios_*` tools
-For Android: use `mcp__dev_toolkit__android_*` tools
+For iOS: use `mcp__dev-toolkit__ios_*` tools
+For Android: use `mcp__dev-toolkit__android_*` tools
 
 **Android extras**: `get_ui_tree` returns XML with bounds/text/resource-id (uiautomator dump), `logcat` for crash detection, `go_back` button.
 
@@ -134,11 +134,11 @@ Step A  -  run the standard visual + accessibility sweep (light + dark + large t
 Step B  -  dispatch compliance skill:
   iOS:
     Load pipeline/skills/shared/core/apple-archive-compliance/SKILL.md
-    Prereq: @mmerterden/dev-toolkit-mcp ≥ v2.4 (provides ios_app_store_audit MCP tool)
+    Prereq: @mmerterden/dev-toolkit-mcp ≥ v2.9.0 (provides ios_app_store_audit MCP tool)
              -  installable via npm; standalone ArchiveGuard binary deprecated in v8.4.0
     Artifact: pick newest .xcarchive under ~/Library/Developer/Xcode/Archives/**
               OR accept explicit path argument after "store-ready"
-    Invoke:   mcp__dev_toolkit__ios_app_store_audit({ archive_path: <path>, rules: "all" })
+    Invoke:   mcp__dev-toolkit__ios_app_store_audit({ archive_path: <path>, rules: "all" })
               OR (Node fallback): node -e "import('@mmerterden/dev-toolkit-mcp/tools/ios-app-store-audit/index.js').then(m => m.runAudit({ archivePath: '<path>', rules: 'all' }).then(r => console.log(JSON.stringify(r))))"
               Humanize via --lang en (promptLanguage is locked to "en"; pass --lang=tr explicitly to opt into Turkish)
   Android:

package/pipeline/lib/credential-store.sh

@@ -84,10 +84,39 @@ require_cmd() {
   fi
 }
 
+# --- Logical key -> backend key --------------------------------------------
+# Callers pass a LOGICAL key ("github", "jira", "figma_pat"). The actual
+# Keychain / libsecret / Credential Manager entry is named by
+# prefs.global.keychainMapping, so a lookup that uses the logical key verbatim
+# finds nothing whenever the two differ -  silently, because a missing entry and
+# a missing mapping look identical from here. Resolve the mapping first and fall
+# back to the logical key when no mapping exists (backward compatible with
+# entries whose name already equals the logical key).
+PREFS_FILE="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+resolve_key() {
+  local logical="$1" mapped=""
+  if [ -f "$PREFS_FILE" ] && command -v python3 >/dev/null 2>&1; then
+    mapped=$(python3 -c '
+import json, sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        prefs = json.load(fh)
+except Exception:
+    sys.exit(0)
+name = prefs.get("global", {}).get("keychainMapping", {}).get(sys.argv[2])
+if isinstance(name, str) and name.strip():
+    sys.stdout.write(name.strip())
+' "$PREFS_FILE" "$logical" 2>/dev/null || true)
+  fi
+  printf '%s' "${mapped:-$logical}"
+}
+
 # --- Subcommands ------------------------------------------------------------
 do_get() {
   local key="${1:-}"
   [ -z "$key" ] && { echo "usage: $0 get <key>" >&2; exit 3; }
+  key=$(resolve_key "$key")
   if delegate_to_python; then
     local val rc
     val=$(python3 "$KEYCHAIN_PY" get "$key" 2>/dev/null) || rc=$?
@@ -128,6 +157,8 @@ if (\$c) { \$c.GetNetworkCredential().Password }
 do_set() {
   local key="${1:-}" val="${2:-}"
   [ -z "$key" ] && { echo "usage: $0 set <key> <value|->" >&2; exit 3; }
+  # Resolve through the same mapping as do_get so set/get stay symmetric.
+  key=$(resolve_key "$key")
   # "-" means: read the secret from stdin (keeps it off argv).
   if [ "$val" = "-" ]; then
     val=$(cat)
@@ -173,6 +204,7 @@ New-StoredCredential -Target '$key_esc' -UserName '${USER:-${USERNAME:-claude}}'
 do_delete() {
   local key="${1:-}"
   [ -z "$key" ] && { echo "usage: $0 delete <key>" >&2; exit 3; }
+  key=$(resolve_key "$key")
   if delegate_to_python; then
     python3 "$KEYCHAIN_PY" delete "$key" >/dev/null 2>&1 || true
     return 0

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,10 +6,10 @@
 
 ---
 
-## 1. Command Inventory (41 commands)
+## 1. Command Inventory (42 commands)
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
@@ -43,7 +43,7 @@ Two parallel shared/core skills under `pipeline/skills/shared/core/` wrap extern
 
 | Skill | Path | Tool wrapper | Rules |
 |---|---|---|---|
-| `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/dev-toolkit-mcp` ≥ v2.4) | 17 (Apple ITMS + App Store Review Guidelines) |
+| `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/dev-toolkit-mcp` ≥ v2.9.0) | 18 (Apple ITMS + App Store Review Guidelines) |
 | `google-play-compliance` | `pipeline/skills/shared/core/google-play-compliance/` | bundletool + aapt2 + apksigner | 21 (4 categories: Technical / Security / Privacy / Hygiene) |
 
 Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 4 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh` (46 assertions).