executing-plans

name: executing-plans description: Executes written implementation plans efficiently using per-batch sub-agent coordinators. This skill should be used when the user has a completed plan.md, asks to "execute the plan", or is ready to run batches of independent tasks in parallel following BDD principles. argument-hint: [plan-folder-path] user-invocable: true allowed-tools: ["TaskCreate", "TaskUpdate", "TaskList", "TaskGet", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "Bash(git-agent:)", "Bash(git:)", "Bash(${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh:)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh:)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/jsonl-emit.sh:*)"]

Executing Plans

Execute written implementation plans through phase-based orchestration: Plan Review → Task Creation → per-batch coordinator dispatch + verification → Git Commit → Completion. Each batch runs in a fresh sub-agent (Agent tool) so the main agent's context never accumulates batch execution transcripts. Execution spans multiple batches across turns — the recommended way to run it is wrapped in Claude Code's built-in /goal (see below).

Recommended: run wrapped in `/goal`

Launch it under Claude Code's built-in /goal (v2.1.139+) so the run continues to completion instead of stopping after a batch:

/goal "Claude has emitted the Phase 6 completion message 'Plan execution complete. All N tasks verified and committed' AND has reported the final commit hash from Phase 5 in the transcript" /superpowers:executing-plans <plan>

/goal is a user-typed outer wrapper — it must prefix the invocation; a skill cannot enable it for itself mid-run. The evaluator judges only what Claude narrates in the transcript (it does NOT read files or run commands) — phrase the condition against narrated output, never filesystem state. Note: executing-plans commits once at Phase 5 after all batches finish — do NOT phrase the condition around a "per-batch commit hash" or it will never match; per-batch evaluator verdicts are progress signals, not completion signals. Full semantics and condition phrasing: ../../skills/references/goal-wrapper.md. The skill body itself is single-turn-driven and orients via scripts/batch-progress.sh at the top of every turn (see Step 1 below).

Step 1 of every iteration — orient via batch-progress.sh

Before doing anything else, run:

bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path>

The script reads the plan dir, counts sprint-contract-batch-*.md and handoff-summary-*.md files, and emits a precise next-action directive ("Batch 3 active — Agent next" / "Batch 2 closed — TaskList then commit-or-next-batch" / "Batch 4 not yet started — Phase 3 steps 0-1-2"). Read the output as your authoritative "where am I" signal and follow the directive. This replaces the old loop's per-iteration filesystem scan + injection — same data, scoped to this skill.

Skip this step on the very first invocation (no plan-path resolved yet) — fall through to "First Action" below.

CRITICAL: Bail-Out Check (run first, on first invocation only)

Read _index.md. If "Execution Plan" YAML lists < 5 tasks in a single batch, bail out: skip coordinator + sprint contract; execute tasks inline and commit. --force token in $ARGUMENTS bypasses. See ./references/bail-out.md for the response template. If that inline work needs a plain "keep going until condition X holds" loop, use /goal directly.

First Action — Resolve Plan Path

Resolve the plan path, then orient.

Resolve the plan path:
- If $ARGUMENTS provides a path (e.g., docs/plans/YYYY-MM-DD-topic-plan/), use it
- Otherwise, pick the *-plan/ folder whose basename sorts last under YYYY-MM-DD-*-plan/ — i.e., the highest date prefix in the name, not filesystem mtime. Use ls -1d docs/plans/*-plan/ 2>/dev/null | sort | tail -1 (do NOT use ls -t / ls -1dt — directory mtimes get bumped when an older folder's files are edited, which makes it rank above a freshly-created folder). Use the result directly (no confirmation).
- If no plan folder is found, abort with a clear error message naming the expected path pattern
Run scripts/batch-progress.sh <plan-path> to print the current batch state. If batches already exist, follow the script's directive directly (skip Phase 1/2 — they ran on a prior turn). Otherwise proceed with Initialization.

Initialization (first turn only)

Plan Check: Verify the folder contains _index.md with "Execution Plan" section.
Context: Read _index.md completely. This is the source of truth for your execution.

Background Knowledge

Core Principles: Review before execution, batch verification, explicit blockers, evidence-driven approach.

MANDATORY SKILL: superpowers:behavior-driven-development must be loaded regardless of execution mode.

Definition of Done

See ./references/definition-of-done.md (non-negotiable; overrides all other guidance).

Phase 1: Plan Review & Understanding

Read Plan: Read _index.md to understand scope, architecture decisions, and extract inline YAML task metadata from the "Execution Plan" section.
Understand Project: Explore codebase structure, key files, and patterns relevant to the plan.
Check Blockers: See ./references/blocker-and-escalation.md.

Phase 2: Task Creation (MANDATORY)

See ./references/phase-2-task-creation.md.

Phase 3: Batch Execution Loop (Context-Reset Architecture)

See ./references/phase-3-orchestration.md and ./references/batch-execution-playbook.md.

Phase 4: Verification & Feedback

See ./references/phase-4-verification.md.

Phase 5: Git Commit

Commit the implementation changes using git-agent (with git fallback).

Actions:

Run: git-agent commit --intent "<feature description>" --co-author "Claude <Model> <Version> <noreply@anthropic.com>"
On auth error, retry with --free flag
Fallback: If git-agent is unavailable or fails, stage files with git add and use git commit with conventional format

See ../../skills/references/git-commit.md for patterns, templates, and requirements. Commit only after all tasks are completed; use a meaningful feature scope.

Phase 6: Completion

Verify all tasks are complete, then output the completion summary.

Final Task Audit: Use TaskList to confirm every task has status completed. If any task is in_progress or pending, do NOT proceed — return to Phase 3 to finish remaining tasks.
Summary message: "Plan execution complete. All [N] tasks verified and committed." (human-facing; not a machine trigger — see note below).

Completion log is automatic. You do NOT write docs/retros/plans-completed.jsonl yourself. The plugin's single Stop hook (hooks/stop-state-sync.sh) detects plan completion from durable on-disk state — every batch handed off (handoff-summary-* count ≥ batch count) plus a git commit touching the handoff-state.md modified-files set — and appends the plan_completed event mechanically, first-completion-only. Detection is state-based, not keyed off any sentence you emit, so it survives paraphrasing or a skipped summary. That log is what /superpowers:retrospective Phase 5a reads completion_commit from. See ../retrospective/references/evolution-protocol.md §Plan Completion Log Schema for the row shape.

Exit Criteria

All tasks executed and verified, evidence captured, no blockers, final verification passes, git commit completed. This skill runs fully autonomously — no user approval step exists. For unattended multi-turn continuation, wrap in /goal (see top of file).

References

./references/blocker-and-escalation.md - Guide for identifying and handling blockers
./references/batch-execution-playbook.md - Pattern for batch execution
./references/definition-of-done.md - Non-negotiable completion rules
./references/phase-2-task-creation.md - TaskCreate / dependency tier workflow
./references/phase-3-orchestration.md - Main-agent batch loop and coordinator spawn
./references/phase-4-verification.md - Evidence, handoff, and intra-plan learning
../../skills/references/git-commit.md - Git commit patterns and requirements (shared cross-skill resource)
../../skills/references/goal-wrapper.md - /goal wrapper semantics and condition phrasing (shared cross-skill resource)
./references/evaluation-file-formats.md - Evaluation file format definitions (sprint contract, evaluation report, handoff summary)
./references/sprint-contract-template.md - Sprint contract template and negotiation protocol
./references/handoff-template.md - Handoff summary template for long plans
./references/intra-plan-learning.md - Pattern scan, batch handoff, and checklist evolution formats
./scripts/batch-progress.sh - Filesystem-derived batch progress orientation (run as Step 1 of every iteration)