obra/superpowers · skills/executing-plans/SKILL.md
executing-plans
“A strict, ledger-keeping way to run a coding plan yourself: TDD-gated, recoverable, a bit wordy”
What it does
Runs a written implementation plan task by task in the current session, with no per-task subagents. Each task is TDD-gated and logged in a ledger file that survives compaction. Plan defects become recorded rulings, and one fresh reviewer checks the whole branch at the end.
- When the agent uses it
- When executing an implementation plan yourself in this session, because your partner chose inline execution or no subagent tool is available.
- Who it is for
- For superpowers users running writing-plans output on a budget. Not for anyone outside that ecosystem, since it depends on sibling skills and their scripts.
- What it costs
- 266 lines, about 4.9k tokens once the agent loads it.
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available
What it tells the agent to do
- Work in a git worktree, run sdd-workspace, and create or resume this plan's ledger at progress.md
- Read the plan and spec, load the TDD skill, and ledger a pre-flight scan of interfaces shared between tasks
- Per task: run task-start, read the brief, follow the RED-GREEN steps, and compare each output to its Expected line
- Fix wrong code by debugging; for a wrong plan, ledger a Ruling and continue; commit as the plan says
- Run task-done with the brief's test command so the completion line is ledgered only if tests pass
- Build a review package and get a fresh reviewer, or self-review; re-grade findings, fix Critical/Important in one TDD pass
- Report rulings and deferred minors, delete the plan's workspace, then use finishing-a-development-branch
Lines worth reading
Straight from the file, with why each one matters.
line 3your human partner chose inline execution, or no subagent tool is available
The trigger names a situation, not a task. It never says what the skill produces.
line 181Every tool call is a turn that re-reads your whole context.
Rare context-cost thinking: it bundles ledger writes into the commit call instead of spending a separate turn.
line 315Unledgered deviation is a decision made in secret.
The sharpest rule here. The agent may depart from the plan, but never silently.
line 321The label graded the spec's silence. Grade what the person gets.
A telling stance: the agent overrides the reviewer's severity labels, judging by the effect on users.
line 322Without it you have a diff and a hope.
The best line in the rationalizations table, and a fair summary of untested fixes.
Watch out for
- Medium
Runs every task without checking in and settles plan conflicts itself. You see those rulings only in the final message.
line 27Do not pause to check in with your human partner
- Low
Runs helper scripts from a sibling skill folder that were not available to review. They execute with the agent's permissions.
line 126../subagent-driven-development/scripts/sdd-workspace PLAN_FILE
- Low
Deletes the plan's workspace directory at the end. It is scoped and git-ignored, but the ledger and logs go with it.
line 87Final review clean: delete this plan's workspace
The scorecard
- TriggerSays when to use it6/10
Clear about when, silent about what it does; an agent must infer the job.
- FocusOne clear job8/10
One job: execute a plan inline. Final review and fix pass stay on that job.
- LeanLight to load5/10
~4.9k tokens; rationale, a dot graph and a long excuses table repeat the steps.
- ConcreteSteps you can follow8/10
Exact scripts, ledger line formats and done criteria; relies on unseen sibling files.
- SafeSafe to run7/10
Four explicit hard stops; autonomy and unseen local scripts are the catch.
What it does well
- The ledger's first line names the plan, so work resumes after compaction or switches executors mid-flight.
- Names exactly four things that halt it: destructive ops, security-sensitive actions, external side effects, a hopeless plan.
- Saves context: test output goes to a file and only the tail is read; briefs are read instead of the whole plan.
How it could be better
Say what it does first in the description
The agent picks skills from the description, and this one names only the situation, not the procedure or result.
Adddescription: Runs a superpowers implementation plan task by task in this session, with TDD per step, a progress ledger and one final whole-branch review. Use when executing a plan inline: your human partner chose inline execution, or no subagent tool is available.
Move rationale and excuses table to a reference
The why-paragraphs, dot graph and rationalizations table stay loaded all session and mostly restate the steps.
AddFor why inline execution works and the excuses to reject, read [rationale.md](rationale.md) if you are tempted to skip a step.
Check sibling scripts exist before starting
The skill fails mid-run if the subagent-driven-development scripts or its own scripts are missing.
AddBefore setup, confirm `../subagent-driven-development/scripts/sdd-workspace`, `../subagent-driven-development/scripts/review-package`, `scripts/task-start` and `scripts/task-done` exist. If any is missing, stop and tell your human partner which <skill> is not installed.
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.