executing-plans

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 929 words, so you can see where the weight sits before reading.

1. 11. Load the plan and challenge it160 words
2. 22. Prepare the workspace146 words
3. 33. Run each task162 words
4. 44. When something goes wrong173 words
5. 55. Risky steps59 words
6. 66. Review as you go46 words
7. 77. Finish116 words

The skill itself

Read it before you install it

---
name: executing-plans
description: Carry out a written implementation plan in the current session - question the plan before touching anything, work through the tasks in order, check each one against real command output, stop and ask when blocked or when the plan itself is wrong, and finish with a report of what was done and where it deviated. Use when the user hands over a plan or says "execute the plan", "implement this plan", "follow the plan" or "start building from the plan", or when a half-finished plan needs resuming. Not for writing or revising the plan (use writing-plans), for design questions (use brainstorming), or for work that has no plan.
license: MIT
---

# Executing plans

Follow the plan. Do not improve on it silently. Load it, question it, execute it task by task with evidence, and stop when it stops making sense.

## 1. Load the plan and challenge it

Before editing anything, read the whole plan and the spec it points to. Look for:

- an ordering error, where a task needs something a later task creates
- a check that cannot be run ("confirm it works") instead of a command with an expected result
- unstated environment assumptions: runtime versions, running services, credentials, test data
- steps that name a type, function or file that no task defines
- steps that destroy or send something: deleting, resetting, force-pushing, migrating shared data, deploying, publishing, spending, messaging other people

Raise concerns with the user before starting, each with a concrete fix. If there are none, say so in one line and go on.

```
The plan is workable. Two questions. Task 4's check says "confirm it works";
I suggest running the API tests and expecting all of them to pass. And no
runtime version is stated; I will use the one in the repository's config
unless you say otherwise.
```

## 2. Prepare the workspace

- Check the branch and the state of the working tree. Do not start on the default branch (main or master) without the user's explicit consent. Offer a new branch or a separate working copy.
- Uncommitted changes you did not make belong to the user. Never discard, stash, reset or overwrite them without asking. If they overlap files the plan touches, ask first.
- When resuming, compare the plan's checkboxes with the real state of the repository (what is committed, what the tests say) before continuing. If they disagree, tell the user. Do not reset files to match the plan.
- If the plan exists only in the conversation, save it to a file before the first change, so progress can be tracked and a fresh session can resume.
- Track progress in the plan's own checkboxes, or in whatever task tracker the host offers.

## 3. Run each task

For each task, in the plan's order:

1. Re-read the task, what it consumes and produces, and its acceptance criteria.
2. Do the steps as written. Keep edits inside the task.
3. Where the plan puts a test first, follow test-driven-development: see it fail for the right reason, then pass.
4. Run each verification and read the output. A task is done when the real output matches the expected result, not when the code looks right. Say what you ran and what it printed.
5. Commit only when the plan's step says to. The user's approval of the plan covers that.
6. Tick the box.

Do not stop between tasks to ask whether to continue, unless the user asked for checkpoints or the plan marks them. At a checkpoint, show what is done and the verification results, then wait. How often to pause is the user's call. A pause every few tasks is common, and no number is right for every plan.

## 4. When something goes wrong

Stop and ask, never guess, when a dependency is missing, an instruction is unclear or contradictory, the plan has a gap that blocks you, or a check keeps failing. When a check fails, work out which of three things is wrong.

| What is wrong | What to do |
|---|---|
| The implementation | Fix it and rerun. If the cause is not obvious, find the root cause first (systematic-debugging). |
| The test | Fix the test, and tell the user what was wrong with it and why. Never edit a test only to make it pass. |
| The plan | Stop. Report it with a proposed correction. Once the user agrees, update the plan with a short note of what changed and why. Never rewrite a requirement silently. |

After two failed attempts at the same step, stop and reassess instead of trying a third time. Two is a sensible default, not a measured limit, and the user can set another.

Never reconcile a confusing state by resetting files.

## 5. Risky steps

A step that deletes data, rewrites history, force-pushes, deploys, publishes, runs a migration on shared data, spends money or contacts other people needs the user's explicit yes at that moment, unless the user already approved that exact step. If such a step was interrupted partway, inspect the real state of the target before retrying. Do not replay it blindly.

## 6. Review as you go

After each task, or each checkpoint, read your own diff against the task: requirements met, nothing extra added, callers still work, error paths handled, the user's changes untouched. For larger or riskier work ask for an independent review (requesting-code-review), and treat what comes back with receiving-code-review.

## 7. Finish

- After the last change, run the plan's final verification and the whole test suite. Read the output. Report every failure by name, including ones you did not cause.
- Report in this shape:

```
Plan: <path>      Branch: <name>
Tasks: <done> of <total> complete

Verification: <command> -> <result>, one line per command
Deviations from the plan: <what, why, who approved it>, or "none"
Not done or open: <anything left, or "none">
```

- Offer the user the choices for the branch: merge it, open a pull request, keep it as it is, or discard it. Do what they choose. Never merge, push or discard on your own. Keep the plan file until the handoff is finished.

The second audit

What we found in the sources

It keeps the short, strict skeleton of the version most others copy (obra/superpowers: review the plan critically, follow it, verify, stop when blocked) and adds what the variants found missing: a triage for failing checks, a safe handling of the user's uncommitted work, a rule for risky steps, and a closing report. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• obra/superpowers ↗ · Primary basis · MIT

  Load the plan and review it critically, raising concerns with the user before starting; follow the steps as written and run the stated verifications; stop and ask instead of guessing when blocked, when an instruction is unclear, or when verification keeps failing; return to review when the plan changes; never start on the main or master branch without the user's consent; finish by letting the user choose how to integrate the work.

• lsy041015/orchestra ↗ · Added ideas · MIT

  Do not stop between tasks to ask whether to continue, but do stop for irreversible, security-sensitive or externally visible operations; inspect your own diff against the task after each task; when the plan is wrong, record a short ruling instead of silently rewriting requirements; preserve the user's unrelated edits; report the real commands and output, including limits and unresolved findings.

• yimwoo/hotl-plugin ↗ · Added ideas · MIT

  Check the working tree before starting and never stash or discard silently ("hidden state mutation weakens governance"); pause at checkpoints only as the user or plan asks; a sensitive step needs approval at the time it runs, and an interrupted effect is inspected and reconciled instead of replayed; never skip a failed step silently; a final review before declaring completion. Its runtime, scripts and branch-naming machinery were left out.

• brunob54/superpowers-orchestrator ↗ · Added ideas · MIT

  Stop after two failed attempts at the same step and reassess rather than forcing a third; keep edits scoped to the current task; do not skip plan steps without the user's approval of the deviation; do not claim completion without fresh command output.

• jnmetacode/superpowers-zh ↗ · Added ideas · MIT

  Read in Chinese. The file marks these as its own additions to the translated upstream: review checks on the plan (steps out of dependency order, verification that is too vague to run, unstated environment assumptions), a triage for a failing check (implementation bug, wrong test, or wrong plan, each with its own action), and an execution report that lists deviations from the plan.

• sitien173/superpowers-ccg ↗ · Added ideas · MIT

  Reconcile the recorded progress with the real state of the repository before resuming, and never reconcile conflicting state by resetting files. Its OpenMCP phases, handover file and job routing were left out.

• thepragmaticbear/bearpaws ↗ · Added ideas · MIT

  If the approved plan exists only in the session, save it to a file before the first change.

What changed

• The description now says what the skill does, lists the phrases that should trigger it, and says what it is not for. The upstream description says "in a separate session with review checkpoints", which the upstream body does not match (see findings).
• Rewritten as one self-contained file: no references to a using-git-worktrees skill, a finishing skill, a subagent skill, a platform-references folder or a task-list tool. Workspace safety and the closing choices are written out inline.
• Dropped the product note telling the agent to inform the user that the toolkit works much better with subagents; no source gives evidence for it.
• Checkpoint cadence is left to the user or plan. Upstream's body has none, one variant pauses every 3 tasks, another does not stop between tasks; none states a basis for a number. The two-failed-attempts cap is kept as a stated default, not a measured limit.
• Added the failing-check triage (fix the implementation, fix the test and say so, or stop and correct the plan), a rule for risky steps, a report shape, and an example of how to raise concerns about a plan.
• Made it explicit that the agent never merges, pushes or discards on its own and keeps the plan file until the handoff is finished.

Problems found in the sources

• !obra/superpowers: The description promises "review checkpoints" and "a separate session", but the body has no checkpoints (it executes every task and stops only on blockers), and writing-plans in the same repository offers this skill as the inline option in the current session. It names three namespaced skills (worktrees, subagent-driven development, finishing a branch), points at a per-platform references folder that a lone copy lacks, and tells the agent to advertise that the toolkit works better with subagents.
• !yimwoo/hotl-plugin: Not self-contained: it needs the hotl-rt runtime, several shell scripts, workflow file conventions and a Branch/Worktree preflight tied to a helper script, and it pauses after every 3 tasks with no stated basis. Its no-auto-stash rule and its handling of uncertain effects are careful.
• !gylove1994/superpowers-deepseek-v4: Upstream's text with a worktree-consent skill and a list of required companion skills added; it keeps the claim that quality is significantly higher with subagents, with no basis stated.
• !thepragmaticbear/bearpaws: Upstream recast in XML-style tags, with namespaced integration skills. It repeats the "quality is significantly higher" claim for subagents without a stated basis.
• !brunob54/superpowers-orchestrator: Uses a Graphviz block, requires commit trailers on every commit, routes UI work to a skill it does not include, and names a worktree skill and a finishing skill that are not in the bundle.
• !lsy041015/orchestra: Calls scripts (sdd-workspace, task-start, task-done) that belong to another skill and a ledger convention that a lone copy lacks, plus namespaced skills throughout. Its rule not to stop between tasks differs from the pause after every 3 tasks in yimwoo/hotl-plugin; this reads as a design choice, not a flaw.
• !jnmetacode/superpowers-zh: Declares inside the file which sections are additions to upstream. Uses a task-list tool and namespaced skills, and the sample report uses emoji check marks.
• !sitien173/superpowers-ccg: Runs only for a folder-layout plan with a PLAN.md and a .handover.md, loads another skill first and needs OpenMCP; it cannot be used without that tooling.

What was dropped

• Runtime state files, owner tokens, heartbeats, action receipts and budget checks from yimwoo/hotl-plugin.
• Ledger scripts and worker presets from lsy041015/orchestra.
• Mandatory Session: and Stage: commit trailers from brunob54/superpowers-orchestrator, which impose a commit format the user did not ask for.
• The frontend-design hand-off for UI tasks in brunob54/superpowers-orchestrator, because it names a skill that is not in this repository.
• OpenMCP gates, phase directories and handover schema from sitien173/superpowers-ccg.
• A pause after every third task (hotl-plugin and one Chinese variant), because no source gives a basis for the number.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/executing-plans ~/.claude/skills/

Pairs with