@ctxthuta/cxops 1.0.6 → 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.
Files changed (94) hide show
  1. package/.antigravity-plugin/plugin.json +34 -0
  2. package/.claude-plugin/marketplace.json +20 -0
  3. package/.claude-plugin/plugin.json +25 -0
  4. package/.codex-plugin/plugin.json +50 -0
  5. package/CLAUDE.md +94 -0
  6. package/assets/antigravity-logo.png +0 -0
  7. package/assets/app-icon.png +0 -0
  8. package/assets/superpowers-small.svg +1 -0
  9. package/hooks/hooks-cursor.json +10 -0
  10. package/hooks/hooks.json +18 -0
  11. package/hooks/run-hook.cmd +79 -0
  12. package/hooks/session-start +90 -0
  13. package/package.json +13 -2
  14. package/plugin/plugin.json +25 -14
  15. package/plugin/skills/brainstorming/SKILL.md +316 -0
  16. package/plugin/skills/brainstorming/builder-check-prompt.md +23 -0
  17. package/plugin/skills/brainstorming/scripts/frame-template.html +213 -0
  18. package/plugin/skills/brainstorming/scripts/helper.js +167 -0
  19. package/plugin/skills/brainstorming/scripts/server.cjs +723 -0
  20. package/plugin/skills/brainstorming/scripts/start-server.sh +216 -0
  21. package/plugin/skills/brainstorming/scripts/stop-server.sh +120 -0
  22. package/plugin/skills/brainstorming/visual-companion.md +299 -0
  23. package/plugin/skills/diagnosing-superpowers/SKILL.md +120 -0
  24. package/plugin/skills/diagnosing-superpowers/prompts/analyst-common.md +38 -0
  25. package/plugin/skills/diagnosing-superpowers/prompts/cost-and-time.md +28 -0
  26. package/plugin/skills/diagnosing-superpowers/prompts/plan-adherence.md +29 -0
  27. package/plugin/skills/diagnosing-superpowers/prompts/quality-evidence.md +26 -0
  28. package/plugin/skills/diagnosing-superpowers/prompts/repeated-work.md +30 -0
  29. package/plugin/skills/diagnosing-superpowers/prompts/request-conflicts.md +20 -0
  30. package/plugin/skills/diagnosing-superpowers/prompts/scrub-audit.md +33 -0
  31. package/plugin/skills/diagnosing-superpowers/prompts/scrub.md +29 -0
  32. package/plugin/skills/diagnosing-superpowers/prompts/similar-session.md +38 -0
  33. package/plugin/skills/diagnosing-superpowers/prompts/skill-timeline.md +30 -0
  34. package/plugin/skills/diagnosing-superpowers/prompts/stumbles.md +28 -0
  35. package/plugin/skills/diagnosing-superpowers/references/context-safety.md +22 -0
  36. package/plugin/skills/diagnosing-superpowers/references/github-issues.md +47 -0
  37. package/plugin/skills/diagnosing-superpowers/references/redaction-policy.md +34 -0
  38. package/plugin/skills/diagnosing-superpowers/references/session-discovery.md +31 -0
  39. package/plugin/skills/diagnosing-superpowers/templates/bundle-README.md +77 -0
  40. package/plugin/skills/diagnosing-superpowers/templates/case.md +64 -0
  41. package/plugin/skills/diagnosing-superpowers/templates/issue.md +70 -0
  42. package/plugin/skills/diagnosing-superpowers/templates/report.md +82 -0
  43. package/plugin/skills/dispatching-parallel-agents/SKILL.md +167 -0
  44. package/plugin/skills/executing-plans/SKILL.md +323 -0
  45. package/plugin/skills/executing-plans/scripts/task-done +55 -0
  46. package/plugin/skills/executing-plans/scripts/task-start +32 -0
  47. package/plugin/skills/finishing-a-development-branch/SKILL.md +225 -0
  48. package/plugin/skills/receiving-code-review/SKILL.md +205 -0
  49. package/plugin/skills/requesting-code-review/SKILL.md +95 -0
  50. package/plugin/skills/requesting-code-review/code-reviewer.md +198 -0
  51. package/plugin/skills/subagent-driven-development/SKILL.md +339 -0
  52. package/plugin/skills/subagent-driven-development/implementer-prompt.md +154 -0
  53. package/plugin/skills/subagent-driven-development/re-review-prompt.md +116 -0
  54. package/plugin/skills/subagent-driven-development/references/batching.md +11 -0
  55. package/plugin/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  56. package/plugin/skills/subagent-driven-development/references/final-review.md +49 -0
  57. package/plugin/skills/subagent-driven-development/references/fix-loop.md +77 -0
  58. package/plugin/skills/subagent-driven-development/references/handling-reports.md +15 -0
  59. package/plugin/skills/subagent-driven-development/references/preflight.md +26 -0
  60. package/plugin/skills/subagent-driven-development/references/resuming.md +12 -0
  61. package/plugin/skills/subagent-driven-development/scripts/review-package +64 -0
  62. package/plugin/skills/subagent-driven-development/scripts/sdd-repo +54 -0
  63. package/plugin/skills/subagent-driven-development/scripts/sdd-workspace +110 -0
  64. package/plugin/skills/subagent-driven-development/scripts/task-brief +108 -0
  65. package/plugin/skills/subagent-driven-development/task-reviewer-prompt.md +209 -0
  66. package/plugin/skills/systematic-debugging/SKILL.md +283 -0
  67. package/plugin/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  68. package/plugin/skills/systematic-debugging/condition-based-waiting.md +115 -0
  69. package/plugin/skills/systematic-debugging/defense-in-depth.md +122 -0
  70. package/plugin/skills/systematic-debugging/find-polluter.sh +72 -0
  71. package/plugin/skills/systematic-debugging/root-cause-tracing.md +169 -0
  72. package/plugin/skills/test-driven-development/SKILL.md +330 -0
  73. package/plugin/skills/test-driven-development/writing-good-tests.md +198 -0
  74. package/plugin/skills/using-git-worktrees/SKILL.md +167 -0
  75. package/plugin/skills/using-superpowers/SKILL.md +65 -0
  76. package/plugin/skills/using-superpowers/references/antigravity-tools.md +23 -0
  77. package/plugin/skills/using-superpowers/references/claude-code-tools.md +29 -0
  78. package/plugin/skills/using-superpowers/references/codex-tools.md +108 -0
  79. package/plugin/skills/using-superpowers/references/gemini-tools.md +63 -0
  80. package/plugin/skills/using-superpowers/references/hermes-tools.md +56 -0
  81. package/plugin/skills/using-superpowers/references/muse-tools.md +35 -0
  82. package/plugin/skills/using-superpowers/references/pi-tools.md +16 -0
  83. package/plugin/skills/verification-before-completion/SKILL.md +120 -0
  84. package/plugin/skills/writing-plans/SKILL.md +204 -0
  85. package/plugin/skills/writing-skills/SKILL.md +399 -0
  86. package/plugin/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  87. package/plugin/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  88. package/plugin/skills/writing-skills/references/bulletproofing.md +80 -0
  89. package/plugin/skills/writing-skills/references/discovery.md +201 -0
  90. package/plugin/skills/writing-skills/references/flowcharts.md +37 -0
  91. package/plugin/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  92. package/plugin/skills/writing-skills/references/persuasion-principles.md +187 -0
  93. package/plugin/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  94. 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"