codex-swarm

The Pair Planning Framework

A pluggable multi-agent planning framework for Claude Code. Swap planning engines (Claude, RepoPrompt, Codex, Gemini) while keeping the same discovery agents and execution patterns.

The Core Insight: All planning engines follow the same meta-pattern: Discovery → Planning → Execution. The framework standardizes discovery (code-scout, doc-scout) and execution (plan-coder) while making the planning layer pluggable. This means you can switch between Claude's speed, RepoPrompt's file intelligence, Codex's reasoning depth, or Gemini's stateless simplicity - all using identical workflows.

Core Concept: Pluggable Planning

┌───────────────────────────────────────────────────────────────────────┐
│                     PAIR PLANNING FRAMEWORK                           │
│                                                                       │
│   DISCOVERY (same for all)          PLANNING (choose one)             │
│   ────────────────────────          ─────────────────────             │
│                                                                       │
│   ┌─────────────┐                   ┌─────────────────────────────┐   │
│   │ code-scout  │                   │     Claude    (pair-*)      │   │
│   │ (codebase)  │                   ├─────────────────────────────┤   │
│   └──────┬──────┘    CONTEXT        │   RepoPrompt  (repoprompt-*)│   │
│          │          ─────────►      ├─────────────────────────────┤   │
│   ┌──────┴──────┐                   │     Codex     (codex-*)     │   │
│   │  doc-scout  │                   ├─────────────────────────────┤   │
│   │ (external)  │                   │     Gemini    (gemini-*)    │   │
│   └─────────────┘                   └──────────────┬──────────────┘   │
│                                                    │                  │
│                                                    │ PLAN             │
│                                                    ▼                  │
│                                                                       │
│   EXECUTION (same for all)                                            │
│   ────────────────────────                                            │
│                                                                       │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                   │
│   │ plan-coder  │  │ plan-coder  │  │ plan-coder  │  (parallel)       │
│   │   file 1    │  │   file 2    │  │   file 3    │                   │
│   └─────────────┘  └─────────────┘  └─────────────┘                   │
└───────────────────────────────────────────────────────────────────────┘

The framework provides:

• Shared agents: code-scout, doc-scout, plan-coder (same implementation across plugins)
• Pluggable planners: Swap between Claude, RepoPrompt (rp-cli), Codex CLI, or Gemini CLI
• Two execution patterns: Pipeline (iterative) or Swarm (one-shot)

Execution Patterns

The framework offers two execution patterns that work with any planning engine.

Pipeline Pattern (Iterative, Human-in-the-Loop)

┌────────────────────────────────────────────────────────────────────────┐
│                       ITERATIVE DISCOVERY LOOP                         │
│                                                                        │
│  code-scout ───► CHECKPOINT ───► doc-scout ───► CHECKPOINT ───► ...    │
│  (background)         │         (background)         │                 │
│       │          User decides         │         User decides           │
│       ▼         "Add research"        ▼        "Complete"              │
│  TaskOutput           │          TaskOutput          │                 │
│       │               │               │              │                 │
│       └───────────────┴───────────────┴──────────────┘                 │
│                               │                                        │
│                       context_package                                  │
└───────────────────────────────┼────────────────────────────────────────┘
                                │
                                ▼
                     ┌────────────────────┐
                     │      PLANNER       │
                     │    (pluggable)     │
                     └─────────┬──────────┘
                               │
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
        ┌────────────┐  ┌────────────┐  ┌────────────┐
        │ plan-coder │  │ plan-coder │  │ plan-coder │  (background)
        │   file1    │  │   file2    │  │   file3    │
        └──────┬─────┘  └──────┬─────┘  └──────┬─────┘
               │               │               │
               └───────────────┼───────────────┘
                               ▼
                          TaskOutput
                        (collect all)