/plan-orchestrate

name: plan-orchestrate
description: Execute implementation plans with parallel TDD workers. Use when ready to run, execute, or start a plan. Triggers on "run the plan", "execute the plan", "implement the plan", "start the plan", "start implementation", "orchestrate", "begin autonomous execution". Requires a plan created by plan-create.
model: sonnet
argument-hint: "[plan-name]"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task

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

**First, resolve the plans directory,** once, and reuse `$PLANS_DIR` for every path below. It is `.claude/plans` unless the project overrides it in `.claude/hcf.json` (see [Plans Directory](#plans-directory) in the README). The script answers with an absolute path resolved from the project root, so the result does not depend on the working directory:

PLANS_DIR="$("{skill-base-dir}/../../hooks/resolve-plans-dir.sh")" || exit 1

**Never substitute a hand-written `jq` line or a literal `.claude/plans`.** A non-zero exit means the project root or the configured value is unusable; surface the script's stderr verbatim and stop. Quote every path built from `$PLANS_DIR` — a configured directory may contain spaces.

Then:

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

Check prerequisites:

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

If not found, output error and stop.

4. 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: Suggest Unattended Completion via /goal

Claude Code's built-in `/goal` command keeps a session working toward a verifiable end state — its evaluator runs after each turn and pushes execution to continue until the condition is met. Only the user can set a goal (`/goal` is a user-typed command and cannot be invoked from a skill), so surface a copy-pasteable tip and continue immediately. This is informational, never a gate — do not wait for a response.

Display:

Tip: for large plans, you can keep this run going unattended with Claude Code's
built-in /goal command (interrupt me now to set it, or set it before a future run):

  /goal the {plan-name} plan run reached a terminal state: plan-orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED

Either way, an interrupted run resumes from disk — just re-run plan-orchestrate {plan-name}.

The suggested condition deliberately names **both** terminal outputs. A goal phrased as only `ALL_TASKS_COMPLETE` leaves the evaluator demanding more turns after a legitimately blocked run, when the correct behavior is to stop and report the blockage.

Step 1: Load Plan Context

Read plan files:

• `$PLANS_DIR/{plan-name}/_plan.md` - Plan overview
• `$PLANS_DIR/{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 `$PLANS_DIR/{plan-name}/_plan.md`
• Set `## Status` to `in_progress`

**Establish the run fingerprint.** Every hook call below passes this back via `--expect=`, so that agent files changing mid-run halt the orchestration rather than silently swapping the pipeline. Read `$PLANS_DIR/{plan-name}/.hook-fingerprint` and handle three distinct states — conflating them is the mistake to avoid:

| State | Action | |-------|--------| | **Present and parseable** (one line: `discover-hooks-fingerprint-v1 <64-hex>`) | Use it as `$RUN_FINGERPRINT`. Pass the file's contents **verbatim** — do not trim, reformat, or re-derive them. | | **Missing** | Not an error. Plans created before this feature have none. Capture one and write it to the plan directory so a resumed run is covered too, then continue: `"{skill-base-dir}/../../hooks/discover-hooks.sh" --fingerprint > "$PLANS_DIR/{plan-name}/.hook-fingerprint"` | | **Present but unparseable** (empty, truncated, prose, wrong length) | **Halt.** Do not silently recapture — that would mask a botched write. Tell the user to delete the file to re-baseline. |

**Never reconstruct, abbreviate, or recall a fingerprint from memory.** It is only ever produced by running the script. A hallucinated digest fails every subsequent hook with bogus drift and bricks the run.

Step 2a: Pre-Implementation Hook

Run the `pre-implementation` hook **once**, after the status is set to `in_progress` and **before** the first batch is spawned.

Resolve and run enrolled agents via the **HOOKS.md discovery routine** (see [Hook Discovery](#hook-discovery) below) with `HOOK = pre-implementation`. Pass each agent the project context as described in [Spawning hook agents](#spawning-hook-agents).

**Exit 0 with empty stdout** is an empty hook: return immediately, log nothing, do no work, and proceed to Step 3. **Any non-zero exit stops the run** — see [Hook Discovery](#hook-discovery) for the full result table.

Step 3: Find Ready Tasks

A task is **ready** when:

• Status is `pending`
• ALL dependencies have status `completed`

ready_tasks = []
for each task