ralph-parallel
Parallel spec execution plugin for Claude Code. Works with ralph-specum to dispatch spec tasks to Agent Teams for concurrent execution.
What It Does
Takes a spec generated by ralph-specum, analyzes task dependencies and file ownership, then dispatches parallelizable groups to Agent Team teammates for simultaneous execution. Coordinates the team through phase gates, quality checkpoints, and session-aware lifecycle management.
Proven results: 80+ tasks dispatched across 4 real specs, with up to 3.4x speedup over serial execution.
Install
/install-plugin kavanaghpatrick/ralph-parallel
Requires ralph-specum to be installed first.
Quick Start
# 1. Create a spec with ralph-specum
/ralph-specum:new my-feature Add user authentication
# 2. Run through spec phases (research -> requirements -> design -> tasks)
/ralph-specum:requirements
/ralph-specum:design
/ralph-specum:tasks
# 3. Dispatch tasks in parallel
/ralph-parallel:dispatch my-feature
# 4. Monitor progress
/ralph-parallel:status
# 5. (Worktree strategy only) Integrate results
/ralph-parallel:merge
Commands
| Command | Description |
|---|
/ralph-parallel:dispatch [spec] [flags] | Analyze tasks, partition into groups, spawn teammates |
/ralph-parallel:status [spec] | Monitor parallel execution progress |
/ralph-parallel:merge [spec] | Verify and integrate results (worktree strategy only) |
Dispatch Flags
| Flag | Default | Description |
|---|
--max-teammates N | 4 | Maximum number of parallel teammates (max 8) |
--strategy | file-ownership | Isolation strategy: file-ownership or worktree |
--dry-run | - | Show partition plan without dispatching |
--abort | - | Cancel active dispatch and shut down teammates |
--reclaim | - | Reclaim coordinator ownership for current session |
Status Flags
| Flag | Description |
|---|
--json | Output raw JSON instead of formatted display |
--watch | Continuously poll and refresh every 30 seconds |
Merge Flags
| Flag | Description |
|---|
--abort | Cancel merge, restore pre-dispatch state |
--continue | Resume merge paused for conflict resolution |
Strategies
File Ownership (default)
Each teammate owns specific files and can only modify those files. The PreToolUse hook enforces ownership at runtime by blocking writes to non-owned files. No merge step needed -- dispatch completes automatically.
Best for: Most specs. Tasks with clear file boundaries.
Limitation: Tasks sharing files must be serialized.
Worktree
Each teammate gets an isolated git worktree branch. All files are accessible but changes live on separate branches. Requires /ralph-parallel:merge after all teammates complete to integrate branches.
Best for: Highly coupled codebases where tasks touch overlapping files.
Limitation: Merge conflicts possible, requires explicit merge step.
How It Works
- Validate: Checks
tasks.md format via validate-tasks-format.py (line-level diagnostics with fix suggestions)
- Parse: Reads tasks, builds a dependency graph with phase ordering and file overlap detection
- Partition: Groups tasks by file ownership (or round-robin for worktree). Detects and resolves file conflicts.
- Baseline: Captures passing test count for regression detection during execution
- Dispatch: Creates an Agent Team, spawns teammates with scoped prompts including file ownership, quality commands, and commit conventions
- Coordinate: Manages phase gates, quality checks, stall detection, and teammate lifecycle
- Complete: Runs
mark-tasks-complete.py, shuts down teammates, marks dispatch merged
Quality Gates
Every task goes through a 6-stage quality gate via the TaskCompleted hook before completion is accepted:
| Stage | Check | Frequency | Blocks On |
|---|
| 1 | Task verify command | Every task | Non-zero exit |
| 2 | Typecheck | Every task | Non-zero exit (if configured) |
| 3 | File existence | Every task | Missing files listed in task |
| 4 | Build | Every 3rd task | Non-zero exit (if configured) |
| 5 | Test suite + regression | Every 2nd task | Failures or test count drop below baseline |
| 6 | Lint | Every 3rd task | Non-zero exit (if configured) |
Test regression detection: At dispatch, a baseline test count is captured. During execution, the gate checks that the current test count hasn't dropped below 90% of baseline (or baseline-1 for small suites). This prevents teammates from accidentally deleting tests.
Phase gates: When ALL tasks in Phase N complete, the lead runs the verify checkpoint task, then executes all quality commands. Phase N+1 teammates only proceed after the gate passes.
