@mmerterden/multi-agent-pipeline 14.2.1 → 14.2.2

package/CHANGELOG.md

@@ -16,6 +16,48 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [14.2.2] - 2026-08-04
+
+### Added
+
+- **`localization-reuse-map` skill** added to `shared/external` — a per-screen
+  localization-reuse map that ties new/legacy/CMS translation keys together,
+  with follow-up fixes for placeholder rendering, snapshot staleness, and the
+  three gates its initial commit left red.
+- **`docs/ecosystem.md`** — a detailed diagram of how this repo, the
+  `multi-agent-plugins` marketplace, and `dev-toolkit-mcp` compose at install
+  time and run time. `docs/architecture.md` cross-links it.
+- **Turkish README (`README.tr.md`)**, cross-linked from `README.md`.
+- Jira intake now surfaces the **parent issue's description** as a
+  confirmable candidate when the child issue's own description is empty.
+- `payload-contracts` reference doc, consolidating the required-reading list
+  for Phase 6 and 7.
+
+### Fixed
+
+- Corrected stale 44/43-command counts to the real 49 across README,
+  `cross-cli-contract.md`, and both sync/update `SKILL.md` copies; fixed a
+  hardcoded "42 command specs" log line in `install/codex.mjs` to count the
+  actual source tree instead.
+- **`audit-log-rotate.sh` could delete the archive it had just created.**
+  `gzip` preserves the source file's mtime by default, so rotating log
+  content already older than `KEEP_DAYS` produced a `.gz` that inherited
+  that old mtime - and the very next line's retention sweep (`find -mtime
+  +$KEEP_DAYS -delete`) deleted it in the same run, before it was ever read.
+  The archive's mtime is now reset to rotation time, so retention counts
+  from when it was archived, not from the age of the content inside it.
+- The mode banner claimed pickers stay English when they didn't - language +
+  dialect resolution fixed.
+- The cost tracker now reads the same state file `phase-tracker.sh` writes.
+- Jira conversion table pipes are now escaped; Intake warnings render at h2.
+- Copilot mode skills carried a stale review claim and missing payload
+  pointers - corrected.
+- 18 cross-script drift and edge-case bugs resolved from code review.
+- Markup dialect is now chosen per surface for channel posts; the Jira table
+  heading-conversion bug fixed.
+- `localization-reuse-map`: empty-cell placeholder is now a single dash; a
+  stale snapshot no longer reads as an unauthored key.
+
 ## [14.2.1] - 2026-07-30
 
 ### Changed

package/README.md

@@ -6,10 +6,14 @@
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/mmerterden/multi-agent-pipeline/blob/main/package.json)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mmerterden/multi-agent-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/mmerterden/multi-agent-pipeline)
 
+🇹🇷 Türkçe: [README.tr.md](./README.tr.md)
+
 An 8-phase AI development pipeline for **Claude Code**, **Copilot CLI** and **Codex CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
 
 Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS / Linux / Windows. Zero runtime dependencies.
 
+📐 **[Architecture diagrams](./docs/architecture.md)** - the 8-phase flow, operating modes, review/triage, Figma subphases, component layout. **[Ecosystem diagram](./docs/ecosystem.md)** - how this repo, the `multi-agent-plugins` marketplace and `dev-toolkit-mcp` compose.
+
 ## Quick Start
 
 ```bash
@@ -52,7 +56,7 @@ One command runs 8 phases, with a gate between the risky ones:
 
 Under the hood: each task runs in its own **git worktree** (or the current branch with `:local`), commits use the **git identity routed from the repo's origin URL**, and **multi-repo** tasks get per-repo worktrees plus an integration build. Tokens stay in the OS keychain; nothing is committed or logged. `/multi-agent:review` can also review an existing GitHub/Bitbucket PR - per-finding inline comments anchored to `file:line` + an explicit Approve / Needs-Work state.
 
-The discipline behind all of this - bounded loops, evidence gates, token-budgeted phase docs, immutable tests, fresh-context handoffs - is catalogued in [docs/engineering.md](./docs/engineering.md). The full feature list lives in [docs/features.md](./docs/features.md).
+The discipline behind all of this - bounded loops, evidence gates, token-budgeted phase docs, immutable tests, fresh-context handoffs - is catalogued in [docs/engineering.md](./docs/engineering.md). The full feature list lives in [docs/features.md](./docs/features.md). How this repo, the `multi-agent-plugins` marketplace, and the `dev-toolkit-mcp` server compose at install time and at run time is diagrammed in [docs/ecosystem.md](./docs/ecosystem.md).
 
 ## Modes
 
@@ -66,7 +70,7 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | Audit | `/multi-agent:design-check` | Mock-mode vs Figma conformance, local-only |
 | Audit | `/multi-agent:testflight-validation` | Pre-submission gates for a TestFlight build: static archive audit → Apple's `altool --validate-app` → Review-Guidelines check. Validates only, never uploads |
 
-Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. 44 commands in all  -  full list: `/multi-agent:help`.
+Helpers: `setup`, `status`, `resume #N`, `kill #N`, `garbage-collect`, `prune-logs`, `purge`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. 49 commands in all  -  full list: `/multi-agent:help`.
 
 ## Stacks
 
@@ -80,17 +84,17 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 44 commands.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 49 commands.
 
 | Tool | Flag | What it installs |
 |---|---|---|
 | Claude Code | `--claude` (default) | slash commands + skills + agents + `PreToolUse` secret-scan hook |
-| Copilot CLI | `--copilot` | instructions + 44 sub-command skills + scripts |
-| Codex CLI | `--codex` | one router skill + 43 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
+| Copilot CLI | `--copilot` | instructions + 49 sub-command skills + scripts |
+| Codex CLI | `--codex` | one router skill + 49 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 
-**Why Codex gets one skill and not 43.** Codex assembles every discovered skill's name
+**Why Codex gets one skill and not 49.** Codex assembles every discovered skill's name
 and description into a single prompt block and drops entries when it overflows, with no
 error. Measured on 0.145: installing one plugin that declares 142 skills surfaced only
 75 of them and evicted an unrelated user skill. So on Codex the pipeline ships a single

package/README.tr.md

@@ -0,0 +1,143 @@
+# @mmerterden/multi-agent-pipeline
+
+[![GitHub Release](https://img.shields.io/github/v/release/mmerterden/multi-agent-pipeline?color=blue)](https://github.com/mmerterden/multi-agent-pipeline/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%20%7C%2020%20%7C%2022-green)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/mmerterden/multi-agent-pipeline/blob/main/package.json)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mmerterden/multi-agent-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/mmerterden/multi-agent-pipeline)
+
+🇬🇧 English: [README.md](./README.md)
+
+**Claude Code**, **Copilot CLI** ve **Codex CLI** için 8 fazlı bir AI geliştirme pipeline'ı. Bir Jira issue'sunu veya GitHub URL'sini tek komutla merge edilmiş bir PR'a dönüştürür - analiz → plan → TDD → review → test → commit → PR - çoklu-repo orkestrasyonu, bir plan-onay kapısı, CLI-farkında paralel review ve store-uyumluluk kontrolleriyle birlikte. Component ve Figma-to-code işleri paket içine gömülmek yerine stack başına marketplace plugin'lerine (iOS/SwiftUI, Android/Compose) devredilir, böylece component skill'leri tek bir yerde yaşar.
+
+Claude Code, Copilot CLI ve Codex CLI üzerinde native çalışır. macOS / Linux / Windows. Sıfır runtime dependency.
+
+📐 **[Mimari diyagramları](./docs/architecture.md)** - 8 faz akışı, çalışma modları, review/triage, Figma subphase'leri, component yapısı. **[Ekosistem diyagramı](./docs/ecosystem.md)** - bu repo, `multi-agent-plugins` marketplace'i ve `dev-toolkit-mcp`'nin nasıl bir araya geldiği.
+
+## Hızlı Başlangıç
+
+```bash
+# public registry'den (auth gerekmez)
+npx @mmerterden/multi-agent-pipeline install --all   # Claude Code + Copilot CLI + Codex CLI
+
+# sonra, bir kere:
+/multi-agent:setup          # keychain token taraması + git kimliği + varsayılan stack
+```
+
+Bir görev çalıştır - girdi tipi otomatik algılanır:
+
+```bash
+/multi-agent "PROJ-1234"                              # Jira id → çek, planla, geliştir
+/multi-agent "https://github.com/org/repo/issues/42"  # GitHub issue URL'i
+/multi-agent "my-app#42"                              # repo + issue numarası
+/multi-agent "fix dark-mode contrast on LoginView"    # serbest-metin bug/özellik
+/multi-agent:jira                                     # açık Jira issue'larını gez → seç
+/multi-agent:issue                                    # atanmamış GitHub issue'larını gez → seç
+```
+
+Her girdi aynı kısa intake'ten geçer - **hesap → (repo) → maturity kontrolü → dev-context** - sonra Phase 0'a girer. Bir Jira id'si veya GitHub URL'i hiçbir kod yazılmadan *önce* çekilir ve maturity-kontrol edilir; serbest-metin bu çekimi atlayıp doğrudan planlamaya geçer. Çoklu-repo görevleri dev-context adımında ekstra repo ekler.
+
+Onayları atlamak için `autopilot`, hızlı dev-only yol için `--dev`, ya da worktree olmadan mevcut branch'te çalışmak için `--local` ekle (örn. `/multi-agent:autopilot "PROJ-1234"`).
+
+Sonra `/multi-agent:update` ile güncelle. Kaldırmak için (tokenlar korunur) `npx @mmerterden/multi-agent-pipeline uninstall`.
+
+## Nasıl çalışır
+
+Tek komut 8 fazı çalıştırır, riskli olanlar arasında bir kapı ile:
+
+- **0 · Init** - girdiyi ayrıştır (Jira id / GitHub URL / serbest metin), hesap + repo(lar) seç, issue'yu çek, maturity kontrolü yap.
+- **1 · Analysis** - stack'i tespit et, codebase'i tara, etkiyi haritala (Opus).
+- **2 · Plan** - bir görev kırılımı yaz ve koda dokunmadan önce **onayın için dur**.
+- **3 · Dev** - TDD: başarısız test → kod → yeşil, repo'nun stiline + aktif stack skill'lerine uyarak.
+- **4 · Review** - önce deterministik kapılar (build / lint / test / secret-scan) geçmeli, sonra bir **CLI-farkında paralel review** - Claude Code 2 model çalıştırır (Fable + Sonnet), Copilot CLI 3 (GPT-5.4 + Opus + Sonnet) - ve bir **Fable triage** sadece aksiyon alınabilir bulguları tutar; blocker'lar Phase 3'e geri döner.
+- **5 · Test** - build + suite'i çalıştır; başarı zorunlu (sahte pass yok).
+- **6 · Commit/PR** - conventional commit, push (başarılı olmalı), bir PR aç (`Ref: #N`, asla otomatik kapatma).
+- **7 · Report** - teknik özet + test senaryolarıyla bir Jira yorumu, channels katmanından gönderilir.
+
+Perde arkasında: her görev kendi **git worktree**'sinde çalışır (ya da `:local` ile mevcut branch'te), commit'ler **repo'nun origin URL'inden yönlendirilen git kimliğini** kullanır, ve **çoklu-repo** görevleri repo başına worktree artı bir integration build alır. Tokenlar OS keychain'de kalır; hiçbir şey commit edilmez ya da loglanmaz. `/multi-agent:review` mevcut bir GitHub/Bitbucket PR'ını da review edebilir - `file:line`'a bağlı bulgu-başına inline yorumlar + açık bir Approve / Needs-Work durumu.
+
+Bunun arkasındaki disiplin - sınırlı loop'lar, kanıt kapıları, token-bütçeli faz dokümanları, değişmez testler, taze-context handoff'lar - [docs/engineering.md](./docs/engineering.md)'de kataloglanmıştır. Tam özellik listesi [docs/features.md](./docs/features.md)'te. Bu repo, `multi-agent-plugins` marketplace'i ve `dev-toolkit-mcp` sunucusunun install zamanında ve run zamanında nasıl bir araya geldiği [docs/ecosystem.md](./docs/ecosystem.md)'de diyagramlanmıştır.
+
+## Modlar
+
+| Mod | Komut | Akış |
+|---|---|---|
+| Full | `/multi-agent "task"` | Tüm 8 faz, interaktif |
+| Autopilot | `/multi-agent:autopilot "task"` | Tüm 8 faz, onaysız |
+| Dev | `/multi-agent:dev "task"` | Init → Dev → Review → Test → Commit → Report |
+| Local | `/multi-agent:local "task"` | Tam pipeline, mevcut branch (worktree yok) |
+| Ship | `/multi-agent:ship` | Lokal iş üzerinde review→test→commit→report kuyruğunu çalıştır |
+| Audit | `/multi-agent:design-check` | Mock-mode vs Figma uygunluğu, yalnızca lokal |
+| Audit | `/multi-agent:testflight-validation` | TestFlight build için pre-submission kapıları: statik archive denetimi → Apple'ın `altool --validate-app`'i → Review-Guidelines kontrolü. Yalnızca doğrular, asla yüklemez |
+
+Yardımcılar: `setup`, `status`, `resume #N`, `kill #N`, `garbage-collect`, `prune-logs`, `purge`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. Toplam 49 komut - tam liste: `/multi-agent:help`.
+
+## Stack'ler
+
+Stack skill'leri [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) marketplace'inde versiyonlu plugin'ler olarak gönderilir. Repo başına bir stack seç:
+
+```bash
+/multi-agent:stack ios        # veya android / frontend / backend / mobile / all
+```
+
+Bu, ilgili plugin'i (+ ortak `ai-common` plugin'ini) repo'nun `.claude/settings.json`'unda etkinleştirir. Phase 1, routing için stack'i otomatik tespit eder. Yeni repo'lar varsayılan olarak iOS'tur.
+
+## Araç desteği
+
+Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 49 komutu alır.
+
+| Araç | Bayrak | Ne kurar |
+|---|---|---|
+| Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + `PreToolUse` secret-scan hook'u |
+| Copilot CLI | `--copilot` | talimatlar + 49 alt-komut skill'i + script'ler |
+| Codex CLI | `--codex` | bir router skill + ref olarak 49 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
+
+Skill'leri stack'e göre filtrele: `--platform=ios\|android\|all`.
+
+**Codex neden 49 değil de tek bir skill alıyor.** Codex, keşfettiği her skill'in adını
+ve açıklamasını tek bir prompt bloğuna toplar ve blok taştığında girdileri hatasızca
+düşürür. 0.145 üzerinde ölçüldü: 142 skill deklare eden bir plugin kurulduğunda sadece
+75'i yüzeye çıktı ve alakasız bir kullanıcı skill'i tahliye edildi. Bu yüzden Codex'te
+pipeline tek bir `multi-agent` router gönderir ve alt-komut spec'lerini, okunana kadar
+hiçbir maliyeti olmayan referans dosyaları olarak tutar - aynı komutlar, aynı davranış,
+host'un gerçekten tutabildiği bir düzen.
+
+Reviewer setleri farklı çünkü mevcut modeller farklı: Claude Code 2 reviewer çalıştırır
+(Fable + Sonnet), Copilot CLI 3 (Opus + GPT-5.4 + Sonnet), Codex CLI 3 (xhigh'da
+gpt-5.6, gpt-5.4, medium'da gpt-5.6). Codex tek-vendor olduğu için üçü arasındaki
+konsensüs, iki-vendor'lu bir host'taki aynı konsensüsten daha zayıf bir kanıttır ve
+triage notu bunu belirtir.
+
+## Token'lar ve entegrasyonlar
+
+`setup` OS keychain'ini tarar ve her token'ı **mantıksal bir isimle** (örn. `jira`) gerçek keychain girdisine eşler - pipeline token'ları bu eşleme üzerinden çözer (`credential-store.sh`), böylece literal keychain isimleri hiçbir sync edilen dosyada görünmez. Token'lar keychain'de kalır (macOS Keychain / Windows Credential Manager / Linux libsecret), **asla commit edilmez ya da loglanmaz**, ve hepsi **opsiyoneldir** - pipeline Phase 0'da ihtiyaç duyduğu herhangi birini sorar.
+
+| Token | Ne için kullanılır | Faz |
+|---|---|---|
+| `jira` | issue'yu çek · rapor yorumunu gönder | 0, 7 |
+| `github` | issue'lar · PR'lar · `gh` auth | 0, 6 |
+| `bitbucket` | PR create/update (reviewer koruyarak) · diff | 6 |
+| `confluence` | analiz / wiki sayfaları yayınla | 7 |
+| `figma` + `figma_mcp` | design context çek | yalnızca analiz |
+| `fortify` | security-scan bulgu kapısı | 4 |
+| `firebase` | Firebase projeleri için Firebase config (base64 JSON) | gerektiğinde |
+| `jenkins` | CI tetikleme / durum | build / deploy |
+| `npm` | paket publish (çoğunlukla CI) | release |
+| `appstore_connect_*` | TestFlight / App Store pre-submission doğrulaması (opsiyonel, iOS) | `testflight-validation` |
+
+**Secret scan**, Claude Code'da bir `PreToolUse` hook'u olarak (bulgu halinde commit'i sert-engeller) ve diğer yerlerde bir pre-push kontrolü olarak çalışır.
+
+## Platform desteği
+
+**macOS**, **Linux** ve **Windows** (Git Bash / WSL) üzerinde çalışır. Shell ve credential erişimi platform-agnostik bir katmandan geçer - keychain otomatik olarak **macOS Keychain**, **Linux libsecret** (`secret-tool`) veya **Windows Credential Manager**'a çözülür, ve script'ler BSD ile GNU araç varyantları arasında fallback yapar. Node.js 18 / 20 / 22.
+
+## Yan repolar
+
+| Repo | Ne olduğu |
+|---|---|
+| [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) | Stack-başına skill toolkit'lerinin marketplace'i (iOS / Android / Frontend / Backend + common). `/multi-agent:stack` ilgili plugin'i etkinleştirir. |
+| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | UI testing / simulator capture / xcodebuild için MCP sunucusu - Phase 5 UI Bug Hunter'ı güçlendirir. Public npm registry'de [`@mmerterden/dev-toolkit-mcp`](https://www.npmjs.com/package/@mmerterden/dev-toolkit-mcp) olarak yayınlanır; installer her CLI'a onu senin için register eder, böylece `npx` ekstra konfigürasyon olmadan onu çözer. |
+
+## Lisans
+
+MIT - bkz. [LICENSE](./LICENSE). Güvenlik sorunları: bkz. [SECURITY.md](./SECURITY.md) (zafiyetler için public issue açma).

package/docs/architecture.md

@@ -117,12 +117,12 @@ graph TB
     end
 
     subgraph "Pipeline Specs"
-        CMD[commands/<br/>39 command files<br/>(34 user-facing)]
+        CMD[commands/<br/>49 command files]
         AGT[agents/<br/>8 agent personas]
         RUL[rules/<br/>12 domain rules]
         PHS[multi-agent-refs/phases/<br/>phase specs + contracts]
         CMP[skills/shared/core/<br/>orchestration skills<br/>incl. compliance]
-        EXT[skills/shared/external/<br/>143 curated skills<br/>(authoring source for the<br/>multi-agent-plugins marketplace)]
+        EXT["skills/shared/external/<br/>150 curated skills<br/>(authoring source for the<br/>multi-agent-plugins marketplace)"]
     end
 
     subgraph "Quality Gates"
@@ -162,18 +162,33 @@ User Input → Phase 0 (Init)
 
 ## Ecosystem Sync Targets
 
+`/multi-agent:sync` actually walks **five** targets, not the three shown in earlier
+revisions of this diagram — Codex CLI and the two independently-shipped repos
+(`multi-agent-plugins`, `dev-toolkit-mcp`) are real sync targets too:
+
 ```mermaid
 graph TD
     CC["Claude Code<br/>(source of truth)"]
-    COP["Copilot CLI<br/>(instructions + unified skills)"]
+    COP["Copilot CLI<br/>(instructions + 49 skills)"]
+    COD["Codex CLI<br/>(1 router skill + 49 refs)"]
     REPO["Pipeline Repo<br/>(npm package)"]
-    WEB["Website<br/>(optional)"]
-    RC["Remote Control<br/>(optional)"]
+    WEB["Website"]
+    PLUGREPO["multi-agent-plugins<br/>(5 stack plugins, own repo)"]
+    DTK["dev-toolkit-mcp<br/>(own repo, own release cadence)"]
 
-    CC -->|instructions + unified skills| COP
-    CC -->|genericized pipeline/| REPO
+    CC -->|copy + reformat| COP
+    CC -->|transform via install.js --codex| COD
+    CC -->|genericize| REPO
     CC -->|version + features| WEB
-    CC -->|pipeline refs| RC
+    REPO -->|build-stack-plugins.mjs| PLUGREPO
+    DTK -.->|sync only detects + ships, never authors| CC
+
     REPO -->|npm publish| NPM["GitHub Packages"]
     WEB -->|auto-deploy| VERCEL["Vercel"]
+    PLUGREPO -->|git push| MKT["Claude marketplace"]
+    DTK -->|npm publish| NPM2["GitHub Packages (private)"]
 ```
+
+Full detail on how these three repos compose at install time and at run time —
+including the Phase 3 → plugin dispatch contract and the Phase 5 → dev-toolkit MCP
+contract — lives in [`docs/ecosystem.md`](./ecosystem.md).

package/docs/ecosystem.md

@@ -0,0 +1,237 @@
+# Ecosystem: Pipeline × Marketplace Plugins × Dev-Toolkit MCP
+
+This pipeline is not one repo. It's three, each owned separately, each versioned
+separately, wired together at install time and at run time:
+
+| Repo | What it owns | Ships as |
+|---|---|---|
+| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 49 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
+| **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 5 independently-versioned plugins |
+| **`dev-toolkit-mcp`** | The pipeline's hands on devices and browsers: 80 MCP tools across 6 categories (simulator/emulator control, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, an agent-DSL batch runner) | npm package, registered as a standard stdio MCP server on every host |
+
+None of the three depends on the others at the code level. They compose through two
+narrow contracts: the **Skill tool** (pipeline → plugin, at Phase 3) and the **MCP
+protocol** (pipeline skills → dev-toolkit, at Phase 5 / design-check / store-ready).
+Either can be swapped or removed without touching the other two's source.
+
+```mermaid
+graph LR
+    subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
+        direction TB
+        PHASES["8 phases · 49 commands"]
+        GATES["deterministic gates + review triage"]
+    end
+
+    subgraph PLUG ["multi-agent-plugins (stack knowledge)"]
+        direction TB
+        IOSP["ai-ios-engineering-toolkit"]
+        ANDP["ai-android-engineering-toolkit"]
+        FEP["ai-frontend-engineering-toolkit"]
+        BEP["ai-backend-toolkit"]
+        COMP["ai-common-engineering-toolkit"]
+    end
+
+    subgraph DTK ["dev-toolkit-mcp (device/browser hands)"]
+        direction TB
+        DEV["Device Control (58)"]
+        A11Y["Accessibility Audit (2)"]
+        STORE["Store Compliance (5)"]
+        WEB["Web Automation (8)"]
+        DESIGN["Design Audit (6)"]
+        AGENTDSL["Agent DSL (1)"]
+    end
+
+    PHASES -->|"Phase 3: Skill tool<br/>taskType===component"| PLUG
+    PHASES -->|"Phase 5 / design-check /<br/>store-ready: MCP tool calls"| DTK
+    GATES -.->|"Phase 4 Security Auditor"| STORE
+
+    style PIPE fill:#ffd,stroke:#333
+    style PLUG fill:#dfd,stroke:#333
+    style DTK fill:#dff,stroke:#333
+```
+
+---
+
+## 1. Authoring flow: one source of truth, five sync targets
+
+`~/.claude/` on the maintainer's machine is authoritative. Everything else is a
+derived, synced, or independently-shipped artifact. `/multi-agent:sync` is the one
+command that walks all five targets in order, detects which are stale, and updates
+only those:
+
+```mermaid
+graph TD
+    CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
+
+    CC -->|"Step 2: copy + reformat<br/>49 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 49 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
+    CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
+
+    REPO -->|"Step 3c: build-stack-plugins.mjs<br/>rebuilds knowledge/ from<br/>shared/external"| PLUGREPO["multi-agent-plugins repo<br/>(5 stack plugins)"]
+
+    DTK2["dev-toolkit-mcp repo<br/>(own codebase, own gates,<br/>NOT generated from Claude)"]
+    SYNC3D["Step 3d: detect movement →<br/>gate → commit → publish"]
+    CC -.->|"sync only SHIPS this,<br/>never authors it"| SYNC3D
+    SYNC3D -.-> DTK2
+
+    REPO -->|"npm publish"| NPM["GitHub Packages"]
+    WEB -->|"git push → auto-deploy"| VERCEL["Vercel"]
+    PLUGREPO -->|"git push"| MKT["Claude Code marketplace"]
+    DTK2 -->|"npm publish"| NPM2["GitHub Packages<br/>(private)"]
+
+    style CC fill:#f9f,stroke:#333
+    style DTK2 fill:#dff,stroke:#333,stroke-dasharray: 5 5
+```
+
+**Why `dev-toolkit-mcp` is drawn differently.** The other four targets are *derived*
+from the Claude Code source — sync writes their content. `dev-toolkit-mcp` is not:
+it's a separate codebase developed on its own schedule. Sync's Step 3d only
+*detects* whether it moved (dirty tree, unpushed commits, untagged version), runs
+**its own** gate suite, and ships it — commit, tag, `npm publish`. If the pipeline
+needs a tool that toolkit doesn't have yet, that's a two-repo change: add the tool
+in `dev-toolkit-mcp`, ship it, then bump the minimum version pin back in
+`cross-cli-contract.md` (see §4).
+
+**Also not generated: the plugins' own authored skills.** `build-stack-plugins.mjs`
+only rebuilds each plugin's `knowledge/` folder from `pipeline/skills/shared/external/`.
+The plugins' lifecycle skills — `create-component`, `evolve-component`,
+`figma-utility`, `code-connect`, `branch-and-pr`, `fix-bug`, and the rest — are
+hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
+
+---
+
+## 2. Plugin marketplace build: one authoring source, five versioned artifacts
+
+```mermaid
+graph TD
+    EXT["pipeline/skills/shared/external/<br/>150 skills — single authoring source<br/>(the pipeline's own phases read these too)"]
+
+    EXT -->|"cross-stack skills"| COMMONP["ai-common-engineering-toolkit<br/>10 skills · v0.2.3"]
+    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-engineering-toolkit<br/>145 skills · v0.6.0"]
+    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-engineering-toolkit<br/>29 skills · v0.1.3"]
+    EXT -->|"backend-only"| BEP["ai-backend-toolkit<br/>32 skills · v0.1.4"]
+    EXT -->|"web/frontend-only"| FEP["ai-frontend-engineering-toolkit<br/>24 skills · v0.1.3"]
+
+    COMMONP --> BUMP{"skill set<br/>changed?"}
+    IOSP --> BUMP
+    ANDP --> BUMP
+    BEP --> BUMP
+    FEP --> BUMP
+    BUMP -->|yes| PATCH["bump that plugin's<br/>patch version"]
+    BUMP -->|no| SKIP["idempotent no-op"]
+
+    PATCH --> CONSUMER["/multi-agent:update<br/>→ claude marketplace update multi-agent-plugins"]
+
+    style EXT fill:#ffd,stroke:#333
+```
+
+A skill counted in more than one platform plugin (a cross-stack knowledge skill
+plus, say, an iOS-specific one) is why the plugins' skill counts sum to more than
+the 150-skill source: `ai-common` skills are vendored into every stack plugin's
+`knowledge/`, not deduplicated across them. Versioning is per-plugin and
+patch-only from this generator — a repo enabling only `ai-ios-engineering-toolkit`
+never pulls an Android-only change.
+
+**Consumption is pull, not push.** A consumer repo enables a stack plugin once
+(`/multi-agent:stack ios`, writing the enabled-plugins list into
+`.claude/settings.json`) and picks up new plugin versions only when it runs
+`/multi-agent:update`, which calls `claude marketplace update multi-agent-plugins`.
+Publishing a new plugin version does not retroactively change anything already
+running in a consumer's session.
+
+---
+
+## 3. Per-host delivery: the same three repos, three different shapes
+
+The three repos land differently on each host, because each host's skill-loading
+behavior is different (see `pipeline/multi-agent-refs/cross-cli-contract.md` for the
+measurements behind this table):
+
+| | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| **Pipeline commands** | 49 slash-command skills, native | 49 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 49 command specs as reference files — Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-engineering-toolkit-architecture`) |
+| **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader — falls back to local frozen `figma-*` skill copies | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
+| **dev-toolkit-mcp** | `claude mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `copilot mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `codex mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |
+
+`smoke-cross-cli-behavior.sh` and `smoke-codex-install.sh` gate the axes that **do**
+have to match (phase labels, placeholder vocabulary, output schemas, command↔skill
+parity count); the table above marks the axes that are allowed to diverge by design.
+
+---
+
+## 4. Runtime: what actually happens during a task
+
+Two independent hand-offs happen inside a single pipeline run, neither aware of the
+other:
+
+```mermaid
+graph TD
+    START["Task running: Phase 3 (Dev)"]
+    START -->|"taskType !== component"| TDD["Standard TDD loop<br/>(pipeline's own code)"]
+    START -->|"taskType === component<br/>+ figmaUrl present"| VALIDATE["ai-ios-engineering-toolkit:figma-validate<br/>(registry, Code Connect, token compliance)"]
+    VALIDATE -->|pass| DISPATCH["Skill tool →<br/>create-component / create-screen<br/>/ evolve-component (dual-name fallback)"]
+    VALIDATE -->|fail| HALT1["halt Phase 3, surface why"]
+    DISPATCH --> REPORT1["plugin returns build/test status →<br/>dispatch layer writes state.phases['3'].subphases[]"]
+
+    REPORT1 --> P4["Phase 4: Review"]
+    P4 --> P5["Phase 5: Test"]
+
+    P5 -->|"UI bug hunt / manual-test /<br/>design-check / store-ready"| MCP["MCP tool call over stdio<br/>e.g. ios_xcodebuild, design_visual_compare,<br/>ios_app_store_audit"]
+    MCP --> DTKPROC["dev-toolkit-mcp process<br/>(npx @mmerterden/dev-toolkit-mcp)"]
+    DTKPROC -->|"result: screenshot / xcresult ID /<br/>18-rule audit verdict"| P5
+
+    style DISPATCH fill:#dfd,stroke:#333
+    style MCP fill:#dff,stroke:#333
+    style HALT1 fill:#fdd,stroke:#333
+```
+
+**Phase 3 → plugin** is a one-shot delegation: the plugin skill does its own
+lifecycle (test → code → build → wiki) and reports back a coarse
+`component-build` result; the pipeline does not re-implement any of that logic, and
+a plugin failure counts against the pipeline's own retry cap (`retryCount === 3` →
+hard stop, per `component-dispatch.md`).
+
+**Phase 5 (and design-check / store-ready) → dev-toolkit** is a long-lived MCP
+session, not a one-shot call: the same stdio server process answers many tool
+calls across a phase (boot simulator once, then screenshot/tap/screenshot/tap...).
+Several pipeline skills pin a **minimum toolkit version** for a specific tool —
+e.g. `apple-archive-compliance` requires `ios_app_store_audit` from
+`dev-toolkit-mcp ≥ v2.9.0` — enforced in `cross-cli-contract.md` and checked by
+`/multi-agent:sync` Step 3d before any dev-toolkit release ships (a version bump
+that drops or renames a tool a pipeline skill depends on is a **major** bump, by
+that step's own contract).
+
+### dev-toolkit-mcp's 80 tools, by category
+
+| Category | Tools | Primary pipeline consumers |
+|---|---|---|
+| Device Control | 58 | `/multi-agent:test`, `test-dark-mode`, `test-accessibility`, `test-dynamic-type`, `test-screenshots`, `manual-test`, `design-check` |
+| Accessibility Audit | 2 | `test-accessibility` |
+| Store Compliance | 5 | `store-ready`, `testflight-validation`, `apple-archive-compliance` skill, Phase 4 Security Auditor |
+| Web Automation | 8 | frontend-stack UI testing (via `test`) |
+| Design Audit | 6 | `design-check` (mock-mode vs Figma conformance) |
+| Autonomous Agent DSL | 1 | any skill that needs a scripted multi-step device flow in one round trip |
+
+---
+
+## 5. Why the boundary is drawn where it is
+
+- **Pipeline ↔ plugins boundary = Skill tool, one direction.** The pipeline
+  classifies (`taskType`, `componentScope`) and tracks state; it never reads or
+  writes plugin-internal files. This is why a corporate marketplace can ship a
+  same-named plugin (`ai-ios-engineering-toolkit:create-ui-component` vs the public
+  `create-component`) and dispatch still resolves correctly — the dual-name
+  fallback lives in the pipeline, the implementation stays entirely in whichever
+  plugin is enabled.
+- **Pipeline ↔ dev-toolkit boundary = MCP protocol, versioned contract.** The
+  pipeline never shells out to `xcrun simctl` or `adb` directly; every device/browser
+  action is a declared MCP tool call with a minimum-version pin. That's what lets
+  `dev-toolkit-mcp` ship on its own release cadence (its own gates, its own
+  `npm publish`) without a pipeline release, as long as pinned tools keep their
+  contract.
+- **Neither boundary is symmetric.** The pipeline depends on both other repos being
+  present *for specific task types* (component work, UI testing) but functions
+  without either — a non-component bugfix task never touches the plugin marketplace,
+  and a task with no UI-testing step never opens the MCP connection.

package/install/_plugin-skills.mjs

@@ -24,9 +24,12 @@
  * @module install/_plugin-skills
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 
+/** Uninstall reads this to know exactly which delivered skill dirs are ours to remove. */
+export const PLUGIN_SKILLS_MANIFEST = ".plugin-skills-manifest.json";
+
 import { copyDir, countFiles, ensureDir, ensureRealDir, isDryRun, wipeDir } from "./_common.mjs";
 
 /** Subtrees a plugin authors itself. `knowledge/` is generated, so it is excluded. */
@@ -254,7 +257,18 @@ export function installAuthoredPluginSkills(opts) {
         `clone {owner}/multi-agent-plugins or enable them in Claude Code to deliver their skills`,
     );
   }
-  return { copied, collided, renamed, plugins, missing, selectionSource };
+  // Uninstall has no way to know which of ~100 flat skill dirs came from a
+  // plugin delivery pass rather than the pipeline's own PIPELINE_CORE_SKILL_DIRS
+  // allowlist - it silently left all of them behind. Persist exactly the names
+  // this pass delivered so uninstall can remove precisely those, nothing more.
+  if (!isDryRun()) {
+    try {
+      writeFileSync(join(dest, PLUGIN_SKILLS_MANIFEST), JSON.stringify([...delivered], null, 2) + "\n");
+    } catch {
+      /* best-effort - a missing manifest just means uninstall skips this cleanup */
+    }
+  }
+  return { copied, collided, renamed, plugins, missing, selectionSource, deliveredNames: [...delivered] };
 }
 
 /**

package/install/codex.mjs

@@ -10,7 +10,7 @@
  * name + description into a single prompt block and silently drops entries once
  * that block overflows - measured at install-design time, one 142-skill plugin
  * surfaced only 75 of its skills AND evicted an unrelated user skill. So the
- * pipeline contributes exactly one skill (`multi-agent`) and keeps its 42
+ * pipeline contributes exactly one skill (`multi-agent`) and keeps its
  * sub-command specs as reference files that cost nothing until read. Converting
  * them into peer skills would silently lose pipeline commands.
  *
@@ -230,7 +230,12 @@ function installRouterSkill(pipelineSrc, skillsDir) {
   const dest = join(skillsDir, "multi-agent");
   ensureDir(dest);
   writeFile(join(dest, "SKILL.md"), skill);
-  console.log(`    -> 1 router skill written to ${dest} (42 command specs stay as refs)`);
+
+  const commandsDir = join(pipelineSrc, "commands", "multi-agent");
+  const specCount = existsSync(commandsDir)
+    ? readdirSync(commandsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length
+    : 0;
+  console.log(`    -> 1 router skill written to ${dest} (${specCount} command specs stay as refs)`);
 }
 
 /**
@@ -279,10 +284,10 @@ function installRefs(pipelineSrc, dest) {
   let count = 0;
   if (existsSync(refsSrc)) count += copyTreeRewritten(refsSrc, dest);
 
-  // The 42 sub-command specs. Skip ONLY the top-level dispatcher SKILL.md -
+  // The sub-command specs. Skip ONLY the top-level dispatcher SKILL.md -
   // it already shipped as the router skill. The filter is on the path relative
   // to the copy root, not the basename: every sub-command spec is itself named
-  // SKILL.md, so a basename filter would copy 42 empty directories and leave
+  // SKILL.md, so a basename filter would copy N empty directories and leave
   // the orchestrator with nothing to read.
   if (existsSync(commandsSrc)) {
     count += copyTreeRewritten(commandsSrc, join(dest, "commands"), (rel) => rel !== "SKILL.md");