heimdall-agent 1.0.0 → 1.2.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 (250) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +443 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +71 -34
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +68 -0
  9. package/agents/orchestrator.md +107 -93
  10. package/agents/reviewer.md +102 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +31 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +762 -573
  22. package/docs/SKILLS.md +393 -275
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
  29. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  30. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  31. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  32. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  33. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  34. package/docs/runs/skill-audit/customization-report.json +380 -0
  35. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  36. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  37. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  38. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  39. package/docs/runs/skill-audit/inventory.json +308 -0
  40. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  41. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  42. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  43. package/docs/runs/skill-audit/probe.ps1 +16 -0
  44. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  45. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  46. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  47. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  50. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  51. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  52. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  53. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  54. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  55. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  56. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  57. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  58. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  59. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  60. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  61. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  62. package/docs/runs/skill-audit/update-manifest.md +88 -0
  63. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  64. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  65. package/docs/runs/skill-audit/upstream-status.json +563 -0
  66. package/docs/runs/skill-audit/verification-results.json +252 -0
  67. package/doctrine/AGENTS.md +42 -77
  68. package/hooks/git/pre-commit +11 -0
  69. package/hooks/heimdall-hook.cjs +81 -2
  70. package/hooks/herdr-agent-state.ps1 +55 -0
  71. package/hooks/hooks.json +0 -11
  72. package/lib/catalog-sync.cjs +167 -0
  73. package/lib/hermes-context.cjs +57 -0
  74. package/lib/model-context.cjs +123 -0
  75. package/lib/path-discovery.cjs +94 -0
  76. package/package.json +7 -3
  77. package/playbooks/01-interactive-grilling-gate.md +23 -6
  78. package/playbooks/02-fast-code-deep-verification.md +3 -2
  79. package/playbooks/03-adversarial-code-review.md +15 -7
  80. package/playbooks/05-canonical-plan-template.md +35 -19
  81. package/playbooks/06-model-registry-matrix.md +24 -13
  82. package/playbooks/07-legacy-code-modernization.md +74 -0
  83. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  84. package/setup.mjs +592 -172
  85. package/skills/antislop/SKILL.md +76 -56
  86. package/skills/antislop/VERSION +1 -0
  87. package/skills/antislop-copywriting/SKILL.md +407 -372
  88. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  89. package/skills/antislop-human/SKILL.md +204 -147
  90. package/skills/antislop-human/contrast-check.py +168 -165
  91. package/skills/antislop-human/contrast-mcp.py +6 -3
  92. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  93. package/skills/antislop-human/references/WCAG.md +127 -0
  94. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  95. package/skills/antislop-ui/SKILL.md +344 -304
  96. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  97. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  98. package/skills/brainstorming/SKILL.md +296 -265
  99. package/skills/brainstorming/builder-check-prompt.md +23 -0
  100. package/skills/brainstorming/scripts/frame-template.html +213 -213
  101. package/skills/brainstorming/scripts/server.cjs +723 -723
  102. package/skills/brandkit/SKILL.md +798 -798
  103. package/skills/brutalist-skill/SKILL.md +93 -92
  104. package/skills/caveman/README.md +68 -0
  105. package/skills/caveman/SKILL.md +73 -38
  106. package/skills/claude-collaborator/SKILL.md +24 -44
  107. package/skills/clean-code/SKILL.md +152 -0
  108. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  109. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  110. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  111. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  112. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  113. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  114. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  115. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  116. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  117. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  118. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  119. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  120. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  121. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  122. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  123. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  124. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  125. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  126. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  127. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  128. package/skills/codebase-design/DEEPENING.md +37 -0
  129. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  130. package/skills/codebase-design/SKILL.md +114 -0
  131. package/skills/codex-collaborator/SKILL.md +24 -45
  132. package/skills/communication-doctrine/SKILL.md +89 -0
  133. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  134. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  135. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  136. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  137. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  138. package/skills/domain-modeling/SKILL.md +74 -0
  139. package/skills/executing-plans/SKILL.md +6 -56
  140. package/skills/executing-plans/scripts/task-done +52 -52
  141. package/skills/executing-plans/scripts/task-start +28 -28
  142. package/skills/gemini-collaborator/SKILL.md +24 -56
  143. package/skills/grill-me/SKILL.md +65 -0
  144. package/skills/handoff/SKILL.md +64 -0
  145. package/skills/herdr/SKILL.md +243 -0
  146. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  147. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  148. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  149. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  150. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  151. package/skills/karpathy-guidelines/SKILL.md +67 -67
  152. package/skills/mcp-engineering/SKILL.md +74 -0
  153. package/skills/minimalist-skill/SKILL.md +87 -85
  154. package/skills/output-skill/SKILL.md +49 -49
  155. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  156. package/skills/owasp-security/reference/languages.md +378 -372
  157. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  158. package/skills/owasp-security/reference/review-checklist.md +134 -132
  159. package/skills/ponytail/SKILL.md +36 -52
  160. package/skills/postgres-best-practices/SKILL.md +30 -52
  161. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  162. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  163. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  164. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  165. package/skills/postgres-best-practices/references/indexing.md +318 -0
  166. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  167. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  168. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  169. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  170. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  171. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  172. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  173. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  174. package/skills/progressive-disclosure/SKILL.md +68 -0
  175. package/skills/pstack-discipline/SKILL.md +40 -0
  176. package/skills/receiving-code-review/SKILL.md +2 -23
  177. package/skills/requesting-code-review/SKILL.md +7 -36
  178. package/skills/soft-skill/SKILL.md +99 -98
  179. package/skills/stitch-skill/DESIGN.md +121 -121
  180. package/skills/stitch-skill/SKILL.md +185 -184
  181. package/skills/strix-security/SKILL.md +54 -53
  182. package/skills/subagent-driven-development/SKILL.md +35 -264
  183. package/skills/subagent-driven-development/references/batching.md +11 -0
  184. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  185. package/skills/subagent-driven-development/references/final-review.md +47 -0
  186. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  187. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  188. package/skills/subagent-driven-development/references/preflight.md +26 -0
  189. package/skills/subagent-driven-development/references/resuming.md +12 -0
  190. package/skills/subagent-driven-development/scripts/review-package +53 -53
  191. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  192. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  193. package/skills/systematic-debugging/SKILL.md +283 -306
  194. package/skills/taste-skill/SKILL.md +542 -1206
  195. package/skills/taste-skill/references/app-screens.md +1199 -0
  196. package/skills/taste-skill/references/colour.md +141 -0
  197. package/skills/taste-skill/references/copy.md +177 -0
  198. package/skills/taste-skill/references/critique.md +182 -0
  199. package/skills/taste-skill/references/imagery.md +791 -0
  200. package/skills/taste-skill/references/layout.md +292 -0
  201. package/skills/taste-skill/references/motion.md +980 -0
  202. package/skills/taste-skill/references/research.md +356 -0
  203. package/skills/taste-skill/references/scenes.md +174 -0
  204. package/skills/taste-skill/references/tells.md +115 -0
  205. package/skills/taste-skill/references/type.md +170 -0
  206. package/skills/test-driven-development/SKILL.md +330 -337
  207. package/skills/thermo/SKILL.md +67 -0
  208. package/skills/threat-modeling/SKILL.md +55 -0
  209. package/skills/to-spec/SKILL.md +75 -0
  210. package/skills/to-tickets/SKILL.md +105 -0
  211. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  212. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  213. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  214. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  215. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  216. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  217. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  218. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  219. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  220. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  221. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  222. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  223. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  224. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  225. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  226. package/skills/verification-before-completion/SKILL.md +0 -14
  227. package/skills/wayfinder/SKILL.md +128 -0
  228. package/skills/writing-plans/SKILL.md +11 -15
  229. package/skills/writing-skills/SKILL.md +21 -303
  230. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  231. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  232. package/skills/writing-skills/references/bulletproofing.md +80 -0
  233. package/skills/writing-skills/references/discovery.md +201 -0
  234. package/skills/writing-skills/references/flowcharts.md +37 -0
  235. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  236. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  237. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  238. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  239. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  240. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  241. package/skills/gpt-tasteskill/SKILL.md +0 -74
  242. package/skills/taste-skill-v1/SKILL.md +0 -226
  243. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  244. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  245. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  246. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  247. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  248. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  249. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  250. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -1,53 +1,53 @@
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 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
- set -euo pipefail
11
-
12
- if [ $# -lt 3 ] || [ $# -gt 4 ]; then
13
- echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
14
- exit 2
15
- fi
16
-
17
- plan=$1
18
- base=$2
19
- head=$3
20
- [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
21
-
22
- git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
23
- git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
24
-
25
- # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
26
- # not rooted at BASE; either would silently produce a bogus review package.
27
- git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
28
- [ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
29
-
30
- if [ $# -eq 4 ]; then
31
- out=$4
32
- else
33
- # Invoke via bash rather than direct exec: some extractors (Python zipfile)
34
- # strip Unix exec bits when unpacking marketplace packages (#2040).
35
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
36
- out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
37
- fi
38
-
39
- {
40
- echo "# Review package: ${base}..${head}"
41
- echo
42
- echo "## Commits"
43
- git log --oneline "${base}..${head}"
44
- echo
45
- echo "## Files changed"
46
- git diff --stat "${base}..${head}"
47
- echo
48
- echo "## Diff"
49
- git diff -U10 "${base}..${head}"
50
- } > "$out"
51
-
52
- commits=$(git rev-list --count "${base}..${head}")
53
- echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
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 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
+ set -euo pipefail
11
+
12
+ if [ $# -lt 3 ] || [ $# -gt 4 ]; then
13
+ echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
14
+ exit 2
15
+ fi
16
+
17
+ plan=$1
18
+ base=$2
19
+ head=$3
20
+ [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
21
+
22
+ git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
23
+ git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
24
+
25
+ # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
26
+ # not rooted at BASE; either would silently produce a bogus review package.
27
+ git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
28
+ [ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
29
+
30
+ if [ $# -eq 4 ]; then
31
+ out=$4
32
+ else
33
+ # Invoke via bash rather than direct exec: some extractors (Python zipfile)
34
+ # strip Unix exec bits when unpacking marketplace packages (#2040).
35
+ dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
36
+ out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
37
+ fi
38
+
39
+ {
40
+ echo "# Review package: ${base}..${head}"
41
+ echo
42
+ echo "## Commits"
43
+ git log --oneline "${base}..${head}"
44
+ echo
45
+ echo "## Files changed"
46
+ git diff --stat "${base}..${head}"
47
+ echo
48
+ echo "## Diff"
49
+ git diff -U10 "${base}..${head}"
50
+ } > "$out"
51
+
52
+ commits=$(git rev-list --count "${base}..${head}")
53
+ echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
@@ -1,82 +1,87 @@
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
- # Usage: sdd-workspace PLAN_FILE
31
- set -euo pipefail
32
-
33
- if [ $# -ne 1 ]; then
34
- echo "usage: sdd-workspace PLAN_FILE" >&2
35
- exit 2
36
- fi
37
-
38
- plan=$1
39
- [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
40
-
41
- slug=$(basename "$plan" .md)
42
- [ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
43
- || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
44
-
45
- root=$(git rev-parse --show-toplevel)
46
- base="$root/.superpowers/sdd"
47
-
48
- # Normalize the plan path (physical directory, so relative/absolute/../
49
- # spellings of one plan compare equal) and express it as the marker value:
50
- # repo-relative when the plan lives under the repo root, absolute otherwise.
51
- plan_dir=$(CDPATH= cd -- "$(dirname "$plan")" && pwd -P)
52
- plan_abs="$plan_dir/$(basename "$plan")"
53
- case "$plan_abs" in
54
- "$root"/*) plan_id=${plan_abs#"$root"/} ;;
55
- *) plan_id=$plan_abs ;;
56
- esac
57
-
58
- # True when the workspace at $1 is (or becomes) this plan's: an existing
59
- # marker must name this plan; a missing marker means a new workspace or a
60
- # pre-marker legacy one, and either way the plan claims it by writing one.
61
- owns() {
62
- if [ -e "$1/plan-path" ]; then
63
- [ "$(cat "$1/plan-path")" = "$plan_id" ]
64
- else
65
- mkdir -p "$1"
66
- printf '%s\n' "$plan_id" > "$1/plan-path"
67
- fi
68
- }
69
-
70
- dir="$base/$slug"
71
- if ! owns "$dir"; then
72
- parent=$(basename "$plan_dir")
73
- dir="$base/$slug-$parent"
74
- if ! owns "$dir"; then
75
- n=2
76
- while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
77
- dir="$base/$slug-$parent-$n"
78
- fi
79
- fi
80
-
81
- printf '*\n' > "$base/.gitignore"
82
- CDPATH= cd -- "$dir" && pwd
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
+ # Usage: sdd-workspace PLAN_FILE
31
+ set -euo pipefail
32
+
33
+ if [ $# -ne 1 ]; then
34
+ echo "usage: sdd-workspace PLAN_FILE" >&2
35
+ exit 2
36
+ fi
37
+
38
+ plan=$1
39
+ [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
40
+
41
+ slug=$(basename "$plan" .md)
42
+ [ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
43
+ || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
44
+
45
+ # Physical path, spelled the way pwd -P spells the plan path below: on Git
46
+ # Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the
47
+ # repo-relative marker check needs both in the same form.
48
+ root=$(CDPATH='' cd -- "$(git rev-parse --show-toplevel)" && pwd -P)
49
+ base="$root/.superpowers/sdd"
50
+
51
+ # Normalize the plan path (physical directory, so relative/absolute/../
52
+ # spellings of one plan compare equal) and express it as the marker value:
53
+ # repo-relative when the plan lives under the repo root, absolute otherwise.
54
+ plan_dir=$(CDPATH='' cd -- "$(dirname "$plan")" && pwd -P)
55
+ plan_abs="$plan_dir/$(basename "$plan")"
56
+ case "$plan_abs" in
57
+ "$root"/*) plan_id=${plan_abs#"$root"/} ;;
58
+ *) plan_id=$plan_abs ;;
59
+ esac
60
+
61
+ # True when the workspace at $1 is (or becomes) this plan's: an existing
62
+ # marker must name this plan; a missing marker means a new workspace or a
63
+ # pre-marker legacy one, and either way the plan claims it by writing one.
64
+ owns() {
65
+ if [ -e "$1/plan-path" ]; then
66
+ [ "$(cat "$1/plan-path")" = "$plan_id" ]
67
+ else
68
+ mkdir -p "$1"
69
+ printf '%s\n' "$plan_id" > "$1/plan-path"
70
+ fi
71
+ }
72
+
73
+ dir="$base/$slug"
74
+ if ! owns "$dir"; then
75
+ parent=$(basename "$plan_dir")
76
+ dir="$base/$slug-$parent"
77
+ if ! owns "$dir"; then
78
+ n=2
79
+ while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
80
+ dir="$base/$slug-$parent-$n"
81
+ fi
82
+ fi
83
+
84
+ # Create-only: a repo may commit its own .gitignore here (e.g. to version
85
+ # progress.md ledgers); overwriting it would revert that on every run.
86
+ [ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
87
+ CDPATH='' cd -- "$dir" && pwd
@@ -1,43 +1,43 @@
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 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).
10
- set -euo pipefail
11
-
12
- if [ $# -lt 2 ] || [ $# -gt 3 ]; then
13
- echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
14
- exit 2
15
- fi
16
-
17
- plan=$1
18
- n=$2
19
- [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
20
-
21
- if [ $# -eq 3 ]; then
22
- out=$3
23
- else
24
- # Invoke via bash rather than direct exec: some extractors (Python zipfile)
25
- # strip Unix exec bits when unpacking marketplace packages (#2040).
26
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
27
- out="$dir/task-${n}-brief.md"
28
- fi
29
-
30
- awk -v n="$n" '
31
- /^```/ { infence = !infence }
32
- !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
33
- intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
34
- }
35
- intask { print }
36
- ' "$plan" > "$out"
37
-
38
- if [ ! -s "$out" ]; then
39
- echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
40
- exit 3
41
- fi
42
-
43
- echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"
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 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).
10
+ set -euo pipefail
11
+
12
+ if [ $# -lt 2 ] || [ $# -gt 3 ]; then
13
+ echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
14
+ exit 2
15
+ fi
16
+
17
+ plan=$1
18
+ n=$2
19
+ [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
20
+
21
+ if [ $# -eq 3 ]; then
22
+ out=$3
23
+ else
24
+ # Invoke via bash rather than direct exec: some extractors (Python zipfile)
25
+ # strip Unix exec bits when unpacking marketplace packages (#2040).
26
+ dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
27
+ out="$dir/task-${n}-brief.md"
28
+ fi
29
+
30
+ awk -v n="$n" '
31
+ /^```/ { infence = !infence }
32
+ !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
33
+ intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
34
+ }
35
+ intask { print }
36
+ ' "$plan" > "$out"
37
+
38
+ if [ ! -s "$out" ]; then
39
+ echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
40
+ exit 3
41
+ fi
42
+
43
+ echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"