Enforce brainstorming workflow with hard gates and process flow#462
Enforce brainstorming workflow with hard gates and process flow#462
Conversation
The brainstorming skill described a process but didn't enforce it. Models would skip the design phase and jump straight to implementation skills like frontend-design, or collapse the entire brainstorming process into a single text block. Changes to brainstorming skill: - Add HARD-GATE: no implementation until design is approved - Add explicit checklist that maps to task items - Add graphviz process flow with writing-plans as terminal state - Add anti-pattern callout for "too simple to need a design" - Scale design sections by section complexity, not project complexity - Make writing-plans the only valid next skill after brainstorming Changes to using-superpowers skill: - Add EnterPlanMode intercept to workflow graph - Route plan mode attempts through brainstorming skill instead Tested with claude -p --plugin-dir across three variants (no skill, original skill, updated skill) to verify behavioral compliance.
📝 WalkthroughWalkthroughReplaces fixed-length design-section guidance with a complexity-scaled approach and enforces a universal HARD-GATE requiring design presentation and user approval before implementation. Adjusts skill orchestration to run brainstorming first when not already performed, before evaluating other skills. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Orchestrator as Skill Orchestrator
participant Brainstorm as Brainstorming Skill
participant Other as Other Skill(s)
User->>Orchestrator: Request action / trigger
Orchestrator->>Orchestrator: Check: About to EnterPlanMode?
Orchestrator->>Orchestrator: Check: Already brainstormed?
alt Not yet brainstormed
Orchestrator->>Brainstorm: Invoke brainstorming skill
Brainstorm->>Brainstorm: Explore problem, ask clarifying questions
Brainstorm->>Brainstorm: Produce designs (scaled by complexity)
Brainstorm->>User: Present design section(s) and request approval
User->>Brainstorm: Approve or request changes
Brainstorm->>Orchestrator: Return approved design
end
Orchestrator->>Orchestrator: Evaluate: Might any skill apply?
Orchestrator->>Other: Invoke applicable skill(s) (e.g., writing-plans)
Other->>User: Return results / plan
Estimated Code Review Effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/using-superpowers/SKILL.md (1)
29-45:⚠️ Potential issue | 🟠 MajorEnterPlanMode gate is unreachable in the flow graph. The new branch has no incoming edge, so the graph still routes directly from “User message received” to “Might any skill apply?”. Add an edge to the gate (and then route to “Might any skill apply?” for the “no” path) so the new logic actually executes.
💡 Proposed flow fix
- "User message received" -> "Might any skill apply?"; + "User message received" -> "About to EnterPlanMode?"; + "About to EnterPlanMode?" -> "Might any skill apply?" [label="no"];
🤖 Fix all issues with AI agents
In `@skills/using-superpowers/SKILL.md`:
- Around line 29-33: The node labeled "About to EnterPlanMode?" is a
decision/question but is rendered as a terminal (doublecircle); change its shape
to a decision by replacing [shape=doublecircle] with [shape=diamond] for the
"About to EnterPlanMode?" node so it matches the semantics (i.e., update the
line containing "About to EnterPlanMode?" to use [shape=diamond]).
| "About to EnterPlanMode?" [shape=doublecircle]; | ||
| "Already brainstormed?" [shape=diamond]; | ||
| "Invoke brainstorming skill" [shape=box]; | ||
| "Might any skill apply?" [shape=diamond]; | ||
| "Invoke Skill tool" [shape=box]; |
There was a problem hiding this comment.
Use a decision shape for “About to EnterPlanMode?”. It’s a question node but is drawn as a terminal (doublecircle), which conflicts with the diagram semantics.
🔧 Suggested tweak
- "About to EnterPlanMode?" [shape=doublecircle];
+ "About to EnterPlanMode?" [shape=diamond];📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "About to EnterPlanMode?" [shape=doublecircle]; | |
| "Already brainstormed?" [shape=diamond]; | |
| "Invoke brainstorming skill" [shape=box]; | |
| "Might any skill apply?" [shape=diamond]; | |
| "Invoke Skill tool" [shape=box]; | |
| "About to EnterPlanMode?" [shape=diamond]; | |
| "Already brainstormed?" [shape=diamond]; | |
| "Invoke brainstorming skill" [shape=box]; | |
| "Might any skill apply?" [shape=diamond]; | |
| "Invoke Skill tool" [shape=box]; |
🤖 Prompt for AI Agents
In `@skills/using-superpowers/SKILL.md` around lines 29 - 33, The node labeled
"About to EnterPlanMode?" is a decision/question but is rendered as a terminal
(doublecircle); change its shape to a decision by replacing [shape=doublecircle]
with [shape=diamond] for the "About to EnterPlanMode?" node so it matches the
semantics (i.e., update the line containing "About to EnterPlanMode?" to use
[shape=diamond]).
…first turn When async is true, the hook may not complete before the model starts responding, meaning the using-superpowers skill instructions aren't in context for the first message.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@hooks/hooks.json`:
- Line 9: The command value using ${CLAUDE_PLUGIN_ROOT} will break on paths with
spaces; update the "command" string so the expanded path is wrapped in single
quotes (e.g., put single quotes around
${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh) to prevent shell word-splitting
when the variable expands.
| @@ -7,7 +7,7 @@ | |||
| { | |||
| "type": "command", | |||
| "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh", | |||
There was a problem hiding this comment.
Quote ${CLAUDE_PLUGIN_ROOT} to avoid path breakage on spaces.
Without single quotes, paths containing spaces will be split by the shell, breaking the hook execution.
🛠️ Suggested fix
- "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+ "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh'",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh", | |
| "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh'", |
🤖 Prompt for AI Agents
In `@hooks/hooks.json` at line 9, The command value using ${CLAUDE_PLUGIN_ROOT}
will break on paths with spaces; update the "command" string so the expanded
path is wrapped in single quotes (e.g., put single quotes around
${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh) to prevent shell word-splitting
when the variable expands.
1 participant
Summary
What changed in brainstorming
<HARD-GATE>: no implementation skills, code, or scaffolding until design is presented and approvedwriting-plansas the terminal state — prevents the model from invoking frontend-design or other implementation skills after brainstormingwriting-plansis the only valid next skill after brainstorming (explicit, repeated)What changed in using-superpowers
EnterPlanModeintercept to workflow graph — checks if brainstorming has happened, invokes it if not, never enters plan modeTest plan
Tested with
claude -p --plugin-diracross three variants:EnterPlanModeon turn 2writing-plans— never touches frontend-design or EnterPlanModeSummary by CodeRabbit
Documentation
Workflow
Chores