diff options
Diffstat (limited to 'skills/subagent-driven-development')
9 files changed, 199 insertions, 38 deletions
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index ea170ed..4519578 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -111,7 +111,8 @@ sequences — the single most expensive failure observed. Track progress in a ledger file, not only in todos. - Each plan owns a workspace: at skill start, run this skill's - `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored + `bash scripts/sdd-workspace PLAN_FILE` by its absolute path, from the + working tree you're executing in — it prints the plan's git-ignored directory (under `<repo-root>/.superpowers/sdd/`), home to every artifact for THIS plan: ledger, briefs, reports, review packages. Another plan's directory is never yours to read or write. @@ -200,7 +201,8 @@ Record BASE (`git rev-parse HEAD`) before dispatching — the review package and fix-round diffs need it. - **Task brief:** before dispatching an implementer, run this skill's - `bash scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a + `bash scripts/task-brief PLAN_FILE N` by its absolute path, from the + working tree you're executing in — it extracts the task's full text to a uniquely named file and prints the path. Compose the dispatch so the brief stays the single source of requirements. Your dispatch should contain: (1) one line on where this @@ -238,7 +240,7 @@ Template: [implementer-prompt.md](implementer-prompt.md) Implementer subagents report one of four statuses. Handle each appropriately: -**DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path. +**DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from the working tree you're executing in — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path. **Any other status** (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED): read [references/handling-reports.md](references/handling-reports.md) and follow @@ -257,7 +259,8 @@ required. Implementer self-review never replaces the task review; both are needed. - Hand the reviewer its diff as a file: run this skill's - `bash scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path + `bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from + the working tree you're executing in, and pass the reviewer the file path it prints (or, without bash: `git log --oneline`, `git diff --stat`, and `git diff -U10` for the range, redirected to one uniquely named file). The output never enters your own context, and the reviewer sees diff --git a/skills/subagent-driven-development/re-review-prompt.md b/skills/subagent-driven-development/re-review-prompt.md index d49c182..eb520df 100644 --- a/skills/subagent-driven-development/re-review-prompt.md +++ b/skills/subagent-driven-development/re-review-prompt.md @@ -110,6 +110,7 @@ Subagent (general-purpose): - `[FIX_BASE_SHA]` — the head the previous review saw - `[HEAD_SHA]` — current commit - `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed + (run by its absolute path, from the working tree you're executing in) **Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED), new breakage in the fix diff, out-of-scope observations, and a round verdict. diff --git a/skills/subagent-driven-development/references/final-review.md b/skills/subagent-driven-development/references/final-review.md index 851a5c5..cf03546 100644 --- a/skills/subagent-driven-development/references/final-review.md +++ b/skills/subagent-driven-development/references/final-review.md @@ -4,7 +4,8 @@ Part of superpowers:subagent-driven-development. Every task in the plan is complete. The final whole-branch review gets a package too: run -`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the +`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` by its absolute path, +from the working tree you're executing in (MERGE_BASE = the commit the branch started from, e.g. `git merge-base main HEAD`) and include the printed path in the final review dispatch, so the final reviewer reads one file instead of re-deriving the branch diff with git commands. Dispatch @@ -19,7 +20,8 @@ with the complete findings list — not one fixer per finding. Per-finding fixers each rebuild context and re-run suites; a real session's final-review fix wave cost more than all its tasks combined. Then run exactly one scoped re-review of the fix wave -(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range, +(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` by its absolute path, +from the working tree you're executing in, over the fix range, [re-review-prompt.md](../re-review-prompt.md)). Adjudicate any residual findings as in the fix loop's breaker (references/fix-loop.md): park with rulings, or rule on the load-bearing diff --git a/skills/subagent-driven-development/references/fix-loop.md b/skills/subagent-driven-development/references/fix-loop.md index 0b476e9..34e4a48 100644 --- a/skills/subagent-driven-development/references/fix-loop.md +++ b/skills/subagent-driven-development/references/fix-loop.md @@ -42,7 +42,7 @@ covering test files in the fix message — a one-line fix does not need the whole suite. **The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` -where FIX_BASE is the head the previous review saw, and dispatch +by its absolute path, from the working tree you're executing in, where FIX_BASE is the head the previous review saw, and dispatch [re-review-prompt.md](../re-review-prompt.md) with the findings list, the brief, the report file, and the printed diff path. The re-reviewer verdicts each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix diff --git a/skills/subagent-driven-development/scripts/review-package b/skills/subagent-driven-development/scripts/review-package index fa7625f..04c2b91 100755 --- a/skills/subagent-driven-development/scripts/review-package +++ b/skills/subagent-driven-development/scripts/review-package @@ -4,13 +4,22 @@ # call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit # tasks intact. # -# Usage: review-package PLAN_FILE BASE HEAD [OUTFILE] +# Usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE] # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff # (named per range, so a re-review after fixes gets a distinct fresh file). +# The repository is the one sdd-repo names; -C DIR runs as if started in DIR, +# as in sdd-workspace. set -euo pipefail +here=$(cd "$(dirname "$0")" && pwd) +if [ "${1:-}" = "-C" ]; then + [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; } + cd "$2" + shift 2 +fi + if [ $# -lt 3 ] || [ $# -gt 4 ]; then - echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2 + echo "usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]" >&2 exit 2 fi @@ -19,35 +28,37 @@ base=$2 head=$3 [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; } -git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; } -git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; } +# Invoke via bash rather than direct exec: some extractors (Python zipfile) +# strip Unix exec bits when unpacking marketplace packages (#2040). +repo=$("${BASH:-bash}" "$here/sdd-repo" --with-commit) + +git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; } +git -C "$repo" rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; } # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or # not rooted at BASE; either would silently produce a bogus review package. -git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; } -[ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; } +git -C "$repo" merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; } +[ "$(git -C "$repo" rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; } if [ $# -eq 4 ]; then out=$4 else - # Invoke via bash rather than direct exec: some extractors (Python zipfile) - # strip Unix exec bits when unpacking marketplace packages (#2040). - dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan") - out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff" + dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan") + out="$dir/review-$(git -C "$repo" rev-parse --short "$base")..$(git -C "$repo" rev-parse --short "$head").diff" fi { echo "# Review package: ${base}..${head}" echo echo "## Commits" - git log --oneline "${base}..${head}" + git -C "$repo" log --oneline "${base}..${head}" echo echo "## Files changed" - git diff --stat "${base}..${head}" + git -C "$repo" diff --stat "${base}..${head}" echo echo "## Diff" - git diff -U10 "${base}..${head}" + git -C "$repo" diff -U10 "${base}..${head}" } > "$out" -commits=$(git rev-list --count "${base}..${head}") +commits=$(git -C "$repo" rev-list --count "${base}..${head}") echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes" diff --git a/skills/subagent-driven-development/scripts/sdd-repo b/skills/subagent-driven-development/scripts/sdd-repo new file mode 100755 index 0000000..b1756b9 --- /dev/null +++ b/skills/subagent-driven-development/scripts/sdd-repo @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +# Print the top-level directory of the git working tree the SDD scripts use: +# the current directory's, exactly as git itself picks one. A caller that +# means a different working tree says so with the scripts' -C DIR, which +# they apply (cd) before calling this. +# +# The plan file's location never picks the repository. An executor working +# in a linked worktree commonly holds an absolute path to the plan in the +# main checkout (writing-plans leaves the plan uncommitted there), and its +# workspace and commits belong to the worktree it is working in. And a +# caller standing outside any repository, such as the skill's own directory +# in an installed plugin, is in the wrong place: guessing a repository from +# the plan would silently act on whichever checkout the path points into. +# +# Outside any working tree, stop. --with-commit also stops on a repository +# with no commit yet, for callers that need HEAD as a BASE or a review +# range. The message covers both ways to get here: running from the wrong +# directory (where 'git init' would be the wrong fix) and a new project +# that has no repository or commit yet. +# +# Single source of truth for which repository the SDD and executing-plans +# scripts work in, so no two of them can disagree. +# +# Usage: sdd-repo [--with-commit] +set -euo pipefail + +with_commit=false +if [ "${1:-}" = "--with-commit" ]; then + with_commit=true + shift +fi + +if [ $# -ne 0 ]; then + echo "usage: sdd-repo [--with-commit]" >&2 + exit 2 +fi + +if root=$(git rev-parse --show-toplevel 2>/dev/null); then + if [ "$with_commit" = false ] || git -C "$root" rev-parse --verify --quiet HEAD >/dev/null; then + printf '%s\n' "$root" + exit 0 + fi + said=$(git -C "$root" rev-parse --verify HEAD 2>&1 >/dev/null) || true +else + said=$(git rev-parse --show-toplevel 2>&1 >/dev/null) || true +fi + +# git's own first line always follows the shared message: where git refuses +# a working tree the caller is inside (dubious ownership, git missing from +# PATH, the cwd inside .git), the shared message alone would be wrong, and +# git's line names the real fix. +echo "SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $PWD). If this is a new project, run 'git init' and make a first commit, then rerun." >&2 +echo "git said: ${said%%$'\n'*}" >&2 +exit 2 diff --git a/skills/subagent-driven-development/scripts/sdd-workspace b/skills/subagent-driven-development/scripts/sdd-workspace index b4661eb..ca3ac3b 100755 --- a/skills/subagent-driven-development/scripts/sdd-workspace +++ b/skills/subagent-driven-development/scripts/sdd-workspace @@ -27,11 +27,23 @@ # Single source of truth for the workspace location, so task-brief and # review-package cannot drift to different directories. # -# Usage: sdd-workspace PLAN_FILE +# The repository is the current directory's (see sdd-repo). -C DIR runs as +# if started in DIR, the way git -C does: a caller working on another +# checkout or worktree needs no `cd DIR ;` prefix, a compound that harnesses +# cannot allowlist because DIR differs on every run (#1799). +# +# Usage: sdd-workspace [-C DIR] PLAN_FILE set -euo pipefail +here=$(cd "$(dirname "$0")" && pwd) +if [ "${1:-}" = "-C" ]; then + [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; } + cd "$2" + shift 2 +fi + if [ $# -ne 1 ]; then - echo "usage: sdd-workspace PLAN_FILE" >&2 + echo "usage: sdd-workspace [-C DIR] PLAN_FILE" >&2 exit 2 fi @@ -44,8 +56,12 @@ slug=$(basename "$plan" .md) # Physical path, spelled the way pwd -P spells the plan path below: on Git # Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the -# repo-relative marker check needs both in the same form. -root=$(CDPATH='' cd -- "$(git rev-parse --show-toplevel)" && pwd -P) +# repo-relative marker check needs both in the same form. Two steps, so a +# failing sdd-repo stops the script instead of handing cd an empty path. +# Invoke via bash rather than direct exec: some extractors (Python zipfile) +# strip Unix exec bits when unpacking marketplace packages (#2040). +toplevel=$("${BASH:-bash}" "$here/sdd-repo") +root=$(CDPATH='' cd -- "$toplevel" && pwd -P) base="$root/.superpowers/sdd" # Normalize the plan path (physical directory, so relative/absolute/../ @@ -84,4 +100,11 @@ fi # Create-only: a repo may commit its own .gitignore here (e.g. to version # progress.md ledgers); overwriting it would revert that on every run. [ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore" -CDPATH='' cd -- "$dir" && pwd + +# On Windows (Git Bash, MSYS2, Cygwin) print C:/Users/... rather than +# /c/Users/... or /tmp/...: the caller may be PowerShell or another native +# tool, which can't resolve MSYS paths, and bash accepts this form too. +# Only the printed path changes; the plan-path markers above keep pwd -P's +# spelling, so existing workspaces still match their plans. +CDPATH='' cd -- "$dir" +if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi diff --git a/skills/subagent-driven-development/scripts/task-brief b/skills/subagent-driven-development/scripts/task-brief index b49fc54..a490211 100755 --- a/skills/subagent-driven-development/scripts/task-brief +++ b/skills/subagent-driven-development/scripts/task-brief @@ -3,14 +3,21 @@ # implementer reads in one call, so the task text never has to be pasted # through the controller's context. # -# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE] +# Usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE] # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<N>-brief.md # (per plan and per worktree; concurrent runs of the SAME plan in the same -# working tree share it). +# working tree share it). -C DIR runs as if started in DIR, as in sdd-workspace. set -euo pipefail +here=$(cd "$(dirname "$0")" && pwd) +if [ "${1:-}" = "-C" ]; then + [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; } + cd "$2" + shift 2 +fi + if [ $# -lt 2 ] || [ $# -gt 3 ]; then - echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2 + echo "usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE]" >&2 exit 2 fi @@ -23,17 +30,75 @@ if [ $# -eq 3 ]; then else # Invoke via bash rather than direct exec: some extractors (Python zipfile) # strip Unix exec bits when unpacking marketplace packages (#2040). - dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan") + dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan") out="$dir/task-${n}-brief.md" fi -awk -v n="$n" ' - /^```/ { infence = !infence } - !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ { - intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)")) +# A task heading is `Task` followed by an ID: letters and digits, optionally +# dot-separated, containing at least one digit (3, 6b, A1, 2.1). The digit +# keeps headings like "## Task Overview" or "#### Task notes" from becoming +# task boundaries. The ID is compared to TASK_NUMBER as a whole string, so +# Task 6 never matches Task 6b, Task 1 never matches Task 1.1, and +# TASK_NUMBER never reaches awk as a regex (#2459). A deeper Task heading +# whose ID extends the requested one with a letter or dot is a sub-task and +# stays in its brief (### Task 7 keeps #### Task 7a), as it always has. +# Depth alone is not enough: plans drift from "## Task 1" to "### Task 2". +# +# The word stays the English literal "Task", whatever language the rest of +# the plan is in. A plan with no Task headings at all usually translated it +# ("## Tarea 1"), so list the headings shaped like tasks before the +# not-found error instead of implying the plan has no task 1 (#2496). +# +# A fence that never closes hides every Task heading after it (#2436). When +# it hides one while the requested task is being captured, that task's end +# can't be found and the brief would run on through every later task: refuse +# (exit 4) rather than hand an implementer several tasks as its requirements. +# When it hides the requested heading itself, say so before the not-found +# error. A stray fence that hides no Task heading (real plans end with a lone +# ``` line) leaves the brief complete, so brief it with a warning. +# The plan path goes through ENVIRON, not -v, which would mangle the +# backslashes of a Windows path. +rc=0 +TASK_BRIEF_PLAN="$plan" awk -v n="$n" ' + /^```/ { infence = !infence; if (infence) { fence_line = NR; hidden = 0 } } + infence && /^#+[ \t]+Task[ \t]/ { hidden = 1 } + !infence && /^#+[ \t]+Task[ \t]/ { + id = $0 + sub(/^#+[ \t]+Task[ \t]+/, "", id) + if (match(id, /^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*/) && substr(id, 1, RLENGTH) ~ /[0-9]/) { + tasks++ + id = substr(id, 1, RLENGTH) + match($0, /^#+/) + subtask = intask && RLENGTH > level && substr(id, 1, length(n)) == n \ + && substr(id, length(n) + 1, 1) ~ /[A-Za-z.]/ + if (!subtask) { + intask = (id == n) + level = RLENGTH + } + } + } + !infence && /^#+[ \t]+[^ \t]+[ \t]+[A-Za-z0-9.]*[0-9]/ && shaped < 5 { shaped_heading[++shaped] = $0 } + intask { print; found = 1 } + END { + where = "the code fence opened at line " fence_line " of " ENVIRON["TASK_BRIEF_PLAN"] " never closes" + if (infence && hidden && (intask || !found)) { + print "task-brief: " where ", so no Task heading after it can be seen; close that fence in the plan and rerun" | "cat >&2" + if (intask) exit 4 + } else if (infence && intask) { + print "task-brief: warning: " where "; it hides no Task heading, so this brief is complete" | "cat >&2" + } + # An open fence that hid Task headings already explains why none were + # seen; the English-word hint would contradict it. + if (!tasks && shaped && !(infence && hidden)) { + print "task-brief: no task headings found. Task headings must use the English word \"Task\" (\"### Task 1: ...\"), even when the rest of the plan is in another language. Headings shaped like tasks:" | "cat >&2" + for (i = 1; i <= shaped; i++) print " " shaped_heading[i] | "cat >&2" + } } - intask { print } -' "$plan" > "$out" +' "$plan" > "$out" || rc=$? +if [ "$rc" -ne 0 ]; then + if [ -f "$out" ]; then rm -f "$out"; fi + exit "$rc" +fi if [ ! -s "$out" ]; then echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2 diff --git a/skills/subagent-driven-development/task-reviewer-prompt.md b/skills/subagent-driven-development/task-reviewer-prompt.md index 5c619bc..4cf7860 100644 --- a/skills/subagent-driven-development/task-reviewer-prompt.md +++ b/skills/subagent-driven-development/task-reviewer-prompt.md @@ -189,7 +189,8 @@ Subagent (general-purpose): **Placeholders:** - `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection -- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N` +- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`, + run by its absolute path, from the working tree you're executing in, prints the path; same file the implementer worked from) - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from the plan's Global Constraints section or the spec: exact values, formats, @@ -200,7 +201,8 @@ Subagent (general-purpose): - `[BASE_SHA]` — commit before this task - `[HEAD_SHA]` — current commit - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review - package to (`bash scripts/review-package PLAN_FILE BASE HEAD` prints the unique + package to (`bash scripts/review-package PLAN_FILE BASE HEAD`, run by its + absolute path, from the working tree you're executing in, prints the unique path it wrote; the package never enters the controller's context) **Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues |
