/run-plan

name: run-plan
description: Use when you have a written implementation plan to execute. Loads the plan, reviews critically, executes tasks in dependency order, and reports completion. Triggers when the user says "run the plan", "execute the plan", or "let's start implementing".

Run Plan

Loads a written plan document, reviews it critically, then executes tasks in dependency order using a worker-validator loop.

Core Principle

Do not follow plans blindly. If the plan has issues, flag them before executing. But if the plan is clear, execute it faithfully.

Hard Gates

1. **Read and review the plan first.** Always review the entire plan before executing. 2. **Criteria are binding; steps are the route.** Never skip a task or alter its Acceptance Criteria. Steps are followed as written when they match reality — when reality contradicts a step (stale anchor, renamed symbol, changed API), the worker adapts minimally to satisfy the criteria and reports the deviation. Silent deviation is prohibited; so is failing a task because the plan's route was stale. 3. **Never skip verification.** Test runs, expected output checks, and other verifications stated in the plan must be performed. 4. **Parallelizable tasks must always run in parallel.** Tasks with no dependencies and no shared file modifications must be dispatched concurrently. Sequential grouping is prohibited. 5. **Worker and Validator must be separate subagents.** The main agent must NOT perform worker or validator roles inline. Each must be dispatched as an independent subagent via the Agent tool. 6. **Validator must not receive worker output.** The validator subagent receives only the plan's task goal and acceptance criteria. It must never receive the worker's diff, logs, or implementation details. The validator judges by reading the code and running tests independently. 7. **Stop when blocked.** Do not guess. Ask the user.

When To Use

• After a plan has been crafted with the `plan-crafting` skill
• When the user says "run this plan" or "execute the plan"
• When a plan document exists and implementation should begin

When NOT To Use

• When no plan document exists yet (use `plan-crafting` first)
• When work scope is still ambiguous (return to the `clarification` skill)
• Single-step tasks that don't need a plan

Process

Step 0: Project Capability Discovery

Before reviewing the plan, discover what the project offers for verification and execution:

1. **Verification infrastructure** — read the plan's `Verification Strategy` header. If present, use it. If absent, run the same discovery as plan-crafting:

• e2e tests → integration tests → verification skills/agents → test suite → build+lint
• Record the discovered command for use in the E2E Gate (Step 3)

2. **Available agents and skills** — scan for project-level agents (`.claude/agents/`), plugin agents, and project skills (`.claude/skills/`) that workers can leverage. If the plan references specific agents in task steps, verify they exist before execution begins.

3. **If an agent/skill is referenced but missing:** Notify the user. Do not block execution — workers can execute steps directly without the agent.

Step 1: Load and Review Plan

1. Read the plan file 2. Review critically:

• Are task dependencies correct?
• Do file paths exist?
• Are there any placeholders in steps?
• Does every task have a Goal and binary-decidable Acceptance Criteria? (If not, the validator contract cannot be filled — return to `plan-crafting`)
• Is anything unclear?

3. If issues found: notify the user before starting 4. If no issues: create tasks via TaskCreate and proceed

Step 2: Task Execution Loop

Each task runs through a **Compliance Check → Worker Implementation → Validator Review** cycle. If the validator rejects, feedback is sent back to the worker for re-implementation.

digraph task_loop {
    rankdir=TB;
    "Compliance check (subagent)" [shape=box];
    "Worker implements (subagent)" [shape=box];
    "Validator reviews (subagent)" [shape=box];
    "Pass?" [shape=diamond];
    "Task complete" [shape=doublecircle];

    "Compliance check (subagent)" -> "Worker implements (subagent)";
    "Worker implements (subagent)" -> "Validator reviews (subagent)";
    "Validator reviews (subagent)" -> "Pass?";
    "Pass?" -> "Task complete" [label="Pass"];
    "Pass?" -> "Worker implements (subagent)" [label="Fail\nfeedback delivered"];
}

For each task, perform the following cycle:

**2-1. Compliance Check (subagent)**

Before starting a task, verify that the current task aligns with the plan:

• Compare the plan's defined steps against current file state
• Confirm that predecessor tasks' outputs exist as expected
• Verify that all dependency tasks have completed
• Confirm no other task modifying the same file is in progress

If issues found: notify the user and resolve before proceeding.

**2-2. Worker Implementation (subagent, via Agent tool)**

Dispatch a subagent (worker) via the Agent tool to execute the task's steps:

• The worker follows the steps as written when they match the actual codebase
• **Bounded adaptation:** when a step contradicts reality (stale anchor, renamed symbol, API shape differs from the plan's code block), the worker makes the smallest change of route that still satisfies the task's Goal and Acceptance Criteria, and records the deviation in its report
• **Adaptation limits — stop and report to the main agent instead of adapting when the fix would:** change an interface another task consumes, touch files outside the task's Files list, or alter an acceptance criterion. These are plan defects, not route noise — the main agent handles them via the Plan Amendment Protocol (see 2-3)
• The worker performs each step's verification (test runs, etc.)
• **If the plan references a project agent or skill for a step**, the worker should use it via the Agent tool or Skill tool. If the agent/skill is unavailable, execute the s