# @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-20%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)

🇹🇷 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 `multi-agent-toolkit-mcp` compose.

### Prerequisites

- **Node.js >= 20.11** - required; the pipeline's own tooling runs on it.
- **`jq`** - optional but recommended. Thirteen shell helpers reach for it and skip in silence without it: cost summaries, the phase tracker's JSON reads, convention extraction, skill signing. The install prints a note when it is missing.
- **`gh`** - for GitHub issue and PR work. Its built-in `--jq` is independent of the `jq` binary.

## Quick Start

```bash
# from the public registry (no auth) - pick the CLIs you actually use
npx @mmerterden/multi-agent-pipeline install --claude    # Claude Code only (default)
npx @mmerterden/multi-agent-pipeline install --copilot   # Copilot CLI only
npx @mmerterden/multi-agent-pipeline install --codex     # Codex CLI only
npx @mmerterden/multi-agent-pipeline install --all       # all three

# then, once:
/multi-agent:setup          # keychain token scan + git identity + default stack
```

Tool flags combine (`--claude --codex`). With no tool flag at all, the installer targets Claude Code only. Other flags: `--dry-run` (show what would be written, write nothing), `--platform=ios|android|all` (skip the stack skills you do not need), `--link` (symlink instead of copy, for local development).

Run a task - the input type is auto-detected:

```bash
/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
```

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.

Add `autopilot` to skip confirmations, or `--local` to work on the current branch without a worktree (e.g. `/multi-agent:autopilot "PROJ-1234"`). Pipeline depth is a question the run asks, not a flag: `/multi-agent` and `/multi-agent:local` offer Full or Short at Phase 0.

Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx @mmerterden/multi-agent-pipeline uninstall`.

**Stack skills are marketplace plugins.** On Claude Code the `ai-<stack>-toolkit` plugins (`multi-agent-plugins` marketplace) are the only stack-skill source - nothing is copied into `~/.claude/skills`. Pick the active stack(s) per repo with `/multi-agent:stack` (multi-select: `ios backend`, or a native picker with no args); each plugin ships a language-aware catalog at `ai-<stack>-toolkit:help`. Copilot CLI and Codex CLI have no plugin loader, so they receive a local copy filtered to the same enabled stacks.

## How it works

One command runs 8 phases, with a gate between the risky ones:

- **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 (Sonnet).
- **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 3 models (Fable + Opus + 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.

`/multi-agent:analysis` runs its own shorter chain and, since v16.12.0, reviews what it wrote before publishing it: the draft goes through the same three-reviewer set and triage as a code diff, a blocking finding returns it to synthesis with dispatch closed, and the gaps that survive are either searched, asked about, or recorded with an owner. It used to publish behind a structural validator alone.

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). How this repo, the `multi-agent-plugins` marketplace, and the `multi-agent-toolkit-mcp` server compose at install time and at run time is diagrammed in [docs/ecosystem.md](./docs/ecosystem.md).

## Modes

| Mode | Command | Flow |
|---|---|---|
| Full | `/multi-agent "task"` | All 8 phases, interactive |
| Autopilot | `/multi-agent:autopilot "task"` | 7 phases (interactive Test gate dropped), no confirmations |
| Local | `/multi-agent:local "task"` | Full pipeline minus the interactive Test gate, current branch (no worktree) |
| Depth | asked at Phase 0 Step 7.5 | Full (all phases) or Short (Dev → Review → Test → Commit → Report). Not a command name  -  `/multi-agent` and `:local` ask, both autopilot entries always run Full |
| Ship | `/multi-agent:resume-local` | Run the review→test→commit→report tail over local work |
| 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 |

Depth, autopilot and `--local` are the only knobs on the run itself; everything else is its own command. The full catalog is below.

## Commands

`/multi-agent` plus 53 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.

### Pipeline entries

| Command | What it does |
|---|---|
| `/multi-agent "task"` | Full pipeline in a worktree. Asks Full or Short depth at Phase 0 |
| `/multi-agent:local "task"` | Same pipeline on the current branch, no worktree |
| `/multi-agent:autopilot "task"` | Worktree, no confirmations, always Full |
| `/multi-agent:local-autopilot "task"` | Current branch, no confirmations, always Full |
| `/multi-agent:resume-local` | Pipeline tail over work already done locally: Review → Build+Test → Commit/PR → Report. No dev phase |

### Task control

| Command | What it does |
|---|---|
| `/multi-agent:status` | Every task's ID, phase, branch and state |
| `/multi-agent:log [#N]` | Show a task's `agent-log.md` (most recent by default) |
| `/multi-agent:resume [#N]` | Carry a stopped or failed task on from its last phase |
| `/multi-agent:kill [#N]` | Stop a task, remove its worktree and branch |
| `/multi-agent:steer #N "<instruction>"` | Correct a running task without stopping it; applied at the next phase boundary |
| `/multi-agent:search` | Ranked search across every task log; `--semantic` queries the triage corpus |
| `/multi-agent:garbage-collect` | Sweep leftover scratch, orphan worktrees and offloaded payloads. Dry-run first |
| `/multi-agent:prune-logs` | Delete per-task logs by age / project / task. Audit trail and metrics kept |
| `/multi-agent:purge` | Wipe every worktree, branch, log and state file. Double confirmation |

### Review

| Command | What it does |
|---|---|
| `/multi-agent:review` | Parallel review of a branch diff or a PR; inline comments + approve/needs-work on PR input |
| `/multi-agent:review-jira` | Grade a Jira issue's readiness for development, comment the gaps |
| `/multi-agent:review-issue` | Same grading for a GitHub issue |
| `/multi-agent:review-analysis` | Review a written analysis document; findings cite the Locked rule they break |
| `/multi-agent:diff-explain` | Map a Phase 4 triage finding back to the diff lines that caused it |
| `/multi-agent:refactor` | Best-practice extraction + bug hunt + derived-skill drift + toolkit MCP research → one plan |
| `/multi-agent:scan` | Skill security scan of local skill directories against a tiered pattern catalog |
| `/multi-agent:prune-prompts` | Zero-base review of the always-on instruction footprint; keep / trial / delete per rule |
| `/multi-agent:ios-coding-standard` | Audit an iOS module against the 99-rule registry, produce a remediation plan |

### Analysis

| Command | What it does |
|---|---|
| `/multi-agent:analysis` | Standalone feature spec: global (23-section handoff) or corporate (IG/UC/FG) profile |
| `/multi-agent:analysis-resolve` | Answer an analysis doc's Section 20 open questions one row at a time |
| `/multi-agent:complaint-analysis` | Customer-complaint triage with Graylog evidence: client / bff root cause, or core routing |

### Testing on a device

| Command | What it does |
|---|---|
| `/multi-agent:test` | UI Bug Hunter on a booted simulator or emulator: screenshot, tap, analyze |
| `/multi-agent:test-dark-mode` | Walk every screen light then dark, report contrast and colour bugs |
| `/multi-agent:test-accessibility` | VoiceOver labels, sub-44pt tap targets, contrast, traits |
| `/multi-agent:test-dynamic-type` | Re-walk every screen at XL through accessibility-XL, report truncation |
| `/multi-agent:test-screenshots [locale]` | App Store screenshot set in a locale (defaults to `tr`) |
| `/multi-agent:manual-test` | Phase 5 standalone: check out the task branch and prepare it for Xcode |

### Design, build and store

| Command | What it does |
|---|---|
| `/multi-agent:design-check` | Mock-mode vs Figma audit with a coverage gate; annotated HTML + PDF report |
| `/multi-agent:store-ready` | Pre-submission gates for iOS and Android: package audit, store validation, policy review |
| `/multi-agent:testflight-validation` | iOS-pinned alias of `store-ready`. Validates only, never uploads |
| `/multi-agent:build-optimize` | Benchmark an Xcode build, run the analyzers, produce a recommend-first plan |

### Tickets and reporting

| Command | What it does |
|---|---|
| `/multi-agent:jira` | Browse your open Jira issues → pick → branch → mode → launch |
| `/multi-agent:issue` | Browse unassigned GitHub issues → pick → auto-assign → launch |
| `/multi-agent:create-jira` | Draft a Task / Bug / Story to the project's own conventions, preview before create |
| `/multi-agent:channels` | Post the multi-channel report: Jira, Confluence, Wiki, PR description, board status |
| `/multi-agent:feedback` | Send one message to the maintainer. Only your text is sent, no logs or paths |

### Your own routines

| Command | What it does |
|---|---|
| `/multi-agent:save [name]` | Save a recurring job as a reusable `/multi-agent:<name>`. Local-only, never synced |
| `/multi-agent:routines` | List your saved routines and what each does |
| `/multi-agent:forget [name]` | Remove a saved routine and its registry entry |

### Setup and maintenance

| Command | What it does |
|---|---|
| `/multi-agent:setup` | First-run wizard: keychain token discovery, git identity, pipeline preparation |
| `/multi-agent:stack [ids]` | Enable the marketplace plugin(s) for this repo. Multi-select |
| `/multi-agent:language [en\|tr]` | Show or set `outputLanguage`; `promptLanguage` stays English |
| `/multi-agent:sync` | One-shot sync: Claude Code, Copilot CLI, pipeline repo, website, toolkit MCP |
| `/multi-agent:update` | Update to the latest published npm release and run migrations |
| `/multi-agent:uninstall` | Remove the pipeline from every CLI. Keychain tokens always left intact |
| `/multi-agent:help` | This catalog, in the terminal, in your `outputLanguage` |

### Subagents

Eight are installed alongside the commands and dispatched by the phases: `explorer` and `task-clarifier` (Phase 0-1), `ios-architect` / `android-architect` / `backend-architect` (Phase 2), `dev-critic` (Phase 3), `code-reviewer` and `security-auditor` (Phase 4).

### Skills that are not commands

Two compliance skills install on every host and back the store gates: `apple-archive-compliance` (18-rule Apple review scan with ITMS code mapping) and `google-play-compliance` (21-rule Play policy catalog with Console error codes). Everything else stack-shaped - SwiftUI, Compose, backend, frontend - comes from the marketplace plugins described below.

## Stacks

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
/multi-agent:stack ios        # or android / frontend / backend / mobile / all
```

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.

## 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 53 commands.

| Tool | Flag | What it installs |
|---|---|---|
| Claude Code | `--claude` (default) | slash commands + skills + agents + three `PreToolUse` hooks (secret scan, agent-guard, read-size gate) |
| Copilot CLI | `--copilot` | instructions + 53 sub-command skills + scripts |
| Codex CLI | `--codex` | one router skill + 53 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 51.** 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
`multi-agent` router and keeps the sub-command specs as reference files that cost
nothing until read - same commands, same behaviour, a layout the host can actually hold.

Reviewer sets differ because the available models do: Claude Code runs 3 reviewers
(Fable + Opus + Sonnet), Copilot CLI 3 (Opus + GPT-5.4 + Sonnet), Codex CLI 3 (gpt-5.6 at
xhigh, gpt-5.4, gpt-5.6 at medium). Claude Code and Codex are single-vendor panels, so
consensus among their three is weaker evidence than the same consensus on Copilot CLI,
the one host whose panel spans two vendors, and the triage note says so.

## Tokens & integrations

`setup` scans your OS keychain and maps each token by a **logical name** (e.g. `jira`) to its real keychain entry - the pipeline resolves tokens through that mapping (`credential-store.sh`), so literal keychain names never appear in synced files. Tokens stay in the keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), are **never committed or logged**, and are all **optional** - the pipeline asks for any it needs at Phase 0.

| Token | Used for | Phase |
|---|---|---|
| `jira` | fetch the issue · post the report comment | 0, 7 |
| `github` | issues · PRs · `gh` auth | 0, 6 |
| `bitbucket` | PR create/update (reviewer-preserving) · diff | 6 |
| `confluence` | publish analysis / wiki pages | 7 |
| `figma` + `figma_mcp` | fetch design context | analysis only |
| `fortify` | security-scan findings gate | 4 |
| `firebase` | Firebase service-account JSON for Firebase projects | as needed |
| `jenkins` | CI trigger / status | build / deploy |
| `npm` | package publish (mostly CI) | release |
| `appstore_connect_*` | TestFlight / App Store pre-submission validation (optional, iOS) | `testflight-validation` |

The **secret scan** runs as a `PreToolUse` hook on Claude Code (hard-blocks a commit on a hit) and as a pre-push check elsewhere.

## Outside a pipeline run

Installing the pipeline is not only useful when you run it. Open an ordinary session and the same three things are available, announced by `rules/outside-the-pipeline.md` which loads with every conversation:

- **Services you already onboarded.** The token `setup` mapped is readable now - resolve the logical name through `credential-store.sh` and fetch the issue, the page, the log. **Reads are ordinary work; writes are not.** Posting a Jira comment, editing an issue or opening a PR goes through the pipeline commands, because the rules that make those safe (never auto-close, `Ref:` not `Closes:`, humanizer on outward prose) live there.
- **The stack skills `/multi-agent:stack` enabled for the repo.** Each toolkit's own `index` skill routes; the pipeline keeps no copy of that table.
- **The `multi-agent-toolkit` MCP.** 80+ tools for a running app - screen state, crash logs, design comparison, store pre-submission.

Uninstall preserves this layer: the tokens, the reader that opens them, the mapping that names them, and the MCP registration. Removing the pipeline should not cost you the credentials you onboarded through it.

## Platform support

Runs on **macOS**, **Linux**, and **Windows** (Git Bash / WSL). Shell and credential access go through a platform-agnostic layer - the keychain resolves automatically to **macOS Keychain**, **Linux libsecret** (`secret-tool`), or **Windows Credential Manager**, and scripts fall back between BSD and GNU tool variants. Node.js 20.11+ (tested on 20 and 22).

## Companion repos

| 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/multi-agent-toolkit-mcp`](https://github.com/mmerterden/multi-agent-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild - powers the Phase 5 UI Bug Hunter. Published on the public npm registry as [`@mmerterden/multi-agent-toolkit-mcp`](https://www.npmjs.com/package/@mmerterden/multi-agent-toolkit-mcp); the installer registers it with each CLI for you, so `npx` resolves it with no extra configuration. |

## License

MIT - see [LICENSE](./LICENSE). Security issues: see [SECURITY.md](./SECURITY.md) (do not open public issues for vulnerabilities).