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

1. Validate: Checks tasks.md format via validate-tasks-format.py (line-level diagnostics with fix suggestions)
2. Parse: Reads tasks, builds a dependency graph with phase ordering and file overlap detection
3. Partition: Groups tasks by file ownership (or round-robin for worktree). Detects and resolves file conflicts.
4. Baseline: Captures passing test count for regression detection during execution
5. Dispatch: Creates an Agent Team, spawns teammates with scoped prompts including file ownership, quality commands, and commit conventions
6. Coordinate: Manages phase gates, quality checks, stall detection, and teammate lifecycle
7. 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.

Quality commands are auto-discovered from package.json, Cargo.toml, pyproject.toml, or Makefile. You can also declare them explicitly in tasks.md (recommended for monorepos):

## Quality Commands
- **Build**: `cargo build`
- **Test**: `cargo test`
- **Lint**: `cargo clippy -- -D warnings`
- **Typecheck**: `tsc --noEmit`

Use N/A for commands that don't apply.

Hooks

Hook	Event	Purpose
session-setup.sh	SessionStart	Detect active dispatches, manage gc.auto, auto-reclaim coordinator session, auto-mark stale dispatches, auto-sync plugin source
file-ownership-guard.sh	PreToolUse (Write/Edit)	Block writes outside owned files. Returns error naming the violation.
task-completed-gate.sh	TaskCompleted	6-stage quality gate pipeline. Blocks task completion if any check fails.
dispatch-coordinator.sh	Stop	Prevents coordinator from stopping mid-dispatch. Uses JSON decision control with block counter safety valve.

Session Isolation

The plugin tracks which Claude Code session owns the coordinator role via coordinatorSessionId in dispatch state. This enables:

• Auto-reclaim: When a new session starts and the previous coordinator is gone, ownership transfers automatically
• Heartbeat safety: Active coordinators write heartbeat timestamps. Reclaim only happens after the heartbeat goes stale (default 10 minutes, configurable via RALPH_RECLAIM_THRESHOLD_MINUTES)
• Stale detection: If a dispatch is active but the team config is dead, the dispatch is auto-marked stale so the stop hook doesn't trap the user
• Explicit release: Setting coordinatorSessionId: null signals intentional release (skips auto-reclaim)

Commit Provenance

Teammates append a Signed-off-by trailer to every commit for provenance tracking:

feat(auth): add login endpoint

Signed-off-by: api-layer

The trailer value is the group name (not git user info). The verify-commit-provenance.py script audits commits against known group names after dispatch.

tasks.md Format

Ralph Parallel reads tasks.md files generated by ralph-specum. The expected format:

## Quality Commands
- **Build**: `npm run build`
- **Test**: `npm test`

## Phase 1: Description

- [ ] 1.1 [P] Task description
  - **Files**: `src/api/auth.ts`, `src/models/user.ts`
  - **Do**:
    1. Implementation step one
    2. Implementation step two
  - **Done when**: Completion criteria
  - **Verify**: `npm test -- --grep auth`
  - **Commit**: `feat(auth): add login endpoint`

- [ ] 1.2 [VERIFY] Verify phase 1
  - **Verify**: `npm test && npm run typecheck`

Markers

Marker	Meaning
[P]	Parallelizable -- can run simultaneously with other [P] tasks in same phase
[VERIFY]	Checkpoint -- runs by the lead after all same-phase tasks complete

Pre-defined Groups

You can pre-define groups in tasks.md for direct control over partitioning:

### Group 1: api-layer [Phase 1]
**Files owned**: `src/api/auth.ts`, `src/api/middleware.ts`

- [ ] 1.1 [P] Add auth endpoint
  - **Files**: `src/api/auth.ts`
  - **Verify**: `npm test`

When pre-defined groups are present, the partitioner uses them directly instead of computing automatic partitions. File ownership conflicts between groups are auto-resolved (assigned to the group with the most tasks touching the file).

Scripts

Script	Purpose
parse-and-partition.py	Parse tasks.md, build dependency graph, partition by file ownership or round-robin
build-teammate-prompt.py	Generate per-group teammate prompts with tasks, ownership, quality checks, KB context
validate-tasks-format.py	Standalone format validator with line-level diagnostics and fix suggestions
mark-tasks-complete.py	Map completed groups to task IDs and update checkboxes in tasks.md
verify-commit-provenance.py	Audit git log Signed-off-by trailers against known group names
capture-baseline.sh	Capture passing test count at dispatch time for regression detection

Dispatch Lifecycle

(none) --> dispatched --> merged         (file-ownership: automatic on completion)
                     --> merging --> merged  (worktree: via /merge)
                     --> stale           (team lost mid-dispatch)
                     --> superseded      (new dispatch for same spec)
                     --> aborted         (via --abort)

Stale dispatches are auto-detected on SessionStart when the team is dead but work is incomplete. Run /ralph-parallel:dispatch to re-dispatch or --abort to cancel.

Error Recovery

Scenario	Action
Teammate crashes	Re-spawn with remaining tasks
Quality gate fails	Teammate receives error output, must fix and retry
File ownership violation	Write blocked, teammate told to message lead
Session restart mid-dispatch	Auto-reclaim via heartbeat, or --reclaim
Team lost (stale dispatch)	Auto-marked stale on SessionStart. Re-dispatch or abort.
Circular file dependencies	Offer worktree strategy or serialize overlapping tasks

Demo Results

Spec	Tasks	Teammates	Strategy	Result
user-auth	12	4	file-ownership	~3.4x speedup vs serial
api-dashboard	4	2	file-ownership	All quality gates passed
gpu-graphics-demo	12	3	file-ownership	Full Rust/wgpu app, all gates passed
forge-sdk-v6	52	4	worktree	339 tests (from 126 baseline), 34 commits

Total: 80+ tasks dispatched, 148+ tests passing across specs, 62 plugin tests.

Requirements

• Claude Code with Agent Teams support
• ralph-specum plugin (for spec generation)
• Python 3.10+ (for analysis scripts)
• jq (used by shell hooks)

License

MIT