parallel-workflow

Parallel Workflow

Guides users through dispatching ralph-specum spec tasks for parallel execution via Claude Code Agent Teams.

Overview

Ralph Parallel extends ralph-specum by enabling multiple spec tasks to execute simultaneously across Agent Teams teammates. Instead of sequential task-by-task execution, tasks are partitioned into non-conflicting groups and dispatched to separate teammates.

Workflow

1. Create spec normally:     /ralph-specum:start my-feature "goal"
2. Complete spec phases:     research -> requirements -> design -> tasks
3. Dispatch for parallel:    /ralph-parallel:dispatch
   -> Analyzes tasks, partitions by file ownership, creates team, spawns teammates
   -> Lead coordinates execution, runs verify checkpoints, handles serial tasks
4. Monitor progress:         /ralph-parallel:status
5. Integrate results:        /ralph-parallel:merge (worktree only; file-ownership auto-completes)
6. Handle remaining serial:  /ralph-specum:implement (if any tasks remain)

Commands

Command	Purpose	Key Flags
/ralph-parallel:dispatch	Analyze tasks, partition, create team, orchestrate	--max-teammates N, --strategy, --dry-run, --abort, --reclaim
/ralph-parallel:status	Show parallel execution progress	--json, --watch
/ralph-parallel:merge	Integrate results / verify consistency	--abort, --continue

Strategies

File Ownership (Default)

Each teammate gets exclusive ownership of certain files. No merge needed -- teammates work in the same repo but on different files. The PreToolUse hook (file-ownership-guard.sh) enforces ownership at runtime by blocking writes to non-owned files.

Best for: Most projects. Simple, no merge complexity. Limitation: Tasks sharing files must be serialized.

Worktree

Each teammate gets its own git worktree with a separate branch. Full file access but requires merge step via /ralph-parallel:merge.

Best for: Highly coupled codebases where tasks touch overlapping files. Limitation: Merge conflicts possible, requires explicit merge step.

tasks.md Format Requirements

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

Task Format

## Phase 1: Description

- [ ] 1.1 [P] Task description
  - **Files**: `src/api/auth.ts`, `src/models/user.ts`
  - **Do**: Implementation steps
  - **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 sequentially by the lead after all same-phase tasks complete

Quality Commands Section

Declare project quality commands at the top of tasks.md. These are used by quality gates and phase verification:

## 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. Three formats are supported (bold markdown preferred):

1. - **Build**: \cmd`` (primary)
2. Code-fenced blocks (backward compat)
3. - Build: cmd (bare dash)

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. This gives the task planner (human or ralph-specum) full control over parallelism.

Dispatch Execution Flow

The dispatch command follows these steps:

1. Resolve spec: Find tasks.md from spec name or .current-spec
2. Validate format: Run validate-tasks-format.py to check task format
3. Partition: Run parse-and-partition.py to build dependency graph and create groups
4. Display plan: Show the partition to the user (mandatory -- user must see it)
5. Write dispatch state: Save to specs/$specName/.dispatch-state.json
6. Capture baseline: Run test suite and record passing test count
7. Create team + tasks: TeamCreate + one TaskCreate per spec task (1:1 mapping)
8. Spawn teammates: One Task tool call per group, all in parallel
9. Coordinate: Phase gates, quality checks, stall detection, serial tasks
10. Cleanup: mark-tasks-complete.py, shut down teammates, TeamDelete, set status

Critical Rules for Dispatch

• Scripts do analysis (parsing, partitioning, prompt building). The dispatch command does orchestration.
• Never execute spec tasks yourself during dispatch -- teammates do that.
• Never skip the partition display -- user must see and approve the plan.
• One TaskCreate per spec task -- never summarize multiple tasks into one.

Dispatch State

Dispatch state is stored at specs/$specName/.dispatch-state.json:

{
  "dispatchedAt": "2026-02-26T15:00:00Z",
  "coordinatorSessionId": "$CLAUDE_SESSION_ID",
  "strategy": "file-ownership",
  "maxTeammates": 4,
  "groups": [
    {
      "name": "api-layer",
      "tasks": ["1.1", "1.2"],
      "ownedFiles": ["src/api/auth.ts", "src/api/middleware.ts"],
      "taskDetails": [...]
    }
  ],
  "serialTasks": [],
  "verifyTasks": [{"id": "1.4", "phase": 1}],
  "qualityCommands": {"build": "npm run build", "test": "npm test"},
  "baselineSnapshot": {"testCount": 42, "capturedAt": "..."},
  "status": "dispatched",
  "completedGroups": []
}

State Lifecycle

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

Stale dispatches: Auto-detected on SessionStart when the team config is dead but dispatch isn't complete. The session-setup hook marks these as stale with a reason and timestamp. Users can re-dispatch or abort.

Quality Gates (6-Stage Pipeline)

Every task completion triggers a quality gate via the TaskCompleted hook:

Stage	Check	Frequency	Blocks On
1	Task's Verify command	Every task	Non-zero exit
2	Typecheck (qualityCommands.typecheck)	Every task	Non-zero exit
3	File existence (all Files listed)	Every task	Missing files
4	Build (qualityCommands.build)	Every 3rd task	Non-zero exit
5	Test suite + regression check	Every 2nd task	Failures or test count drop
6	Lint (qualityCommands.lint)	Every 3rd task	Non-zero exit

Test regression detection: If baseline test count was captured at dispatch, the gate checks that current test count hasn't dropped below 90% of baseline (or below baseline-1 for small test 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 qualityCommands.build, qualityCommands.test, and qualityCommands.lint. Phase N+1 teammates only proceed after the gate passes.

Hooks

Hook	Event	Purpose
session-setup.sh	SessionStart	Detect active dispatches, manage gc.auto, auto-reclaim coordinator session, auto-mark stale dispatches
file-ownership-guard.sh	PreToolUse (Write/Edit)	Block writes outside owned files. Returns error message naming the violation.
task-completed-gate.sh	TaskCompleted	6-stage quality gate. Blocks task completion if any check fails.
dispatch-coordinator.sh	Stop	Prevents coordinator from stopping mid-dispatch. Re-injects coordination context after compaction.
merge-guard.sh	PreToolUse (Write|Edit)	Intercepts status="merged" writes, runs validate-pre-merge.py
teammate-idle-gate.sh	TeammateIdle	Prevents teammates from going idle with uncompleted tasks, safety valve after N blocks

What Claude Sees From Hooks

On session start with active dispatch:

ralph-parallel: Active parallel dispatch for spec 'my-feature'
ralph-parallel: Status: 1/3 groups complete (file-ownership strategy)
ralph-parallel: Groups: api-layer, ui-components, data-models
ralph-parallel: Run /ralph-parallel:status to see progress

On file ownership violation:

FILE OWNERSHIP VIOLATION: You (api-layer) attempted to write 'src/models/User.ts'
Your owned files: src/api/auth.ts, src/api/middleware.ts
Message the lead if you need changes to this file.

On task quality gate failure:

QUALITY GATE FAILED for task 1.2 (1.2: Add auth endpoint)
Verify command failed (exit 1): npm test -- --grep auth
--- Output (last 50 lines) ---
[test output]
Fix the issues and mark the task complete again.

On coordinator trying to stop mid-dispatch:

You are coordinating a parallel dispatch for spec 'my-feature'.
STATUS: 1/3 groups complete
NEXT ACTIONS:
1. Check TaskList for teammate progress
2. If waiting for teammates: they may be idle -- check and send status messages
3. When all Phase N tasks done: run the verify checkpoint yourself
4. When all tasks done: run mark-tasks-complete.py, set status="merged", shut down teammates, TeamDelete

Commit Provenance Convention

Teammates must 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). Do NOT use git commit -s -- it produces the wrong format (user.name + user.email instead of group name). Append the trailer manually.

The verify-commit-provenance.py script audits commits against known group names after dispatch. It is a standalone audit script, not wired into any hooks.

Teammate Behavior

Each teammate receives a generated prompt (via build-teammate-prompt.py) that includes:

1. Identity: Group name, spec name
2. Tasks: Full task blocks with Files/Do/Verify/Commit fields
3. TaskList IDs: 1:1 mapping to spec tasks (claim via TaskUpdate)
4. File ownership: Explicit list of files they may modify
5. Quality checks: Build/test/lint commands to run before marking tasks done
6. Commit convention: Signed-off-by trailer format
7. Communication protocol: Message lead on completion, blockers, or phase transitions

Teammate execution loop per task:

1. Claim TaskList task (TaskUpdate: owner + in_progress)
2. Implement the task
3. Run verify command
4. Commit with provenance trailer
5. Mark [x] in tasks.md
6. Mark TaskList task as completed

After all tasks: message lead "Group [name] complete. All N tasks verified."

Stall Detection and Recovery

If no teammate message is received for 10+ minutes:

1. Send status check message to the teammate
2. Wait 5 more minutes
3. If still no response: re-spawn the stalled teammate with remaining tasks
4. If re-spawn fails: serialize remaining tasks and warn the user

Never reassign tasks to yourself (the coordinator) -- that defeats parallel execution.

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	session-setup.sh auto-reclaims coordinator, or use --reclaim
Team lost (stale dispatch)	Auto-marked stale on SessionStart. Re-dispatch or abort.
All tasks already complete	parse-and-partition.py exits with code 2 -- nothing to dispatch
Single task remaining	Exit code 3 -- use /ralph-specum:implement instead
Circular file dependencies	Offer worktree strategy or serialize overlapping tasks

Worked Example

A spec "todo-api" with 4 tasks:

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

## Phase 1

- [ ] 1.1 [P] Create Todo model          Files: src/models/Todo.ts
- [ ] 1.2 [P] Create API handler          Files: src/api/todos.ts
- [ ] 1.3 [P] Add validation middleware   Files: src/api/middleware.ts
- [ ] 1.4 [VERIFY] Run full test suite

Dispatch partitions into 2 groups (all files are unique -- maximum parallelism):

Dispatch Plan for 'todo-api'
Strategy: file-ownership
Teams: 2 teammates + 1 lead

Group 1: backend (2 tasks)
  Tasks: 1.1, 1.2
  Files: src/models/Todo.ts, src/api/todos.ts

Group 2: middleware (1 task)
  Tasks: 1.3
  Files: src/api/middleware.ts

Verify checkpoints: 1.4
Serial tasks: none

Execution flow:

1. Lead creates team "todo-api-parallel"
2. Creates 4 TaskList tasks: #1 (1.1), #2 (1.2), #3 (1.3), #4 (1.4 -- blockedBy #1,#2,#3)
3. Spawns "backend" and "middleware" teammates in parallel
4. Both work simultaneously on their owned files
5. Quality gates run per task (verify command + supplemental checks)
6. Teammates message lead: "Group backend complete. 2 tasks verified."
7. Lead runs verify 1.4: full test suite -- PASS
8. Lead runs mark-tasks-complete.py
9. Lead sets status = "merged", shuts down team, TeamDelete
10. Output: "ALL_PARALLEL_COMPLETE -- 4 tasks done."

Tips

• Start with file-ownership strategy -- it's simpler and covers most cases
• Keep tasks well-scoped: smaller tasks parallelize better
• Use [P] markers in tasks.md to tag parallel-safe tasks
• Use [VERIFY] markers for checkpoint tasks that validate a phase
• Monitor with /ralph-parallel:status -- don't wait blindly for messages
• Use --dry-run to preview the partition plan before dispatching
• Pre-define groups in tasks.md when you want explicit control over partitioning
• Quality Commands in tasks.md override auto-discovery -- always declare them for monorepos
• qualityCommands.dev is discovered but intentionally not executed by quality gates