skills/execute-plan/SKILL.md

name, description, user-invocable

name	description	user-invocable
execute-plan	Execute an implementation plan by splitting it into parallel tasks, delegating to worker subagents, verifying with reviewers, and running tests. Use when there is a plan (session decisions or file) that needs to be implemented.	true

execute-plan

Parameters

Pass an optional plan file path: /skill:execute-plan PLAN.md. Without a file, use the current session's accumulated decisions as the plan.

Protocol

1. Read or collect the plan

• If a file path is given as argument, read it.
• Otherwise, use the current session's decisions/direction as the plan.

2. Delegate to planner

Fork a planner subagent with outputSchema to produce a structured task graph:

{
  "tasks": [
    {
      "id": "string",
      "description": "string",
      "instructions": "string",
      "outputs": ["file/path.ts"],
      "reads": [],
      "dependsOn": ["task-id"],
      "runTests": ["cmd"]
    }
  ]
}

The planner must ensure parallelizable tasks have disjoint outputs.

3. Execute by dependency waves

Topologically sort the tasks. For each wave (tasks with no unmet dependencies):

• Launch all wave tasks in parallel with fresh context worker subagents.

• Wrap each worker's prompt with:

  You are the sole writer for the task below. Do not modify any files outside the listed outputs. If you encounter problems, report them clearly. On success, report what you changed and confirm completion.

• Wait for the wave to complete (wait({ all: true })).

4. Handle failures

• Collect all failures from the wave.
• Delegate to a reviewer subagent (fresh context) to investigate failures and produce a repair plan (a new task graph covering only unresolved problems).
• Recursively invoke execute-plan on the repair plan.
• Cap: maximum 5 repair iterations. After that, present remaining problems to the user and ask how to proceed.
• Prompt the user only for conceptual/scope-level problems that cannot be fixed without altering the plan's scope.

5. Verify results

When all waves complete successfully:

• Launch a parallel reviewer fanout (fresh context) with distinct angles:
  1. Correctness / regressions
  2. Guideline conformance
  3. Tests / validation
• Each reviewer may run tests as needed but must report only overall findings, not test output.
• If reviewers find problems, generate a repair plan and go to step 4.

6. Run tests

Run any test commands from the original plan context (runTests fields or globally known test commands). Report the outcome. Failures generate a repair plan (step 4).

7. Present results

Summarize to the user: what was implemented, verification status, test results, and any remaining open items.

Constraints

• Workers run with fresh context.
• One writer thread per worktree; do not launch parallel workers modifying the same files.
• Do not enact the plan without going through this protocol.