# multiagent-template

> Orchestrate teams of AI coding agents in a structured pipeline (PLAN → BUILD → TEST → VERIFY → SHIP). Unlike single-agent tools, multiagent-template prevents context collapse and ensures accountability via role separation and approval gates. Works with 13 providers: Claude, Gemini, Codex, Cursor, Windsurf, Cline, Aider, Continue, Roo, Qwen, Copilot, Nessy, Kiro.

## The Problem

Single-agent code generation fails at scale: context collapse, no accountability, inconsistent quality. One agent can't architect, develop, review, and ship autonomously without degrading.

## The Solution

A structured workspace where specialized agents (architect, developer, reviewer, DevOps) operate in a gated five-step pipeline — `PLAN → BUILD → TEST → VERIFY → SHIP` — with defined roles and handoff points. Each step has an approval gate; failures auto-retry before escalating to the human.

## Project

- [GitHub Repository](https://github.com/Neftedollar/multiagent-template): Source code, templates, and CLI tool
- [NuGet Package](https://www.nuget.org/packages/multiagent-setup): Install via `dotnet tool install -g multiagent-setup`
- [Landing Page](https://neftedollar.com/multiagent-template/): Overview and quick start
- [Russian README](https://github.com/Neftedollar/multiagent-template/blob/main/README_RU.md): Русская версия

## Install

```bash
# macOS / Linux — Homebrew (no .NET required)
brew install Neftedollar/multiagent-template/multiagent-setup

# One-liner bootstrap (installs all dependencies including .NET / Homebrew)
curl -fsSL https://raw.githubusercontent.com/Neftedollar/multiagent-template/main/bootstrap.sh | bash -s -- MyProject

# NuGet (requires git, gh, jq, .NET 10)
dotnet tool install -g multiagent-setup
multiagent-setup new MyProject
```

## Supported AI Coding Agents

### Terminal agents
- **Claude** (`claude`) — Claude Code by Anthropic, default provider
- **Nessy** (`nessy`) — Claude-compatible agent, reuses `.claude/` config
- **Gemini** (`gemini`) — Gemini CLI by Google
- **Codex** (`codex`) — OpenAI Codex CLI
- **Qwen** (`qwen-code`) — Qwen Code by Alibaba

### IDE agents
- **Cursor** (`cursor`) — Cursor IDE; rules injected via `.cursor/rules/` (MDC format)
- **Windsurf** (`windsurf`) — Windsurf IDE by Codeium; rules via `.windsurf/rules/`
- **Copilot** (`copilot`) — GitHub Copilot in VS Code; instructions via `.github/copilot-instructions.md`
- **Cline** (`cline`) — Cline VS Code extension; rules via `.clinerules`
- **Aider** (`aider`) — Aider AI pair programmer; config via `.aider.conf.yml` (auto-reads CLAUDE.md)
- **Continue.dev** (`continue`) — VS Code/JetBrains extension; config via `.continue/config.yaml` with `/orchestrator` slash command
- **Roo Code** (`roo`) — Roo Code VS Code extension; rules auto-loaded from `.roo/rules/`
- **Amazon Kiro** (`kiro`) — Kiro VS Code extension (AWS); steering docs auto-loaded from `.kiro/steering/`

Use `--provider all` to scaffold all providers at once, `add-provider <name>` (or `add-provider all`) to add providers to an existing workspace, `remove-provider <name>` to remove one, `list-providers` to see installed vs. available, or `update` to pull the latest templates into an existing workspace.

## Key Concepts

### Pipeline
The orchestrator runs a 5-step pipeline: `PLAN → BUILD → TEST → VERIFY → SHIP`. Each step ends with a gate (APPROVED / NEEDS WORK). Failed gates trigger automatic retries with helper agents before escalating to the human.

### Agent Roles
Specialized slash commands sourced from [agency-agents](https://github.com/msitarzewski/agency-agents). Key roles: `/orchestrator`, `/engineering-software-architect`, `/engineering-backend-architect`, `/engineering-frontend-developer`, `/engineering-code-reviewer`, `/product-manager`, `/engineering-security-engineer`, `/design-ux-researcher`.

### Hook System
All safety hooks are baked into the `multiagent-setup` binary (cross-platform, no shell scripts):
- `block-dangerous` — blocks destructive commands
- `enforce-commit-msg` — enforces conventional commits
- `auto-lint` — runs formatter after file edits
- `stop-guard` — reminds agents to run tests and persist knowledge
- `research-reminder` — reminds to store research findings

### Infrastructure (optional)
- **AGE graph** — PostgreSQL + Apache AGE knowledge base for modules, pipelines, role bindings, security findings
- **O'Brien** — pgvector semantic memory for agent coordination and recall

## CLI Reference

```
multiagent-setup new <project> [org] [--provider <name>] [--template default|saas|oss|internal]
multiagent-setup init [dir] [--provider <name>] [--template <name>] [--force]
multiagent-setup add-provider <provider>|all [--force]
multiagent-setup remove-provider <provider> [--force] [--dry-run]
multiagent-setup list-providers
multiagent-setup update [--force] [--dry-run]
multiagent-setup sync-roles [--clone|--pull] [--global] [--agency-dir <path>]
multiagent-setup install-mcps [--docker|--manual] [--age-conn <str>] [--obrien-conn <str>] [--target <dir>]
multiagent-setup hook <name>
multiagent-setup doctor [--for sync-roles|init|update]
multiagent-setup completions zsh|pwsh
```

## Source Structure

- `tools/setup-cli/` — .NET CLI source (C#, .NET 10)
- `tools/setup-cli/Templates/` — embedded workspace templates
- `tools/setup-cli/Templates/providers/` — provider-specific configs (codex, qwen, cursor, windsurf, copilot, gemini, cline, aider, continue, roo, kiro)
- `tools/setup-cli/Templates/.claude/` — Claude/Nessy config templates
- `tools/setup-cli/Templates/docs/` — process.md, role-capabilities.md, workflow specs

## License

MIT — free for commercial and personal use.