ralph

What it does

Spawns a subagent for every task to process items pulled from a queue, ensuring isolated context per phase. Supports serial processing with optional parallel mode, and can filter by batch or by current phase type. Provides a dry-run option to preview actions without executing. Outputs a RALPH HANDOFF block at the end of each task to communicate work done and any queue updates.

How it works

1. Parse arguments: N tasks to process (required unless --dry-run), optional --parallel, --batch, --type, --dry-run, and --handoff.
2. Read queue state from ops/queue.yaml, ops/queue/queue.yaml, or ops/queue/queue.json to identify pending tasks.
3. Build a list of actionable tasks (status == "pending"), applying --batch and --type filters if provided.
4. If --dry-run, output a summary of the queue and next tasks, then stop.
5. In serial mode (default unless --parallel): for up to N tasks, select the next pending task, read its metadata, and construct a phase-specific prompt including:
   • task file path, task id, current_phase, and target
   • instruction to use the skill with --handoff and ONE PHASE ONLY
   • mandated subagent spawning for every task via the Task tool
   • output of a RALPH HANDOFF block
6. Spawn a subagent using Task with the constructed prompt; wait for completion.
7. On return, extract the RALPH HANDOFF block if present, capture Learnings, and queue updates.
8. Advance the task to the next phase (or mark done if last phase) and update current_phase and completed_phases accordingly.
9. Re-filter the queue for the next iteration and repeat until N tasks are processed or none are pending.
10. In parallel mode (--parallel): process up to 5 concurrent claims through all phases, with a separate Phase B cross-connect validation step after completion. Incompatibility with --type is enforced, returning an error if both are provided.

When to use it

Use when you need structured, isolated context per task phase and want automated, per-task subagent execution with explicit phase sequencing. Use --dry-run to validate impact before execution. Use --parallel to process multiple claims end-to-end concurrently, then validate cross-connections.

What it can touch

• Task tool is mandatory for spawning subagents for every task.
• Access to queue files: ops/queue.yaml, ops/queue/queue.yaml, ops/queue/queue.json for reading and updating task state.
• Phase-specific prompts reference: ops/queue/{FILE} and {TARGET}, {ID}, {CURRENT_PHASE}, {DOMAIN:note} paths.

Caveats

• Subagent spawning is mandatory for every task; inline execution is prohibited.
• The lead session must not perform task work directly; only delegate via Task tool calls.
• If a RALPH HANDOFF block is missing, the system will log a warning but proceed.
• The final report must reflect phase progression logic according to the queue's phase_order; last phase marks done and timestamps appropriately.