@mmerterden/multi-agent-pipeline 10.7.0 → 10.7.2

package/README.md

@@ -5,802 +5,98 @@
 [![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)
 
-8-phase AI development pipeline for **Claude Code** and **Copilot CLI**. Multi-repo orchestration, platform identity routing, push-must-succeed policy, CLI-aware parallel review with Opus triage (Claude Code: 2-model Opus+Sonnet · Copilot CLI: 3-model GPT-5.4+Opus+Sonnet), commit/PR creation - and, as of 5.0.0, a generic Figma-to-Component pipeline that works on iOS (SwiftUI) and Android (Jetpack Compose) with the same workflow.
+An 8-phase AI development pipeline for **Claude Code** and **Copilot 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. Includes a generic Figma-to-Component pipeline for iOS (SwiftUI) and Android (Jetpack Compose).
 
-### Current at-a-glance (live from filesystem)
-
-| Surface | Count |
-|---|---|
-| Slash commands (colon-form `/multi-agent:*`) | 35 |
-| Copilot skills (dash-form `multi-agent-*`) | 35 |
-| Platforms (Claude Code, Copilot CLI) | 2 |
-| Store-compliance skills (`apple-archive-compliance`, `google-play-compliance`) | 2 |
-| Figma skills (iOS + Android + Common) | 41 |
-| External skill catalog (`shared/external/`) | 143 |
-| Total `SKILL.md` files across all groups | 221 |
-| Smoke suites | 108 |
-| Golden-task fixtures (`pipeline/eval/golden-tasks/`) | 8 |
-| Eval-triage fixtures | 11 |
-| JSON schemas | 16 |
-| Agent personas | 8 |
-| Pipeline phases | 8 |
-
-> **Claude Code** and **Copilot CLI** run the full pipeline natively - the gate scripts + live tracker are installed to `~/.claude` / `~/.copilot`, and on Claude Code a `PreToolUse` hook hard-blocks on the secret scan.
-
-> Security issue? See [SECURITY.md](./SECURITY.md). Please do not open public issues for vulnerabilities.
-
-## Prerequisites
-
-- Node.js 18+
-- Claude Code (https://claude.ai/code) **or** GitHub Copilot CLI
-- macOS, Linux, or Windows (Git Bash / WSL). Native credential storage everywhere:
-  - **macOS** → Keychain (`security`)
-  - **Linux** → libsecret (`secret-tool` - `apt install libsecret-tools` / `dnf install libsecret`)
-  - **Windows** → Credential Manager (PowerShell `CredentialManager` module - `Install-Module CredentialManager`)
-- Runtime CLIs the pipeline shells out to:
-  - `gh` (GitHub CLI) for issue / PR flows
-  - `jq` for JSON parsing
-  - `python3` (stdlib only, used by the deterministic keychain helper)
-  - `bash` 4+
-
-The package is **public on npmjs.org** - no auth, no PAT, no `~/.npmrc` setup needed:
-
-```bash
-npm view @mmerterden/multi-agent-pipeline version
-# → prints "10.0.0" (or newer)
-```
-
-If `npm view` shows a stale version, run `npm cache clean --force` and retry.
-
-> **New here?** Worked end-to-end transcripts live in [`examples/`](./examples/) - bug fix from Jira, feature in autopilot, `--dev` fast path, and recovery from a broken run. Read one before you run the pipeline on your own code.
->
-> **Something broke?** [`docs/recovery-guide.md`](./docs/recovery-guide.md) is the single-page index of every failure mode (triage fallback, worktree collision, state corruption, identity rewind, etc.) and its fix.
->
-> **Planning breaking changes?** [`ROADMAP.md`](./ROADMAP.md) tracks what's coming and what's been declined.
+Runs natively on Claude Code and Copilot CLI. macOS / Linux / Windows. Zero runtime dependencies.
 
 ## Quick Start
 
-### Option A - Install from source (recommended for development)
-
-Clone the repo and run the installer directly - full read access to source files.
-
-```bash
-git clone git@github.com:mmerterden/multi-agent-pipeline.git
-cd multi-agent-pipeline
-npm install
-node install.js                         # Claude Code (default)
-node install.js --copilot               # Copilot CLI
-node install.js --all                   # Both Claude + Copilot
-
-node install.js --link                  # Symlink mode (dev, saves ~10K tokens)
-node install.js --all --dry-run         # Preview every operation, write nothing
-
-# Token-preserving uninstall (Keychain access tokens NEVER touched)
-node install.js                         # ...later...
-node pipeline/scripts/uninstall.mjs --dry-run     # preview what would be removed
-node pipeline/scripts/uninstall.mjs --yes         # remove from every installed target
-
-# Optional: expose the CLI globally as 'multi-agent-pipeline'
-npm link
-```
-
-**IMPORTANT - run setup before your first task:**
-
-```
-/multi-agent:setup
-```
-
-This discovers your Keychain tokens (Jira, Bitbucket, GitHub, etc.), sets up your git identity, and maps everything into `~/.claude/multi-agent-preferences.json`. Without this step, the pipeline cannot find your tokens and will ask for them repeatedly.
-
-Update later with `git pull && npm install` inside the clone. Pin to a specific version by checking out the corresponding tag (`git tag -l` to list).
-
-### Option B - npx (public registry, no auth)
-
 ```bash
-npx @mmerterden/multi-agent-pipeline install            # Claude Code only (default)
-npx @mmerterden/multi-agent-pipeline install --copilot  # Copilot CLI only
-npx @mmerterden/multi-agent-pipeline install --all      # Both native CLIs (Claude + Copilot)
-npx @mmerterden/multi-agent-pipeline install --link     # Symlink mode
-npx @mmerterden/multi-agent-pipeline install --all --dry-run  # Preview, write nothing
-
-# Token-preserving uninstall
-npx @mmerterden/multi-agent-pipeline uninstall          # interactive, all targets
-npx @mmerterden/multi-agent-pipeline uninstall --dry-run # preview only
-```
+# from the public registry (no auth)
+npx @mmerterden/multi-agent-pipeline install --all   # Claude Code + Copilot CLI
 
-### Option C - Global install (public registry, no auth)
-
-```bash
-npm install -g @mmerterden/multi-agent-pipeline
-multi-agent-pipeline install            # same flags apply
+# then, once:
+/multi-agent:setup          # keychain token scan + git identity + default stack
 ```
 
-## Privacy & Telemetry
-
-**Opt-in only.** The installer sends nothing by default. If you want to help the
-project by sharing an anonymous install ping, opt in per-install with
-`MULTI_AGENT_TELEMETRY=1`:
+Run a task — the input type is auto-detected:
 
 ```bash
-MULTI_AGENT_TELEMETRY=1 node install.js
-# or for npx/global
-MULTI_AGENT_TELEMETRY=1 npx @mmerterden/multi-agent-pipeline install
-```
-
-When opted in, the ping includes:
-
-- Package name + version
-- Install method (`source`, `npx`, `global`, `npm-install`)
-- Flags passed (e.g. `--copilot`, `--all`)
-- Your GitHub username (via `gh api user` if authenticated) and Git email
-- Hostname, OS, arch, Node version
-
-Nothing else is collected. Ping failures are silent - telemetry never blocks or
-slows down the install.
-
-## What's new
-
-- **v10.4.0** (2026-07-02) - New `/multi-agent:finish` command: continue already-done LOCAL work through the pipeline tail in one shot — parallel review → build+test success gate → commit/push/PR → technical analysis + a Jira comment with test scenarios, without re-developing (phases 1-3 skipped). Pairs with `dev-local`/`local` (which skip Review + Test) or with hand-coded/hand-tested changes. Command inventory 34 → 35.
-- **v10.3.0** (2026-07-02) - Android (Jetpack Compose) parity for the 10.2.0 interaction skills: `figma-navigation` / `figma-overlays` / `figma-bottom-sheets` now carry both a SwiftUI and a Compose section (Navigation Compose; Snackbar/AlertDialog/Dialog + state-driven loading; `ModalBottomSheet`), same emit-intent rules and `ui.*` config hooks on both platforms. Plus a review pass: corrected the `animated-gradient-border` snippet (animate `AngularGradient(angle:)` on a static shape, not `rotationEffect`) and genericized the sheet corner-radius example token.
-- **v10.2.0** (2026-07-02) - Generic SwiftUI interaction coverage for figma-to-swiftui: three new cross-cutting integration skills (`figma-navigation`, `figma-overlays`, `figma-bottom-sheets`) + a reconcile-and-extend workflow (`figma-evolve-component`), all native-SwiftUI-first with an optional per-project `ui.*` config hook (so the same capabilities work on any SwiftUI codebase, no app-specific coupling). Phase 3D dev detection (§1.5.4) and Phase 4 review both consume them; `figma-to-swiftui` accessibility reference enriched with the VoiceOver-minimalism decision tree; new `animated-gradient-border` UI pattern. Figma-common skills 27 → 31, total figma skills 37 → 41.
-- **v10.1.0** (2026-06-20) - Fable 5 retired (no longer available): the five heavy agent personas plus Phase 1 / Phase 2 / Phase 4 reviewer-1 + triage and `--dev` fast mode now route to Opus (top available tier); fallback ladder is `opus -> sonnet`. Per-task cost guard (`costBudget`) now defaults on in warn mode. Token economy: Phase 4 shared cache prefix + single-repo diff cap, Phase 1 light Explore tier for small bugfixes, triage prior-art injection capped.
-- **v10.0.0** (2026-06-12) - quality major driven by a 10-category self-audit + competitive sweep: validator gates wired into phases 1/2/4 (fails closed), Phase 3 code-simplifier diff-shrink pass, Phase 4 lesson memory loop, Phase 2 cross-artifact consistency gate, skill frontmatter linter (repaired 31 SKILL.md), installer `--dry-run` + unknown-flag rejection, timeout-guarded smoke runner, adapter family deduplicated (~490 lines), CI hardening (blocking lint, npm audit, shellcheck), tag-driven npm release automation, CHANGELOG split (310KB -> 40KB).
-- **v9.10.2** (2026-06-11) - live per-phase token narration on completion; tracker mandates per-phase cost lines in the final report.
-- **v9.10.1** (2026-06-11) - Claude Fable 5 fallback contract: date gate, dispatch retry, and budget guard when the Fable tier is unavailable.
-- **v9.10.0** (2026-06-11) - Claude Fable 5 adoption on the Claude Code side: the five heavy agent personas plus Phase 1 / Phase 2 / Phase 4 reviewer-1 + triage and `--dev` fast mode route to `claude-fable-5`; cost ledger gains `fable` pricing and fixes the stale `opus` entry.
-
-Full version history lives in [CHANGELOG.md](./CHANGELOG.md) - every release entry is recorded there to avoid drift between the two files.
-
-
-## Troubleshooting
-
-### `sh: multi-agent-pipeline: command not found`
-
-`npx` couldn't fetch the package. Most common causes:
-
-- Network blocked or proxy in front of npmjs.org.
-- Stale npx cache - `npx clear-npx-cache` then retry.
-- Wrong package name (it is `@mmerterden/multi-agent-pipeline`, with the scope).
-
-### `npm error code E404` on `registry.npmjs.org`
-
-The package wasn't reachable. Quick checks:
-
-```bash
-curl -fsSL "https://registry.npmjs.org/@mmerterden/multi-agent-pipeline" | jq -r '."dist-tags".latest'
-# Should print 10.0.0 (or newer)
-```
-
-- If this prints a version → your local npm cache is stale; run `npm cache clean --force` and retry.
-- If it 404s → registry outage or scope/package-name typo. Verify the URL hits the JSON above.
-
-### Older PAT / GitHub Packages docs
-
-Earlier README revisions referenced GitHub Packages with a Classic PAT and `~/.npmrc` setup. The package moved to **public npmjs.org** in v8.6.1; no token, no `~/.npmrc` line is needed. If you set one up previously, you can leave it - it just won't be consulted.
-
-## Tool support
-
-The pipeline runs natively on **Claude Code** and **Copilot CLI** — the two CLIs it targets. Both install from the same `pipeline/skills/` source and get identical skill coverage.
-
-| Tool | Install Flag | How It Works |
-| --- | --- | --- |
-| **Claude Code** | `--claude` (default) | Native: slash commands + shared + figma skills + agents + rules + scripts |
-| **Copilot CLI** | `--copilot` | Native: instructions + shared + figma skills + scripts |
-
-Skill tree:
-
-- `pipeline/skills/shared/core/` - **orchestration skills** (`multi-agent-*` dash-form mirrors of the colon-form slash commands + compliance skills + orchestrator)
-- `pipeline/skills/shared/external/` - **curated iOS / Android / generic guidance skills** (SwiftUI, Jetpack Compose, testing, performance, security, etc.) — also distributed as versioned marketplace plugins in `mmerterden/multi-agent-plugins`
-- `pipeline/skills/figma-ios/` + `pipeline/skills/figma-android/` - **platform-specific Phase 3 sub-skills** (SwiftUI and Jetpack Compose code generation)
-- `pipeline/skills/figma-common/` - **platform-agnostic Figma helpers** (iterate, commit, wiki setup, MCP auth, performance harness)
-
-Filter the skill set by stack with `--platform=ios|android|all`. Both CLIs also receive the same `pipeline/scripts/` tree so single-CLI installs stay self-contained.
-
-### Uninstall (token-preserving)
-
-```bash
-npx @mmerterden/multi-agent-pipeline uninstall            # interactive, all installed targets
-npx @mmerterden/multi-agent-pipeline uninstall --dry-run  # preview, zero side effects
-```
-
-Personal access tokens stored in macOS Keychain / Windows Credential Manager / Linux libsecret are **never touched** by the uninstaller. Smoke tests enforce this with a static check that fails the build if the script ever references a credential-store deletion API.
-
-## Pipeline Phases
-
-```
-Phase 0: Init - Project selection, branch setup, identity, worktree
-Phase 1: Analysis - Stack detection, codebase exploration
-Phase 2: Planning - Task decomposition, architecture review, user approval
-Phase 3: Dev - TDD cycle: test → code → build
-Phase 4: Review - Deterministic gates + parallel review + Opus triage
-                     • Claude Code → Opus + Sonnet (2 paralel)
-                     • Copilot CLI → GPT-5.4 + Opus + Sonnet (3 paralel)
-Phase 5: Test - Optional manual testing + MCP device audits (on-demand)
-Phase 6: Commit - Pre-commit local checkout prompt, git commit, push, PR creation
-Phase 7: Report - External: Jira comment · Wiki + Figma screenshots · Confluence
-                     Internal: Log · Knowledge + memory capture
-```
-
-### Full Pipeline Flow
-
-```mermaid
-flowchart TD
-    INPUT["🎯 <b>User Input</b><br/>Issue # · Jira URL · Free-text · jira · issue"]
-
-    subgraph SETUP ["Setup"]
-        P0["<b>Phase 0: Init</b><br/>Project detect · Worktree<br/>Branch · Identity · Task type"]
-        P1["<b>Phase 1: Analysis</b><br/>Parallel Explore agents<br/>Stack detection · Guide load"]
-        P2["<b>Phase 2: Planning</b><br/>Task decompose<br/>Architect review · User approval"]
-    end
-
-    subgraph DEVELOP ["Development"]
-        P3["<b>Phase 3: Dev</b><br/>🔴 RED: test<br/>🟢 GREEN: implement<br/>🔵 REFACTOR · Build pass"]
-    end
-
-    subgraph REVIEW ["Review"]
-        R1["<b>Opus</b><br/>Security<br/>Architecture"]
-        R2["<b>GPT-5.4</b><br/>Quality<br/>Edge cases"]
-        R3["<b>Sonnet</b><br/>Correctness<br/>Style"]
-        TRIAGE["<b>Opus Triage</b><br/>Filter noise · Deduplicate<br/>Forward actionable only"]
-    end
-
-    subgraph DELIVER ["Delivery"]
-        P5["<b>Phase 5: Test</b><br/>Manual test<br/>Device audits (on-demand)"]
-        P6["<b>Phase 6: Commit</b><br/>Secret scan · Commit<br/>Push · PR create"]
-        P7["<b>Phase 7: Report</b>"]
-        subgraph REPORT ["Phase 7 sub-steps"]
-            direction LR
-            H1["Jira comment<br/>(analysis + tests)"]
-            H2["Wiki + Figma<br/>screenshots"]
-            H3["Confluence<br/>(optional)"]
-            H4["Report · Log"]
-            H5["Knowledge +<br/>memory capture"]
-        end
-        P7 --> H1 --> H2 --> H3 --> H4 --> H5
-    end
-
-    INPUT --> P0
-    P0 --> P1
-    P1 --> P2
-    P2 --> P3
-    P3 --> R1 & R2 & R3
-    R1 & R2 & R3 --> TRIAGE
-    TRIAGE -->|"✅ Approved"| P5
-    TRIAGE -->|"🔧 Fix needed (≤3x)"| P3
-    P5 --> P6
-    P6 --> P7
-
-    style INPUT fill:#818cf8,stroke:#6366f1,color:#fff
-    style P3 fill:#fbbf24,stroke:#f59e0b,color:#000
-    style TRIAGE fill:#38bdf8,stroke:#0ea5e9,color:#000
-    style P7 fill:#4ade80,stroke:#22c55e,color:#000
-    style H1 fill:#fde68a,stroke:#f59e0b,color:#000
-    style H2 fill:#c084fc,stroke:#a855f7,color:#000
-    style H3 fill:#bae6fd,stroke:#0ea5e9,color:#000
-```
-
-### Operating Modes
-
-```mermaid
-flowchart LR
-    subgraph NORMAL ["Normal (Full 8-phase)"]
-        direction LR
-        N0[Init] --> N1[Analysis] --> N2[Planning] --> N3[Dev] --> N4[Review] --> N5[Test] --> N6[Commit] --> N7[Report]
-    end
-
-    subgraph DEV ["--dev (Fast, Opus)"]
-        direction LR
-        D0[Init] --> D3["Dev<br/>(Opus)"] --> D6[Commit] --> D7[Report]
-    end
-
-    subgraph AUTO ["autopilot (No confirmations)"]
-        direction LR
-        A0[Init] --> A1[Analysis] --> A2[Planning] --> A3[Dev] --> A4[Review] --> A6[Commit] --> A7[Report]
-    end
-
-    subgraph FAST ["--dev autopilot (Fastest)"]
-        direction LR
-        F0[Init] --> F3["Dev<br/>(Opus)"] --> F6["Commit<br/>(auto)"] --> F7[Report]
-    end
-
-    style D3 fill:#fbbf24,stroke:#f59e0b,color:#000
-    style F3 fill:#fbbf24,stroke:#f59e0b,color:#000
-    style F6 fill:#4ade80,stroke:#22c55e,color:#000
-```
-
-### Review Architecture (Phase 4)
-
-```mermaid
-flowchart TD
-    DIFF["📝 Code Diff"]
-
-    DIFF --> OPUS["<b>Opus</b><br/>🔒 Security · Architecture<br/>Data flow · Auth"]
-    DIFF --> GPT["<b>GPT-5.4</b><br/>✨ Code quality · Edge cases<br/>Error paths · Logic"]
-    DIFF --> SON["<b>Sonnet</b><br/>✅ Correctness · Best practices<br/>Naming · Style"]
-
-    OPUS --> TRIAGE
-    GPT --> TRIAGE
-    SON --> TRIAGE
-
-    TRIAGE["<b>Opus Triage</b><br/>Deduplicate findings<br/>Filter false-positives<br/>Reject out-of-scope<br/>Classify severity"]
-
-    TRIAGE -->|"✅ PASS"| NEXT["Phase 5: Test"]
-    TRIAGE -->|"🔧 FIX_REQUIRED"| BACK["Phase 3: Dev<br/>(retry ≤3x)"]
-
-    style DIFF fill:#818cf8,stroke:#6366f1,color:#fff
-    style TRIAGE fill:#38bdf8,stroke:#0ea5e9,color:#000
-    style NEXT fill:#4ade80,stroke:#22c55e,color:#000
-    style BACK fill:#f87171,stroke:#ef4444,color:#000
-```
-
-### Figma SubPhase Integration (Phase 3)
-
-When `figmaConfigPath` is set in project preferences, Phase 3 dispatches the Figma-to-SwiftUI pipeline instead of standard TDD:
-
-```mermaid
-flowchart TD
-    P3["<b>Phase 3: Dev</b>"]
-
-    P3 -->|default| TDD["<b>Standard TDD</b><br/>RED → GREEN → REFACTOR → build"]
-    P3 -->|"figmaConfigPath set"| FIG
-
-    subgraph FIG ["Figma-to-SwiftUI Pipeline (17 SubPhases)"]
-        direction TB
-
-        subgraph INIT_G ["Init + Gather"]
-            S0["3.0 Init<br/>Parse URL · Branch · Assign"]
-            S1["3.1 Gather<br/>Fetch design context"]
-        end
-
-        subgraph PREP ["Preparation (parallel)"]
-            S2A["3.2A TestingIDs"]
-            S2B["3.2B Localization"]
-            S2C["3.2C Accessibility"]
-            S2D["3.2D Analytics"]
-        end
-
-        S3["3.3 Token Mapping<br/>Figma values → design tokens"]
-
-        subgraph IMPL ["Implementation (sequential)"]
-            S4A["3.4A Config"]
-            S4B["3.4B View"]
-            S4C["3.4C Docs"]
-            S4D["3.4D Preview"]
-            S4E["3.4E Modifiers"]
-            S4F["3.4F Wiki"]
-        end
-
-        subgraph TEST_G ["Testing"]
-            S5A["3.5A ViewInspector"]
-            S5B["3.5B Snapshot"]
-            S5C["3.5C Unit"]
-        end
-
-        S6["3.6 CodeConnect<br/>Figma ↔ code link"]
-
-        S0 --> S1
-        S1 --> S2A & S2B & S2C & S2D
-        S2A & S2B & S2C & S2D --> S3
-        S3 --> S4A --> S4B --> S4C --> S4D --> S4E --> S4F
-        S4F --> S5A --> S5B --> S5C
-        S5C --> S6
-    end
-
-    style P3 fill:#fbbf24,stroke:#f59e0b,color:#000
-    style TDD fill:#4ade80,stroke:#22c55e,color:#000
-    style S3 fill:#818cf8,stroke:#6366f1,color:#fff
-    style S6 fill:#c084fc,stroke:#a855f7,color:#000
+/multi-agent "PROJ-1234"                              # Jira id → fetch, plan, build
+/multi-agent "https://github.com/org/repo/issues/42"  # GitHub issue URL
+/multi-agent "my-app#42"                              # repo + issue number
+/multi-agent "fix dark-mode contrast on LoginView"    # free-text bug/feature
+/multi-agent:jira                                     # browse your open Jira issues → pick
+/multi-agent:issue                                    # browse unassigned GitHub issues → pick
 ```
 
-### Ecosystem Architecture
+Every input runs the same short intake — **account → (repo) → maturity check → dev-context** — then enters Phase 0. A Jira id or GitHub URL is fetched and maturity-checked *before* any code is written; free-text skips the fetch and goes straight to planning. Multi-repo tasks add extra repos at the dev-context step.
 
-```mermaid
-flowchart TD
-    CC["<b>Claude Code</b><br/>(Source of Truth)<br/><br/>~/.claude/commands/<br/>~/.claude/agents/<br/>~/.claude/scripts/"]
-
-    CC -->|"instructions + 206 skills + scripts"| COP["<b>Copilot CLI</b><br/>~/.copilot/skills/<br/>~/.copilot/scripts/<br/>copilot-instructions.md"]
-    CC -->|"genericized pipeline/"| REPO["<b>Pipeline Repo</b><br/>@mmerterden/<br/>multi-agent-pipeline"]
-    CC -.->|"optional"| WEB["<b>Website</b><br/>(your docs site)"]
-    CC -.->|"optional"| RC["<b>Remote Control</b><br/>(your dashboard)"]
-
-    REPO -->|"npm publish"| NPM["<b>GitHub Packages</b><br/>(npm)"]
-    WEB -->|"auto-deploy"| VERCEL["Vercel"]
-
-    style CC fill:#818cf8,stroke:#6366f1,color:#fff
-    style REPO fill:#fbbf24,stroke:#f59e0b,color:#000
-    style NPM fill:#4ade80,stroke:#22c55e,color:#000
-    style WEB fill:#38bdf8,stroke:#0ea5e9,color:#000
-```
+Add `autopilot` to skip confirmations, `--dev` for the fast dev-only path, or `--local` to work on the current branch without a worktree (e.g. `/multi-agent:autopilot "PROJ-1234"`).
 
-### Claude Code (Full Mode)
+Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx @mmerterden/multi-agent-pipeline uninstall`.
 
-All 8 phases with sub-agents, parallel review + Opus triage (2-model Opus+Sonnet on Claude Code, 3-model GPT+Opus+Sonnet on Copilot CLI), TaskCreate visual tracking.
-
-```bash
-# Pipeline tasks
-/multi-agent "MOBILE-12345"                              # Jira issue
-/multi-agent "#42"                                        # GitHub issue
-/multi-agent "Fix dark mode colors in LoginView"          # Free-text
-/multi-agent:dev "MOBILE-12345"                           # Fast mode (Opus)
-/multi-agent:autopilot "MOBILE-12345"                     # Skip confirmations
-/multi-agent:dev-autopilot "MOBILE-12345"                 # Zero interaction
-
-# Helper commands
-/multi-agent:status                                       # List all tasks
-/multi-agent:log 1                                        # Show task log
-/multi-agent:resume 1                                     # Resume stopped task
-/multi-agent:kill 1                                       # Delete task worktree
-/multi-agent:review                                       # Review current diff
-/multi-agent:setup                                        # Token + identity onboarding (asks promptLanguage + outputLanguage)
-/multi-agent:language tr                                  # Toggle pipeline languages (en / tr per axis)
-/multi-agent:test                                         # UI Bug Hunter
-/multi-agent:channels "PR-url"                            # Post report (Jira / Confluence / Wiki / PR)
-/multi-agent:search "query"                               # Full-text log search
-/multi-agent:scan                                         # Skill security scan
-/multi-agent:refactor                                     # Refactor planner
-/multi-agent:update                                       # Update pipeline
-/multi-agent:sync                                         # Sync ecosystem
-/multi-agent:purge                                        # Full reset (double-confirm)
-
-# Flag syntax (equivalent to dedicated commands above)
-/multi-agent "MOBILE-12345" --dev                         # same as :dev
-/multi-agent "MOBILE-12345" --dev autopilot               # same as :dev-autopilot
-```
-
-### Copilot CLI (Lite Mode)
-
-Same pipeline logic, invoked via dash syntax (`multi-agent-*`).
-
-```bash
-# Pipeline tasks
-multi-agent "MOBILE-12345"                               # Jira issue
-multi-agent "#42"                                         # GitHub issue
-multi-agent "Fix dark mode colors in LoginView"           # Free-text
-multi-agent-dev "MOBILE-12345"                            # Fast mode (Opus)
-multi-agent-autopilot "MOBILE-12345"                      # Skip confirmations
-multi-agent-dev-autopilot "MOBILE-12345"                  # Zero interaction
-
-# Helper commands
-multi-agent-status                                        # List all tasks
-multi-agent-log 1                                         # Show task log
-multi-agent-resume 1                                      # Resume stopped task
-multi-agent-kill 1                                        # Delete task worktree
-multi-agent-review                                        # Review current diff
-multi-agent-setup                                         # Token + identity onboarding
-multi-agent-test                                          # UI Bug Hunter
-multi-agent-channels "PR-url"                             # Post report (Jira / Confluence / Wiki / PR)
-multi-agent-search "query"                                # Full-text log search
-multi-agent-scan                                          # Skill security scan
-multi-agent-refactor                                      # Refactor planner
-multi-agent-update                                        # Update pipeline
-multi-agent-sync                                          # Sync ecosystem
-multi-agent-purge                                         # Full reset (double-confirm)
-```
+## How it works
 
-## Supported Stacks
+One command runs 8 phases, with a gate between the risky ones:
 
-| Platform                      | Detection                                    | Guide Loaded            |
-| ----------------------------- | -------------------------------------------- | ----------------------- |
-| **iOS/Swift**                 | `.xcodeproj`, `Package.swift`                | SwiftUI Component Guide |
-| **Android/Kotlin**            | `build.gradle`, `build.gradle.kts`           | Jetpack Compose Guide   |
-| **Backend** (Python/Node/Go)  | `requirements.txt`, `package.json`, `go.mod` | Backend API Guide       |
-| **Frontend** (React/Vue/Next) | `package.json` + framework detection         | Frontend Guide          |
+- **0 · Init** — parse the input (Jira id / GitHub URL / free text), pick account + repo(s), fetch the issue, run a maturity check.
+- **1 · Analysis** — detect the stack, scan the codebase, map impact (Opus).
+- **2 · Plan** — write a task breakdown and **stop for your approval** before touching code.
+- **3 · Dev** — TDD: failing test → code → green, following the repo's style + the active stack skills.
+- **4 · Review** — deterministic gates (build / lint / test / secret-scan) must pass first, then a **CLI-aware parallel review** — Claude Code runs 2 models (Fable + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) — and a **Fable triage** keeps only actionable findings; blockers loop back to Phase 3.
+- **5 · Test** — build + run the suite; success is required (no faked passes).
+- **6 · Commit/PR** — conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
+- **7 · Report** — technical summary + a Jira comment with test scenarios, posted through the channels layer.
 
-Stack is auto-detected. Build commands, test runners, lint tools, and review focus areas all adapt automatically.
+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.
 
 ## Modes
 
-| Mode | Claude Code | Copilot CLI | Description |
-| ---- | ----------- | ----------- | ----------- |
-| Normal | `/multi-agent "task"` | `multi-agent "task"` | Full 8 phases with CLI-aware parallel review (Claude: 2-model · Copilot: 3-model) |
-| Fast | `/multi-agent:dev "task"` | `multi-agent-dev "task"` | Init → Dev(Opus) → Commit → Report |
-| Local | `/multi-agent "task" --local` | `multi-agent "task" --local` | No worktree - works on local branch |
-| Autopilot | `/multi-agent:autopilot "task"` | `multi-agent-autopilot "task"` | Skip confirmations, auto commit/PR |
-| Fastest | `/multi-agent:dev-autopilot "task"` | `multi-agent-dev-autopilot "task"` | Zero interaction |
-| Test | `/multi-agent:test` | `multi-agent-test` | UI Bug Hunter - visual + accessibility |
-| Channels | `/multi-agent:channels <target>` | `multi-agent-channels <target>` | Post report to Jira / Confluence / Wiki / PR (multi-select, humanizer pass, reviewer-preserving) |
-| Stack | `/multi-agent:stack ios` | `multi-agent-stack ios` | Select stack by enabling the matching marketplace plugin(s) |
-| Language | `/multi-agent:language [prompt\|output] <en\|tr>` | `multi-agent-language [prompt\|output] <en\|tr>` | Toggle `promptLanguage` (interactive prompts) and/or `outputLanguage` (assistant explanations). External payloads stay English. |
+| Mode | Command | Flow |
+|---|---|---|
+| Full | `/multi-agent "task"` | All 8 phases, interactive |
+| Autopilot | `/multi-agent:autopilot "task"` | All 8 phases, no confirmations |
+| Dev | `/multi-agent:dev "task"` | Init → Dev → Commit → Report |
+| Local | `/multi-agent:local "task"` | Full pipeline, current branch (no worktree) |
+| Finish | `/multi-agent:finish` | Run the review→test→commit→report tail over local work |
 
-## UI Bug Hunter + Audit Tools
+Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `jira`, `issue`, `analysis`. Full list: `/multi-agent:help`.
 
-Automated visual testing and compliance audits. Requires the mobile MCP server.
+## Stacks
 
-```bash
-# Claude Code                              # Copilot CLI
-/multi-agent:test                           # multi-agent-test
-/multi-agent:test "dark mode"               # multi-agent-test "dark mode"
-/multi-agent:test "accessibility"           # multi-agent-test "accessibility"
-/multi-agent:test "dynamic type"            # multi-agent-test "dynamic type"
-/multi-agent:test "store-ready"             # multi-agent-test "store-ready"
-/multi-agent:test "biometric"               # multi-agent-test "biometric"
-/multi-agent:test "performance"             # multi-agent-test "performance"
-```
-
-### How Audit Tools Work
-
-All audits run via **direct Bash commands** - no MCP server dependency. Pipeline uses `xcrun simctl`, `adb`, `codesign`, `aapt2` etc. natively.
-
-| Audit                 | What It Does                                           | Command                      | When                    |
-| --------------------- | ------------------------------------------------------ | ---------------------------- | ----------------------- |
-| iOS Accessibility     | Missing labels, small tap targets                      | `swift ui-tree-dumper.swift` | Phase 5 - user requests |
-| Android Accessibility | Missing contentDescription, small touch targets        | `adb shell uiautomator dump` | Phase 5 - user requests |
-| iOS Biometric         | Face ID / Touch ID success/failure                     | `xcrun simctl keychain`      | Phase 5 - auth flow     |
-| Android Launch Time   | Cold start time (ms)                                   | `adb shell am start -W`      | Phase 5 - performance   |
-| iOS Archive           | App Store compliance: signing, debug tools, privacy    | `codesign`, `plutil`, `nm`   | Phase 6 - release       |
-| Android APK           | Play Store compliance: target SDK, debuggable, signing | `aapt2`, `apksigner`         | Phase 6 - release       |
-
-**Important**: Audits are **on-demand** - triggered by user, not automatic. Phase 4 does code-level accessibility review (free, no device needed). Phase 5/6 do device-level audits only when requested.
-
-**No external dependencies** - only standard Xcode CLI tools (iOS) and Android SDK (Android). Platform guides include **compliance rules** that map 1:1 to audit checks - follow the guide, pass the audit.
-
-## Stack Selection (marketplace plugins)
-
-Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack **enables the matching plugin(s)** in the repo's `.claude/settings.json` `enabledPlugins` — the stack toolkit plus `ai-common-engineering-toolkit` (cross-stack skills). This replaced the old `stack-swap.sh` mechanic (which physically moved skill directories on a SessionStart hook); enablement is now declarative, per-repo, and versioned.
+Stack skills ship as versioned plugins in the [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) marketplace. Select a stack per-repo:
 
 ```bash
-# Claude Code                              # Copilot CLI
-/multi-agent:stack                          multi-agent-stack                # show enabled plugins
-/multi-agent:stack ios                      multi-agent-stack ios            # SwiftUI toolkit + common
-/multi-agent:stack android                  multi-agent-stack android        # Compose toolkit + common
-/multi-agent:stack backend                  multi-agent-stack backend        # Python/Node toolkit + common
-/multi-agent:stack frontend                 multi-agent-stack frontend       # React/TSX toolkit + common
-/multi-agent:stack mobile                   multi-agent-stack mobile         # iOS + Android + common
-/multi-agent:stack all                      multi-agent-stack all            # all four toolkits + common
+/multi-agent:stack ios        # or android / frontend / backend / mobile / all
 ```
 
-Add the marketplace once with `claude marketplace add {owner}/multi-agent-plugins`. Newly published plugin versions are pulled by `/multi-agent:update`. The plugins are rebuilt from `pipeline/skills/shared/external/` via `pipeline/scripts/build-stack-plugins.mjs` (run by `multi-agent:sync` Step 3c), which bumps the patch version of any plugin whose skill set changed. The old `stack-swap.sh` mechanic has been removed.
-
-## Setup
-
-```bash
-# 1. Install pipeline
-npx @mmerterden/multi-agent-pipeline install --all
-
-# 2. Configure
-/multi-agent:setup                          # Claude Code
-multi-agent-setup                           # Copilot CLI
-# -> Jira project key (e.g., MOBILE, APP, ENG)
-# -> Git identity (name + email)
-# -> Keychain token scan + mapping
-
-# That's it! Pipeline works standalone - no additional dependencies needed.
-```
-
-## Hooks & Context Management
-
-Pipeline includes automated safety hooks and session optimization, configured during installation.
+This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's `.claude/settings.json`. Phase 1 auto-detects the stack for routing. New repos default to iOS.
 
-### Pre-Commit Secret Detection
-
-A `PreToolUse` hook runs before every `git commit`, scanning staged files for:
-
-- Hardcoded API keys, tokens, secrets
-- AWS access keys (`AKIA...`)
-- Private keys (RSA/EC/DSA/OPENSSH)
-- `.env` files and credentials files
-- Firebase/GCP service account JSON
-
-If secrets are found, the commit is **blocked** with a clear message.
-
-### Context Management
-
-`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` triggers context compaction at 65% usage instead of the default ~80%. This prevents performance degradation in long 8-phase pipeline sessions.
-
-### Local CI (pre-push)
-
-**CI is local-only** via the `pre-push` git hook (no GitHub Actions).
-Run the full gate manually anytime, or wire the hook to run it on every `git push`:
-
-```bash
-# One-off check
-bash pipeline/scripts/pre-push-check.sh
-
-# Install as a git hook - runs automatically on `git push`
-ln -sf ../../pipeline/scripts/pre-push-check.sh .git/hooks/pre-push
-chmod +x .git/hooks/pre-push
-```
-
-Runs unit tests, smoke suites, eval fixtures, schema validation, and lint - the same gate that used to run in CI. Bypass only in emergencies with
-`git push --no-verify`.
-
-### Scripts
-
-| Script                 | Purpose                                          |
-| ---------------------- | ------------------------------------------------ |
-| `pre-commit-check.sh`  | Secret detection before commits                  |
-| `build-stack-plugins.mjs` | Rebuild stack plugins from `shared/external`, bump changed plugin versions |
-| `keychain-save.sh`     | Save tokens/JSON to macOS Keychain (interactive) |
-| `keychain.py`          | Deterministic Python Keychain helper (get/set/delete/list/doctor); shell driver auto-delegates on macOS/Linux |
-| `github-ssh-setup.sh`  | GitHub SSH key generation + config               |
-| `ui-tree-dumper.swift` | iOS accessibility tree dumper for audits         |
-
-All scripts are installed to `~/.claude/scripts/` during setup.
-
-## Platform Support
-
-| Tier      | Platform              | Requirements                                                |
-| --------- | --------------------- | ----------------------------------------------------------- |
-| Primary   | macOS 13+             | Keychain-backed token storage, `xcodebuild`, `xcrun simctl` |
-| Primary   | Linux (Ubuntu 22.04+) | Token storage via env vars / `gh auth`; no Xcode features   |
-| Secondary | Windows (WSL2)        | Same as Linux; Xcode features unavailable                   |
-
-Node.js 18+ required everywhere. Git 2.38+ (for `git worktree` improvements) recommended.
-
-## Testing
-
-```bash
-npm test
-```
-
-Runs **~1,300 assertions** across four layers:
-
-| Layer             | Count                          | What                                                     |
-| ----------------- | ------------------------------ | -------------------------------------------------------- |
-| Node unit tests   | 92 tests across 19 suites      | CLI routing, install helpers, settings.json hooks, security |
-| Smoke suites      | 73 scripts, ~1,210 assertions  | End-to-end contract tests for every script and phase doc |
-| Eval fixtures     | 11 adversarial cases + 2 golden tasks | Semantic regression for triage classification + full pipeline replay |
-| Schema validation | 13 schemas                     | Structural integrity of JSON schemas                     |
-
-CI runs locally via the `pre-push` git hook (see **Scripts** above) - no GitHub Actions. Enable the hook once per clone with `ln -sf ../../pipeline/scripts/pre-push-check.sh .git/hooks/pre-push`.
-
-## Key Features
-
-Ten highlights - see [`docs/features.md`](docs/features.md) for the full catalog.
+## Tool support
 
-1. **8-phase orchestration** with lazy-loaded phase specs - only pay token cost for the current phase.
-2. **CLI-aware parallel review + Opus triage** - Opus (security/architecture) + Sonnet (quality/correctness) run in parallel on Claude Code (2-model); Copilot CLI adds GPT-5.4 (edge cases/different perspective) for a 3-model set. A single Opus triage pass filters false-positives, rejects out-of-scope findings, and forwards only actionable items to Phase 3. Reviewer noise never auto-triggers rework.
-3. **Bitbucket / GitHub PR automation** with default reviewers auto-injected, draft/ready prompt, body preservation (no literal `\n`, no HTML entities).
-4. **`channels` command** posts task reports to Jira / Confluence / Wiki / PR with multi-select channel + content. Humanizer pass per-channel, reviewer-preserving Bitbucket PR PUT. Phase 7 delegates; also invocable post-hoc for fixes made outside the pipeline.
-5. **Deterministic safety gates + pre-commit local-checkout prompt + runtime triage validator**: pre-commit secret scan (PreToolUse hook), xcodebuild lock queue, 3-iteration hard-kill on retry loops, "checkout locally and test before commit?" Phase 6 prompt, and a zero-dep Node validator that gates Phase 4 triage output on real exit codes - no longer just markdown guidance. Includes telemetry (metrics.jsonl + aggregator - GPT-5.4 reviewer metric emitted only on Copilot CLI) and a sync-parity script that catches Claude↔Copilot↔repo drift before it ships.
-6. **Cross-session learning**: per-project knowledge base (architecture, patterns, gotchas) + user-level memory (feedback, project constraints, references).
-7. **Schema-validated state + smoke-tested contracts**: `schemas/*.schema.json` for `agent-state.json` and preferences; `scripts/smoke-channels-flow.sh` guards body-preservation + Bitbucket PUT contract + multi-channel dispatch.
-8. **Task Type Detection** - every task classified as component/bugfix/feature/refactor/chore at Phase 0 Step 9, used by every downstream phase for deterministic routing.
-9. **SubPhase progress tracking** for specialized workflows - component generation (figma-to-swiftui) reports nested SubPhases under the parent main phase instead of inflating the top-level phase count.
-10. **Interactive launchers**: `multi-agent-jira` lists your open Jira issues; `multi-agent-issue` lists unassigned GitHub issues. Pick one → choose branch → choose mode (full/--dev) → autopilot? → pipeline starts. GitHub issues are auto-assigned on selection.
+The pipeline runs natively on **Claude Code** and **Copilot CLI** — both install from the same `pipeline/skills/` source and get identical coverage.
 
-## What's Included
+| Tool | Flag | Notes |
+|---|---|---|
+| Claude Code | `--claude` (default) | slash commands + skills + agents + `PreToolUse` secret-scan hook |
+| Copilot CLI | `--copilot` | instructions + skills + scripts |
 
-```
-pipeline/
-  commands/
-    multi-agent.md              Main orchestrator
-    sim-test.md                 Mobile UI Bug Hunter
-    figma-to-swiftui.md         Figma -> SwiftUI component generator
-    deploy.md                   iOS deployment checklist
-    archive-guard.md            .xcarchive App Store compliance scan
-    security-review.md          Deep security audit
-    multi-agent/
-      help.md                   Usage guide
-      setup.md                  Token + identity + Jira key onboarding
-      status.md                 List all tasks
-      log.md                    Show task log
-      resume.md                 Resume stopped task
-      kill.md                   Delete task worktree
-      purge.md                  Full reset (double-confirm)
-      review.md                 Review current diff
-      channels.md               Multi-channel reporter (Jira/Confluence/Wiki/PR)
-      jira.md                   Interactive Jira picker
-      issue.md                  Interactive GitHub issue picker
-      dev.md                    Fast mode (Opus)
-      autopilot.md              Skip confirmations
-      dev-autopilot.md          Fastest path (dev + autopilot)
-      test.md                   UI Bug Hunter
-      search.md                 Full-text log search
-      scan.md                   Skill security scanner
-      refactor.md               Refactor planner
-      update.md                 Update pipeline
-      sync.md                   Sync ecosystem (Claude/Copilot/repo)
-      refs/
-        rules.md                Global non-negotiable rules
-        keychain.md             Token registry
-        knowledge.md            Project knowledge system
-        audit-guide.md          Audit tool integration rules
-        swiftui-guide.md        iOS component guide + compliance rules
-        android-guide.md        Android component guide + compliance rules
-        backend-guide.md        Backend API guide
-        frontend-guide.md       Frontend component guide
-        phases.md               Phase reference + ASCII flow diagram
-        phases/
-          phase-0-init.md       Project setup (8-step interactive)
-          phase-1-analysis.md   Stack detection + codebase exploration
-          phase-2-planning.md   Task decomposition + architecture review
-          phase-3-dev.md        TDD development + build queue
-          phase-4-review.md     Gates + code review + accessibility check
-          phase-5-test.md       User testing + device audits (on-demand)
-          phase-6-commit.md     Commit + PR (reviewers + draft prompt)
-          phase-7-report.md    External (Jira/Wiki/Confluence) + internal log + knowledge + memory
-          modes.md              Autopilot, --dev, --local
-          operations.md         Kill, resume, purge
-          log-format.md         Log file spec
-  skills/
-    shared/
-      core/                     22 orchestration skills (multi-agent-*) -                                 pipeline-critical; changes here affect pipeline
-                                behavior directly.
-      external/                 127 iOS/Android/generic guidance skills imported
-                                from upstream (mirrors of third-party skill sets
- - SwiftUI, Compose, Kotlin, Swift, web, backend,
-                                CI/CD, HIG, etc.).
-    figma-common/               Platform-agnostic Figma pipeline shared steps
-    figma-ios/                  Figma → SwiftUI component generator (iOS)
-    figma-android/              Figma → Jetpack Compose component generator (Android)
-  schemas/                      JSON Schemas
-    agent-state.schema.json     Validates $HOME/.claude/logs/.../agent-state.json
-    prefs.schema.json           Validates $HOME/.claude/multi-agent-preferences.json
-    triage-output.schema.json   Validates Phase 4 triage output
-    token-budget.json           Per-phase token limits + warn thresholds
-  agents/
-    code-reviewer.md            Phase 4 reviewer (CLI-aware: 2-model Claude / 3-model Copilot + Opus triage)
-    explorer.md                 Phase 1 codebase scanner
-    ios-architect.md            iOS architecture review
-    android-architect.md        Android architecture review
-    backend-architect.md        Backend/API architecture review
-    security-auditor.md         Security audit (OWASP)
-  rules/
-    code-style.md               Naming, structure, patterns
-    git-conventions.md          Commit messages, branching
-    testing.md                  Test naming, structure, coverage
-    tdd.md                      Red-Green-Refactor, testing pyramid
-    code-review.md              Review priority, severity, checklist
-    security.md                 Keychain, ATS, credentials, privacy
-    performance.md              Bottlenecks, caching strategy
-    debugging.md                Scientific debugging method
-    app-store-guidelines.md     App Store Review Guidelines
-    figma-pipeline.md           Figma -> SwiftUI generation rules
-    swiftui-qa.md               3-layer test strategy, 13-item checklist
-    kotlin-android.md           Kotlin & Android conventions
-  eval/
-    triage/
-      01-10/                    10 adversarial eval fixtures
-  scripts/
-    pre-commit-check.sh         Secret detection hook
-    build-stack-plugins.mjs     Rebuild stack plugins + version bump
-    keychain-save.sh            Save tokens/JSON to macOS Keychain
-    github-ssh-setup.sh         GitHub SSH key generation + setup
-    ui-tree-dumper.swift        iOS accessibility tree dumper
-    eval-triage.mjs             Eval runner for triage fixtures
-    validate-triage.mjs         Runtime triage validator
-    validate-schemas.mjs        Zero-dep shallow validator for *.schema.json
-    aggregate-metrics.mjs       Telemetry aggregator
-    log-metric.sh               Telemetry metric logger
-    phase-banner.sh             Phase banner UI renderer
-    phase-tracker.sh            Phase progress tracker
-    sync-parity-check.sh        Claude↔Copilot↔repo parity checker
-    smoke-*.sh                  Contract smoke tests (10 suites, 115 assertions)
-  claude-md-template.md         CLAUDE.md starter template
-  preferences-template.json     Empty config template
-
-docs/
-  features.md                   Full feature catalog
-  adr/                          Architecture Decision Records (0001+)
-
-CHANGELOG.md                    Version history
-docs/architecture.md            Mermaid diagrams: pipeline flow, modes, components
-docs/best-practices.md          Competitor-informed patterns and pipeline rules
-SECURITY.md                     Vulnerability reporting policy
-```
+Filter skills by stack with `--platform=ios\|android\|all`.
 
-## Ecosystem Sync
+## Setup notes
 
-The pipeline maintains consistency across multiple repositories and CLI targets:
+- **Tokens** stay in the OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret) and are never committed or logged. `setup` maps them into `~/.claude/multi-agent-preferences.json`.
+- **Secret scan** runs as a `PreToolUse` hook on Claude Code (hard-blocks a commit on a hit) and as a pre-push check elsewhere.
+- **All tokens are optional** — the pipeline asks for any it needs at Phase 0.
 
-```bash
-# Claude Code                              # Copilot CLI
-/multi-agent:sync                           # multi-agent-sync
-/multi-agent:sync status                    # multi-agent-sync status
-/multi-agent:sync to-copilot                # multi-agent-sync to-copilot
-/multi-agent:sync to-repo                   # multi-agent-sync to-repo
-/multi-agent:sync release                   # multi-agent-sync release
-```
+## Companion repos
 
-| Target             | What syncs                                           |
-| ------------------ | ---------------------------------------------------- |
-| **Claude Code**    | Source of truth - commands, agents, scripts          |
-| **Copilot CLI**    | Summary mirror + 206 unified skills + scripts |
-| **Pipeline Repo**  | Genericized open-source version (no personal data)   |
-| **Website**        | Version, phase/model counts, feature strings (EN+TR) |
-| **Remote Control** | Pipeline feature references                          |
+| Repo | What it is |
+|---|---|
+| [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) | Marketplace of per-stack skill toolkits (iOS / Android / Frontend / Backend + common). `/multi-agent:stack` enables the matching plugin. |
+| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild — powers the Phase 5 UI Bug Hunter. `npx @mmerterden/dev-toolkit-mcp` |
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE). Security issues: see [SECURITY.md](./SECURITY.md) (do not open public issues for vulnerabilities).