/start

name: start
description: Use when starting work on any task, when the user mentions metaswarm, or when the user wants to begin tracked development work
auto_activate: true
triggers:
  - "work on issue"
  - "start issue"
  - "start task"
  - "use metaswarm"
  - "@metaswarm"
  - "agent-ready label"

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 <path-to-design.md>`

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