ralph-swarm

ralph-swarm

Spec-driven planning with parallel execution via Agent Teams

One command. Full spec. Then build — sequentially or in parallel.

By default, each planning phase pauses for review. Use --full to run all phases at once.

Goal → Research → (pause) → Requirements → (pause) → Design → (pause) → Tasks → Execution

What Is This?

ralph-swarm is a Claude Code plugin that takes a development goal, breaks it into a structured spec (research, requirements, design, tasks), then executes each task — either one-at-a-time or in parallel using Agent Teams.

You: "Add user authentication with JWT"
ralph-swarm: *researches codebase, writes requirements, designs architecture, breaks into tasks*
ralph-swarm: *executes each task with specialized agents*
ralph-swarm: SWARM COMPLETE

Two phases:

1. Planning — Four sequential sub-phases produce a full spec. No code is written.
2. Execution — Tasks from the spec are executed by specialized agents. Code is written here.

Who It's For

• Teams or solo developers who want a repeatable planning workflow before coding
• Medium/large tasks where a written spec improves execution quality
• Repos with enough parallelizable work to benefit from Agent Teams + worktrees
• People who want a safer default (review first) with an opt-in autopilot path (--yolo)

Not A Fit If

• You want a lightweight one-shot coding shortcut with minimal process
• The task is tiny (1-2 quick edits) and planning overhead will dominate
• The repo is highly coupled, making parallel execution mostly ineffective
• You do not want hook-driven state persistence / resumption behavior

Installation

# Add the marketplace
/plugin marketplace add Divkix/ralph-swarm

# Install the plugin
/plugin install ralph-swarm@ralph-swarm

# Restart Claude Code

Note: ralph-swarm hook scripts require jq or python3 to parse .ralph-swarm-state.json safely.

git clone https://github.com/Divkix/ralph-swarm.git
claude --plugin-dir ./ralph-swarm/plugins/ralph-swarm

Quick Start

Sequential with review (default)

/ralph-swarm:start "Build an authentication system with JWT tokens"

Runs the research phase and pauses. Continue with /ralph-swarm:requirements, /ralph-swarm:design, and /ralph-swarm:tasks (or use --full to run all phases at once), then review and execute.

Parallel with review

/ralph-swarm:start "Build an authentication system with JWT tokens" --swarm

Same incremental planning flow (research first, then review/pause commands), but execution uses multiple agents working in parallel after /ralph-swarm:go.

Full autopilot

/ralph-swarm:start "Build an authentication system with JWT tokens" --swarm --yolo

Plans, skips review, immediately fires up a team of agents. No human in the loop until it finishes.

Commands

Flags

How It Works

Planning Phase

Planning consists of four sub-phases that run in strict order. Each delegates to a specialized agent: