diff options
| author | Jesse Vincent <jesse@primeradiant.com> | 2026-09-18 17:28:09 -0700 |
|---|---|---|
| committer | Jesse Vincent <jesse@primeradiant.com> | 2026-09-18 17:28:09 -0700 |
| commit | cffb7c95b64524cd59ddb4d1c9d2c2675482315e (patch) | |
| tree | 38263673a455cdf894f19301aa284009d7edb1d8 /skills/executing-plans | |
| parent | 835c5f951cce3e169b755218a9d8f26b5854f0d5 (diff) | |
Plans as directories, and a boundary check before each next planplan-directories
A plan is a directory: 00-header.md plus one NN-<task>.md per task. The
brief for task N is the header plus that file; sdd-workspace, task-brief,
review-package, task-start and task-done take a file or a directory.
Before starting the next plan in a set, executors run
scripts/plan-boundary, which names every identifier the plan consumes
from earlier plans that the code as built does not contain, in the next
plan and in every later plan's Plan Set entry, and fix the plan until it
prints clean. Measured: the directory form executes the same as the file
form (inline 9/9, SDD 6/6, same cost) and plans at the same volume; the
gate kept a five-plan set consistent with the code 2/2 against a planted
cross-plan naming conflict, where a per-ruling duty managed 0/2.
Diffstat (limited to 'skills/executing-plans')
| -rw-r--r-- | skills/executing-plans/SKILL.md | 22 | ||||
| -rwxr-xr-x | skills/executing-plans/scripts/plan-boundary | 59 | ||||
| -rwxr-xr-x | skills/executing-plans/scripts/task-done | 2 | ||||
| -rwxr-xr-x | skills/executing-plans/scripts/task-start | 2 |
4 files changed, 77 insertions, 8 deletions
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 9703f20..98acdee 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -107,6 +107,11 @@ digraph process { ## Setup +A plan is one file, or a directory (`00-header.md` plus one `NN-<task>.md` +per task, the form writing-plans writes). Every script below takes either; +"the plan" means the whole of it, and "the header" means the part above +Task 1 or `00-header.md`. + 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 @@ -123,7 +128,7 @@ The workspace and ledger are shared with superpowers:subagent-driven-development 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 + `../subagent-driven-development/scripts/sdd-workspace PLAN` — 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 @@ -136,7 +141,7 @@ and the new one resumes from the same ledger. 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>`. + `# SDD ledger — plan: <plan path>`. - `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if that happens, recover from `git log`. @@ -169,7 +174,7 @@ 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 +- Run this skill's `scripts/task-start PLAN 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, @@ -221,7 +226,7 @@ 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>` +Run this skill's `scripts/task-done PLAN 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: @@ -233,7 +238,7 @@ mark the todo complete and take the next task. ## Final Review -Run `../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD` +Run `../subagent-driven-development/scripts/review-package PLAN 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. @@ -301,7 +306,12 @@ partner's behalf — and the findings you chose not to act on — reach them. When a plan follows this one in the Plan Set, finishing this plan means starting that one, under the same method and in this session: the set was -reviewed once, and only the four stops stop you. +reviewed once, and only the four stops stop you. Before its Task 1, run +`scripts/plan-boundary NEXT_PLAN` (this skill's directory): it names +every identifier the plan's Consumes lines take from earlier plans that +the code as built does not contain. Fix each one in the plan file, ledger +it as a ruling, and re-run until it prints `boundary: clean`. The plan runs +as written after that, so a name it still gets wrong is executed wrong. 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 diff --git a/skills/executing-plans/scripts/plan-boundary b/skills/executing-plans/scripts/plan-boundary new file mode 100755 index 0000000..2735910 --- /dev/null +++ b/skills/executing-plans/scripts/plan-boundary @@ -0,0 +1,59 @@ +#!/usr/bin/env bash +# Check the next plan against the code as built before starting it. +# +# Collects every backticked identifier in the plan's task-level `Consumes` +# lines and in its own Plan Set entry, drops the ones this plan itself +# produces (its `Produces` lines and the functions/types its code blocks +# define), and reports each remaining name that does not occur in the +# repository's source outside plans/ and docs/. Then, for every plan that +# comes after it in the same directory, checks the names its Plan Set entry +# attributes to plans already complete ("from plan K: ...", K before the next +# plan), so a ruling in the plan just finished cannot leave a later plan +# consuming a name the code does not have. A hit is a plan that says what the +# code does not: fix the plan, re-run until it prints "boundary: clean". +# +# A plan is a file or a directory (00-header.md plus NN-<task>.md files). +# +# Usage: plan-boundary NEXT_PLAN +# Exit: 0 when clean, 1 when any consumed name is missing, 2 on usage error. +set -euo pipefail +[ $# -eq 1 ] || { echo "usage: plan-boundary NEXT_PLAN" >&2; exit 2; } +next=${1%/}; [ -e "$next" ] || { echo "no such plan: $next" >&2; exit 2; } +root=$(git rev-parse --show-toplevel 2>/dev/null || pwd) +stop='^(and|or|the|from|of|in|a|an|to|with|for|int|string|bool|byte|rune|error|nil|true|false|func|type|struct|var|const|Plan|Task|Tasks|plan|plans|md|s|m|g|t|x|y|dt|None|self|str|list|dict|float|Decimal|date|datetime|time|Duration)$' +idents() { # backticked spans on stdin -> identifiers, one per line; paths and files skipped + grep -o '`[^`]*`' | tr -d '`' | grep -v -e '/' -e '\.md$' | grep -o '[A-Za-z_][A-Za-z0-9_]*' | sort -u +} +plan_text() { if [ -d "$1" ]; then cat "$1"/00-header.md "$1"/[0-9][0-9]-*.md 2>/dev/null; else cat "$1"; fi; } +in_code() { git -C "$root" grep -q -w -- "$1" -- ':!plans/*' ':!docs/*' ':!*.md' 2>/dev/null; } +missing=0; found=0 +check() { # names on stdin, label + local n; while IFS= read -r n; do [ -n "$n" ] || continue + if in_code "$n"; then found=$((found+1)); else echo "missing in code: $n (consumed by $1)"; missing=1; fi + done +} +# 1. the next plan: task-level Consumes plus its own Plan Set entry, minus what it produces +name=$(basename "$next"); text=$(plan_text "$next") +body=$(printf '%s\n' "$text" | awk '/^## Plan Set/{skip=1;next} /^## /{skip=0} !skip') +own=$(printf '%s\n' "$text" | awk '/^## Plan Set/{f=1;next} /^## /{f=0} f' | grep -F -- "$name" || true) +consumes=$( { printf '%s\n' "$body" | grep -i -A8 'Consumes'; printf '%s\n' "$own"; } | idents | grep -v -E "$stop" || true) +produces=$( { printf '%s\n' "$body" | grep -i -A8 'Produces' | idents; printf '%s\n' "$body" | awk '/^```/{f=!f;next} f' | grep -o -E '^(func(tion)? (\([^)]*\) )?[A-Za-z_][A-Za-z0-9_]*|type [A-Za-z_][A-Za-z0-9_]*|class [A-Za-z_][A-Za-z0-9_]*|def [A-Za-z_][A-Za-z0-9_]*)' | awk '{print $NF}'; } | sort -u || true) +check "$name" < <(comm -23 <(echo "$consumes") <(echo "$produces")) # no pipe: check must set missing/found in this shell +# 2. every later plan in the same directory: names its Plan Set entry attributes to plans already complete +parent=$(dirname "$next"); idx=0; k=0 +for p in $(ls -d "$parent"/* 2>/dev/null | sort); do k=$((k+1)); [ "${p%/}" = "$next" ] && idx=$k; done +if [ "$idx" -gt 0 ]; then k=0 + for p in $(ls -d "$parent"/* 2>/dev/null | sort); do + k=$((k+1)); [ "$k" -gt "$idx" ] || continue + pn=$(basename "$p"); entry=$(plan_text "$p" | awk '/^## Plan Set/{f=1;next} /^## /{f=0} f' | grep -F -- "$pn" || true) + [ -n "$entry" ] || continue + # segments "from plan K: `a`, `b`" (or "Plan K's `a`") for K before the next plan + names=$(printf '%s\n' "$entry" | grep -o -i -E "(from plans? [0-9]+[^\`]*|plan [0-9]+'s)[^;.]*" | while IFS= read -r seg; do + kk=$(printf '%s' "$seg" | grep -o -E '[0-9]+' | head -1); [ -n "$kk" ] && [ "$kk" -lt "$idx" ] || continue + printf '%s\n' "$seg" | idents | grep -v -E "$stop" || true + done | sort -u) + check "$pn (from plans before $name)" <<< "$names" + done +fi +[ $missing -eq 0 ] && { echo "boundary: clean ($found consumed names found in code)"; exit 0; } +exit 1 diff --git a/skills/executing-plans/scripts/task-done b/skills/executing-plans/scripts/task-done index dd09871..161e4a6 100755 --- a/skills/executing-plans/scripts/task-done +++ b/skills/executing-plans/scripts/task-done @@ -4,7 +4,7 @@ # 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...] +# Usage: task-done PLAN TASK_NUMBER BASE -- TEST_COMMAND [ARGS...] (PLAN: file or directory) # BASE is the SHA task-start printed; the completion line records BASE..HEAD. # Exit: the test command's exit status. set -euo pipefail diff --git a/skills/executing-plans/scripts/task-start b/skills/executing-plans/scripts/task-start index fab75b5..bddb0f5 100755 --- a/skills/executing-plans/scripts/task-start +++ b/skills/executing-plans/scripts/task-start @@ -5,7 +5,7 @@ # 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 +# Usage: task-start PLAN TASK_NUMBER (PLAN: the plan file, or a plan directory) # Prints: # brief: <path to the task's brief file> # base: <full SHA of HEAD> |
