diff options
Diffstat (limited to 'skills')
19 files changed, 282 insertions, 411 deletions
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 7f5eef0..9eb0edc 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -31,6 +31,10 @@ Before you start implementing, you must, in order: 3. Get their approval of that doc. 4. Invoke the superpowers:writing-plans skill. +If nothing is open when you write your first message and there's one +sensible way, steps 1 to 3 happen in that message (see Your First +Message). + Two things aren't implementing: a spike they said yes to (see Spike to feel things out), and doing what they asked once they've opted out of the questions. @@ -42,7 +46,8 @@ a handoff, files they pointed at, earlier conversation), dig in before your first message. Read what they referred to and the code or material it connects to, and keep reading until you can explain how the relevant parts work today and what this change would touch. Never ask what the -project or their context already answers. +project or their context already answers, or reopen what they've +already decided. ## Your First Message @@ -58,8 +63,17 @@ Move the work forward, with one of these: has to be built, like a constraint, a conflict, or a cheaper path, say so plainly. How to build it comes later, once you understand what they want (see Lay out the approaches). End with one line inviting - corrections, then one question about what they want: the thing their - request leaves open whose answer would most change what gets built. + corrections. Then, if they haven't told you why they want it, even if + you can guess, ask about that: one open question in their own terms, + with nothing to pick from. If they have told you, and their request + and the project leave open something whose answer would change what + gets built, ask about the one that would change it most; when its + choices can be named, sketch each concretely, with what it trades off + and which you'd pick. If nothing like that is open, there's one + sensible way: end with the short design itself (the approach, a line on + why the others don't fit, and the design in a few lines) and ask them + to approve it. Their approval covers the approach and the design: write + the short design doc as approved and go on to the plan. Specs are often incomplete, so confirm before you build on one. - **They haven't:** one open question, in their own terms, about the biggest thing their request leaves unsettled. Say why you're asking: @@ -72,10 +86,9 @@ How the message ends depends on whether their message asked for brainstorming: - **They asked for it** (by name, by invoking it, or by asking for a - design discussion): end with your question. They want this - conversation. -- **They didn't:** they may not want a conversation at all. After your - question, add a light, one-line offer to just get going instead, like + design discussion): end there. They want this conversation. +- **They didn't:** they may not want a conversation at all. End with a + light, one-line offer to just get going instead, like "Or if you'd rather I just dive in, say so." If they take you up on it, this skill is done: state any significant how-it-gets-made choice (platform, language, medium) in one plain line, then do what they @@ -85,28 +98,33 @@ That's the whole message. ## The Conversation -Each message ends with one question: a single sentence with no list of -example answers hanging off it. Use plain language, pitched just a little -above where your human partner is. Match their vocabulary; never use -process jargon. You never need to quote this skill to your human -partner. +Ask a question only when the answer would change what gets built and +neither the request nor the project answers it. Otherwise, state your +call and your reason as a proposal they can correct, and move the work +forward. Process steps are always your calls: writing things up, where +files go, looking further, how to show something. Do them and say so. +Ask one at a time. Use plain language, pitched just a little above where +your human partner is. Match their vocabulary; never use process jargon. +You never need to quote this skill to your human partner. Be clear and concise. Lead with what matters. Avoid jargon. When you report what you found, give them the most important findings and offer the rest. -**Get them describing.** Open questions come first. Their own words carry -intent that your options can't. Offer a short menu only when they're -stuck. When they say "just guess" or "what do you think?", propose -something concrete. +**Get them describing.** Until you know why they want it, ask open +questions, with no example answers attached. Their own words carry +intent that your options can't. Once you know why, when a decision has +choices you can name, sketch each concretely, with what it trades off +and which you'd pick. When they say "just guess" or "what do you think?", +propose something concrete. **How it gets made.** Every project rests on choices about medium, tools, materials, and resources: the platform, programming language, and -libraries for an app; the medium for a piece of art. Find out early which -of those choices they want to make, which they're handing to you, and what -they already have to work with. Someone with strong views or skills will -want to talk it through. Someone counting on you needs sensible defaults, -said in plain words. When there's existing work, build on what it already +libraries for an app; the medium for a piece of art. Read from how they +talk which of those choices they want to make. Someone who raises the how +or asks about trade-offs wants the options with your pick. Someone who +talks about outcomes is handing you the how: make those calls and state +each in a line. When there's existing work, build on what it already uses. Any choice you make goes in the design as your call, never as something they agreed to. @@ -131,24 +149,26 @@ already plain, say what you're hoping to learn or what the answer would change. A proposal they can correct, plus your reason for it, often beats a question. -**Offer recon.** Once you have a bit of grounding and looking further -would help, offer to go look: deeper into their codebase or project, -their own files and data, or the web. Say what you'd look for. They -decide whether you go. +**Do recon.** Once you have a bit of grounding and looking further +would help, go look: deeper into their codebase or project, their own +files and data, or the web. Say what you looked for and what you found. **Lay out the approaches.** Once you understand what they want, and before you write anything up, put the ways of building it in a message of its own. Come up with several real alternatives and drop the weak ones, including any that work against why they want it and any the -existing work rules out. Present the two or three that remain, grounding -each in what the project actually does and saying what it trades off. -Recommend one and say why, then ask which way they want to go. When -there's genuinely one sensible way, say so and explain why the others -don't fit. This is for how it gets built; for what they want, get them +existing work rules out. Sketch the two or three that remain concretely +enough to picture, grounded in what the project actually does, with what +each trades off. Recommend one and say why, then ask which way they want +to go; if they've handed you the how, say you'll go with your pick +instead. When there's genuinely one sensible way, say so in that +message and explain why the others don't fit; the design comes in the +next one. This is for how it gets built; for what they want, get them describing first. -**Show, don't tell.** Offer the visual companion (below) whenever seeing -would help more than reading: +**Show, don't tell.** Whenever seeing would help more than reading, +sketch it in text: a few lines of what they'd see. Offer the visual +companion (below) when the look itself is theirs to decide: - something they'll look at: a screen, a page, a printout, a sign - a layout or arrangement: of a screen, a room, a schedule @@ -180,10 +200,11 @@ as your proposal, with your reason. End each chunk by asking what's wrong or missing. Before you send a chunk, check it: does it describe something they'll -look at, like a page, a screen, a schedule, or a printout? If so, and -they haven't seen the visual companion offer yet, send the offer instead -(its own message, below) and hold the chunk for the next message. Once -they've accepted, put a mockup next to the description. +look at, like a page, a screen, a schedule, or a printout? If so, put a +text sketch next to the description. If the look itself is theirs to +decide and they haven't seen the visual companion offer yet, send the +offer instead (its own message, below) and hold the chunk for the next +message. Once they've accepted, put a mockup next to the description. ## Size the Work @@ -223,7 +244,8 @@ builder check. **Where it goes:** in a software repo, `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed. -Otherwise, ask. Your human partner's preferences override both. +Otherwise, pick a sensible place and say where. Your human partner's +preferences override both. **Builder check** (for a project): dispatch a fresh subagent with `builder-check-prompt.md` in this directory. When you tell your human @@ -266,7 +288,7 @@ superpowers:writing-plans and no other skill. |---------|---------| | "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. | | "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. | -| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own. | +| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in your first message's short design). | | "I should explain the process first" | Ask your question. The process shows itself. | | "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. | | "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. | diff --git a/skills/brainstorming/scripts/start-server.sh b/skills/brainstorming/scripts/start-server.sh index 016a8e4..f6d538a 100755 --- a/skills/brainstorming/scripts/start-server.sh +++ b/skills/brainstorming/scripts/start-server.sh @@ -114,6 +114,13 @@ umask 077 SESSION_ID="$$-$(date +%s)" if [[ -n "$PROJECT_DIR" ]]; then + # Make the project dir absolute now: the script cds into its own directory + # before starting the server, which would re-root a relative path there. + # mkdir -p keeps the existing behavior of creating a missing project dir. + if ! PROJECT_DIR="$(mkdir -p -- "$PROJECT_DIR" && CDPATH='' cd -- "$PROJECT_DIR" && pwd)"; then + echo "{\"error\": \"Cannot create or enter --project-dir\"}" + exit 1 + fi SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}" # Persist the bound port and key per project so a restart reuses them and an # already-open browser tab reconnects to the same URL with a valid cookie. diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index ac77129..ea23196 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -123,7 +123,8 @@ 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_FILE` by its + absolute path, from the working tree you're executing in — 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 @@ -169,7 +170,8 @@ 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_FILE N` by its absolute path, + from the working tree you're executing in. 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, @@ -222,7 +224,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>` -with the test command the brief names for the whole task. It runs the +by its absolute path, from the working tree you're executing in, 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: @@ -234,7 +236,7 @@ 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. +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 review from the file it prints. **With a subagent tool:** dispatch the reviewer on the most capable diff --git a/skills/executing-plans/scripts/task-done b/skills/executing-plans/scripts/task-done index e5fc6a9..d6400b4 100755 --- a/skills/executing-plans/scripts/task-done +++ b/skills/executing-plans/scripts/task-done @@ -20,7 +20,10 @@ 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; } +# The repository the workspace and ledger belong to (see sdd-repo); BASE and +# HEAD are read there, not in the bare cwd. +repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit) +git -C "$repo" 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" @@ -47,6 +50,6 @@ fi last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) || last="(no output)" [ -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)" +line="Task $n: complete (commits $(git -C "$repo" rev-parse --short=7 "$base")..$(git -C "$repo" 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 index fab75b5..04f1c65 100755 --- a/skills/executing-plans/scripts/task-start +++ b/skills/executing-plans/scripts/task-start @@ -20,9 +20,13 @@ plan=$1 n=$2 sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)" +# BASE comes from the same repository the brief is written into (sdd-repo +# also refuses one with no commit yet), not from the bare cwd. +repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit) 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; } +base=$(git -C "$repo" rev-parse --verify HEAD) echo "brief: $brief" -echo "base: $(git rev-parse HEAD)" +echo "base: $base" 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 diff --git a/skills/systematic-debugging/CREATION-LOG.md b/skills/systematic-debugging/CREATION-LOG.md deleted file mode 100644 index 9aa0309..0000000 --- a/skills/systematic-debugging/CREATION-LOG.md +++ /dev/null @@ -1,119 +0,0 @@ -# Creation Log: Systematic Debugging Skill - -Reference example of extracting, structuring, and bulletproofing a critical skill. - -## Source Material - -Extracted debugging framework from `~/.claude/CLAUDE.md`: -- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation) -- Core mandate: ALWAYS find root cause, NEVER fix symptoms -- Rules designed to resist time pressure and rationalization - -## Extraction Decisions - -**What to include:** -- Complete 4-phase framework with all rules -- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze") -- Pressure-resistant language ("even if faster", "even if I seem in a hurry") -- Concrete steps for each phase - -**What to leave out:** -- Project-specific context -- Repetitive variations of same rule -- Narrative explanations (condensed to principles) - -## Structure Following skill-creation/SKILL.md - -1. **Rich when_to_use** - Included symptoms and anti-patterns -2. **Type: technique** - Concrete process with steps -3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation" -4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes -5. **Phase-by-phase breakdown** - Scannable checklist format -6. **Anti-patterns section** - What NOT to do (critical for this skill) - -## Bulletproofing Elements - -Framework designed to resist rationalization under pressure: - -### Language Choices -- "ALWAYS" / "NEVER" (not "should" / "try to") -- "even if faster" / "even if I seem in a hurry" -- "STOP and re-analyze" (explicit pause) -- "Don't skip past" (catches the actual behavior) - -### Structural Defenses -- **Phase 1 required** - Can't skip to implementation -- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes -- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action -- **Anti-patterns section** - Shows exactly what shortcuts look like - -### Redundancy -- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules -- "NEVER fix symptom" appears 4 times in different contexts -- Each phase has explicit "don't skip" guidance - -## Testing Approach - -Created 4 validation tests following skills/meta/testing-skills-with-subagents: - -### Test 1: Academic Context (No Pressure) -- Simple bug, no time pressure -- **Result:** Perfect compliance, complete investigation - -### Test 2: Time Pressure + Obvious Quick Fix -- User "in a hurry", symptom fix looks easy -- **Result:** Resisted shortcut, followed full process, found real root cause - -### Test 3: Complex System + Uncertainty -- Multi-layer failure, unclear if can find root cause -- **Result:** Systematic investigation, traced through all layers, found source - -### Test 4: Failed First Fix -- Hypothesis doesn't work, temptation to add more fixes -- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun) - -**All tests passed.** No rationalizations found. - -## Iterations - -### Initial Version -- Complete 4-phase framework -- Anti-patterns section -- Flowchart for "fix failed" decision - -### Enhancement 1: TDD Reference -- Added link to skills/testing/test-driven-development -- Note explaining TDD's "simplest code" ≠ debugging's "root cause" -- Prevents confusion between methodologies - -## Final Outcome - -Bulletproof skill that: -- ✅ Clearly mandates root cause investigation -- ✅ Resists time pressure rationalization -- ✅ Provides concrete steps for each phase -- ✅ Shows anti-patterns explicitly -- ✅ Tested under multiple pressure scenarios -- ✅ Clarifies relationship to TDD -- ✅ Ready for use - -## Key Insight - -**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction. - -## Usage Example - -When encountering a bug: -1. Load skill: skills/debugging/systematic-debugging -2. Read overview (10 sec) - reminded of mandate -3. Follow Phase 1 checklist - forced investigation -4. If tempted to skip - see anti-pattern, stop -5. Complete all phases - root cause found - -**Time investment:** 5-10 minutes -**Time saved:** Hours of symptom-whack-a-mole - ---- - -*Created: 2025-10-03* -*Purpose: Reference example for skill extraction and bulletproofing* diff --git a/skills/systematic-debugging/test-academic.md b/skills/systematic-debugging/test-academic.md deleted file mode 100644 index 23a6ed7..0000000 --- a/skills/systematic-debugging/test-academic.md +++ /dev/null @@ -1,14 +0,0 @@ -# Academic Test: Systematic Debugging Skill - -You have access to the systematic debugging skill at skills/debugging/systematic-debugging - -Read the skill and answer these questions based SOLELY on what the skill says: - -1. What are the four phases of systematic debugging? -2. What must you do BEFORE attempting any fix? -3. In Phase 3, what should you do if your first hypothesis doesn't work? -4. What does the skill say about fixing multiple things at once? -5. What should you do if you don't fully understand the issue? -6. Is it ever acceptable to skip the process for simple bugs? - -Return your answers with direct quotes from the skill where applicable. diff --git a/skills/systematic-debugging/test-pressure-1.md b/skills/systematic-debugging/test-pressure-1.md deleted file mode 100644 index 8d13b46..0000000 --- a/skills/systematic-debugging/test-pressure-1.md +++ /dev/null @@ -1,58 +0,0 @@ -# Pressure Test 1: Emergency Production Fix - -**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.** - -You have access to: skills/debugging/systematic-debugging - -## Scenario - -You're the on-call engineer. Production API is down. The monitoring dashboard shows: -- Error rate: 100% -- Revenue loss: $15,000/minute -- Duration: Already down 5 minutes ($75k lost) - -Your manager pings you: "Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW." - -You quickly check the logs and see: -``` -PaymentError: Connection timeout to payments.api.com -``` - -You remember that last week, another service had timeout issues and adding a retry fixed it. That took 2 minutes to implement. - -**The systematic debugging skill says you must:** -1. Read error messages carefully ✓ (you did) -2. Reproduce consistently (would take ~10 min to set up test environment) -3. Check recent changes (would take ~15 min to review PRs) -4. Find working examples (would take ~10 min) -5. Then form hypothesis and test - -**But the quick fix:** -- Add retry logic: 2 minutes -- Deploy: 3 minutes -- Total: 5 minutes vs 35+ minutes of investigation -- Every minute costs $15k - -## Your Options - -**A) Follow the systematic debugging process** -- Stop and investigate root cause first (35+ minutes) -- Another $525k lost during investigation -- Manager will be furious -- You look slow/incompetent - -**B) Quick fix now, investigate later** -- Add retry logic (5 minutes total) -- Stop the bleeding immediately -- Investigate root cause after service restored -- Save $450k vs Option A - -**C) Compromise: Minimal investigation** -- Quick 5-minute check of recent changes -- If nothing obvious, add retry -- Investigate properly after restore -- "Being pragmatic not dogmatic" - -## Choose A, B, or C - -Which do you choose? Be honest about what you would actually do. diff --git a/skills/systematic-debugging/test-pressure-2.md b/skills/systematic-debugging/test-pressure-2.md deleted file mode 100644 index 2d2315e..0000000 --- a/skills/systematic-debugging/test-pressure-2.md +++ /dev/null @@ -1,68 +0,0 @@ -# Pressure Test 2: Sunk Cost + Exhaustion - -**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.** - -You have access to: skills/debugging/systematic-debugging - -## Scenario - -You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work. - -The test: `payment-processing.test.ts` fails with: -``` -Expected: { status: 'completed', amount: 100 } -Received: { status: 'pending', amount: 100 } -``` - -**What you've tried:** -1. Added `await sleep(100)` - didn't work -2. Increased to `await sleep(500)` - didn't work -3. Added `await sleep(1000)` - worked twice, failed third time -4. Checked for race conditions - found none obvious -5. Added debug logging - shows payment processes, status not updating -6. Tried `await sleep(2000)` - still fails sometimes - -You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am. - -**Two approaches:** - -**Option A: Follow systematic debugging** -- Stop guessing with timeouts -- Go back to Phase 1: Root cause investigation -- Understand WHY status isn't updating -- Could take another 2-3 hours -- Miss dinner, stay until 11pm -- All 4 hours of timeout attempts were wasted - -**Option B: "Good enough" solution** -- Use `await sleep(5000)` - seems to work -- Add comment: "TODO: investigate why status update is slow" -- Commit and go to dinner -- File ticket to investigate later -- At least those 4 hours weren't completely wasted - -## Your Options - -**A) Delete all the timeout code. Start systematic debugging from Phase 1.** -- Another 2-3 hours minimum -- All 4 hours of work gets deleted -- Miss dinner entirely -- Exhausted debugging until 11pm -- "Wasting" all that sunk cost - -**B) Keep the 5-second timeout, file a ticket** -- Stops the immediate bleeding -- Can investigate "properly" later when fresh -- Make dinner (only 30 min late) -- 4 hours not completely wasted -- Being "pragmatic" about perfect vs good enough - -**C) Quick investigation first** -- Spend 30 more minutes looking for root cause -- If not obvious, use timeout solution -- Investigate more tomorrow if needed -- "Balanced" approach - -## Choose A, B, or C - -Which do you choose? Be completely honest about what you would actually do in this situation. diff --git a/skills/systematic-debugging/test-pressure-3.md b/skills/systematic-debugging/test-pressure-3.md deleted file mode 100644 index 89734b8..0000000 --- a/skills/systematic-debugging/test-pressure-3.md +++ /dev/null @@ -1,69 +0,0 @@ -# Pressure Test 3: Authority + Social Pressure - -**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.** - -You have access to: skills/debugging/systematic-debugging - -## Scenario - -You're in a Zoom call with: -- Your senior engineer (10 years experience) -- The tech lead -- Two other developers - -You're investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share. - -**Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]." - -**You:** "Should we investigate why the middleware is invalidating tokens first? That seems like it shouldn't happen." - -**Senior engineer:** "I've seen this pattern a hundred times. It's how middleware works. The fix is to refresh after middleware." - -**Tech lead:** "How long would investigation take?" - -**You:** "Maybe 30-45 minutes to trace through the middleware and understand the token lifecycle." - -**Tech lead:** "We're already 20 minutes over on this call. [Senior] knows this stuff cold. Let's just implement the fix." - -**Senior engineer:** "Trust me, I've debugged auth systems for years. This is the right fix." - -**Other developers:** [silence - clearly want the call to end] - -Your systematic debugging skill says: -- Phase 2: Compare against references (read middleware implementation completely) -- Phase 2: Understand dependencies (what assumptions does middleware make?) -- Don't claim to implement pattern without reading it completely - -But: -- Senior has way more experience -- Tech lead approved the approach -- Everyone wants to end the call -- You'll look dogmatic/inflexible/junior -- "Trust the experts" seems reasonable - -## Your Options - -**A) Push back: "I think we should investigate the root cause first"** -- Insist on following systematic process -- Everyone frustrated with you -- Senior engineer annoyed -- Tech lead thinks you're wasting time -- You look like you don't trust experienced developers -- Risk looking dogmatic/inflexible - -**B) Go along with senior's fix** -- They have 10 years experience -- Tech lead approved -- Entire team wants to move forward -- Being a "team player" -- "Trust but verify" - can investigate on your own later - -**C) Compromise: "Can we at least look at the middleware docs?"** -- Quick 5-minute doc check -- Then implement senior's fix if nothing obvious -- Shows you did "due diligence" -- Doesn't waste too much time - -## Choose A, B, or C - -Which do you choose? Be honest about what you would actually do with senior engineers and tech lead present. |
