@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.0

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. Use when asked to review a project for bugs, gaps or improvements, or to check whether derived skills have drifted from upstream."
+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
 
@@ -73,19 +75,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>/` only holds whatever the last `claude marketplace update` fetched. Reading 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 actually resolves, and some upstreams keep per-plugin `plugin.json` versions deliberately unused - reading those records a version nobody ships. An entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG stated in as many words 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" (nothing to check). 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 the entry as "upstream unreachable" and move on (do not fail the whole run).
+2. For each entry, resolve the current upstream version, in this order, stopping at the first that answers:
+   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`. Also run `git -C <clone> fetch --dry-run` (or compare against `@{u}`) and say so when the clone is itself behind, so a stale working copy is not silently trusted either.
+   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the currently active account even when the repo exists - that is an unreachable result, not a "no drift" result.
+   - **Plugin cache** under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/`: last resort only. When the cache is the only source that answered, report the entry as **`unverified (cache only)`**, never as "up to date", and add a plan item to configure `upstreamLocalClone`.
+   - If nothing is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole 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 (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs).
+   - 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 (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs). Ignore changelog entries that only touch skills outside `upstreamSkills` - they are not ours to port.
 4. Emit the drift table (plan band D):
 
 ```
@@ -96,6 +106,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 +250,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 +259,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 +272,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 +290,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 +314,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 +323,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 +336,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/resume/SKILL.md

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Durmuş veya hata almış bir görevi kaldığı fazdan devam ettirir."
 argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most recent paused task is used."
 ---
@@ -10,7 +10,7 @@ argument-hint: "[#id]  -  optional: task ID (e.g. #2). If omitted, the most rece
 
 Resume a paused or failed task from the last successful phase.
 
-> **Not the same as `/multi-agent:finish`.** `resume` continues a **tracked pipeline task** (needs its `agent-state.json`/worktree) from where it stopped. `/multi-agent:finish` takes **ad-hoc local work** on the current branch (no prior task required) and runs the pipeline tail — Review → Build+Test → PR → Jira report — over it.
+> **Not the same as `/multi-agent:finish`.** `resume` continues a **tracked pipeline task** (needs its `agent-state.json`/worktree) from where it stopped. `/multi-agent:finish` takes **ad-hoc local work** on the current branch (no prior task required) and runs the pipeline tail - Review → Build+Test → PR → Jira report - over it.
 
 ## Steps
 

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

@@ -1,5 +1,5 @@
 ---
-description: "Run parallel review on a branch's 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 and sets approve/needs-work review state."
+description: "Run parallel review on a branch's 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 and sets approve/needs-work review state. Use when a branch diff or a pull request needs reviewing before it merges."
 description-tr: "Bir branch diff'i veya Pull Request üzerinde paralel review koşar: Claude Code'da 2 model (Fable + Sonnet), Copilot CLI'da 3 model (GPT + Opus + Sonnet). PR girdisinde bulgu başına inline yorum atar ve approve/needs-work durumunu işaretler."
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  optional: PR by number/URL, repo+number, or local branch. Supports GitHub and Bitbucket Server URLs. If omitted (interactive), open GitHub + Bitbucket PRs are listed for multi-select; autopilot falls back to the current branch."
 ---
@@ -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/review-issue/SKILL.md

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Bir GitHub issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri issue yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
 ---

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Bir Jira issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri Jira yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[JIRA-KEY | Jira URL]  -  optional; with no argument, pick from your open Jira issues"
 ---

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Kaydettiğin /multi-agent rutinlerini (/multi-agent:save ile) listeler; her birinin ne yaptığını outputLanguage'e göre gösterir."
 argument-hint: ""
 allowed-tools: Bash, Read

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

@@ -1,5 +1,5 @@
 ---
-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; it is stored local-only and 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; it is stored local-only and never synced. Use when a job keeps recurring and should become its own reusable command."
 description-tr: "Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydeder. Konuşmayı + CLAUDE.md'ni tarayıp aday rutinler önerir, sen seçip ad verirsin; local-only saklanır, asla sync edilmez."
 argument-hint: "[name]  -  optional command name; asked if omitted"
 allowed-tools: Bash, Read, AskUserQuestion

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Skill güvenlik taraması: yerel skill dizinlerini kademeli desen kataloğuna göre tarar."
 allowed-tools: Bash, Read
 argument-hint: "[--strict] [--threshold critical|high|medium|low] [--json] [--root PATH]"

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Tüm agent-log.md dosyalarında akıllı sıralama ve filtrelerle log araması. İsteğe bağlı --semantic bayrağı repo bazlı triyaj korpusunu sorgular."
 allowed-tools: Bash, Read
 argument-hint: "\"query\" [--project NAME] [--since 7d] [--phase N] [--semantic] [--json|--tsv]"

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "İlk kurulum sihirbazı: keychain token keşfi, Git Identity kaydı ve pipeline hazırlığı."
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
@@ -823,4 +823,4 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
    `ai-common-engineering-toolkit@multi-agent-plugins` is always set `true` alongside the stack plugin.
 3. Report the enabled set. To change later, run `/multi-agent:stack <ios|android|frontend|backend|...>` in the repo. Pipeline Phase 1 auto-detects the stack for its own routing regardless of enablement.
 
-The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork — nothing in the pipeline is coupled to a specific account.
+The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork - nothing in the pipeline is coupled to a specific account.

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

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Bu repo için aktif stack'i seçer: eşleşen marketplace plugin'lerini .claude/settings.json'da etkinleştirir (ios/android/mobile/backend/frontend/fullstack/all)."
 allowed-tools: Bash, Read, Edit, Write
 ---
@@ -8,7 +8,7 @@ allowed-tools: Bash, Read, Edit, Write
 
 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 in `~/.claude/skills/`. There is no SessionStart hook and no directory shuffling — enablement is declarative, per-repo, and versioned.
+This replaces the old `stack-swap.sh` mechanic that physically moved skill directories in `~/.claude/skills/`. There is no SessionStart hook and no directory shuffling - enablement is declarative, per-repo, and versioned.
 
 ## Usage
 
@@ -89,7 +89,7 @@ Use the Read + Edit/Write tools (JSON must stay valid). Then print the resulting
 
 ## 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 (or reload the window) for Claude Code 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/commands/multi-agent/status/SKILL.md

@@ -1,5 +1,5 @@
 ---
-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."
 description-tr: "Tüm multi-agent görevlerinin ID, faz, branch ve durumunu gösterir."
 ---
 

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. Use when work is finished and should be propagated across Claude Code, Copilot CLI, the repos, the website and the dev-toolkit 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 |
 
 ---
@@ -121,7 +125,7 @@ If nothing is stale → report "All targets up to date" and stop.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
-   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** — these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
+   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
      ```bash
      # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
@@ -188,7 +192,7 @@ node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs" --dry
 node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
 ```
 
-**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent — a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which runs `claude marketplace update multi-agent-plugins`).
+**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent - a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which runs `claude marketplace update multi-agent-plugins`).
 
 **Publish (only if the generator reported bumps):**
 
@@ -203,7 +207,108 @@ if ! git diff --quiet; then
 fi
 ```
 
-Never author skills directly in the plugins repo's `knowledge/` — they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.
+Never author skills directly in the plugins repo's `knowledge/` - they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.
+
+---
+
+## 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.
 
 ---
 
@@ -242,25 +347,26 @@ 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
 ```
 
 ---
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
-This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports natively.
+This runs on the Claude <-> Copilot axis - the two CLIs the pipeline supports natively.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.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

@@ -1,5 +1,5 @@
 ---
-description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at /multi-agent:manual-test."
+description: "UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb). Auto-detects platform. Screenshot + tap + analyze on the booted device. The Phase 5 Manual Test flow lives at /multi-agent:manual-test. Use when a running app should be driven on a simulator or emulator to hunt UI bugs."
 description-tr: "UI Bug Hunter - iOS Simulator (simctl) + Android Emulator (adb). Platformu otomatik algılar. Açık cihazda screenshot + tap + analiz. Faz 5 Manuel Test akışı /multi-agent:manual-test'te."
 argument-hint: '[scenario]  -  e.g. "dark mode" | "accessibility" | "dynamic type" | "screenshot tr" | "store-ready" | (empty = full sweep)'
 ---
@@ -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`.