heimdall-agent 1.0.0 → 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 (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  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 +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -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 +21 -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 +210 -100
  22. package/docs/SKILLS.md +341 -245
  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/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /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"