plan-orchestrate

Plan Orchestrate

Execute all tasks in a plan using parallel TDD workers. Fully autonomous after invocation.

Usage

plan-orchestrate {plan-name}

Example: plan-orchestrate user-auth

Prerequisites

1. Plan must exist at .claude/plans/{plan-name}/
2. Project must be configured (.claude/testing.md exists)
3. Plan status must be ready or in_progress

Check prerequisites:

ls .claude/plans/{plan-name}/_plan.md .claude/testing.md 2>/dev/null

If not found, output error and stop.

1. Must be on the correct feature branch

Verify the current branch matches feature/{plan-name}:

git branch --show-current

If the current branch is not feature/{plan-name}:

• Output an error explaining which branch is expected
• Ask the user if they'd like to check out feature/{plan-name}
• Do NOT proceed until on the correct branch

Project Configuration

<testing> @.claude/testing.md </testing>

<code-standards> @.claude/code-standards.md </code-standards>

Execution Algorithm

Step 0: Check for Ralph Wiggum Plugin

Before starting execution, check if the ralph-wiggum plugin is installed by looking at the available skills listed in the system reminder. If skills like ralph-wiggum:ralph-loop, ralph-wiggum:help, or ralph-wiggum:cancel-ralph appear in the available skills list, the plugin is installed.

Do NOT use claude plugin list via Bash — this command does not work from inside a Claude Code session and will produce false negatives.

If ralph-wiggum IS installed (skills are listed):

• Automatically wrap execution with ralph-wiggum for session persistence
• Invoke: /ralph-wiggum:loop "plan-orchestrate {plan-name}" --completion-promise "ALL_TASKS_COMPLETE" --max-iterations 100
• This ensures the orchestrator continues even if context limits are reached

If ralph-wiggum is NOT installed (skills are not listed):

• Display a warning:

``` WARNING: ralph-wiggum plugin is not installed.

For large plans, execution may stop if context limits are reached. The orchestrator will continue, but session persistence is not available.

To install ralph-wiggum for automatic session recovery: claude plugin marketplace add anthropics/claude-code claude plugin install ralph-wiggum@claude-code-plugins

Continuing without ralph-wiggum... ```

• Continue with execution (the orchestrator will still work, but without session persistence)

Step 1: Load Plan Context

Read plan files:

• .claude/plans/{plan-name}/_plan.md - Plan overview
• .claude/plans/{plan-name}/*.md - All task files (excluding _plan.md)

Note: Testing and code standards are auto-included above.

Parse each task file to extract:

• Task number (from filename)
• Status (pending | in_progress | completed | blocked)
• Dependencies (from Depends on field)
• Requirements (checkboxes)
• Retry count

Build a dependency graph as a data structure.

Step 2: Update Plan Status

If plan status is ready, change to in_progress:

• Edit .claude/plans/{plan-name}/_plan.md
• Set ## Status to in_progress

Step 3: Find Ready Tasks

A task is ready when:

• Status is pending
• ALL dependencies have status completed

ready_tasks = []
for each task in tasks:
    if task.status == "pending":
        if all(dep.status == "completed" for dep in task.dependencies):
            ready_tasks.append(task)

Step 4: Check Termination Conditions

All Complete:

if all(task.status == "completed" for task in tasks):
    Run Step 4a: Post-Implementation Pipeline (quality gates before final completion)
    STOP

Blocked State:

if len(ready_tasks) == 0:
    if any(task.status == "pending" for task in tasks):
        # Tasks exist but none are ready - dependency deadlock or all blocked
        blocked_tasks = [t for t in tasks if t.status == "blocked"]
        Output: TASKS_BLOCKED: {list blocked task numbers and reasons}
        STOP

Step 4a: Post-Implementation Pipeline

When all tasks are complete, run the agents configured in the post-implementation phase of pipeline.md.

1. Read the pipeline configuration:

Parse the ## post-implementation section from the <pipeline> context included in CLAUDE.md. Each bullet point is an agent name to run.

2. Get the list of changed files:

git add -A && git diff --name-only --cached && git reset HEAD

This temporarily stages everything to get the file list, then unstages. Nothing is committed yet.

3. For each agent in the post-implementation list, run it with the changed files:

For agents that operate on file batches (like standards-enforcer), split files into batches of ~10 and spawn parallel subagents. For agents that operate on the plan as a whole, spawn a single subagent.

How to determine the agent's mode: Read the agent's .md file. If it references "batch" or "file list" in its prompt format, use batch mode. Otherwise, use single mode.

Batch mode (e.g., standards-enforcer):

Use the Task tool with subagent_type="{agent-name}" for EACH batch.
All Task tool calls MUST be made in a SINGLE message to enable parallel execution.

Worker Prompt (per batch):

**CRITICAL: Pass the COMPLETE, VERBATIM content of the <code-standards> and <testing> tags above.

Do NOT summarize, condense, or paraphrase. The full documents contain nuanced rules

that are lost when summarized. Copy-paste the entire content between the tags.**

## Code Standards
{paste the COMPLETE content of <code-standards> verbatim — do NOT summarize}

## Testing Standards
{paste the COMPLETE content of <testing> verbatim — do NOT summarize}

## Files to Review
{list of files in this batch, one per line}

Single mode (e.g., doc-updater):

Use the Task tool with subagent_type="{agent-name}" once.

Pass the plan name, changed files list, and any relevant project context.

4. After ALL post-implementation agents complete, run validation:

# Run full test suite
{parallel test command from testing.md}

CRITICAL: Nothing is committed until AFTER the full test suite passes. This ensures no broken code is ever committed.

5. On tests passing: First, update _plan.md status to completed. Then stage and commit everything together in a single commit:

# 1. Update plan status BEFORE committing
# (edit .claude/plans/{plan-name}/_plan.md — set Status to "completed")

# 2. Stage everything: implementation + pipeline agent fixes + plan files (including updated status)
git add -A .claude/plans/{plan-name}/
git add -A
git commit -m "feat({plan-name}): {plan title summary}"

IMPORTANT: There must be exactly ONE commit here — do NOT make a separate commit for the plan status update. Update the status first, then stage and commit all changes together.

Output: ALL_TASKS_COMPLETE

6. On test failure:

• Revert only the post-implementation agent changes to isolate whether they broke things:

``bash git stash `` Re-run the test suite on just the implementation.

• If implementation tests pass: a post-implementation agent broke something. Drop the stash, commit implementation only, and output:

``` ALL_TASKS_COMPLETE

WARNING: Post-implementation pipeline broke tests. Implementation committed without pipeline fixes. Review and run manually. ```

• If implementation tests also fail: a TDD worker produced broken code. Restore the stash (git stash pop) and output TASKS_BLOCKED with details.

Step 5: Spawn Parallel Workers

For EACH ready task, spawn a Task tool subagent in parallel (single message with multiple Task tool calls):

Use the Task tool with subagent_type="tdd-worker" for EACH ready task.
All Task tool calls MUST be made in a SINGLE message to enable parallel execution.

Worker Prompt (pass to each tdd-worker):

**CRITICAL: Pass the COMPLETE, VERBATIM content of the <testing> and <code-standards> tags above.

Do NOT summ