3 +description: Use for vague goals, new features, product decisions, UX/UI work, or architecture choices before implementation. Enforces design approval before code, writes a spec, self-reviews it, then hands off to writing-plans.
8 +Design before code. No exceptions for “simple” work.
12 +Do not implement, scaffold, edit production code, or invoke implementation workflows until:
14 +1. design was presented,
17 +4. spec self-review passed,
18 +5. user approved the written spec.
20 +Tiny tasks may have tiny designs. They still need approval.
24 +1. Explore project context.
25 + - read relevant docs/files
26 + - inspect current structure
27 + - note constraints and existing patterns
28 + - inspect recent commits if useful
29 +2. If visual questions are likely, offer visual companion in its own message.
30 +3. Ask clarifying questions one at a time.
31 +4. Propose 2-3 approaches with tradeoffs.
33 +6. Present design in small sections.
34 +7. Ask approval after each section.
35 +8. Write spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` unless project rules say otherwise.
36 +9. Self-review spec; fix placeholders, contradictions, ambiguity, overscope.
37 +10. Commit the spec when project workflow uses git and project rules allow it.
38 +11. Ask user to review spec file.
39 +12. After approval, hand off only to `writing-plans`.
43 +- One question per message.
44 +- Multiple choice preferred.
45 +- Ask only blocking questions.
46 +- If request is too large, decompose first; brainstorm one subproject.
50 +Scale section length to complexity. Cover only relevant sections:
54 +- architecture/components
56 +- component boundaries: single responsibility, clear interfaces, independent tests
57 +- errors/failure modes
59 +- migration/rollout, only if truly needed
63 +Before user review, check:
65 +- `TODO`, `TBD`, placeholders
67 +- unclear ownership or boundaries
68 +- requirements that can be interpreted two ways
69 +- scope too large for one implementation plan
70 +- missing verification strategy
72 +Fix inline before asking user.
74 +##
Output checkpoints 78 +- existing patterns: ...
80 +- visual companion: useful | not useful
85 +- recommendation: ...
92 +DESIGN_SECTION n/N — <name>
99 +- path: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
100 +- self-review: passed
101 +- next after approval: /writing-plans <path>
106 +- Coding during brainstorming.
107 +- Dumping a giant spec without section approval.
108 +- Asking five questions at once.
109 +- “This is too simple for design.”
110 +- Generic scalable/flexible fluff.
111 +- Unrelated refactors while touching existing code.
112 +- Writing a spec full of hedges instead of decisions.
116 +Use only when seeing beats reading: mockups, layouts, palettes, diagrams, side-by-side UX choices.
118 +Offer in its own message:
121 +Some of this may be easier to judge visually. I can open a local browser companion for mockups/diagrams/options. Use it?
126 +1. Ask user to run `/superpowers visual start` if not already live.
127 +2. Use returned `content` dir.
128 +3. Write one fresh `.html` fragment per screen.
129 +4. Tell user the URL and what is on screen.
130 +5. Ask user to click/select if useful and answer in terminal.
131 +6. Read the events file path announced by `/superpowers visual start` directly when interpreting browser feedback.
132 +7. Push a waiting screen before returning to text-only discussion.
134 +Visual state is ephemeral platform state, not project files. Specs/design docs remain project files when approved.