# @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 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.

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 |

Helpers: `setup`, `status`, `resume #N`, `kill #N`, `garbage-collect`, `prune-logs`, `purge`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `review-analysis`, `feedback`, `create-jira`, `save`, `routines`, `forget`. 53 commands in all  -  full list: `/multi-agent:help`.

## 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 + `PreToolUse` secret-scan hook |
| 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 2 reviewers
(Fable + 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). Codex is single-vendor, so consensus among its three
is weaker evidence than the same consensus on a two-vendor host, 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 config (base64 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.** 83 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).