Skip to main content
skill CX Codex

executing-plans · fradser — Claude Code skill: what it does and install

executing-plans — a skill for Claude Code, Codex, and Cursor. Executes written implementation plans in task batches using isolated coordinator sub-agents and a single final commit.

MIT 126 installs ★ 597 updated 2026-11-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add FradSer/dotclaude --skill executing-plans -a claude-code
Open on GitHub

What executing-plans does

This skill coordinates plan execution across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It reads the _index.md plan file, tracks current state using batch-progress.sh, and spawns a fresh sub-agent for each batch. This structure keeps batch transcripts out of the main agent's conversational context.

Execution stops before batch dispatch if _index.md contains fewer than five tasks in a single batch, switching to inline execution unless passed --force. It strictly mandates superpowers:behavior-driven-development and superpowers:verification-before-completion, refusing completion claims that lack fresh test evidence. Git commits occur once in Phase 5 rather than per batch.

What it helps with

  • execute multi-step engineering plans from structured markdown directories
  • prevent context window bloat by isolating tasks inside sub-agents
  • enforce mandatory verification gates before marking tasks complete
  • block execution on invalidated plans marked with expired status

Example prompts for the agent

  • /superpowers:executing-plans docs/plans/2025-03-auth-system-plan/
  • /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 docs/plans/2025-03-auth-system-plan/
  • /superpowers:executing-plans --force docs/plans/2025-03-quick-refactor-plan/

How to install executing-plans

1Skills CLI (Vercel)

npx skills add FradSer/dotclaude --skill executing-plans -a claude-code

2Manually: put the files in place

~/.claude/skills/executing-plans/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/executing-plans/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about executing-plans

How to install executing-plans in Claude Code?

Run npx skills add FradSer/dotclaude --skill executing-plans -a claude-code in your terminal.

What does executing-plans do?

It orchestrates implementation plans by splitting tasks into batches, delegating each to a sub-agent, verifying outputs, and committing changes to Git.

Why wrap executing-plans in the /goal command?

Wrapping it in Claude Code's /goal prevents execution from halting after a single batch turn, keeping the agent active until the final completion message appears.

Source text

SKILL.md · MIT
---
name: executing-plans
description: Executes a written implementation plan via per-batch sub-agent coordinators with verification and commits between batches. Use when a plan exists and the user wants it executed, or invokes /superpowers:executing-plans <plan-path>.
argument-hint: [plan-folder-path]
user-invocable: true
disable-model-invocation: true
allowed-tools: ["TaskCreate", "TaskUpdate", "TaskList", "TaskGet", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "Workflow", "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:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/task-brief.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/review-package.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/lib/task-ledger.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 `bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/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
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.**

1. 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
2. Run `bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path>` to print the current batch state. The bare path `scripts/batch-progress.sh` does NOT resolve — the skill runs in the plan's repository cwd, not the plugin dir, so the script must be addressed by its absolute plugin path. 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)

1. **Plan Check**: Verify the folder contains `_index.md` with "Execution Plan" section. Consult the docs index before spawning any batch: `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <plan-path>`. If the row's status is `expired:`, REFUSE — the plan has been invalidated by a retro and is no longer authoritative; tell the user which retro invalidated it and stop. If the status is `implemented:<old-sha>` (rework after ship), run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "wip"` BEFORE spawning batch 1 so the index reflects that the plan is being worked again. Then consult memory: run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active` and Read the top topically-relevant matches before Phase 1 "Plan Review."
2. **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.

> **CRITICAL — two internal gate skills are load-bearing, not optional.** Every implementer sub-agent prompt MUST instruct loading `superpowers:verification-before-completion` before reporting any task done (no completion claims without fresh verification evidence pasted in the return), and the batch coordinator MUST load `superpowers:receiving-code-review` before acting on an evaluator REWORK verdict (verify each rework item against the codebase; no blind implementation). Omitting either from a coordinator prompt is a protocol violation. Details: `./references/batch-execution-playbook.md` (Agent Prompt Template + Rework Loop).

## Definition of Done

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

## Phase 1: Plan Review & Understanding

1. **Read Plan**: Read `_index.md` to understand scope, architecture decisions, and extract inline YAML task metadata from the "Execution Plan" section.
2. **Understand Project**: Explore codebase structure, key files, and patterns relevant to the plan.
3. **Check Blockers**: See `./references/blocker-and-escalation.md`.
4. **Pre-Flight Conflict Scan** (once, before Phase 2): Check every task's explicit instructions against the resolved `code-v{N}.md` checklist for contradictions (e.g. a task mandating a stub or duplicated logic the checklist forbids). No-op if none found. See `./references/preflight-conflict-scan.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`.

> **CRITICAL — declare a model on every sub-agent dispatch.** When you spawn a batch coordinator or any reviewer via the Agent tool, always pass an explicit `model` (`sonnet` for ordinary implementation/verification, `opus` only for hard reasoning or final whole-branch review, `haiku` for mechanical sweeps). An unspecified `model` silently inherits the session's most expensive tier — left to choose, dispatches drift to top-tier and burn the budget. Pick the cheapest tier the work allows; never let it default.

> **CRITICAL — the native `Workflow` tool is opt-in only.** Never call `Workflow` unless the user has explicitly opted into multi-agent orchestration (said "use a workflow" / equivalent, or ultracode is on). A run under `/goal` must NOT silently fan out background agents. Without opt-in, use the default bounded Agent-tool spawn rounds and surface the option in one line. Opt-in rules and task mapping: `../../skills/references/workflow-orchestration.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**:
1. Run: `git-agent commit --intent "<feature description>" --co-author "Claude <Model> <Version> <[email protected]>"`
2. On auth error, retry with `--free` flag
3. **Fallback**: If git-agent is unavailable or fails, invoke the `/git:commit` skill via the Skill tool; full ladder in `../../skills/references/git-commit.md`

**CRITICAL — flip the plan's docs-index row post-commit (do-not-defer).** After the implementation commit lands, flip the plan's index row to `implemented`: `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "implemented:$(git rev-parse --short HEAD)"`. Then commit the index update as its own tiny commit: `git-agent commit --no-stage --intent "mark <plan> implemented in docs index"`. NEVER use `--amend` — it would rewrite history and confuse the Stop hook's `completion_commit` detection (the hook keys off the tip commit on the plan's modified-files set; an amended tip silently repoints it).

**CRITICAL — conditional memory-write step, folded into the same follow-up commit above (do-not-defer).** Gated on the existing intra-plan-learning variety-gap signal (`references/intra-plan-learning.md:54` — all checklist items PASS for a batch but the batch required 2+ rework rounds before reaching PASS). If any batch this run hit that signal, also write `docs/memory/pitfall_<slug>.md` capturing the recurring rework cause, then run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category pitfall`, staged into the same dedicated follow-up commit created above — do not create a separate commit for it. This variety-gap trigger is explicitly distinct from the separate hard-abort cap at batch-execution-playbook.md:165 (max 2 rework rounds before escalation), which is NOT a memory-write trigger — that cap governs the rework loop's hard stop, not memory capture. If no batch hit the variety-gap signal, this step is a no-op.

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.

1. **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.
2. **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/preflight-conflict-scan.md` - Phase 1 scan for task-vs-checklist contradictions before Phase 2
- `./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)
- `../../skills/references/workflow-orchestration.md` - native `Workflow` escalation for large parallel batches (opt-in rules + task mapping)
- `./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)
- `../../lib/task-brief.sh` - Extract one task's text to a file the implementer reads from disk (diff/task-text-as-files)
- `../../lib/review-package.sh` - Generate a net-diff review package file the evaluator reads from disk
- `../../lib/task-ledger.sh` - Durable per-task completion ledger; check before dispatch, append after PASS

© FradSer · MIT · FradSer/dotclaude

Similar skills

All skills for Agent setup: memory, context, orchestration →

executing-plans by other authors comes first.

executing-plans Jesse Vincent executing-plans runs an implementation plan in the current session instead of assigning each task to a subagent. Use it for inline work with TDD, a decision ledger, and a final branch review. CX Codex +1 242,988installs executing-plans mdiri-ai executing-plans is a Claude Code skill that carries out written implementation plans with review checkpoints. It pauses when a blocker needs clarification. CX Codex +1 ★ 6,467repo stars executing-plans osmontero The executing-plans Claude Code skill carries out a written implementation plan in stages, with checks between batches. It activates when subagents cannot be used or tasks are too coupled to split up. CX Codex +1 107installs executing-plans dev-toolings The executing-plans skill guides Claude Code through an approved implementation plan, with test-first steps and a separate commit for each one. Use it for multi-step work or to resume after an interruption. CX Codex +1 ★ 234repo stars implement Garrick Aden-Buie (@gadenbuie) implement coordinates the rollout of a plan file by splitting work across parallel subagents. It checks git branch status and monitors progress. CX Codex +1 572installs flanner elandlabs flanner keeps AI agent plans in one managed folder, tracks revisions, and exposes their history. Use it for architecture notes and migration plans. CX Codex +1 ★ 5repo stars flow-next-work Gordon Mickel flow-next-work executes Flow-Next specs and tasks step by step: manages Git branches, tracks task states in .flow/ via flowctl, runs tests, and creates clean commits. CX Codex +1 ★ 730repo stars paseo-handoff getpaseo paseo-handoff transfers the current task to a fresh agent with context, decisions, and constraints. Useful when moving work into a clean session or an isolated git worktree. CX Codex +1 5,600installs resolve-issue sentimony resolve-issue — a skill for Claude Code and Codex that orchestrates a GitHub issue from intake through implementation and review. Runs upon providing an issue reference, supporting manual approvals or --auto mode. CX Codex +1 1,200installs agile-workflow agent-skills agile-workflow walks an agent through the agile task cycle step by step: sync, pick a task, implement, review, merge. Useful when you want a guided process instead of one-off commands. CX Codex +1 373installs

From the same set16

The whole set →
patent-architect patent-architect searches prior art through SerpAPI or WebSearch and drafts Chinese patent application forms. Handy when documenting technical innovations. CX Codex +1 622installs behavior-driven-development behavior-driven-development — a BDD skill for feature work, bug fixes, and executable tests. It turns behavior examples into failing tests before implementation. CX Codex +1 151installs commit-and-push commit-and-push — a skill for Claude Code, Codex, Cursor, and other platforms that generates atomic commits using Conventional Commits standard via git-agent and pushes them to the remote repository. CX Codex +1 126installs brainstorming brainstorming — a skill for Claude Code and five other tools that turns raw ideas into ready BDD specs. It researches your codebase autonomously and commits the technical design without asking questions mid-run. CX Codex +1 124installs writing-plans writing-plans — a skill for Claude Code, Codex, Cursor and other platforms that transforms a finished design into an executable implementation plan. CX Codex +1 123installs refactor-project refactor-project — a skill for Claude Code, Codex, Cursor and other agents that runs automated refactoring across every file in the project at once. Cuts duplication, normalises patterns, and strips legacy code in a single pass. CX Codex +1 122installs plugin-best-practices plugin-best-practices validates Claude Code plugin structure, manifests, and architecture against framework standards. Ensures your plugin meets requirements before marketplace submission. CX Codex +1 121installs commit This skill creates atomic conventional commits through git-agent. Use it when a short intent should become a focused Git commit. CX Codex +1 121installs

Project sponsors

Companies that keep this analytics open