markshust/hcf/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

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 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.

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: 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:

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 launched.

Resolve and run enrolled agents via the HOOKS.md discovery routine (see Hook Discovery below) with HOOK = pre-implementation. Pass each agent the project context as described in 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 for the full result table.

Step 3: Find Ready Tasks

Execution is a rolling loop, not a lockstep one. Each task starts as soon as its own dependencies are complete; it never waits for unrelated tasks that happened to start alongside its dependencies. Track a running set — the tasks with a worker in flight in this session.

A task is ready when:

• Status is pending (an in_progress task from an interrupted run counts as

pending — see Task Already In Progress)

• ALL dependencies have status completed
• It is not in the running set

ready_tasks = []
for each task in tasks (in task-number order):
    if task.status == "pending" and task not in running:
        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: End-of-Run Hooks (quality gates + commit sequence before final completion)
    STOP

Waiting:

if len(ready_tasks) == 0 and len(running) > 0:
    # Nothing new can start yet, but workers are in flight
    Go to Step 6 and wait for the next completion

Blocked State:

if len(ready_tasks) == 0 and len(running) == 0:
    if any(task.status == "pending" for task in tasks):
        # Tasks exist but none are ready and nothing is running - 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

Hook Discovery

All hooks in this skill (pre-implementation, pre-batch, post-batch, post-implementation, pre-commit, post-commit) resolve their enrolled agents by running `hooks/discover-hooks.sh`, the single implementation of HOOKS.md → Discovery Routine. Never enumerate agent files by hand and never write a glob loop to do it. For a given HOOK:

"{skill-base-dir}/../../hooks/discover-hooks.sh" --hook=<HOOK> --expect="$RUN_FINGERPRINT"

{skill-base-dir} is the `Base directory for this skill` value stated when this skill loaded — it is given verbatim, so no path inference is needed. ${CLAUDE_PLUGIN_ROOT} is not available in a skill's Bash calls. $RUN_FINGERPRINT is the value established at Step 2.

Then, by result:

• Exit 0, empty stdout → empty hook. Return immediately — no staging, no

diffing, no spawns, and no logging or narration. "No narration" is literal and is the rule most often broken: do not name the hook, do not say it is empty/skipped, do not explain why it is empty, and do not say the discovery script returned no agents. A filtered query prints zero bytes precisely so there is nothing to echo. An empty hook is completely invisible in the user-facing output. See HOOKS.md → Empty-hook fast path.

• Exit 0, output → PRINT it verbatim as the resolved order, then spawn.
• Exit 1 or 2 → stop the run. Surface stderr verbatim.
• Exit 3 → stop the run. An agent file declares an invalid phase or

mode. Surface stderr verbatim; it names the file and the fix.

• Exit 4 → halt HCF. Hook enrollment changed since this run started, so the

remaining hooks would execute a different pipeline than the plan was reviewed against. Surface stderr verbatim. Stop launching (see Stopping mid-run) and do not commit.

• Script missing or not executable → hard failure. Say so and stop. There is

no prose fallback; reconstructing the routine by hand is the failure this design exists to end.

Only exit 0 with empty stdout is an empty hook. Every other non-zero exit is an error to report loudly.

On a normal (exit 0, non-empty) result, spawn each agent per its `mode` field (single → one subagent for the whole plan; batch → split the relevant file list into batches of ~10 and spawn parallel subagents, one Task call per batch, all in a single message). The spawn mode comes from the agent's mode frontmatter field — never from sniffing the agent body text.

Spawning hook agents

Hook agents are spawned with the Task tool using subagent_type="{agent-name}". The orchestrator only has <testing> and <code-standards> in context (see Project Configuration) — it does NOT have <architecture>. Pass each hook agent the project context it needs verbatim:

**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.**

For a `batch` agent, send one prompt per batch:

## 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}

For a `single` agent, send one prompt covering the whole plan, including the plan name, the changed-files list, and <testing> + <code-standards> verbatim.

If a hook agent needs project architecture, that is out of scope for this

orchestrator — it does not load <architecture>. Do NOT fabricate an

## Project Architecture paste here.

Step 4a: End-of-Run Hooks (Post-Implementation → Tests → Commit)

When all tasks are complete, run the end-of-run hook sequence. The control flow is strictly:

post-implementation → run full test suite → pre-commit → commit → post-commit

**CRITICAL INVARIANT: NOTHING is committed until AFTER the full test suite

passes.** This ensures no broken code is ever committed. The pre-commit hook

runs after tests pass and before the commit; post-commit runs after

the commit and before the push/PR prompt.

1. Run the `post-implementation` hook:

Resolve and run enrolled agents via the Hook Discovery routine with HOOK = post-implementation. To give batch agents a file list, first compute the changed files (this stages everything only to read the list, then unstages — nothing is committed). The plans directory is left out: plan files are working state, not code for agents to review.

git add -A && git reset -q -- "$PLANS_DIR" && git diff --name-only --cached && git reset HEAD