diff options
| author | Jesse Vincent <jesse@primeradiant.com> | 2026-09-17 15:51:07 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-17 17:14:38 -0700 |
| commit | 2b89c4c3f375ab479c3bc0644a76fea78a0f44bb (patch) | |
| tree | 9e3d16f234fb7ad2045c8fdaa3944176b80bbbb6 /skills/executing-plans | |
| parent | b070d8258ddb712c67dbaecef384f9eb7a876f5d (diff) | |
Rebuild executing-plans as a first-class inline execution modeinline-execution
A cheaper execution mode alongside subagent-driven development: the
session implements every task itself under the same workspace, ledger
and stopping rules, with one fresh whole-branch review on the most
capable model at the end. Helper scripts task-start/task-done keep the
ledger and test log honest; the final fix pass re-grades findings and
fixes Critical/Important under TDD. writing-plans' handoff, SDD's
when-to-use text and two README lines change to match.
Diffstat (limited to 'skills/executing-plans')
| -rw-r--r-- | skills/executing-plans/SKILL.md | 384 | ||||
| -rwxr-xr-x | skills/executing-plans/scripts/task-done | 52 | ||||
| -rwxr-xr-x | skills/executing-plans/scripts/task-start | 28 |
3 files changed, 423 insertions, 41 deletions
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index b51d97d..9535a2b 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -1,64 +1,366 @@ --- name: executing-plans -description: Use when you have a written implementation plan to execute in a separate session with review checkpoints +description: 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 --- # Executing Plans -## Overview +Execute the plan yourself, task by task, in this session: no implementer +subagent per task, no reviewer per task. One fresh-context review of the +whole branch at the end. -Load plan, review critically, execute all tasks, report when complete. +**Why inline:** Subagent-driven development pays for a fresh implementer +and a fresh reviewer on every task, each re-reading the codebase from zero. +Inline execution pays for one context (yours) plus one reviewer at the end. +What it gives up is a fresh context per task and a second pair of eyes per +task. This skill keeps what those two things bought, by other means: the +brief is the spec, the ledger is your memory, TDD is the per-task gate, and +the final reviewer is the second pair of eyes. -**Announce at start:** "I'm using the executing-plans skill to implement this plan." +**Core principle:** The plan already did the thinking. Execute it exactly, +prove each step with a test you watched fail and then pass, and leave a +record that survives your own forgetting. -**Note:** Tell your human partner that Superpowers works much better with access to subagents (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill. +**Narration:** between tool calls, narrate at most one short line — the +ledger and the tool results carry the record. + +**Continuous execution:** Do not pause to check in with your human partner +between tasks. They chose inline execution to spend less, not to answer +"should I continue?" after every task. Execute all tasks from the plan +without stopping. + +**Rulings, not stalls.** Conflicts, ambiguities, plan defects — decide them. +The spec is the binding authority, the plan is its argument, and your +judgment settles what neither answers. Record every decision in the ledger +as `Ruling: <what you decided> — <why> — <what it costs if wrong>`, and keep +going. Deviating from the plan without a ledgered ruling is a decision made +in secret. + +Four things stop you, and only these: an irreversible or destructive +operation; a security-sensitive action; a side effect outside this worktree +that norms say you ask about first (a merge, a push to a shared branch, a +publish); and a plan so broken that every path forward is a guess. For +those, stop and ask. + +## When to Use + +- You have a plan from superpowers:writing-plans and your human partner + chose inline execution at the handoff. +- Your harness has no subagent tool (see the per-platform references in + `../using-superpowers/references/`). Never fabricate a dispatch; run + the plan here. +- Tasks are mostly independent — the same precondition as + superpowers:subagent-driven-development. + +A fully specified plan makes inline execution transcription plus testing: +it runs well on a mid-tier session model, and the one place the most +capable model earns its cost is the final review, which this skill +dispatches separately. Tell your human partner so when they choose inline. + +Prefer superpowers:subagent-driven-development when your human partner +wants a review gate on every task, or when the plan is long enough that +its later tasks would run on a compacted context. Inline execution over a +long plan still works — the ledger is what makes it recoverable — but the +last tasks get the least of you. ## The Process -### Step 1: Load and Review Plan -1. Ensure an isolated workspace: use superpowers:using-git-worktrees to create one or verify the existing one -2. Read plan file -3. Review critically - identify any questions or concerns about the plan -4. If concerns: Raise them with your human partner before starting -5. If no concerns: Create todos for the plan items and proceed +```dot +digraph process { + rankdir=TB; + + subgraph cluster_per_task { + label="Per Task"; + "task-start: brief + BASE; read the brief" [shape=box]; + "Work the steps in order: TDD, run every verification, read every output" [shape=box]; + "Step output matches plan's Expected?" [shape=diamond]; + "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [shape=box]; + "Commit as the plan's commit steps say" [shape=box]; + "Completion contract met?" [shape=diamond]; + "task-done: run tests, ledger the result; mark todo complete" [shape=box]; + } + + "Setup: worktree, workspace + ledger, read plan + spec, pre-flight scan" [shape=box]; + "More tasks remain?" [shape=diamond]; + "Final whole-branch review (fresh reviewer if you have one)" [shape=box]; + "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" [shape=box]; + "Final review clean: delete this plan's workspace" [shape=box]; + "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; + + "Setup: worktree, workspace + ledger, read plan + spec, pre-flight scan" -> "task-start: brief + BASE; read the brief"; + "task-start: brief + BASE; read the brief" -> "Work the steps in order: TDD, run every verification, read every output"; + "Work the steps in order: TDD, run every verification, read every output" -> "Step output matches plan's Expected?"; + "Step output matches plan's Expected?" -> "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [label="no"]; + "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" -> "Work the steps in order: TDD, run every verification, read every output"; + "Step output matches plan's Expected?" -> "Commit as the plan's commit steps say" [label="yes, last step"]; + "Commit as the plan's commit steps say" -> "Completion contract met?"; + "Completion contract met?" -> "Work the steps in order: TDD, run every verification, read every output" [label="no - finish the task"]; + "Completion contract met?" -> "task-done: run tests, ledger the result; mark todo complete" [label="yes"]; + "task-done: run tests, ledger the result; mark todo complete" -> "More tasks remain?"; + "More tasks remain?" -> "task-start: brief + BASE; read the brief" [label="yes"]; + "More tasks remain?" -> "Final whole-branch review (fresh reviewer if you have one)" [label="no"]; + "Final whole-branch review (fresh reviewer if you have one)" -> "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger"; + "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" -> "Final review clean: delete this plan's workspace"; + "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch"; +} +``` + +## Setup + +Ensure the work happens in an isolated workspace: use +superpowers:using-git-worktrees to create one or verify the existing one. +Never start implementation on a main/master branch without your human +partner's explicit consent. + +Conversation memory does not survive compaction. An inline executor that +loses its place re-implements tasks whose commits already exist — the same +failure as a controller re-dispatching them, paid for in your own context. +Track progress in a ledger file, not only in todos. Harness todos are a +live view; the ledger is the record. + +The workspace and ledger are shared with superpowers:subagent-driven-development +— same directory, same format — so a plan can change executors mid-flight +and the new one resumes from the same ledger. + +- Each plan owns a workspace: at skill start, run + `../subagent-driven-development/scripts/sdd-workspace PLAN_FILE` — it + prints the plan's git-ignored directory + (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to every + artifact for THIS plan: ledger, briefs, review packages. Another plan's + directory is never yours to read or write. +- Check for this plan's ledger at `<workspace>/progress.md`. If its first + line names your plan file, tasks with a `Task <N>: complete` line are + DONE — do not redo them; resume at the first task without one. Their + commits exist in git even when your context no longer remembers making + them: after compaction, trust the ledger and `git log` over your own + recollection. A ledger whose first line names a different plan file is + another plan's progress: leave it and start your own, fresh. +- Create the ledger with its identity as the first line: + `# SDD ledger — plan: <plan file path>`. +- `git clean -fdx` will destroy the workspace (it's git-ignored scratch); + if that happens, recover from `git log`. + +Read the plan once, note its context and Global Constraints, and create a +todo per task. If the plan names a Spec, read that too: the spec is the +authority the plan argues from, and conflicts inside the plan resolve +against it. A plan with no reachable spec gets a ledger note saying so — +rulings made without one are provisional. + +**REQUIRED SUB-SKILL:** load superpowers:test-driven-development now, +before Task 1. It governs every step of every task below; a plan whose +steps already say "write the failing test first" does not exempt you +from reading it. + +Before Task 1, scan the plan for conflicts between tasks. The plan's +Interfaces blocks tell you where to look: for every task that consumes +what an earlier task produces, one ledger row — the two tasks, what one +produces against what the other consumes, and what you found. Tasks that +share nothing get no row; a plan whose tasks share nothing gets the single +line `Pre-flight: no shared interfaces`. Rule on each conflict a row +surfaces with the spec as the binding authority, record the ruling beside +its row, and start Task 1. Each task's own text is checked when you read +its brief, not here. + +## The Task Loop + +Everything you print, and every tool result, stays resident in your +context for the rest of the session. Redirect long test output to a file +in the workspace and read its tail; read a brief, not the whole plan. + +### 1. Take the task + +- Run this skill's `scripts/task-start PLAN_FILE N`. It prints the brief + path and BASE (the commit the task's range is cut from) in one call. + Read the brief for every task, including ones you remember from setup: + what you remember is a summary, the brief has the exact values, + signatures, and test cases. +- Mark the task's todo in_progress. + +Every tool call is a turn that re-reads your whole context. Bookkeeping +rides along with work — a ledger append in the same call as the commit, +never in a call of its own. + +### 2. Work the steps + +The plan's steps are already in RED-GREEN order; follow them in that +order under superpowers:test-driven-development, loaded at setup. A test +step's code is written first and run first. Watching it fail is a step, +not a formality — a test that passes before the implementation exists is +a finding about the test. + +Every step that runs a command has an `Expected:` line. Run the command, +read its output, and compare. Three outcomes: + +- **Matches.** Next step. +- **The code is wrong.** Use superpowers:systematic-debugging. Find the + cause; never patch the symptom to make the step's output match. +- **The plan is wrong** — a step contradicts the spec, an interface from an + earlier task doesn't match what this task consumes, a command that + cannot work. Rule on the smallest change that satisfies the spec, ledger + it as `Task <N>: Ruling: <finding> — <what you decided and why>`, and + continue. The ruling is carried, not remembered: later tasks that touch + the same interface read it from the ledger. + +Commit as the plan's commit steps say. A task that spans several commits +is fine; BASE is what the review range is cut from, never `HEAD~1`. + +### 3. The completion contract + +Before a task's ledger line, all of the following are true, with evidence +in this session — not inferred from the diff looking right: + +- Every test the brief names exists and ran in this task, and you read + the output. +- The final test run for the task passed — `task-done` is that run, and + it writes the command and result into the ledger line. +- Every `Expected:` line in the brief was compared against real output. +- Every deviation from the brief has a `Ruling:` line in the ledger. + +**REQUIRED SUB-SKILL:** superpowers:verification-before-completion governs +the claim. If any item is missing, the task is not complete: finish it. + +### 4. Complete the task + +Run this skill's `scripts/task-done PLAN_FILE N BASE -- <test command>` +with the test command the brief names for the whole task. It runs the +tests, keeps the full output in the workspace, prints the tail, and — only +if they pass — appends the completion line to the ledger: + +`Task <N>: complete (commits <base7>..<head7>, tests: <command> → <result>)` + +A failing run records nothing; the task is not complete. When it records, +mark the todo complete and take the next task. + +## Final Review + +Run `../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD` +(MERGE_BASE = the commit the branch started from, e.g. +`git merge-base main HEAD`) and review from the file it prints. + +**With a subagent tool:** dispatch the reviewer on the most capable +available model — the whole-branch review is a judgment task — using +superpowers:requesting-code-review's +[code-reviewer.md](../requesting-code-review/code-reviewer.md), with the +package path, the plan and spec paths, and a pointer to the ledger's +`Ruling:` lines so it can weigh the calls you made. Specify the model +explicitly; an omitted model inherits the session's, which may not be the +most capable. This is the one fresh context the whole run buys. Do not +skip it, and do not replace it with your own read of the diff. + +**Without a subagent tool:** read code-reviewer.md and perform that review +yourself against the package, as a separate pass after the last task's +ledger line. Write `Final review: self-review (no subagent tool)` to the +ledger, and say so in your final message: a self-review by the author is +weaker than a fresh reviewer, and your human partner decides whether that +is enough before merge. + +Sort the findings before you act on any of them. The reviewer's severity +labels are advice; the gate is yours. Re-grade first, by effect: the +spec is a vision document, and a finding's grade is what a reasonable +person using this software gets if it ships, not whether the spec names +the input that triggers it — a reviewer who set a finding at Minor +because the spec was silent has graded the spec, not the effect. Then: + +- **Critical and Important** enter the fix pass. +- **Minor** goes to the ledger as `Final: minor (deferred): <one-liner>` + and to your final message under "Deferred minors". Minors never enter + the fix pass, and never become rulings — a ruling is a decision about a + conflict, not a note that you declined a polish suggestion. + +Fix the Critical and Important findings yourself — you are the +implementer here — in ONE pass. Each fix is verified by TDD, not by a +second reviewer: write the test that reproduces the finding, watch it +fail, make it pass, then run the whole suite. Record each in the ledger as +`Final: fixed <finding> — <test name> RED→GREEN, suite <N>/<N>`. A fix +without a test that failed first is not verified; a suite that is not +green after the pass means the pass is not over. Do not dispatch a +re-review: it would re-read a diff whose covering tests already answer +"addressed" and whose suite run already answers "broke nothing". + +A finding you decide not to fix is a ruling — `Final: Ruling: <finding> — +<why the code stands> — <cost if wrong>` — and reaches your human partner +in the rulings list. There is no second fix pass. + +## Finish + +Before you delete anything, collect every ledger line containing +`Ruling:` into your final message under "Rulings I made", in the order you +made them, each with what it costs if wrong, and every `minor (deferred)` +line under "Deferred minors". Both lists are exhaustive. Your final +message is the only place the decisions you took on your human partner's +behalf — and the findings you chose not to act on — reach them. + +When the final review is clean and its fixes are committed, delete this +plan's workspace directory — the git history is the record now. Sibling +directories belong to other plans; leave them alone. + +Use superpowers:finishing-a-development-branch. + +## Common Rationalizations + +| Excuse | Reality | +|--------|---------| +| "I remember what Task N says" | You remember a summary. The brief has the exact values. Read it. | +| "The plan's code is right, skip watching the test fail" | A test you never saw fail proves nothing. It is one step. Run it. | +| "I'll run the full suite at the end instead of per step" | Per-step runs are how you learn which step broke it. The end-of-task run is the contract, not a substitute. | +| "The plan is wrong here, I'll just do the right thing" | Do the right thing and ledger the ruling. Unledgered deviation is a decision made in secret. | +| "I'll write the ledger lines after a few tasks" | Compaction does not wait for a convenient moment. One line per task, in the same message as the commit. | +| "Let me check in before the next task" | They chose inline to spend less. Progress prompts spend their time instead. Only the four stops stop you. | +| "I read my own diff carefully; the final reviewer is redundant" | Same author, same blind spots. The reviewer is the only fresh context this run buys. | +| "Tests should pass, the change was trivial" | "Should" is not evidence. The contract requires the command and its output. | +| "Subagents are slow and expensive, I'll skip the final review too" | Inline already removed the per-task reviewers. One review of the whole branch is the floor, not the ceiling. | +| "The reviewer said Minor, so it's Minor" | The label graded the spec's silence. Grade what the person gets. Re-grade, then gate. | +| "The fix is obvious, no need for a failing test first" | The failing test is the only proof the finding was real and is now gone. Without it you have a diff and a hope. | +| "I'll fix the minors too while I'm in there" | Every minor you fix is a test, a fix, and a suite run your partner did not ask for. Ledger them; your partner decides. | + +## Example Workflow + +``` +You: I'm using the executing-plans skill to implement this plan inline. -### Step 2: Execute Tasks +[Setup: worktree verified] +[Read plan once: docs/superpowers/plans/feature-plan.md; spec read] +[Resolve workspace: sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start] +[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger] +[Create todos for all tasks] -For each task: -1. Mark as in_progress -2. Follow each step exactly (plan has bite-sized steps) -3. Run verifications as specified -4. Mark as completed +Task 1: Hook installation script -### Step 3: Complete Development +[task-start plan 1 → brief read; BASE a1b2c3d] +[Step 1: write failing test — written] +[Step 2: run it — FAIL: install_hook not defined. Matches Expected.] +[Step 3: implement — written] +[Step 4: run it — PASS 1/1. Matches Expected.] +[Step 5: commit — d4e5f6a] +[Contract: tests ran, output read, no deviations] +[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)] -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 +Task 2: Recovery modes -## When to Stop and Ask for Help +[task-start plan 2 → brief read; BASE d4e5f6a] +[Step 2: run failing test — FAIL, but on an import error: Task 1 exported + installHook, brief consumes install_hook] +[Ruling: brief's consumer name is a typo against Task 1's Produces block; + use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename] +[Steps 2-5 as planned; commit b7c8d9e] +[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)] -**STOP executing immediately when:** -- Hit a blocker (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.** +[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model] +Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor. +[Re-grade: Important stands; minors → ledger as deferred] +[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit] +[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12] -## When to Revisit Earlier Steps +Rulings I made: +- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename) -**Return to Review (Step 1) when:** -- Partner updates the plan based on your feedback -- Fundamental approach needs rethinking +Deferred minors: +- README lacks a usage example +- recovery.js could split verify/repair into two files -**Don't force through blockers** - stop and ask. +[Delete this plan's workspace — the record now lives in git] -## Remember -- Review plan critically first -- Follow plan steps exactly -- Don't skip verifications -- Reference skills when plan says to -- Stop when blocked, don't guess -- Never start implementation on main/master branch without explicit user consent +Using superpowers:finishing-a-development-branch. +``` diff --git a/skills/executing-plans/scripts/task-done b/skills/executing-plans/scripts/task-done new file mode 100755 index 0000000..dd09871 --- /dev/null +++ b/skills/executing-plans/scripts/task-done @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Close one task of an inline plan execution in a single call: run the task's +# test command, keep its full output in the workspace, print the tail, and — +# only if the command succeeded — append the completion line to the ledger. +# A failing command records nothing: the task is not complete. +# +# Usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...] +# BASE is the SHA task-start printed; the completion line records BASE..HEAD. +# Exit: the test command's exit status. +set -euo pipefail + +if [ $# -lt 5 ] || [ "$4" != "--" ]; then + echo "usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]" >&2 + exit 2 +fi + +plan=$1 +n=$2 +base=$3 +shift 4 +sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)" + +git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; } + +dir=$("$sdd/sdd-workspace" "$plan") +log="$dir/task-${n}-tests.log" +ledger="$dir/progress.md" + +# Render the command the way a person would type it, for the ledger line. +cmd="" +for a in "$@"; do + case "$a" in + *[[:space:]\"\;\|\&]*) cmd="$cmd '$a'" ;; + *) cmd="$cmd $a" ;; + esac +done +cmd=${cmd# } + +rc=0 +"$@" > "$log" 2>&1 || rc=$? + +tail -n 5 "$log" +if [ "$rc" -ne 0 ]; then + echo "task-done: test command exited $rc; Task $n NOT recorded (full output: $log)" >&2 + exit "$rc" +fi + +last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) +[ -f "$ledger" ] || printf '# SDD ledger — plan: %s\n' "$plan" > "$ledger" +line="Task $n: complete (commits $(git rev-parse --short=7 "$base")..$(git rev-parse --short=7 HEAD), tests: $cmd → $last)" +printf '%s\n' "$line" >> "$ledger" +echo "ledger: $line" diff --git a/skills/executing-plans/scripts/task-start b/skills/executing-plans/scripts/task-start new file mode 100755 index 0000000..fab75b5 --- /dev/null +++ b/skills/executing-plans/scripts/task-start @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Begin one task of an inline plan execution in a single call: extract the +# task's brief (via subagent-driven-development's task-brief, so both skills +# share one workspace) and record BASE, the commit the task's review range is +# cut from. One tool call instead of two, because every call in an inline +# session is a turn that re-reads the whole context. +# +# Usage: task-start PLAN_FILE TASK_NUMBER +# Prints: +# brief: <path to the task's brief file> +# base: <full SHA of HEAD> +set -euo pipefail + +if [ $# -ne 2 ]; then + echo "usage: task-start PLAN_FILE TASK_NUMBER" >&2 + exit 2 +fi + +plan=$1 +n=$2 +sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)" + +out=$("$sdd/task-brief" "$plan" "$n") +brief=$(printf '%s\n' "$out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p') +[ -n "$brief" ] || { echo "task-brief did not report a path: $out" >&2; exit 1; } + +echo "brief: $brief" +echo "base: $(git rev-parse HEAD)" |
