metaswarm

metaswarm

A self-improving multi-agent orchestration framework for Claude Code, Gemini CLI, and Codex CLI. Coordinate 18 specialized AI agents and 13 orchestration skills through a complete software development lifecycle, from issue to merged PR, with recursive orchestration, parallel review gates, and a git-native knowledge base.

What Is This?

metaswarm is an extraction of a production-tested agentic orchestration system. It has been proven in the field writing production-level code with 100% test coverage, mandatory TDD, multi-reviewed spec-driven development, and SDLC best practices across hundreds of PRs. It provides:

• 18 specialized agent personas (Researcher, Architect, Coder, Security Auditor, PR Shepherd, etc.)
• A structured 9-phase workflow: Research → Plan → Design Review Gate → Work Unit Decomposition → Orchestrated Execution → Final Review → PR Creation → PR Shepherd → Closure & Learning
• 4-Phase Orchestrated Execution Loop: Each work unit runs through IMPLEMENT → VALIDATE → ADVERSARIAL REVIEW → COMMIT. The orchestrator validates independently (never trusts subagent self-reports), and adversarial reviewers check DoD compliance with file:line evidence
• Parallel Design Review Gate: 5 specialist agents (PM, Architect, Designer, Security, CTO) review in parallel with a 3-iteration cap before human escalation
• Recursive orchestration: Swarm Coordinators spawn Issue Orchestrators, which spawn sub-orchestrators for complex epics (swarm of swarms)
• Git-native task tracking: Uses BEADS (bd CLI) for issue/task management, dependencies, and knowledge priming
• Knowledge base: JSONL-based fact store for patterns, gotchas, decisions, and anti-patterns — agents prime from this before every task
• Quality rubrics: Standardized review criteria for code, architecture, security, testing, planning, and adversarial spec compliance
• External AI tool delegation: Optionally delegate implementation and review tasks to OpenAI Codex CLI and Google Gemini CLI for cost savings and cross-model adversarial review
• Visual review: Playwright-based screenshot capture for reviewing web UIs, presentations, and rendered pages
• PR lifecycle automation: Autonomous CI monitoring, review comment handling, and thread resolution
• Workflow enforcement: Mandatory quality gate intercepts at every handoff point — agents cannot skip design review, plan review, or knowledge capture
• Context recovery: Approved plans and execution state persist to disk via BEADS, surviving context compaction and session interruption

Architecture

Your prompt (spec with DoD items) or GitHub Issue
        │
        ▼
┌─────────────────────────────────┐
│  Swarm Coordinator               │
│  - Assign to worktree            │
│  - Spawn Issue Orchestrator      │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│  Issue Orchestrator              │
│  - Create BEADS epic             │
│  - Decompose into work units     │
└─────────────────────────────────┘
        │
        ▼
  Research → Plan → Design Review Gate (5 parallel reviewers)
        │
        ▼
  Work Unit Decomposition (DoD items, file scopes, dependency graph)
        │
        ▼
  Orchestrated Execution Loop (per work unit):
    IMPLEMENT → VALIDATE → ADVERSARIAL REVIEW → COMMIT
    (Optionally delegates IMPLEMENT to Codex/Gemini CLI)
    (Cross-model REVIEW: writer always reviewed by different model)
        │
        ▼
  Final Comprehensive Review (cross-unit integration)
        │
        ▼
  PR Creation → PR Shepherd (auto-monitors to merge)
        │
        ▼
  Closure → Knowledge Extraction (feedback loop)

Repository Structure