Start

BEADS Multi-Agent Orchestration Skill

This skill coordinates a swarm of specialized AI agents to autonomously handle GitHub Issues from creation to merged PR.

---

Quick Start

Start Work on a GitHub Issue

# User triggers via any of:
@beads start #123
bd start 123
/beads-start 123

Check BEADS Status

bd ready          # Show tasks ready to work
bd list           # Show all tasks
bd stats          # Show project statistics
bd doctor         # Check system health

---

Agent Roster

| Agent | Role | Spawned When | | ------------------------- | ------------------------------ | ---------------------------------- | | Issue Orchestrator | Main coordinator per Issue | Issue receives agent-ready label | | Researcher Agent | Codebase exploration | Orchestrator creates research task | | Architect Agent | Implementation planning | Research complete | | Product Manager Agent | Use case & user benefit review | Design review gate (parallel) | | Designer Agent | UX/API design review | Design review gate (parallel) | | Security Design Agent | Security threat modeling | Design review gate (parallel) | | CTO Agent | TDD readiness & plan review | Design review gate (parallel) | | Coder Agent | TDD implementation | Design review gate approved | | Code Review Agent | Internal code review | Implementation complete | | Security Auditor | Security review (code) | Implementation complete | | Release Engineer Agent | Safe delivery from merge through production | QA approves PR, PR reaches merge readiness | | PR Shepherd | PR lifecycle management | PR created |

See ./agents/ directory for detailed agent definitions.

---

Design Review Gate (NEW)

For complex features created via brainstorming, an automatic Design Review Gate ensures quality before implementation:

Design Document Created
        │
        ▼
┌─────────────────────────────────────────────────┐
│           DESIGN REVIEW GATE                     │
│                                                  │
│  Spawns in PARALLEL:                            │
│  • Architect Agent (technical architecture)     │
│  • Designer Agent (UX/API design)               │
│  • UX Reviewer (user flows, integration WUs)    │
│  • CTO Agent (TDD readiness)                    │
│                                                  │
│  ALL must approve to proceed                    │
└─────────────────────────────────────────────────┘
        │
        ├── Any NEEDS_REVISION? → Iterate on design (max 3x)
        │
       ALL APPROVED
        │
        ▼
   Create BEADS Epic → Begin Implementation

Triggering the Design Review Gate

The gate is automatically triggered when:

• superpowers:brainstorming completes and commits a design doc
• User runs /review-design

Review Criteria by Agent

| Agent | Focus Areas | | --------------- | ---------------------------------------------------------- | | Product Manager | Use case clarity, user benefits, scope, success metrics | | Architect | Service architecture, dependencies, patterns, integration | | Designer | API design, UX flows, developer experience, consistency | | Security Design | Threat modeling, auth/authz, data protection, OWASP Top 10 | | UX Reviewer | User flows, text wireframes, integration WUs, empty/error states | | CTO | TDD readiness, codebase alignment, completeness, risks |

Iteration Protocol

• Max 3 iterations before human escalation
• Each iteration: revise design → re-run all reviewers
• Escalation options: Override / Defer / Cancel

See the design-review-gate skill for full details.

---

Team Mode Coordination

When multiple Claude Code sessions are active on the same repository (e.g., parallel worktrees), metaswarm automatically enters Team Mode. In Team Mode, agents behave as persistent teammates with context retention across sessions and direct inter-agent messaging for coordination. Mode detection is automatic based on the presence of concurrent sessions.

For the full Team Mode protocol — including message routing, context sharing, and conflict resolution — see ./guides/agent-coordination.md.

---

Plan Review Gate

After the Architect creates an implementation plan and before it reaches the Design Review Gate, the plan passes through the Plan Review Gate. Three adversarial reviewers validate the plan independently:

| Reviewer | Focus | | --- | --- | | Feasibility | Technical viability, dependency risks, resource constraints | | Completeness | Missing work units, untested edge cases, gaps in Definition of Done | | Scope & Alignment | Plan stays within issue scope, aligns with codebase conventions |

All 3 must APPROVE before the plan proceeds. See the plan-review-gate skill for the full skill definition.

---

Orchestrated Execution

After design review approval, implementation follows the 4-phase execution loop per work unit. This replaces the previous linear "implement then review" flow with rigorous independent validation and adversarial review.

Core Principle

Trust nothing. Verify everything. Review adversarially.

Plan Validation (Pre-Flight)

Before submitting to the Design Review Gate, the orchestrator runs a pre-flight checklist covering architecture, dependency graph, API contracts, security, UI/UX, and external dependencies. This catches structural issues (missing service layer, wrong dependency graph, oversized WUs) before spending agent cycles on review.

The 4-Phase Loop

For each work unit (a discrete, spec-driven change with DoD items):

1. IMPLEMENT — Coding subagent executes against the spec using TDD, with the Project Context Document
2. VALIDATE — Orchestrator independently runs quality gates (tsc, eslint, vitest, coverage enforcement from .coverage-thresholds.json). Never trust subagent self-reports. Quality gates are blocking state transitions, not advisory.
3. ADVERSARIAL REVIEW — Fresh review subagent checks against spec contract. Binary PASS/FAIL with file:line evidence. Uses adversarial-review-rubric.md. When external tools are configured, cross-model review ensures the writer is always reviewed by a different AI model (see External Tools section below).
4. COMMIT — Only after adversarial PASS. Updates SERVICE-INVENTORY.md and Project Context Document.

On FAIL: fix → re-validate → spawn fresh reviewer (max 3 retries → escalate to human). There is NO path from FAIL to COMMIT without passing through the retry loop.

When to Use Orchestrated Execution

• The task has a written spec with enumerable Definition of Done items
• The implementation involves multiple work units (3+ logical changes)
• You need independent verification — subagent self-reports aren't sufficient
• The changes are high-stakes (schema changes, security, new architectural patterns)
• You want proactive human checkpoints at planned review points

When NOT to Use It

• Single-file bug fixes or copy changes
• Tasks without a written spec or DoD items
• Quick prototyping or exploratory work
• Tasks where the overhead of decomposition exceeds the work itself

For simple tasks, the standard linear flow (implement → code review → PR) works fine.

Key Concepts

Work Unit Decomposition: Break the implementation plan into discrete work units, each with:

• A spec section and enumerated DoD items
• A declared file scope (which files it may modify)
• Dependencies on other work units
• An optional human checkpoint flag

Independent Validation: The orchestrator runs tsc, eslint, and vitest directly — it does NOT ask the coding subagent "did the tests pass?" and accept the answer.

Adversarial Review: Fundamentally different from collaborative code review. The reviewer is an independent auditor checking spec compliance, not a helpful colleague suggesting improvements. Binary PASS/FAIL verdict. Evidence required (file:line references).

Fresh Reviewer Rule: On re-review after FAIL, a NEW reviewer instance is spawned with no memory of the previous review. This prevents anchoring bias.

Human Checkpoints: Planned pauses at critical boundaries (schema changes, security code, first use of new patterns). The orchestrator waits for explicit human approval before continuing.

Final Comprehensive Review: After all work units pass, a cross-unit review catches integration issues that per-unit reviews miss.

See orchestrated-execution skill for the complete pattern, including work unit structure, parallel execution, recovery protocol, and anti-patterns.

---

External AI Tools (Optional)

When external AI CLI tools are configured (.metaswarm/external-tools.yaml), the orchestrator can delegate implementation and review tasks to OpenAI Codex CLI and Google Gemini CLI. This enables cost savings through cheaper models and cross-model adversarial review that eliminates single-model blind spots.

How It Integrates

External tools slot directly into the existing 4-phase execution loop:

• Phase 1 (IMPLEMENT): The orchestrator may delegate to an external tool instead of spawning a Claude subagent. The tool works in an isolated git worktree.
• Phase 2 (VALIDATE): Unchanged — the orchestrator independently runs all quality gates regardless of who implemented.
• Phase 3 (ADVERSARIAL REVIEW): Cross-model review — the writer is always reviewed by a different model (e.g., Codex writes, Gemini + Claude review).
• Phase 4 (COMMIT): Unchanged — merge worktree branch after all phases pass.

Escalation Chain

The orchestrator adapts based on tool availability:

| Available Tools | Escalation Chain | Max Attempts | |---|---|---| | Both Codex + Gemini | A(2) → B(2) → Claude(1) → user | 5 | | One tool only | Tool(2) → Claude(1) → user | 3 | | No tools | Claude → user (existing behavior) | unchanged |

Each escalated model receives the previous model's branch as a reference. See the external-tools skill for the full skill definition.

Health Check

/external-tools-health

Checks installation, authentication, and reachability of all configured adapters.

---

Visual Review

The visual-review skill enables agents to take screenshots of web pages, presentations, and UIs using Playwright for visual inspection. This bridges the gap where agents cannot see rendered output.

Usage

The skill is triggered when tasks involve visual output (web UIs, Reveal.js presentations, landing pages, email templates). It captures screenshots at configurable viewport sizes, and agents analyze them for layout, typography, colors, spacing, and content issues.

Prerequisites

npx playwright install chromium

For remote/headless environments, the skill serves screenshots via HTTP file server so users can view them in their local browser.

See the visual-review skill for the complete workflow.

---

Workflow Overview

GitHub Issue #123 (agent-ready label)
        │
        ▼
┌─────────────────────────────────────┐
│       Issue Orchestrator             │
│  Creates BEADS epic, delegates work  │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Research Phase                 │
│  Researcher Agent explores codebase  │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Planning Phase                 │
│  Architect Agent creates plan        │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Plan Review Gate               │
│  3 adversarial reviewers:            │
│  Feasibility, Completeness,         │
│  Scope & Alignment                   │
│  ALL 3 must approve                  │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│   External Dependency Detection      │
│   Scans spec for API keys/creds     │
│   Prompts user to configure them    │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│   Plan Validation (Pre-Flight)       │
│   Architecture, deps, API contracts  │
│   Security, UI/UX, external deps    │
└─────────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                    DESIGN REVIEW GATE (PARALLEL)                          │
│                                                                           │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌───────┐ │
│  │   PM    │ │ Architect│ │ Designer │ │ Security │ │UX Revw.│ │  CTO  │ │
│  │(users)  │ │  (tech)  │ │ (UX/API) │ │ (threats)│ │(flows) │ │ (TDD) │ │
│  └─────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ └───────┘ │
│                                                                           │
│  ALL SIX must approve (max 3 iterations)                                  │
└──────────────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Work Unit Decomposition        │
│  Break plan into work units w/ DoD   │
│  Build dependency graph              │
└─────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────────────────────────────┐
│           ORCHESTRATED EXECUTION LOOP (per work unit)          │
│                                                                │
│   ┌──────────┐    ┌──────────┐    ┌──────────────┐   ┌──────┐ │
│   │IMPLEMENT │───→│ VALIDATE │───→│  ADVERSARIAL │──→│COMMIT│ │
│   │(Coder)   │    │(Orchest.)│    │   REVIEW     │   │      │ │
│   └──────────┘    └──────────┘    └──────┬───────┘   └──────┘ │
│        ▲                                 │ FAIL                │
│        └─────────────────────────────────┘                     │
│                                                                │
│   Trust nothing. Verify everything. Review adversarially.      │
└───────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│   Final Comprehensive Review         │
│   Cross-unit integration check       │
│   Full test suite + type check       │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│   PR Creation (Auto-Shepherd)        │
│   bin/create-pr-with-shepherd.sh     │
│   → Auto-invokes pr-shepherd skill   │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       PR Shepherd (Automatic)        │
│  Monitors CI, handles reviews,       │
│  resolves threads automatically      │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Human Approval & Merge         │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Release Engineer                │
│  Pre-merge verify → merge → CI →     │
│  deploy → post-deploy QA → release   │
└─────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Close Epic & Extract Learnings │
└─────────────────────────────────────┘

GTG (Good-To-Go) Merge Gate

GTG is the final merge gate. It consolidates CI status, comment classification, and thread resolution into a single deterministic check. Agents should use it as the primary readiness signal:

# Check if PR is ready to merge
gtg

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dsifry](https://github.com/dsifry)
- **Source:** [dsifry/metaswarm](https://github.com/dsifry/metaswarm)
- **License:** MIT

Install and usage instructions live in the source repository linked above.