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
@@ -70,23 +70,13 @@ digraph process {
70
70
  "Implementer implements, tests, commits, self-reviews" [shape=box];
71
71
  "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
72
72
  "Spec ✅ and quality approved?" [shape=diamond];
73
- "Finding conflicts with plan text?" [shape=diamond];
74
- "Rule on the conflict, ledger the ruling" [shape=box];
75
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
76
- "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
77
- "All findings addressed?" [shape=diamond];
78
- "R = 5?" [shape=diamond];
79
- "Adjudicate each open finding" [shape=box];
80
- "Any load-bearing finding?" [shape=diamond];
81
- "Rule and continue; stop only if every path forward is a guess" [shape=box];
82
- "Park findings in ledger with rulings" [shape=box];
73
+ "Fix loop: read references/fix-loop.md before every round" [shape=box];
83
74
  "Append completion to ledger, mark todo complete" [shape=box];
84
75
  }
85
76
 
86
77
  "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
87
78
  "More tasks remain?" [shape=diamond];
88
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
89
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
79
+ "Final review and finish: read references/final-review.md" [shape=box];
90
80
  "Final review clean: delete this plan's workspace" [shape=box];
91
81
  "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
92
82
 
@@ -98,25 +88,12 @@ digraph process {
98
88
  "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
99
89
  "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
100
90
  "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
101
- "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
102
- "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
103
- "Rule on the conflict, ledger the ruling" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
104
- "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
105
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
106
- "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
107
- "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
108
- "All findings addressed?" -> "R = 5?" [label="no"];
109
- "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
110
- "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
111
- "Adjudicate each open finding" -> "Any load-bearing finding?";
112
- "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
113
- "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
114
- "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
91
+ "Spec ✅ and quality approved?" -> "Fix loop: read references/fix-loop.md before every round" [label="no"];
92
+ "Fix loop: read references/fix-loop.md before every round" -> "Append completion to ledger, mark todo complete" [label="addressed, or parked at the cap"];
115
93
  "Append completion to ledger, mark todo complete" -> "More tasks remain?";
116
94
  "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
117
- "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
118
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
119
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
95
+ "More tasks remain?" -> "Final review and finish: read references/final-review.md" [label="no"];
96
+ "Final review and finish: read references/final-review.md" -> "Final review clean: delete this plan's workspace";
120
97
  "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
121
98
  }
122
99
  ```
@@ -134,17 +111,14 @@ sequences — the single most expensive failure observed. Track progress in
134
111
  a ledger file, not only in todos.
135
112
 
136
113
  - Each plan owns a workspace: at skill start, run this skill's
137
- `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
114
+ `bash scripts/sdd-workspace PLAN_FILE` by its absolute path, from the
115
+ working tree you're executing in — it prints the plan's git-ignored
138
116
  directory (under `<repo-root>/.superpowers/sdd/`), home to
139
117
  every artifact for THIS plan: ledger, briefs, reports, review packages.
140
118
  Another plan's directory is never yours to read or write.
141
- - Check for this plan's ledger at `<workspace>/progress.md`. If its first
142
- line names your plan file, tasks with a `Task <N>: complete` line are DONE
143
- — do not re-dispatch them; resume at the first task without one. A task
144
- whose last line is a fix round is mid-loop: resume the loop at the next
145
- round. A ledger whose first line names a different plan file — or a stray
146
- ledger at the old flat path `.superpowers/sdd/progress.md` — is another
147
- plan's progress: leave it in place and start your own, fresh.
119
+ - Check for this plan's ledger at `<workspace>/progress.md`. If one exists,
120
+ read [references/resuming.md](references/resuming.md) before anything
121
+ else: it says whose ledger it is and where to resume.
148
122
  - Create the ledger with its identity as the first line:
149
123
  `# SDD ledger — plan: <plan file path>`.
150
124
  - The ledger is your recovery map: the commits it names exist in git even
@@ -159,27 +133,9 @@ authority the plan argues from, and conflicts inside the plan resolve
159
133
  against it. A plan with no reachable spec gets a ledger note saying so —
160
134
  rulings made without one are provisional.
161
135
 
162
- Before dispatching Task 1, scan the plan once for conflicts, writing down
163
- what you checked as you check it:
164
-
165
- - tasks that contradict each other or the plan's Global Constraints
166
- - anything the plan explicitly mandates that the review rubric treats as a
167
- defect (a test that asserts nothing, verbatim duplication of a logic block)
168
-
169
- The scan's output is a table, not a verdict. One row for every pair of tasks
170
- that share a file or an interface: the two tasks, what one produces against
171
- what the other consumes, and what you found. One row for every task: whether
172
- its own text agrees with itself — the tests it specifies against the code it
173
- specifies, the files it creates against the files it later touches. "The scan
174
- is clean" without those rows is not a scan you ran.
175
-
176
- Write the table to the ledger. Rule on everything you find before execution
177
- begins — each finding against the plan text that mandates it — and record
178
- each ruling in the ledger. If the scan is clean, proceed without comment.
179
- Rule on each conflict it surfaces — the spec is the binding authority, the
180
- plan is its argument — record the ruling beside its row, and dispatch
181
- Task 1. The review loop remains the net for conflicts that only emerge from
182
- implementation.
136
+ Before dispatching Task 1, read [references/preflight.md](references/preflight.md)
137
+ and run the conflict scan it describes. Its table and rulings go in the
138
+ ledger.
183
139
 
184
140
  ## Model Selection
185
141
 
@@ -220,13 +176,9 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
220
176
 
221
177
  ## The Task Loop
222
178
 
223
- **Batch small same-shape work.** When the plan lists several tasks that are
224
- each a small, independent edit of the same kind — the same one-line fix,
225
- constant change, or field addition repeated across files — do not dispatch
226
- one subagent per task. Compose ONE dispatch brief listing every file and
227
- its change, send the whole batch to a single subagent, and review its diff
228
- as one unit. Reserve one-dispatch-per-task for work that needs its own
229
- judgment, its own tests, or its own review surface.
179
+ **Small same-shape work:** when the plan lists several small edits of the
180
+ same kind across files, read [references/batching.md](references/batching.md)
181
+ before dispatching them.
230
182
 
231
183
  Everything you paste into a dispatch prompt — and everything a subagent
232
184
  prints back — stays resident in your context for the rest of the session
@@ -249,7 +201,8 @@ Record BASE (`git rev-parse HEAD`) before dispatching — the review package
249
201
  and fix-round diffs need it.
250
202
 
251
203
  - **Task brief:** before dispatching an implementer, run this skill's
252
- `bash scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
204
+ `bash scripts/task-brief PLAN_FILE N` by its absolute path, from the
205
+ working tree you're executing in — it extracts the task's full text to a
253
206
  uniquely named file and prints the path. Compose the dispatch so the
254
207
  brief stays the single source of
255
208
  requirements. Your dispatch should contain: (1) one line on where this
@@ -287,19 +240,11 @@ Template: [implementer-prompt.md](implementer-prompt.md)
287
240
 
288
241
  Implementer subagents report one of four statuses. Handle each appropriately:
289
242
 
290
- **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
291
-
292
- **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.
243
+ **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from the working tree you're executing in — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
293
244
 
294
- **NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
295
-
296
- **BLOCKED:** The implementer cannot complete the task. Assess the blocker:
297
- 1. If it's a context problem, provide more context and re-dispatch with the same model
298
- 2. If the task requires more reasoning, re-dispatch with a more capable model
299
- 3. If the task is too large, break it into smaller pieces
300
- 4. If the plan itself is wrong, rule on the correction, ledger it, and re-dispatch with the ruling carried in the dispatch
301
-
302
- **Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
245
+ **Any other status** (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED): read
246
+ [references/handling-reports.md](references/handling-reports.md) and follow
247
+ it, every time you get one.
303
248
 
304
249
  If the implementer asks questions — before starting or mid-task — answer
305
250
  clearly and completely, provide additional context if needed, and don't
@@ -314,7 +259,8 @@ required. Implementer self-review never replaces the task review; both are
314
259
  needed.
315
260
 
316
261
  - Hand the reviewer its diff as a file: run this skill's
317
- `bash scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
262
+ `bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from
263
+ the working tree you're executing in, and pass the reviewer the file path
318
264
  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
319
265
  and `git diff -U10` for the range, redirected to one uniquely named
320
266
  file). The output never enters your own context, and the reviewer sees
@@ -342,12 +288,9 @@ needed.
342
288
  loop. If the prompt you are writing contains "do not flag," "don't treat X
343
289
  as a defect," "at most Minor," or "the plan chose" — stop: you are
344
290
  pre-judging, usually to spare yourself a review loop.
345
- The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
346
- that live in unchanged code or span tasks. These do not block the rest of the
347
- review, but you must resolve each one yourself before marking the task
348
- complete: you hold the plan and cross-task context the reviewer
349
- lacks. If you confirm an item is a real gap, treat it as a failed spec
350
- review — it enters the fix loop with the other findings.
291
+ If the reviewer reports "⚠️ Cannot verify from diff" items, read
292
+ [references/cannot-verify.md](references/cannot-verify.md) before you mark
293
+ the task complete.
351
294
 
352
295
  Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
353
296
 
@@ -356,77 +299,10 @@ Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
356
299
  The loop triggers when the review reports spec ❌, any Critical or Important
357
300
  finding, or a ⚠️ item you confirmed as a real gap.
358
301
 
359
- Before the loop starts, two routes leave it immediately:
360
-
361
- - Record Minor findings in the progress ledger as you go
362
- (`Task <N>: minor (deferred): <one-liner>`), and point the final
363
- whole-branch review at that list so it can triage which must be fixed
364
- before merge. A roll-up nobody reads is a silent discard. Minor findings
365
- never enter the loop.
366
- - A finding labeled plan-mandated — or any finding that conflicts with
367
- what the plan's text requires — is yours to rule on: weigh the finding
368
- against the plan text, decide with the spec as the binding authority, and
369
- ledger the ruling before you act on it. Do not dismiss the finding because
370
- the plan mandates it, and do not dispatch a fix that contradicts the plan
371
- without a recorded ruling.
372
- Everything else enters the loop. A fix round is one fix dispatch plus one
373
- scoped re-review. Five rounds maximum per task:
374
-
375
- **Rounds 1-3 — resume the original implementer.** Send it the open findings
376
- verbatim. Its context is intact: it knows the task, the code, and its own
377
- choices. If your harness cannot send another message to a live subagent,
378
- dispatch a fresh implementer carrying the brief path, the report-file path,
379
- and the findings — the report file is the persistent memory either way.
380
-
381
- **Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
382
- Model Selection), with the brief path, the report-file path, the open
383
- findings, and this framing: "A prior implementer attempted this task
384
- [N] times; you own it now. Read the report file for what was tried." A loop
385
- that survives three resumes usually means the implementer cannot see its
386
- own problem — fresh eyes and a capability bump in one move.
387
-
388
- **Every round, either way:** the implementer fixes, re-runs the tests
389
- covering the amended code, appends its fix report to the same report file,
390
- and returns the short contract. Before re-dispatching the reviewer, confirm
391
- the fix report contains the covering tests, the command run, and the
392
- output; dispatch the re-review once all three are present. Name the
393
- covering test files in the fix message — a one-line fix does not need the
394
- whole suite.
395
-
396
- **The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
397
- where FIX_BASE is the head the previous review saw, and dispatch
398
- [re-review-prompt.md](re-review-prompt.md) with the findings list, the
399
- brief, the report file, and the printed diff path. The re-reviewer verdicts
400
- each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
401
- diff only. New Critical/Important breakage in the fix diff joins the open
402
- findings list. Out-of-scope observations go to the ledger as deferred
403
- minors — they never extend the loop.
404
-
405
- **After each round,** append to the ledger:
406
- `Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
407
-
408
- Never fix findings yourself in the controller session — your context stays
409
- clean for coordination, and controller fixes skip review.
410
-
411
- **The breaker.** When round 5's re-review still leaves findings open, stop
412
- dispatching. Adjudicate each open finding yourself — you hold the plan and
413
- the cross-task context the reviewer lacks:
414
-
415
- - **The reviewer is wrong, or the point is contestable:** park it —
416
- `Task <N>: parked — <finding> — Ruling: <why the code stands>`. The final
417
- review sees both sides.
418
- - **Real, but nothing downstream builds on it:** park it the same way, with
419
- a ruling that says it's real and deferred.
420
- - **Real and load-bearing** — a later task builds on it, or it reveals a
421
- plan defect: rule on the smallest change that unblocks the dependent work,
422
- ledger it as `Task <N>: Ruling: <finding> — <what you decided and why>`,
423
- and carry it into the next task's dispatch. Parking a structural failure
424
- silently lets every dependent task build on it. Stop only when the defect
425
- leaves every path forward a guess.
426
-
427
- Adjudicate only at the cap. Adjudicating earlier to end a loop is
428
- pre-judging with a different name. Every adjudication is a ledger entry —
429
- a silent discard is forbidden.
302
+ When it triggers, read [references/fix-loop.md](references/fix-loop.md) and
303
+ follow it. Read it again before every round, even if you read it earlier in
304
+ this session: it holds the round cap, the breaker, and the ledger line each
305
+ round writes, and your memory of it does not survive compaction.
430
306
 
431
307
  ### 5. Complete the task
432
308
 
@@ -444,47 +320,9 @@ parked-with-ruling at the cap.
444
320
 
445
321
  ## Final Review
446
322
 
447
- The final whole-branch review gets a package too: run
448
- `bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
449
- branch started from, e.g. `git merge-base main HEAD`) and include the
450
- printed path in the final review dispatch, so the final reviewer reads
451
- one file instead of re-deriving the branch diff with git commands. Dispatch
452
- on the most capable available model (see Model Selection), using
453
- superpowers:requesting-code-review's
454
- [code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
455
- the ledger's deferred-minor and parked lines so it can triage which must be
456
- fixed before merge.
457
-
458
- If the final whole-branch review returns findings, dispatch ONE fix subagent
459
- with the complete findings list — not one fixer per finding.
460
- Per-finding fixers each rebuild context and re-run suites; a real
461
- session's final-review fix wave cost more than all its tasks combined.
462
- Then run exactly one scoped re-review of the fix wave
463
- (`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
464
- [re-review-prompt.md](re-review-prompt.md)).
465
- Adjudicate any residual findings as in the task loop's breaker: park with
466
- rulings, or rule on the load-bearing ones and ledger what you decided. Only
467
- the four classes above stop you here. There is no second fix wave —
468
- residual load-bearing findings surface to your human partner when
469
- finishing-a-development-branch presents the options.
470
-
471
- ## Finish
472
-
473
- Before you delete anything, collect every ledger line containing `Ruling:` —
474
- preflight rulings, parked findings, breaker adjudications, all of them — into
475
- your final message under "Rulings I made", in the order you made them, each
476
- with what it costs if wrong. The list is exhaustive: if the ledger holds a
477
- ruling, the list holds it. That list is the only place the decisions you
478
- took on your human partner's behalf reach them — they read it and rework
479
- whatever you got wrong. A ruling that dies with the workspace was a decision
480
- made in secret.
481
-
482
- When the final whole-branch review is clean and its fixes are merged,
483
- delete this plan's workspace (`rm -rf <workspace>`) — the git history is
484
- the record now. Sibling directories belong to other plans; leave them
485
- alone.
486
-
487
- Use superpowers:finishing-a-development-branch.
323
+ When every task is complete, read
324
+ [references/final-review.md](references/final-review.md) and follow it. It
325
+ covers the whole-branch review, its single fix wave, and how you finish.
488
326
 
489
327
  ## Common Rationalizations
490
328
 
@@ -499,70 +337,3 @@ Use superpowers:finishing-a-development-branch.
499
337
  | "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
500
338
  | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
501
339
  | "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
502
-
503
- ## Example Workflow
504
-
505
- ```
506
- You: I'm using Subagent-Driven Development to execute this plan.
507
-
508
- [Setup: worktree verified]
509
- [Read plan file once: docs/superpowers/plans/feature-plan.md]
510
- [Resolve workspace: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
511
- [Create todos for all tasks]
512
-
513
- Task 1: Hook installation script
514
-
515
- [Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
516
-
517
- Implementer: "Before I begin - should the hook be installed at user or system level?"
518
-
519
- You: "User level (~/.config/superpowers/hooks/)"
520
-
521
- Implementer: [Later]
522
- - Implemented install-hook command
523
- - Added tests, 5/5 passing
524
- - Self-review: Found I missed --force flag, added it
525
- - Committed
526
-
527
- [Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
528
- Task reviewer: Spec ✅ - all requirements met, nothing extra.
529
- Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
530
-
531
- [Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
532
-
533
- Task 2: Recovery modes
534
-
535
- [Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
536
-
537
- Implementer: [No questions]
538
- - Added verify/repair modes
539
- - 8/8 tests passing
540
- - Committed
541
-
542
- [Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
543
- Task reviewer: Spec ❌:
544
- - Missing: Progress reporting (spec says "report every 100 items")
545
- Issues (Important): Magic number (100)
546
-
547
- [Fix round 1: resume the implementer with both findings]
548
- Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
549
- Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
550
-
551
- [Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
552
- Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
553
- Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
554
- Verdict: all findings addressed.
555
-
556
- [Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
557
- [Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
558
-
559
- ...
560
-
561
- [After all tasks]
562
- [Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
563
- Final reviewer: All requirements met. Deferred minors triaged: none block merge.
564
-
565
- [Delete this plan's workspace — the record now lives in git]
566
-
567
- Done! Using superpowers:finishing-a-development-branch.
568
- ```
@@ -0,0 +1,11 @@
1
+ # Batching Small Same-Shape Work
2
+
3
+ Part of superpowers:subagent-driven-development.
4
+
5
+ **Batch small same-shape work.** When the plan lists several tasks that are
6
+ each a small, independent edit of the same kind — the same one-line fix,
7
+ constant change, or field addition repeated across files — do not dispatch
8
+ one subagent per task. Compose ONE dispatch brief listing every file and
9
+ its change, send the whole batch to a single subagent, and review its diff
10
+ as one unit. Reserve one-dispatch-per-task for work that needs its own
11
+ judgment, its own tests, or its own review surface.
@@ -0,0 +1,10 @@
1
+ # "Cannot Verify From Diff" Items
2
+
3
+ Part of superpowers:subagent-driven-development.
4
+
5
+ The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
6
+ that live in unchanged code or span tasks. These do not block the rest of the
7
+ review, but you must resolve each one yourself before marking the task
8
+ complete: you hold the plan and cross-task context the reviewer
9
+ lacks. If you confirm an item is a real gap, treat it as a failed spec
10
+ review — it enters the fix loop with the other findings.
@@ -0,0 +1,47 @@
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` (MERGE_BASE = the commit the
8
+ branch started from, e.g. `git merge-base main HEAD`) and include the
9
+ printed path in the final review dispatch, so the final reviewer reads
10
+ one file instead of re-deriving the branch diff with git commands. Dispatch
11
+ on the most capable available model (see SKILL.md's Model Selection), using
12
+ superpowers:requesting-code-review's
13
+ [code-reviewer.md](../../requesting-code-review/code-reviewer.md). Point it at
14
+ the ledger's deferred-minor and parked lines so it can triage which must be
15
+ fixed before merge.
16
+
17
+ If the final whole-branch review returns findings, dispatch ONE fix subagent
18
+ with the complete findings list — not one fixer per finding.
19
+ Per-finding fixers each rebuild context and re-run suites; a real
20
+ session's final-review fix wave cost more than all its tasks combined.
21
+ Then run exactly one scoped re-review of the fix wave
22
+ (`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
23
+ [re-review-prompt.md](../re-review-prompt.md)).
24
+ Adjudicate any residual findings as in the fix loop's breaker
25
+ (references/fix-loop.md): park with rulings, or rule on the load-bearing
26
+ ones and ledger what you decided. Only the four things that stop a running
27
+ plan (top of SKILL.md) stop you here. There is no second fix wave —
28
+ residual load-bearing findings surface to your human partner when
29
+ finishing-a-development-branch presents the options.
30
+
31
+ ### Finish
32
+
33
+ Before you delete anything, collect every ledger line containing `Ruling:` —
34
+ preflight rulings, parked findings, breaker adjudications, all of them — into
35
+ your final message under "Rulings I made", in the order you made them, each
36
+ with what it costs if wrong. The list is exhaustive: if the ledger holds a
37
+ ruling, the list holds it. That list is the only place the decisions you
38
+ took on your human partner's behalf reach them — they read it and rework
39
+ whatever you got wrong. A ruling that dies with the workspace was a decision
40
+ made in secret.
41
+
42
+ When the final whole-branch review is clean and its fixes are merged,
43
+ delete this plan's workspace (`rm -rf <workspace>`) — the git history is
44
+ the record now. Sibling directories belong to other plans; leave them
45
+ alone.
46
+
47
+ 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
+ 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.