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,285 +1,294 @@
1
1
  ---
2
2
  name: brainstorming
3
- description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
3
+ description: "You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation)."
4
4
  ---
5
5
 
6
- # Brainstorming Ideas Into Designs
7
-
8
- Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
9
-
10
- Start by classifying how much process the request needs, then work
11
- through your path: understand the context, refine the idea, present a
12
- design, and get your human partner's approval.
13
-
14
- ## Establish Shared Understanding
15
-
16
- The outcome of brainstorming is an understanding your human partner can
17
- recognize and correct, grounded in what they want to accomplish.
18
-
19
- 1. **Discover intent.** Use the request and available context to identify
20
- the intended outcome, who it is for, and what success looks like. When
21
- that information is missing, ask one focused question about purpose or
22
- intended use before proposing features or an approach. Knowing the app
23
- genre does not tell you why your partner wants it. Gathering missing
24
- requirements does not ask them to authorize the task again.
25
- 2. **Write back your understanding.** Summarize the intended outcome,
26
- relevant constraints, and success criteria in a short note your partner
27
- can assess. Separate what they said from assumptions. Invite correction
28
- and incorporate their answer before treating this as the design brief.
29
- 3. **Carry intent into the design.** Preserve the agreed understanding in
30
- the selected path's design artifact: the written spec for architectural
31
- work, or the in-chat design/probe for bounded work and spikes. Check
32
- proposed features and technical choices against that understanding.
33
-
34
- When the request already supplies the purpose and constraints, reflect
35
- that understanding instead of asking the same questions again. Keep the
36
- note concise; its accuracy and the opportunity to correct it matter.
6
+ # Brainstorming
7
+
8
+ You are very good at building. You build what you believe your human
9
+ partner wants, and that belief is usually thinner than it feels. This
10
+ skill is for finding out what they actually want, and why, before
11
+ anything gets built.
12
+
13
+ People often haven't finished working out what they want. Good questions
14
+ help them think it through. When you understand the why, you make the
15
+ hundred decisions they never mention the way they would have made them.
16
+
17
+ ## First: What Do You Actually Know?
18
+
19
+ Before you reply, ask yourself: what do I know about what they want, and
20
+ why?
21
+
22
+ - **Everything that matters is in the request** ("make the icon cornflower
23
+ blue"). This is a quick, clear task. Do it, and say what you did.
24
+ - **Something non-trivial is missing.** Start the conversation.
25
+
26
+ Before you start implementing, you must, in order:
27
+
28
+ 1. Lay out the approaches in a message of their own, and have your
29
+ human partner pick one (see Lay out the approaches).
30
+ 2. Write the design doc, short or full (see Size the Work).
31
+ 3. Get their approval of that doc.
32
+ 4. Invoke the superpowers:writing-plans skill.
33
+
34
+ Two things aren't implementing: a spike they said yes to (see Spike to
35
+ feel things out), and doing what they asked once they've opted out of
36
+ the questions.
37
+
38
+ ## Look Before You Ask
39
+
40
+ In an existing project, or when they've given you context (a spec, a plan,
41
+ a handoff, files they pointed at, earlier conversation), dig in before your
42
+ first message. Read what they referred to and the code or material it
43
+ connects to, and keep reading until you can explain how the relevant
44
+ parts work today and what this change would touch. Never ask what the
45
+ project or their context already answers.
46
+
47
+ ## Your First Message
48
+
49
+ Move the work forward, with one of these:
50
+
51
+ - **They've already said what they want** (a spec, a plan, a detailed
52
+ request): aim for about 200 words for the whole message. Echo their
53
+ request back in your own words, so they can see whether you've got its
54
+ shape: what they want, who it's for, and why, as far as they've said.
55
+ Add what you found that bears on it: how the relevant parts work today
56
+ and what the change would touch. If you found something they may not
57
+ have considered that would change what they're asking for or how it
58
+ has to be built, like a constraint, a conflict, or a cheaper path, say
59
+ so plainly. How to build it comes later, once you understand what they
60
+ want (see Lay out the approaches). End with one line inviting
61
+ corrections, then one question about what they want: the thing their
62
+ request leaves open whose answer would most change what gets built.
63
+ Specs are often incomplete, so confirm before you build on one.
64
+ - **They haven't:** one open question, in their own terms, about the
65
+ biggest thing their request leaves unsettled. Say why you're asking:
66
+ what the answer would change about what you build. For "a website for
67
+ my bakery": "If it's mostly for people deciding whether to stop by,
68
+ I'd lead with hours and what's in the case today; taking orders is a
69
+ different site. What do you want someone to do when they land on it?"
70
+
71
+ How the message ends depends on whether their message asked for
72
+ brainstorming:
73
+
74
+ - **They asked for it** (by name, by invoking it, or by asking for a
75
+ design discussion): end with your question. They want this
76
+ conversation.
77
+ - **They didn't:** they may not want a conversation at all. After your
78
+ question, add a light, one-line offer to just get going instead, like
79
+ "Or if you'd rather I just dive in, say so." If they take you up on
80
+ it, this skill is done: state any significant how-it-gets-made choice
81
+ (platform, language, medium) in one plain line, then do what they
82
+ asked through the normal workflow.
83
+
84
+ That's the whole message.
85
+
86
+ ## The Conversation
87
+
88
+ Each message ends with one question: a single sentence with no list of
89
+ example answers hanging off it. Use plain language, pitched just a little
90
+ above where your human partner is. Match their vocabulary; never use
91
+ process jargon. You never need to quote this skill to your human
92
+ partner.
93
+
94
+ Be clear and concise. Lead with what matters. Avoid jargon. When you
95
+ report what you found, give them the most important findings and offer
96
+ the rest.
97
+
98
+ **Get them describing.** Open questions come first. Their own words carry
99
+ intent that your options can't. Offer a short menu only when they're
100
+ stuck. When they say "just guess" or "what do you think?", propose
101
+ something concrete.
102
+
103
+ **How it gets made.** Every project rests on choices about medium, tools,
104
+ materials, and resources: the platform, programming language, and
105
+ libraries for an app; the medium for a piece of art. Find out early which
106
+ of those choices they want to make, which they're handing to you, and what
107
+ they already have to work with. Someone with strong views or skills will
108
+ want to talk it through. Someone counting on you needs sensible defaults,
109
+ said in plain words. When there's existing work, build on what it already
110
+ uses. Any choice you make goes in the design as your call, never as
111
+ something they agreed to.
112
+
113
+ **Ground to cover.** This is territory, not a script. Never read these
114
+ out as questions:
115
+
116
+ - what kind of thing this is, and what makes it special
117
+ - why now, and what success looks like to them
118
+ - goals, non-goals, and anti-goals (what would make this a failure even
119
+ if it technically works)
120
+ - prior art: what they've seen elsewhere, loved or hated
121
+ - current state: what exists now, what they've tried
122
+ - the details they care about
123
+
124
+ **Make every question specific** to their project and what they've told
125
+ you. Ask Socratically, the way a sharp colleague would: build each
126
+ question on their last answer or on something you found, so it helps
127
+ them think through a consequence or a case they may have missed
128
+ ("Voting closes before the meeting, and two members joined this month.
129
+ Does someone who joins mid-round get a vote?"). When the reason isn't
130
+ already plain, say what you're hoping to learn or what the answer would
131
+ change. A proposal they can correct, plus your reason for it, often
132
+ beats a question.
133
+
134
+ **Offer recon.** Once you have a bit of grounding and looking further
135
+ would help, offer to go look: deeper into their codebase or project,
136
+ their own files and data, or the web. Say what you'd look for. They
137
+ decide whether you go.
138
+
139
+ **Lay out the approaches.** Once you understand what they want, and
140
+ before you write anything up, put the ways of building it in a message
141
+ of its own. Come up with several real alternatives and drop the weak
142
+ ones, including any that work against why they want it and any the
143
+ existing work rules out. Present the two or three that remain, grounding
144
+ each in what the project actually does and saying what it trades off.
145
+ Recommend one and say why, then ask which way they want to go. When
146
+ there's genuinely one sensible way, say so and explain why the others
147
+ don't fit. This is for how it gets built; for what they want, get them
148
+ describing first.
149
+
150
+ **Show, don't tell.** Offer the visual companion (below) whenever seeing
151
+ would help more than reading:
152
+
153
+ - something they'll look at: a screen, a page, a printout, a sign
154
+ - a layout or arrangement: of a screen, a room, a schedule
155
+ - a flow or a sequence of steps
156
+ - options that would look different from each other
157
+ - a structure that's easier to see than read: a diagram, a timeline, a map
158
+
159
+ Once they've accepted, use it for mockups to react to, side-by-side
160
+ options, and throwaway prototypes they can click.
161
+
162
+ **Spike to feel things out.** Agentic work is waterfall, but very, very
163
+ fast. A quick throwaway build is often the cheapest way to learn what
164
+ they want or whether something works. Offer one when it would help.
165
+ When they just want to spike, get out of the way. Spikes get no tests
166
+ or minimal ones, aren't bulletproof, and skip the plan, implementation,
167
+ and review process. Bring what the spike taught you back into the
168
+ conversation.
169
+
170
+ ## Play It Back
171
+
172
+ Play back as you go. As soon as you understand one part well enough to
173
+ describe it (what it's for and who it serves, say, or how one piece
174
+ behaves), describe that part back in about 200-300 words, then return to
175
+ questions about the next part. Playback and questions alternate through
176
+ the whole conversation; the last chunk covers whatever is left.
177
+
178
+ Only what they said goes in as theirs. Anything you filled in goes in
179
+ as your proposal, with your reason. End each chunk by asking what's wrong
180
+ or missing.
181
+
182
+ Before you send a chunk, check it: does it describe something they'll
183
+ look at, like a page, a screen, a schedule, or a printout? If so, and
184
+ they haven't seen the visual companion offer yet, send the offer instead
185
+ (its own message, below) and hold the chunk for the next message. Once
186
+ they've accepted, put a mockup next to the description.
187
+
188
+ ## Size the Work
189
+
190
+ Once you understand what they want and they've picked an approach, say
191
+ how big the work is in plain words. They can override it.
192
+
193
+ | Size | The design doc |
194
+ |------|----------------|
195
+ | A small change | a short one: what you already covered together, written down |
196
+ | A project | the full written design (below) |
197
+
198
+ Short or full, the design doc has an **Approaches** part: the two or
199
+ three ways you considered building it, what each trades off, which one
200
+ they picked, and why. They pick in the conversation, before you write
201
+ the doc.
202
+
203
+ If it grows mid-task, stop, say so, and step up a size.
204
+
205
+ If this is really several independent projects, say so, agree on an
206
+ order, and brainstorm them one at a time.
207
+
208
+ ## The Written Design
209
+
210
+ Write a plain document a talented builder in the domain could plan
211
+ from without going back to your human partner. Cover:
212
+
213
+ - intent and the why
214
+ - goals, non-goals, anti-goals
215
+ - constraints
216
+ - approaches (above)
217
+ - the parts of the how they decided, as they decided them
218
+ - what's left to the builder
219
+
220
+ For a small change, the short design covers the same points in a line
221
+ or two each and goes straight to your human partner, without the
222
+ builder check.
223
+
224
+ **Where it goes:** in a software repo,
225
+ `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
226
+ Otherwise, ask. Your human partner's preferences override both.
227
+
228
+ **Builder check** (for a project): dispatch a fresh subagent with
229
+ `builder-check-prompt.md` in this directory. When you tell your human
230
+ partner you're writing it up, say a reviewer will read it first and you
231
+ may come back once with a few questions. Don't hand over the document
232
+ until the check is back. Sort what the builder asks into three piles:
233
+
234
+ - **Answered already** by the conversation or the project: put the answer
235
+ in the document.
236
+ - **Minor:** a sensible builder could settle it without changing what gets
237
+ built. Settle it yourself and mark it in the document as your call.
238
+ - **Theirs:** only your human partner can answer it, and the answer changes
239
+ what gets built.
240
+
241
+ Bring the "theirs" pile in one message, most important first. Update the
242
+ document with their answers, then hand it over with a short list of the
243
+ calls you made so they can check those while reading. That's the only
244
+ round of questions the check produces. Without a subagent tool, read the
245
+ document as that builder yourself.
37
246
 
38
247
  <HARD-GATE>
39
- Before taking any implementation action, including invoking an
40
- implementation skill, writing product code, scaffolding, installing
41
- product dependencies, or creating an external project, complete the
42
- selected path's prerequisites:
43
-
44
- - Spike: the human partner approves the question and probe.
45
- - Bounded: the human partner approves the short in-chat design.
46
- - Architectural: the human partner reviews and approves the written spec,
47
- then reviews the written implementation plan and selects its execution
48
- method. Conversational design approval only permits writing the spec;
49
- written-spec approval only permits invoking writing-plans.
50
-
51
- A reply approves the stage actually presented. Approval of an idea or
52
- feature scope does not approve artifacts that do not exist yet. Resume
53
- at the earliest incomplete stage; do not turn one approval into permission
54
- to skip the rest of the selected path. Read-only project exploration is
55
- allowed while those prerequisites remain incomplete.
248
+ Nothing gets built until your human partner approves the design doc:
249
+ the short one for a small change, the full one for a project.
250
+ Building includes writing product code, scaffolding, installing
251
+ dependencies, creating projects, and invoking an implementation skill.
252
+ Reading and exploring are fine.
253
+
254
+ Two exceptions. If they opted out of the questions, the skill is done
255
+ and the gate goes with it. A spike they said yes to may be built; it
256
+ stays labeled throwaway, and keeping what it produced is a new request
257
+ that comes back through this gate.
258
+
259
+ After the design doc is approved, the next step is the plan: invoke
260
+ superpowers:writing-plans and no other skill.
56
261
  </HARD-GATE>
57
262
 
58
- ## Three Paths
59
-
60
- Before your first question, classify the request and say the
61
- classification out loud — "this looks bounded, so I'll present a short
62
- design here rather than write a spec" — so your human partner can
63
- override it:
64
-
65
- - **Spike** — a feasibility question ("can we...", "is it possible...",
66
- "quick and dirty is fine") whose output is an answer, not code you
67
- keep. Present the question and what you'll try in 2-3 sentences, get
68
- a nod, then find out as cheaply as correctness allows. No design
69
- doc, no spec file. Report findings as a recommendation; anything you
70
- built stays labeled throwaway.
71
- - **Bounded** — a well-scoped change to code that already exists in
72
- this repo: a new flag, a small endpoint, a one-file fix.
73
- Understanding the kind of app is not enough — bounded means the flow
74
- you are changing is already here to read. If there is no existing
75
- flow to change, the task is not bounded. Ask the clarifying
76
- questions that matter, present a short design IN CHAT (a few
77
- sentences to a few short paragraphs), and STOP. Implementation
78
- starts only after your human partner says yes to that design — a
79
- bounded task's approval is as hard a gate as an architectural
80
- one. No spec file, no implementation plan document.
81
- - **Architectural** — new projects, new subsystems, changes that
82
- restructure how components fit together or alter interfaces others
83
- depend on. Follow the full process: questions, approaches, sectioned
84
- design, written spec, then the writing-plans skill.
85
-
86
- When in doubt between two paths, take the heavier one. The ratchet is
87
- one-way: hidden complexity discovered mid-task upgrades the path —
88
- stop, say so, and step up. Nothing downgrades mid-task.
89
-
90
- ## Anti-Pattern: "Too Simple To Need Approval"
91
-
92
- Every path ends with your human partner approving the required design
93
- before implementation. A bounded change may need only two sentences in
94
- chat. A new todo-list project is architectural and requires the written
95
- spec and planning handoffs. Scale the artifact to the selected path;
96
- complete that path's reviews before implementation.
97
-
98
263
  ## Red Flags
99
264
 
100
265
  | Thought | Reality |
101
266
  |---------|---------|
102
- | "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. |
103
- | "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
104
- | "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
105
- | "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
106
- | "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
107
- | "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
108
- | "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
109
-
110
- ## Checklist
111
-
112
- Classify first, announce the path, then create a task for each item on
113
- your path and complete them in order.
114
-
115
- **Spike:**
116
- 1. **Explore project context** — enough to frame the probe
117
- 2. **Present question + probe plan** — 2-3 sentences
118
- 3. **Get approval** — a nod is enough
119
- 4. **Investigate** — as cheaply as correctness allows
120
- 5. **Report findings** — a recommendation; label anything built as throwaway
121
-
122
- **Bounded:**
123
- 1. **Explore project context** — check files, docs, recent commits
124
- 2. **Ask clarifying questions** — one at a time, the ones that matter
125
- 3. **Present short design in chat** — approach, files touched, testing
126
- 4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
127
- 5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
128
-
129
- **Architectural:**
130
- 1. **Explore project context** — check files, docs, recent commits
131
- 2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
132
- 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
133
- 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
134
- 5. **Present design** — in sections scaled to their complexity, get user approval after each section
135
- 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
136
- 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
137
- 8. **User reviews written spec** — ask user to review the spec file before proceeding
138
- 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
139
-
140
- ## Process Flow
141
-
142
- ```dot
143
- digraph brainstorming {
144
- "Classify: spike / bounded / architectural" [shape=diamond];
145
- "Present question + probe (2-3 sentences)" [shape=box];
146
- "Ask clarifying questions (bounded)" [shape=box];
147
- "Present short design in chat" [shape=box];
148
- "Human approves?" [shape=diamond];
149
- "Investigate; report recommendation" [shape=doublecircle];
150
- "Implement via normal workflow (no plan doc)" [shape=doublecircle];
151
- "Explore project context" [shape=box];
152
- "Ask clarifying questions" [shape=box];
153
- "Propose 2-3 approaches" [shape=box];
154
- "Present design sections" [shape=box];
155
- "User approves design?" [shape=diamond];
156
- "Write design doc" [shape=box];
157
- "Spec self-review\n(fix inline)" [shape=box];
158
- "User reviews spec?" [shape=diamond];
159
- "Invoke writing-plans skill" [shape=doublecircle];
160
- "Hidden complexity? Upgrade path" [shape=box];
161
-
162
- "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
163
- "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
164
- "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
165
- "Present question + probe (2-3 sentences)" -> "Human approves?";
166
- "Ask clarifying questions (bounded)" -> "Present short design in chat";
167
- "Present short design in chat" -> "Human approves?";
168
- "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
169
- "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
170
- "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
171
- "Explore project context" -> "Ask clarifying questions";
172
- "Ask clarifying questions" -> "Propose 2-3 approaches";
173
- "Propose 2-3 approaches" -> "Present design sections";
174
- "Present design sections" -> "User approves design?";
175
- "User approves design?" -> "Present design sections" [label="no, revise"];
176
- "User approves design?" -> "Write design doc" [label="yes"];
177
- "Write design doc" -> "Spec self-review\n(fix inline)";
178
- "Spec self-review\n(fix inline)" -> "User reviews spec?";
179
- "User reviews spec?" -> "Write design doc" [label="changes requested"];
180
- "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
181
- }
182
- ```
183
-
184
- **Terminal states are path-bound.** Architectural: the ONLY skill you
185
- invoke after brainstorming is writing-plans — never frontend-design,
186
- mcp-builder, or any other implementation skill. Bounded: after
187
- approval, implementation proceeds directly through the normal
188
- development workflow; no plan document. Spike: the terminal state is a
189
- reported recommendation.
190
-
191
- ## The Process
192
-
193
- The subsections below serve the bounded and architectural paths (a
194
- spike stops at "present the probe, get a nod"). Sections from
195
- **Exploring approaches** onward are architectural-path depth — for
196
- bounded work, context plus a few questions plus a short in-chat design
197
- is the whole process.
198
-
199
- **Understanding the idea:**
200
-
201
- - Check out the current project state first (files, docs, recent commits)
202
- - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
203
- - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
204
- - For appropriately-scoped projects, ask questions one at a time to refine the idea
205
- - Prefer multiple choice questions when possible, but open-ended is fine too
206
- - Only one question per message - if a topic needs more exploration, break it into multiple questions
207
- - Focus on understanding: purpose, constraints, success criteria
208
-
209
- **Exploring approaches:**
210
-
211
- - Propose 2-3 different approaches with trade-offs
212
- - Present options conversationally with your recommendation and reasoning
213
- - Lead with your recommended option and explain why
214
- - YAGNI ruthlessly - remove unnecessary features from every approach and design
215
-
216
- **Presenting the design:**
217
-
218
- - Once you believe you understand what you're building, present the design
219
- - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
220
- - Ask after each section whether it looks right so far
221
- - Cover: architecture, components, data flow, error handling, testing
222
- - Be ready to go back and clarify if something doesn't make sense
223
-
224
- **Design for isolation and clarity:**
225
-
226
- - Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
227
- - For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
228
- - Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
229
- - Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
230
-
231
- **Working in existing codebases:**
232
-
233
- - Explore the current structure before proposing changes. Follow existing patterns.
234
- - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
235
- - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
236
-
237
- ## After the Design (architectural path)
238
-
239
- **Documentation:**
240
-
241
- - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
242
- - (User preferences for spec location override this default)
243
- - Use elements-of-style:writing-clearly-and-concisely skill if available
244
- - Commit the design document to git
245
-
246
- **Spec Self-Review:**
247
- After writing the spec document, look at it with fresh eyes:
248
-
249
- 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
250
- 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
251
- 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
252
- 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
253
-
254
- Fix any issues inline. No need to re-review — just fix and move on.
255
-
256
- **User Review Gate:**
257
- After the spec review loop passes, ask the user to review the written spec before proceeding:
258
-
259
- > "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
260
-
261
- Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
262
-
263
- **Implementation:**
264
-
265
- - Invoke the writing-plans skill to create a detailed implementation plan
266
- - Do NOT invoke any other skill. writing-plans is the next step.
267
+ | "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
268
+ | "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
269
+ | "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own. |
270
+ | "I should explain the process first" | Ask your question. The process shows itself. |
271
+ | "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. |
272
+ | "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
267
273
 
268
274
  ## Visual Companion
269
275
 
270
- A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
271
-
272
- **Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
273
- > "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."
276
+ A browser tab for showing mockups, diagrams, and prototypes. It's a
277
+ tool, not a mode: accepting it doesn't send every question to the
278
+ browser.
274
279
 
275
- **This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.
280
+ **Offer it just-in-time.** Offer it the first time one of the moments
281
+ above comes up, never upfront. The offer is its own message with nothing
282
+ else in it:
276
283
 
277
- **Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
284
+ > "This might be easier if I show you. Want me to open a browser tab with some mockups?"
278
285
 
279
- - **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
280
- - **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
286
+ If they decline, stay in text and don't offer again unless they raise it.
281
287
 
282
- A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
288
+ **Per question, ask: would they understand this better by seeing it?**
289
+ Mockups, layouts, diagrams, and side-by-side designs go in the browser.
290
+ Requirements, scope, tradeoffs, and conceptual choices stay in text. A
291
+ question about a UI topic isn't automatically a visual question.
283
292
 
284
- If they agree to the companion, read the detailed guide before proceeding:
285
- `skills/brainstorming/visual-companion.md`
293
+ If they accept, read `visual-companion.md` in this directory before
294
+ starting the server.
@@ -0,0 +1,23 @@
1
+ # Builder Check Prompt
2
+
3
+ Dispatch a fresh general-purpose subagent with this prompt once the
4
+ written design exists. Fill in the domain and the document path.
5
+
6
+ ```
7
+ You are a talented [DOMAIN, e.g. "software engineer", "event planner",
8
+ "bakery consultant"]. You've been handed a design document and asked to
9
+ put together a plan to build what it describes. You will not be able to
10
+ talk to the person who wrote it.
11
+
12
+ Read [DOCUMENT_PATH].
13
+
14
+ Report only the questions you'd still need answered before you could plan
15
+ this well: places where you'd have to guess and a wrong guess would
16
+ matter. For each, give the question and why the answer changes the plan.
17
+ Rank them by importance.
18
+
19
+ Skip anything the document explicitly leaves to the builder, and anything
20
+ you could reasonably decide yourself. Skip nitpicks about wording.
21
+
22
+ If nothing important is left, say "nothing important left".
23
+ ```