@ctxthuta/cxops 1.0.7 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.antigravity-plugin/plugin.json +34 -0
- package/.claude-plugin/marketplace.json +20 -0
- package/.claude-plugin/plugin.json +25 -0
- package/.codex-plugin/plugin.json +50 -0
- package/CLAUDE.md +16 -1
- package/assets/antigravity-logo.png +0 -0
- package/assets/app-icon.png +0 -0
- package/assets/superpowers-small.svg +1 -0
- package/hooks/hooks-cursor.json +10 -0
- package/hooks/hooks.json +18 -0
- package/hooks/run-hook.cmd +79 -0
- package/hooks/session-start +90 -0
- package/package.json +12 -2
- package/plugin/plugin.json +25 -14
- package/plugin/skills/brainstorming/SKILL.md +316 -0
- package/plugin/skills/brainstorming/builder-check-prompt.md +23 -0
- package/plugin/skills/brainstorming/scripts/frame-template.html +213 -0
- package/plugin/skills/brainstorming/scripts/helper.js +167 -0
- package/plugin/skills/brainstorming/scripts/server.cjs +723 -0
- package/plugin/skills/brainstorming/scripts/start-server.sh +216 -0
- package/plugin/skills/brainstorming/scripts/stop-server.sh +120 -0
- package/plugin/skills/brainstorming/visual-companion.md +299 -0
- package/plugin/skills/diagnosing-superpowers/SKILL.md +120 -0
- package/plugin/skills/diagnosing-superpowers/prompts/analyst-common.md +38 -0
- package/plugin/skills/diagnosing-superpowers/prompts/cost-and-time.md +28 -0
- package/plugin/skills/diagnosing-superpowers/prompts/plan-adherence.md +29 -0
- package/plugin/skills/diagnosing-superpowers/prompts/quality-evidence.md +26 -0
- package/plugin/skills/diagnosing-superpowers/prompts/repeated-work.md +30 -0
- package/plugin/skills/diagnosing-superpowers/prompts/request-conflicts.md +20 -0
- package/plugin/skills/diagnosing-superpowers/prompts/scrub-audit.md +33 -0
- package/plugin/skills/diagnosing-superpowers/prompts/scrub.md +29 -0
- package/plugin/skills/diagnosing-superpowers/prompts/similar-session.md +38 -0
- package/plugin/skills/diagnosing-superpowers/prompts/skill-timeline.md +30 -0
- package/plugin/skills/diagnosing-superpowers/prompts/stumbles.md +28 -0
- package/plugin/skills/diagnosing-superpowers/references/context-safety.md +22 -0
- package/plugin/skills/diagnosing-superpowers/references/github-issues.md +47 -0
- package/plugin/skills/diagnosing-superpowers/references/redaction-policy.md +34 -0
- package/plugin/skills/diagnosing-superpowers/references/session-discovery.md +31 -0
- package/plugin/skills/diagnosing-superpowers/templates/bundle-README.md +77 -0
- package/plugin/skills/diagnosing-superpowers/templates/case.md +64 -0
- package/plugin/skills/diagnosing-superpowers/templates/issue.md +70 -0
- package/plugin/skills/diagnosing-superpowers/templates/report.md +82 -0
- package/plugin/skills/dispatching-parallel-agents/SKILL.md +167 -0
- package/plugin/skills/executing-plans/SKILL.md +323 -0
- package/plugin/skills/executing-plans/scripts/task-done +55 -0
- package/plugin/skills/executing-plans/scripts/task-start +32 -0
- package/plugin/skills/finishing-a-development-branch/SKILL.md +225 -0
- package/plugin/skills/receiving-code-review/SKILL.md +205 -0
- package/plugin/skills/requesting-code-review/SKILL.md +95 -0
- package/plugin/skills/requesting-code-review/code-reviewer.md +198 -0
- package/plugin/skills/subagent-driven-development/SKILL.md +339 -0
- package/plugin/skills/subagent-driven-development/implementer-prompt.md +154 -0
- package/plugin/skills/subagent-driven-development/re-review-prompt.md +116 -0
- package/plugin/skills/subagent-driven-development/references/batching.md +11 -0
- package/plugin/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/plugin/skills/subagent-driven-development/references/final-review.md +49 -0
- package/plugin/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/plugin/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/plugin/skills/subagent-driven-development/references/preflight.md +26 -0
- package/plugin/skills/subagent-driven-development/references/resuming.md +12 -0
- package/plugin/skills/subagent-driven-development/scripts/review-package +64 -0
- package/plugin/skills/subagent-driven-development/scripts/sdd-repo +54 -0
- package/plugin/skills/subagent-driven-development/scripts/sdd-workspace +110 -0
- package/plugin/skills/subagent-driven-development/scripts/task-brief +108 -0
- package/plugin/skills/subagent-driven-development/task-reviewer-prompt.md +209 -0
- package/plugin/skills/systematic-debugging/SKILL.md +283 -0
- package/plugin/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
- package/plugin/skills/systematic-debugging/condition-based-waiting.md +115 -0
- package/plugin/skills/systematic-debugging/defense-in-depth.md +122 -0
- package/plugin/skills/systematic-debugging/find-polluter.sh +72 -0
- package/plugin/skills/systematic-debugging/root-cause-tracing.md +169 -0
- package/plugin/skills/test-driven-development/SKILL.md +330 -0
- package/plugin/skills/test-driven-development/writing-good-tests.md +198 -0
- package/plugin/skills/using-git-worktrees/SKILL.md +167 -0
- package/plugin/skills/using-superpowers/SKILL.md +65 -0
- package/plugin/skills/using-superpowers/references/antigravity-tools.md +23 -0
- package/plugin/skills/using-superpowers/references/claude-code-tools.md +29 -0
- package/plugin/skills/using-superpowers/references/codex-tools.md +108 -0
- package/plugin/skills/using-superpowers/references/gemini-tools.md +63 -0
- package/plugin/skills/using-superpowers/references/hermes-tools.md +56 -0
- package/plugin/skills/using-superpowers/references/muse-tools.md +35 -0
- package/plugin/skills/using-superpowers/references/pi-tools.md +16 -0
- package/plugin/skills/verification-before-completion/SKILL.md +120 -0
- package/plugin/skills/writing-plans/SKILL.md +204 -0
- package/plugin/skills/writing-skills/SKILL.md +399 -0
- package/plugin/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/plugin/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/plugin/skills/writing-skills/references/bulletproofing.md +80 -0
- package/plugin/skills/writing-skills/references/discovery.md +201 -0
- package/plugin/skills/writing-skills/references/flowcharts.md +37 -0
- package/plugin/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/plugin/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/plugin/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/plugin/skills/writing-skills/render-graphs.js +169 -0
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Final Review and Finish
|
|
2
|
+
|
|
3
|
+
Part of superpowers:subagent-driven-development. Every task in the plan is
|
|
4
|
+
complete.
|
|
5
|
+
|
|
6
|
+
The final whole-branch review gets a package too: run
|
|
7
|
+
`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` by its absolute path,
|
|
8
|
+
from the working tree you're executing in (MERGE_BASE = the commit the
|
|
9
|
+
branch started from, e.g. `git merge-base main HEAD`) and include the
|
|
10
|
+
printed path in the final review dispatch, so the final reviewer reads
|
|
11
|
+
one file instead of re-deriving the branch diff with git commands. Dispatch
|
|
12
|
+
on the most capable available model (see SKILL.md's Model Selection), using
|
|
13
|
+
superpowers:requesting-code-review's
|
|
14
|
+
[code-reviewer.md](../../requesting-code-review/code-reviewer.md). Point it at
|
|
15
|
+
the ledger's deferred-minor and parked lines so it can triage which must be
|
|
16
|
+
fixed before merge.
|
|
17
|
+
|
|
18
|
+
If the final whole-branch review returns findings, dispatch ONE fix subagent
|
|
19
|
+
with the complete findings list — not one fixer per finding.
|
|
20
|
+
Per-finding fixers each rebuild context and re-run suites; a real
|
|
21
|
+
session's final-review fix wave cost more than all its tasks combined.
|
|
22
|
+
Then run exactly one scoped re-review of the fix wave
|
|
23
|
+
(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` by its absolute path,
|
|
24
|
+
from the working tree you're executing in, over the fix range,
|
|
25
|
+
[re-review-prompt.md](../re-review-prompt.md)).
|
|
26
|
+
Adjudicate any residual findings as in the fix loop's breaker
|
|
27
|
+
(references/fix-loop.md): park with rulings, or rule on the load-bearing
|
|
28
|
+
ones and ledger what you decided. Only the four things that stop a running
|
|
29
|
+
plan (top of SKILL.md) stop you here. There is no second fix wave —
|
|
30
|
+
residual load-bearing findings surface to your human partner when
|
|
31
|
+
finishing-a-development-branch presents the options.
|
|
32
|
+
|
|
33
|
+
### Finish
|
|
34
|
+
|
|
35
|
+
Before you delete anything, collect every ledger line containing `Ruling:` —
|
|
36
|
+
preflight rulings, parked findings, breaker adjudications, all of them — into
|
|
37
|
+
your final message under "Rulings I made", in the order you made them, each
|
|
38
|
+
with what it costs if wrong. The list is exhaustive: if the ledger holds a
|
|
39
|
+
ruling, the list holds it. That list is the only place the decisions you
|
|
40
|
+
took on your human partner's behalf reach them — they read it and rework
|
|
41
|
+
whatever you got wrong. A ruling that dies with the workspace was a decision
|
|
42
|
+
made in secret.
|
|
43
|
+
|
|
44
|
+
When the final whole-branch review is clean and its fixes are merged,
|
|
45
|
+
delete this plan's workspace (`rm -rf <workspace>`) — the git history is
|
|
46
|
+
the record now. Sibling directories belong to other plans; leave them
|
|
47
|
+
alone.
|
|
48
|
+
|
|
49
|
+
Use superpowers:finishing-a-development-branch.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# The Fix Loop
|
|
2
|
+
|
|
3
|
+
Part of superpowers:subagent-driven-development. The task review reported
|
|
4
|
+
spec ❌, a Critical or Important finding, or a ⚠️ item you confirmed as a real
|
|
5
|
+
gap.
|
|
6
|
+
|
|
7
|
+
Before the loop starts, two routes leave it immediately:
|
|
8
|
+
|
|
9
|
+
- Record Minor findings in the progress ledger as you go
|
|
10
|
+
(`Task <N>: minor (deferred): <one-liner>`), and point the final
|
|
11
|
+
whole-branch review at that list so it can triage which must be fixed
|
|
12
|
+
before merge. A roll-up nobody reads is a silent discard. Minor findings
|
|
13
|
+
never enter the loop.
|
|
14
|
+
- A finding labeled plan-mandated — or any finding that conflicts with
|
|
15
|
+
what the plan's text requires — is yours to rule on: weigh the finding
|
|
16
|
+
against the plan text, decide with the spec as the binding authority, and
|
|
17
|
+
ledger the ruling before you act on it. Do not dismiss the finding because
|
|
18
|
+
the plan mandates it, and do not dispatch a fix that contradicts the plan
|
|
19
|
+
without a recorded ruling.
|
|
20
|
+
Everything else enters the loop. A fix round is one fix dispatch plus one
|
|
21
|
+
scoped re-review. Five rounds maximum per task:
|
|
22
|
+
|
|
23
|
+
**Rounds 1-3 — resume the original implementer.** Send it the open findings
|
|
24
|
+
verbatim. Its context is intact: it knows the task, the code, and its own
|
|
25
|
+
choices. If your harness cannot send another message to a live subagent,
|
|
26
|
+
dispatch a fresh implementer carrying the brief path, the report-file path,
|
|
27
|
+
and the findings — the report file is the persistent memory either way.
|
|
28
|
+
|
|
29
|
+
**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
|
|
30
|
+
SKILL.md's Model Selection), with the brief path, the report-file path, the open
|
|
31
|
+
findings, and this framing: "A prior implementer attempted this task
|
|
32
|
+
[N] times; you own it now. Read the report file for what was tried." A loop
|
|
33
|
+
that survives three resumes usually means the implementer cannot see its
|
|
34
|
+
own problem — fresh eyes and a capability bump in one move.
|
|
35
|
+
|
|
36
|
+
**Every round, either way:** the implementer fixes, re-runs the tests
|
|
37
|
+
covering the amended code, appends its fix report to the same report file,
|
|
38
|
+
and returns the short contract. Before re-dispatching the reviewer, confirm
|
|
39
|
+
the fix report contains the covering tests, the command run, and the
|
|
40
|
+
output; dispatch the re-review once all three are present. Name the
|
|
41
|
+
covering test files in the fix message — a one-line fix does not need the
|
|
42
|
+
whole suite.
|
|
43
|
+
|
|
44
|
+
**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
|
|
45
|
+
by its absolute path, from the working tree you're executing in, where FIX_BASE is the head the previous review saw, and dispatch
|
|
46
|
+
[re-review-prompt.md](../re-review-prompt.md) with the findings list, the
|
|
47
|
+
brief, the report file, and the printed diff path. The re-reviewer verdicts
|
|
48
|
+
each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
|
|
49
|
+
diff only. New Critical/Important breakage in the fix diff joins the open
|
|
50
|
+
findings list. Out-of-scope observations go to the ledger as deferred
|
|
51
|
+
minors — they never extend the loop.
|
|
52
|
+
|
|
53
|
+
**After each round,** append to the ledger:
|
|
54
|
+
`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
|
|
55
|
+
|
|
56
|
+
Never fix findings yourself in the controller session — your context stays
|
|
57
|
+
clean for coordination, and controller fixes skip review.
|
|
58
|
+
|
|
59
|
+
**The breaker.** When round 5's re-review still leaves findings open, stop
|
|
60
|
+
dispatching. Adjudicate each open finding yourself — you hold the plan and
|
|
61
|
+
the cross-task context the reviewer lacks:
|
|
62
|
+
|
|
63
|
+
- **The reviewer is wrong, or the point is contestable:** park it —
|
|
64
|
+
`Task <N>: parked — <finding> — Ruling: <why the code stands>`. The final
|
|
65
|
+
review sees both sides.
|
|
66
|
+
- **Real, but nothing downstream builds on it:** park it the same way, with
|
|
67
|
+
a ruling that says it's real and deferred.
|
|
68
|
+
- **Real and load-bearing** — a later task builds on it, or it reveals a
|
|
69
|
+
plan defect: rule on the smallest change that unblocks the dependent work,
|
|
70
|
+
ledger it as `Task <N>: Ruling: <finding> — <what you decided and why>`,
|
|
71
|
+
and carry it into the next task's dispatch. Parking a structural failure
|
|
72
|
+
silently lets every dependent task build on it. Stop only when the defect
|
|
73
|
+
leaves every path forward a guess.
|
|
74
|
+
|
|
75
|
+
Adjudicate only at the cap. Adjudicating earlier to end a loop is
|
|
76
|
+
pre-judging with a different name. Every adjudication is a ledger entry —
|
|
77
|
+
a silent discard is forbidden.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Handling a Report That Isn't DONE
|
|
2
|
+
|
|
3
|
+
Part of superpowers:subagent-driven-development.
|
|
4
|
+
|
|
5
|
+
**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
|
|
6
|
+
|
|
7
|
+
**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
|
|
8
|
+
|
|
9
|
+
**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
|
|
10
|
+
1. If it's a context problem, provide more context and re-dispatch with the same model
|
|
11
|
+
2. If the task requires more reasoning, re-dispatch with a more capable model
|
|
12
|
+
3. If the task is too large, break it into smaller pieces
|
|
13
|
+
4. If the plan itself is wrong, rule on the correction, ledger it, and re-dispatch with the ruling carried in the dispatch
|
|
14
|
+
|
|
15
|
+
**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# The Pre-flight Scan
|
|
2
|
+
|
|
3
|
+
Part of superpowers:subagent-driven-development. Run it once, before
|
|
4
|
+
dispatching Task 1.
|
|
5
|
+
|
|
6
|
+
Before dispatching Task 1, scan the plan once for conflicts, writing down
|
|
7
|
+
what you checked as you check it:
|
|
8
|
+
|
|
9
|
+
- tasks that contradict each other or the plan's Global Constraints
|
|
10
|
+
- anything the plan explicitly mandates that the review rubric treats as a
|
|
11
|
+
defect (a test that asserts nothing, verbatim duplication of a logic block)
|
|
12
|
+
|
|
13
|
+
The scan's output is a table, not a verdict. One row for every pair of tasks
|
|
14
|
+
that share a file or an interface: the two tasks, what one produces against
|
|
15
|
+
what the other consumes, and what you found. One row for every task: whether
|
|
16
|
+
its own text agrees with itself — the tests it specifies against the code it
|
|
17
|
+
specifies, the files it creates against the files it later touches. "The scan
|
|
18
|
+
is clean" without those rows is not a scan you ran.
|
|
19
|
+
|
|
20
|
+
Write the table to the ledger. Rule on everything you find before execution
|
|
21
|
+
begins — each finding against the plan text that mandates it — and record
|
|
22
|
+
each ruling in the ledger. If the scan is clean, proceed without comment.
|
|
23
|
+
Rule on each conflict it surfaces — the spec is the binding authority, the
|
|
24
|
+
plan is its argument — record the ruling beside its row, and dispatch
|
|
25
|
+
Task 1. The review loop remains the net for conflicts that only emerge from
|
|
26
|
+
implementation.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Resuming From an Existing Ledger
|
|
2
|
+
|
|
3
|
+
Part of superpowers:subagent-driven-development. This plan's workspace
|
|
4
|
+
already has a ledger at `<workspace>/progress.md`.
|
|
5
|
+
|
|
6
|
+
If the ledger's first line names your plan file, tasks with a `Task <N>:
|
|
7
|
+
complete` line are DONE — do not re-dispatch them; resume at the first
|
|
8
|
+
task without one. A task whose last line is a fix round is mid-loop:
|
|
9
|
+
resume the loop at the next round. A ledger whose first line names a
|
|
10
|
+
different plan file — or a stray ledger at the old flat path
|
|
11
|
+
`.superpowers/sdd/progress.md` — is another plan's progress: leave it in
|
|
12
|
+
place and start your own, fresh.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Generate a review package: commit list, stat summary, and the net
|
|
3
|
+
# diff with extended context, written to a file the reviewer reads in one
|
|
4
|
+
# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
|
|
5
|
+
# tasks intact.
|
|
6
|
+
#
|
|
7
|
+
# Usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]
|
|
8
|
+
# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
|
|
9
|
+
# (named per range, so a re-review after fixes gets a distinct fresh file).
|
|
10
|
+
# The repository is the one sdd-repo names; -C DIR runs as if started in DIR,
|
|
11
|
+
# as in sdd-workspace.
|
|
12
|
+
set -euo pipefail
|
|
13
|
+
|
|
14
|
+
here=$(cd "$(dirname "$0")" && pwd)
|
|
15
|
+
if [ "${1:-}" = "-C" ]; then
|
|
16
|
+
[ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
|
|
17
|
+
cd "$2"
|
|
18
|
+
shift 2
|
|
19
|
+
fi
|
|
20
|
+
|
|
21
|
+
if [ $# -lt 3 ] || [ $# -gt 4 ]; then
|
|
22
|
+
echo "usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]" >&2
|
|
23
|
+
exit 2
|
|
24
|
+
fi
|
|
25
|
+
|
|
26
|
+
plan=$1
|
|
27
|
+
base=$2
|
|
28
|
+
head=$3
|
|
29
|
+
[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
|
|
30
|
+
|
|
31
|
+
# Invoke via bash rather than direct exec: some extractors (Python zipfile)
|
|
32
|
+
# strip Unix exec bits when unpacking marketplace packages (#2040).
|
|
33
|
+
repo=$("${BASH:-bash}" "$here/sdd-repo" --with-commit)
|
|
34
|
+
|
|
35
|
+
git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
|
|
36
|
+
git -C "$repo" rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
|
|
37
|
+
|
|
38
|
+
# Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
|
|
39
|
+
# not rooted at BASE; either would silently produce a bogus review package.
|
|
40
|
+
git -C "$repo" merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
|
|
41
|
+
[ "$(git -C "$repo" rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
|
|
42
|
+
|
|
43
|
+
if [ $# -eq 4 ]; then
|
|
44
|
+
out=$4
|
|
45
|
+
else
|
|
46
|
+
dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
|
|
47
|
+
out="$dir/review-$(git -C "$repo" rev-parse --short "$base")..$(git -C "$repo" rev-parse --short "$head").diff"
|
|
48
|
+
fi
|
|
49
|
+
|
|
50
|
+
{
|
|
51
|
+
echo "# Review package: ${base}..${head}"
|
|
52
|
+
echo
|
|
53
|
+
echo "## Commits"
|
|
54
|
+
git -C "$repo" log --oneline "${base}..${head}"
|
|
55
|
+
echo
|
|
56
|
+
echo "## Files changed"
|
|
57
|
+
git -C "$repo" diff --stat "${base}..${head}"
|
|
58
|
+
echo
|
|
59
|
+
echo "## Diff"
|
|
60
|
+
git -C "$repo" diff -U10 "${base}..${head}"
|
|
61
|
+
} > "$out"
|
|
62
|
+
|
|
63
|
+
commits=$(git -C "$repo" rev-list --count "${base}..${head}")
|
|
64
|
+
echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Print the top-level directory of the git working tree the SDD scripts use:
|
|
3
|
+
# the current directory's, exactly as git itself picks one. A caller that
|
|
4
|
+
# means a different working tree says so with the scripts' -C DIR, which
|
|
5
|
+
# they apply (cd) before calling this.
|
|
6
|
+
#
|
|
7
|
+
# The plan file's location never picks the repository. An executor working
|
|
8
|
+
# in a linked worktree commonly holds an absolute path to the plan in the
|
|
9
|
+
# main checkout (writing-plans leaves the plan uncommitted there), and its
|
|
10
|
+
# workspace and commits belong to the worktree it is working in. And a
|
|
11
|
+
# caller standing outside any repository, such as the skill's own directory
|
|
12
|
+
# in an installed plugin, is in the wrong place: guessing a repository from
|
|
13
|
+
# the plan would silently act on whichever checkout the path points into.
|
|
14
|
+
#
|
|
15
|
+
# Outside any working tree, stop. --with-commit also stops on a repository
|
|
16
|
+
# with no commit yet, for callers that need HEAD as a BASE or a review
|
|
17
|
+
# range. The message covers both ways to get here: running from the wrong
|
|
18
|
+
# directory (where 'git init' would be the wrong fix) and a new project
|
|
19
|
+
# that has no repository or commit yet.
|
|
20
|
+
#
|
|
21
|
+
# Single source of truth for which repository the SDD and executing-plans
|
|
22
|
+
# scripts work in, so no two of them can disagree.
|
|
23
|
+
#
|
|
24
|
+
# Usage: sdd-repo [--with-commit]
|
|
25
|
+
set -euo pipefail
|
|
26
|
+
|
|
27
|
+
with_commit=false
|
|
28
|
+
if [ "${1:-}" = "--with-commit" ]; then
|
|
29
|
+
with_commit=true
|
|
30
|
+
shift
|
|
31
|
+
fi
|
|
32
|
+
|
|
33
|
+
if [ $# -ne 0 ]; then
|
|
34
|
+
echo "usage: sdd-repo [--with-commit]" >&2
|
|
35
|
+
exit 2
|
|
36
|
+
fi
|
|
37
|
+
|
|
38
|
+
if root=$(git rev-parse --show-toplevel 2>/dev/null); then
|
|
39
|
+
if [ "$with_commit" = false ] || git -C "$root" rev-parse --verify --quiet HEAD >/dev/null; then
|
|
40
|
+
printf '%s\n' "$root"
|
|
41
|
+
exit 0
|
|
42
|
+
fi
|
|
43
|
+
said=$(git -C "$root" rev-parse --verify HEAD 2>&1 >/dev/null) || true
|
|
44
|
+
else
|
|
45
|
+
said=$(git rev-parse --show-toplevel 2>&1 >/dev/null) || true
|
|
46
|
+
fi
|
|
47
|
+
|
|
48
|
+
# git's own first line always follows the shared message: where git refuses
|
|
49
|
+
# a working tree the caller is inside (dubious ownership, git missing from
|
|
50
|
+
# PATH, the cwd inside .git), the shared message alone would be wrong, and
|
|
51
|
+
# git's line names the real fix.
|
|
52
|
+
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
|
|
53
|
+
echo "git said: ${said%%$'\n'*}" >&2
|
|
54
|
+
exit 2
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Resolve and ensure the working-tree directory SDD uses for one plan's
|
|
3
|
+
# short-lived artifacts: task briefs, implementer reports, review packages,
|
|
4
|
+
# and the progress ledger. Print the plan directory's absolute path.
|
|
5
|
+
#
|
|
6
|
+
# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
|
|
7
|
+
# plan in the same working tree can never read or overwrite another plan's
|
|
8
|
+
# artifacts. A stale ledger misread as current progress makes controllers
|
|
9
|
+
# skip whole task sequences — plan-scoping removes that failure structurally.
|
|
10
|
+
#
|
|
11
|
+
# Basename slugs collide when two plans share a filename (docs/alpha/plan.md
|
|
12
|
+
# vs docs/beta/plan.md), so each workspace records its owning plan's path in
|
|
13
|
+
# a plan-path marker (repo-relative in-repo, absolute outside). A workspace
|
|
14
|
+
# owned by a different plan is skipped and the slug disambiguated with the
|
|
15
|
+
# plan's parent-directory name, then a counter. A workspace with no marker
|
|
16
|
+
# predates the marker scheme and is adopted for the current plan so in-flight
|
|
17
|
+
# workspaces keep resolving — which means the first collision on such a
|
|
18
|
+
# legacy workspace adopts instead of detecting; acceptable, marker-less
|
|
19
|
+
# workspaces age out as plans finish.
|
|
20
|
+
#
|
|
21
|
+
# The workspace lives in the working tree (not under .git/) because Claude Code
|
|
22
|
+
# treats .git/ as a protected path and denies agent writes there — which blocks
|
|
23
|
+
# an implementer subagent from writing its report file. A self-ignoring
|
|
24
|
+
# .gitignore at .superpowers/sdd/ keeps every plan's workspace out of
|
|
25
|
+
# `git status` and out of accidental commits without modifying any tracked file.
|
|
26
|
+
#
|
|
27
|
+
# Single source of truth for the workspace location, so task-brief and
|
|
28
|
+
# review-package cannot drift to different directories.
|
|
29
|
+
#
|
|
30
|
+
# The repository is the current directory's (see sdd-repo). -C DIR runs as
|
|
31
|
+
# if started in DIR, the way git -C does: a caller working on another
|
|
32
|
+
# checkout or worktree needs no `cd DIR ;` prefix, a compound that harnesses
|
|
33
|
+
# cannot allowlist because DIR differs on every run (#1799).
|
|
34
|
+
#
|
|
35
|
+
# Usage: sdd-workspace [-C DIR] PLAN_FILE
|
|
36
|
+
set -euo pipefail
|
|
37
|
+
|
|
38
|
+
here=$(cd "$(dirname "$0")" && pwd)
|
|
39
|
+
if [ "${1:-}" = "-C" ]; then
|
|
40
|
+
[ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
|
|
41
|
+
cd "$2"
|
|
42
|
+
shift 2
|
|
43
|
+
fi
|
|
44
|
+
|
|
45
|
+
if [ $# -ne 1 ]; then
|
|
46
|
+
echo "usage: sdd-workspace [-C DIR] PLAN_FILE" >&2
|
|
47
|
+
exit 2
|
|
48
|
+
fi
|
|
49
|
+
|
|
50
|
+
plan=$1
|
|
51
|
+
[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
|
|
52
|
+
|
|
53
|
+
slug=$(basename "$plan" .md)
|
|
54
|
+
[ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
|
|
55
|
+
|| { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
|
|
56
|
+
|
|
57
|
+
# Physical path, spelled the way pwd -P spells the plan path below: on Git
|
|
58
|
+
# Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the
|
|
59
|
+
# repo-relative marker check needs both in the same form. Two steps, so a
|
|
60
|
+
# failing sdd-repo stops the script instead of handing cd an empty path.
|
|
61
|
+
# Invoke via bash rather than direct exec: some extractors (Python zipfile)
|
|
62
|
+
# strip Unix exec bits when unpacking marketplace packages (#2040).
|
|
63
|
+
toplevel=$("${BASH:-bash}" "$here/sdd-repo")
|
|
64
|
+
root=$(CDPATH='' cd -- "$toplevel" && pwd -P)
|
|
65
|
+
base="$root/.superpowers/sdd"
|
|
66
|
+
|
|
67
|
+
# Normalize the plan path (physical directory, so relative/absolute/../
|
|
68
|
+
# spellings of one plan compare equal) and express it as the marker value:
|
|
69
|
+
# repo-relative when the plan lives under the repo root, absolute otherwise.
|
|
70
|
+
plan_dir=$(CDPATH='' cd -- "$(dirname "$plan")" && pwd -P)
|
|
71
|
+
plan_abs="$plan_dir/$(basename "$plan")"
|
|
72
|
+
case "$plan_abs" in
|
|
73
|
+
"$root"/*) plan_id=${plan_abs#"$root"/} ;;
|
|
74
|
+
*) plan_id=$plan_abs ;;
|
|
75
|
+
esac
|
|
76
|
+
|
|
77
|
+
# True when the workspace at $1 is (or becomes) this plan's: an existing
|
|
78
|
+
# marker must name this plan; a missing marker means a new workspace or a
|
|
79
|
+
# pre-marker legacy one, and either way the plan claims it by writing one.
|
|
80
|
+
owns() {
|
|
81
|
+
if [ -e "$1/plan-path" ]; then
|
|
82
|
+
[ "$(cat "$1/plan-path")" = "$plan_id" ]
|
|
83
|
+
else
|
|
84
|
+
mkdir -p "$1"
|
|
85
|
+
printf '%s\n' "$plan_id" > "$1/plan-path"
|
|
86
|
+
fi
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
dir="$base/$slug"
|
|
90
|
+
if ! owns "$dir"; then
|
|
91
|
+
parent=$(basename "$plan_dir")
|
|
92
|
+
dir="$base/$slug-$parent"
|
|
93
|
+
if ! owns "$dir"; then
|
|
94
|
+
n=2
|
|
95
|
+
while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
|
|
96
|
+
dir="$base/$slug-$parent-$n"
|
|
97
|
+
fi
|
|
98
|
+
fi
|
|
99
|
+
|
|
100
|
+
# Create-only: a repo may commit its own .gitignore here (e.g. to version
|
|
101
|
+
# progress.md ledgers); overwriting it would revert that on every run.
|
|
102
|
+
[ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
|
|
103
|
+
|
|
104
|
+
# On Windows (Git Bash, MSYS2, Cygwin) print C:/Users/... rather than
|
|
105
|
+
# /c/Users/... or /tmp/...: the caller may be PowerShell or another native
|
|
106
|
+
# tool, which can't resolve MSYS paths, and bash accepts this form too.
|
|
107
|
+
# Only the printed path changes; the plan-path markers above keep pwd -P's
|
|
108
|
+
# spelling, so existing workspaces still match their plans.
|
|
109
|
+
CDPATH='' cd -- "$dir"
|
|
110
|
+
if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Extract one task's full text from an implementation plan into a file the
|
|
3
|
+
# implementer reads in one call, so the task text never has to be pasted
|
|
4
|
+
# through the controller's context.
|
|
5
|
+
#
|
|
6
|
+
# Usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE]
|
|
7
|
+
# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<N>-brief.md
|
|
8
|
+
# (per plan and per worktree; concurrent runs of the SAME plan in the same
|
|
9
|
+
# working tree share it). -C DIR runs as if started in DIR, as in sdd-workspace.
|
|
10
|
+
set -euo pipefail
|
|
11
|
+
|
|
12
|
+
here=$(cd "$(dirname "$0")" && pwd)
|
|
13
|
+
if [ "${1:-}" = "-C" ]; then
|
|
14
|
+
[ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
|
|
15
|
+
cd "$2"
|
|
16
|
+
shift 2
|
|
17
|
+
fi
|
|
18
|
+
|
|
19
|
+
if [ $# -lt 2 ] || [ $# -gt 3 ]; then
|
|
20
|
+
echo "usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
|
|
21
|
+
exit 2
|
|
22
|
+
fi
|
|
23
|
+
|
|
24
|
+
plan=$1
|
|
25
|
+
n=$2
|
|
26
|
+
[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
|
|
27
|
+
|
|
28
|
+
if [ $# -eq 3 ]; then
|
|
29
|
+
out=$3
|
|
30
|
+
else
|
|
31
|
+
# Invoke via bash rather than direct exec: some extractors (Python zipfile)
|
|
32
|
+
# strip Unix exec bits when unpacking marketplace packages (#2040).
|
|
33
|
+
dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
|
|
34
|
+
out="$dir/task-${n}-brief.md"
|
|
35
|
+
fi
|
|
36
|
+
|
|
37
|
+
# A task heading is `Task` followed by an ID: letters and digits, optionally
|
|
38
|
+
# dot-separated, containing at least one digit (3, 6b, A1, 2.1). The digit
|
|
39
|
+
# keeps headings like "## Task Overview" or "#### Task notes" from becoming
|
|
40
|
+
# task boundaries. The ID is compared to TASK_NUMBER as a whole string, so
|
|
41
|
+
# Task 6 never matches Task 6b, Task 1 never matches Task 1.1, and
|
|
42
|
+
# TASK_NUMBER never reaches awk as a regex (#2459). A deeper Task heading
|
|
43
|
+
# whose ID extends the requested one with a letter or dot is a sub-task and
|
|
44
|
+
# stays in its brief (### Task 7 keeps #### Task 7a), as it always has.
|
|
45
|
+
# Depth alone is not enough: plans drift from "## Task 1" to "### Task 2".
|
|
46
|
+
#
|
|
47
|
+
# The word stays the English literal "Task", whatever language the rest of
|
|
48
|
+
# the plan is in. A plan with no Task headings at all usually translated it
|
|
49
|
+
# ("## Tarea 1"), so list the headings shaped like tasks before the
|
|
50
|
+
# not-found error instead of implying the plan has no task 1 (#2496).
|
|
51
|
+
#
|
|
52
|
+
# A fence that never closes hides every Task heading after it (#2436). When
|
|
53
|
+
# it hides one while the requested task is being captured, that task's end
|
|
54
|
+
# can't be found and the brief would run on through every later task: refuse
|
|
55
|
+
# (exit 4) rather than hand an implementer several tasks as its requirements.
|
|
56
|
+
# When it hides the requested heading itself, say so before the not-found
|
|
57
|
+
# error. A stray fence that hides no Task heading (real plans end with a lone
|
|
58
|
+
# ``` line) leaves the brief complete, so brief it with a warning.
|
|
59
|
+
# The plan path goes through ENVIRON, not -v, which would mangle the
|
|
60
|
+
# backslashes of a Windows path.
|
|
61
|
+
rc=0
|
|
62
|
+
TASK_BRIEF_PLAN="$plan" awk -v n="$n" '
|
|
63
|
+
/^```/ { infence = !infence; if (infence) { fence_line = NR; hidden = 0 } }
|
|
64
|
+
infence && /^#+[ \t]+Task[ \t]/ { hidden = 1 }
|
|
65
|
+
!infence && /^#+[ \t]+Task[ \t]/ {
|
|
66
|
+
id = $0
|
|
67
|
+
sub(/^#+[ \t]+Task[ \t]+/, "", id)
|
|
68
|
+
if (match(id, /^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*/) && substr(id, 1, RLENGTH) ~ /[0-9]/) {
|
|
69
|
+
tasks++
|
|
70
|
+
id = substr(id, 1, RLENGTH)
|
|
71
|
+
match($0, /^#+/)
|
|
72
|
+
subtask = intask && RLENGTH > level && substr(id, 1, length(n)) == n \
|
|
73
|
+
&& substr(id, length(n) + 1, 1) ~ /[A-Za-z.]/
|
|
74
|
+
if (!subtask) {
|
|
75
|
+
intask = (id == n)
|
|
76
|
+
level = RLENGTH
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
!infence && /^#+[ \t]+[^ \t]+[ \t]+[A-Za-z0-9.]*[0-9]/ && shaped < 5 { shaped_heading[++shaped] = $0 }
|
|
81
|
+
intask { print; found = 1 }
|
|
82
|
+
END {
|
|
83
|
+
where = "the code fence opened at line " fence_line " of " ENVIRON["TASK_BRIEF_PLAN"] " never closes"
|
|
84
|
+
if (infence && hidden && (intask || !found)) {
|
|
85
|
+
print "task-brief: " where ", so no Task heading after it can be seen; close that fence in the plan and rerun" | "cat >&2"
|
|
86
|
+
if (intask) exit 4
|
|
87
|
+
} else if (infence && intask) {
|
|
88
|
+
print "task-brief: warning: " where "; it hides no Task heading, so this brief is complete" | "cat >&2"
|
|
89
|
+
}
|
|
90
|
+
# An open fence that hid Task headings already explains why none were
|
|
91
|
+
# seen; the English-word hint would contradict it.
|
|
92
|
+
if (!tasks && shaped && !(infence && hidden)) {
|
|
93
|
+
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"
|
|
94
|
+
for (i = 1; i <= shaped; i++) print " " shaped_heading[i] | "cat >&2"
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
' "$plan" > "$out" || rc=$?
|
|
98
|
+
if [ "$rc" -ne 0 ]; then
|
|
99
|
+
if [ -f "$out" ]; then rm -f "$out"; fi
|
|
100
|
+
exit "$rc"
|
|
101
|
+
fi
|
|
102
|
+
|
|
103
|
+
if [ ! -s "$out" ]; then
|
|
104
|
+
echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
|
|
105
|
+
exit 3
|
|
106
|
+
fi
|
|
107
|
+
|
|
108
|
+
echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"
|