Skip to content

vt-c-executing-plans

Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches

Plugin: core-standards
Category: Other
Command: /vt-c-executing-plans

Executing Plans

Overview

Load plan, review critically, execute tasks in batches, report for review between batches.

Core principle: Batch execution with checkpoints for architect review.

Announce at start: "I'm using the executing-plans skill to implement this plan."

The Process

Step 0.5: Check for Existing Wave State

Before loading the plan, check for prior execution state and orphaned worktrees.

1. Resume detection: - Check specs/[N]-feature/wave-state.yaml (derive spec directory from current branch or .active-spec) - If it exists with incomplete execution: 

Resuming wave execution from Wave 2 (3/5 tasks completed)
- Skip completed waves when execution begins - Start from the first incomplete wave - If it does not exist: proceed with fresh execution

2. Orphan worktree detection: - Run git worktree list at startup - Check for worktrees matching the pattern .worktrees/wave-* - If found and no active wave-state.yaml references them: 

Found orphaned worktrees from a previous run:
  .worktrees/wave-2-task-2.1
  .worktrees/wave-2-task-2.2
Clean up? [Yes / Keep for inspection]
- On cleanup: git worktree remove <path> --force

wave-state.yaml format: 

execution_id: "<ISO-8601 timestamp>"
current_wave: 2
max_waves: 3
tasks:
  "1.1":
    status: completed
    wave: 1
  "2.1":
    status: completed
    wave: 2
  "2.2":
    status: failed
    wave: 2
    error_summary: "Test assertion failed"
  "3.1":
    status: blocked
    wave: 3
    blocked_by: "2.2"

Step 1: Load and Review Plan

  1. Read plan file
  2. Review critically - identify any questions or concerns about the plan
  3. If concerns: Raise them with your human partner before starting
  4. If no concerns: Create TodoWrite and proceed

Step 1.5: Parse Task Dependencies

After loading the plan, parse tasks.md to extract tasks and their dependency relationships.

1. Extract structure from tasks.md: - Phase headings: ## Phase N: Name (optionally with [P] marker for parallelizable phases) - Task IDs: ### N.M Task Name - Explicit dependency annotations: **Depends on**: X.Y or **Depends on**: Phase N - Inline references: prose like "reuses algorithm from 1.1" or "extends the parser in 2.3" — extract the referenced task ID as a dependency - File annotations: **File**: path/to/file (used for overlap detection in Step 1.6)

2. Build dependency graph:

Pattern Rule
No annotations, no [P] Default: Task N.M depends on ALL tasks in Phase N-1
[P] on phase heading Tasks in that phase have NO implicit phase dependency
**Depends on**: X.Y Explicit dependency on task X.Y (overrides phase default for that task)
**Depends on**: Phase N Explicit dependency on ALL tasks in Phase N
Inline reference to task ID (e.g., "reuses X.Y") Implicit dependency on the referenced task
No dependencies found anywhere All tasks are independent (single wave)

3. Detect circular dependencies: - Run cycle detection on the dependency graph - If a cycle is found: report ALL tasks involved in the cycle with their dependency chains - Stop execution — do not attempt to break cycles automatically

⛔ Circular dependency detected:
  Task 2.1 → depends on 3.1 → depends on 2.1
Resolve the cycle in tasks.md before re-running.

If the plan has only one task, skip wave computation entirely and execute directly (existing behavior).

If no dependencies are parseable (legacy flat plan without phases/task IDs), fall back to existing flat batch execution (Step 2 legacy behavior).

Step 1.6: Compute Execution Waves

Using the dependency graph from Step 1.5, compute wave groupings via topological sort with level assignment.

Algorithm:

  1. Let resolved = set of tasks already completed (from wave-state.yaml if resuming, otherwise empty)
  2. Repeat until all tasks are assigned to a wave: a. wave = tasks whose dependencies are ALL in resolved (or have no dependencies) b. If wave is empty and unassigned tasks remain → circular dependency (should have been caught in Step 1.5) c. Sort wave: by priority (P0 > P1 > P2) if tasks have priority annotations, then by task ID (N.M numeric ordering) d. If len(wave) > 5: split into sub-waves of 3–5 tasks each e. Add wave to wave list; add wave's tasks to resolved

File-overlap detection (before execution):

For each wave with 2+ tasks, check if any tasks declare modifications to the same file paths (from **File**: or **Action**: sections in tasks.md):

⚠ File overlap detected in Wave 2:
  Task 2.1 and Task 2.3 both modify: src/parser.ts
Options:
  (a) Serialize: move Task 2.3 to a new sub-wave after 2.1 completes
  (b) Proceed anyway (risk merge conflicts)

If user chooses serialize: split the overlapping task into a sub-wave that runs after the other task completes.

Display wave plan to user:

Wave Execution Plan
═══════════════════════════════════════════
Wave 1 (sequential — 1 task):
  1.1  Setup environment

Wave 2 (parallel — 3 tasks):
  2.1  Implement parser
  2.2  Implement validator
  2.3  Write unit tests

Wave 3 (sequential — 1 task):
  3.1  Integration testing

Total: 5 tasks in 3 waves
═══════════════════════════════════════════

Ask user to confirm before starting execution.

Step 2: Execute Waves

If no dependency graph was built (legacy flat plan): fall back to flat batch execution: 1. Group tasks into batches of 3 2. For each batch: a. Mark each task as in_progress in TodoWrite b. Execute each task in order — follow the plan step exactly, run any verification steps c. Mark each task as completed when done d. After the batch: report results and wait for user feedback before continuing 3. Continue with the next batch of 3 until all tasks are complete

If wave plan exists: execute wave-by-wave as follows.

For each wave (sequential):

2a. Pre-wave setup: - Check wave-state.yaml — skip completed waves when resuming - Display: "Starting Wave N (M tasks)"

2b. Dispatch tasks:

Single-task wave (no worktree needed): - Execute task directly in current directory - Same as existing batch execution behavior

Multi-task wave (parallel with worktree isolation): - For each task in the wave, dispatch an Agent with isolation: "worktree", passing: - Task description from tasks.md (action, file paths, verification steps) - Clear goal and constraints - Expected output: summary of what was done - Dispatch ALL agents in a single message (parallel execution) - Wait for all agents to complete

2c. Post-task handling:

Successful tasks: - If worktree used: merge worktree branch back to current branch 

git merge <worktree-branch> --no-ff -m "Wave N: Task M.N — <task name>"
- If merge conflict: pause, display conflict, ask user to resolve before continuing - Clean up worktree after successful merge

Failed tasks: - Record error summary in wave-state.yaml - Do NOT block other tasks in the same wave - Mark dependent tasks in later waves as blocked - Clean up the failed task's worktree (but leave in-progress worktrees intact if user aborts mid-wave, for manual inspection)

2d. Wave checkpoint: - Write current state to specs/[N]-feature/wave-state.yaml - Display checkpoint summary: 

Wave 2 Complete
─────────────────────────────────────
✓ 2.1  Implement parser        completed
✓ 2.2  Implement validator     completed
✗ 2.3  Write unit tests        failed
  Error: Test assertion failed

Impact: 3.1 is blocked (depends on 2.3)
─────────────────────────────────────
- Ask user: Continue to next wave? / Retry failed tasks? / Stop?

Step 3: Report

When batch complete: - Show what was implemented - Show verification output - Say: "Ready for feedback."

Step 4: Continue

Based on feedback: - Apply changes if needed - Execute next batch - Repeat until complete

Step 5: Complete Development

After all tasks complete and verified: - Announce: "I'm using the finishing-a-development-branch skill to complete this work." - REQUIRED SUB-SKILL: Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice

When to Stop and Ask for Help

STOP executing immediately when: - Hit a blocker mid-batch (missing dependency, test fails, instruction unclear) - Plan has critical gaps preventing starting - You don't understand an instruction - Verification fails repeatedly

Ask for clarification rather than guessing.

When to Revisit Earlier Steps

Return to Review (Step 1) when: - Partner updates the plan based on your feedback - Fundamental approach needs rethinking

Don't force through blockers - stop and ask.

Remember

  • Review plan critically first
  • Follow plan steps exactly
  • Don't skip verifications
  • Reference skills when plan says to
  • Between batches: just report and wait
  • Stop when blocked, don't guess