oprogramadorreal/optimus-claude / skills/brainstorm
brainstorm
VerifiedRuns a structured design conversation — clarifies intent, proposes 2-3 approaches with trade-offs, iterates the design — and writes a user-approved engineering spec to docs/specs/ that /optimus:tdd auto-detects. No implementation happens until the spec is approved. With the scaffold argument, creates docs/product/ steering skeletons instead (never overwrites, authors no content). Recommends /optimus:init first.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.1 KB |
| SKILL.md | skill md | 9.3 KB |
| agents/openai.yaml | config | 198 B |
| references/plan-mode-handoff.md | markdown | 4.8 KB |
| references/scenario-style.md | markdown | 2.6 KB |
| templates/product/mvp-prd.md | markdown | 1.7 KB |
| templates/product/product-context.md | markdown | 1.7 KB |
| templates/product/tech-stack.md | markdown | 1.8 KB |
README.md
View on GitHub# optimus:brainstorm
Guides structured design brainstorming — explores the codebase, asks clarifying questions, proposes 2-3 approaches with trade-offs, and writes a user-approved engineering spec to `docs/specs/YYYY-MM-DD-<slug>.md`. Enforces a hard gate: no implementation until the spec is approved, even for "simple" tasks.
## When to use
Before implementing a new feature or significant change — especially when the work touches multiple components, multiple valid approaches exist, you want a persistent spec that survives conversation resets, or a JIRA ticket is too vague for direct implementation (brainstorm auto-detects JIRA context from `docs/jira/`).
**When not:** simple, well-understood task → `/optimus:tdd` directly; pure refactoring → `/optimus:refactor`; quick prototyping → plan mode alone.
## What it does
1. Loads project context, coding guidelines, and the optional `docs/product/` steering cascade
2. Gathers intent — JIRA auto-detection, then up to 3 clarifying questions
3. Proposes 2-3 approaches with trade-offs and a marked recommendation
4. Iterates the design with you until approved
5. Writes the approved spec, including a conditional Given/When/Then **Scenarios** section that `/optimus:tdd` maps to Red-Green-Refactor cycles
6. Routes to the right next step (refactor, unit-test, TDD, or a plan-mode handoff)
## Scaffold mode
`/optimus:brainstorm scaffold` bootstraps spec-driven development on a greenfield project: it creates `docs/product/product-context.md`, `mvp-prd.md`, and `tech-stack.md` as empty TODO skeletons for a human to fill (replacing the 2.x spec-init skill). It never overwrites existing files and authors no product content. Fill the TODOs top-down, then re-run `/optimus:brainstorm` — the design flow reads the cascade as steering. See [`references/sdd-mapping.md`](../../references/sdd-mapping.md) for the precedence contract.
## Recommended workflow
| Situation | Workflow |
|-----------|----------|
| Small (1-2 components) | brainstorm → `/optimus:tdd` (auto-detects the spec) |
| Medium-to-large | brainstorm → plan mode (review-only, do not approve) → `/optimus:tdd` |
| From JIRA | `/optimus:jira` → brainstorm → plan mode → `/optimus:tdd` |
| Greenfield product | brainstorm scaffold → fill the cascade → brainstorm |
Brainstorm generates the plan-mode prompt inline — no separate `/optimus:prompt` step needed for this chain.
Under Codex, the handoff uses its available plan/review controls and `$optimus:tdd`, with a copyable plan when the host cannot save it yet. Claude-specific toggle/approval instructions are not applied to Codex. The durable spec and `### Refined plan` heading are shared between hosts.
## Relationship to other skills
| Skill | Relationship |
|-------|--------------|
| `/optimus:jira` | Brainstorm auto-detects task files in `docs/jira/` — run jira first for JIRA-tracked work |
| `/optimus:tdd` | Auto-detects specs in `docs/specs/`; consumes each spec scenario as one Red-Green-Refactor cycle |
| `/optimus:refactor` | For restructuring without new behavior, use refactor instead of brainstorm |
| `/optimus:prompt` | For handoff prompts outside the brainstorm→plan→tdd chain |
## Prerequisites
- `/optimus:init` should have been run (CLAUDE.md and coding guidelines inform design decisions); scaffold mode has no prerequisites
## Skill structure
| File | Purpose |
|------|---------|
| `SKILL.md` | Design workflow, scaffold mode, and the spec template |
| `references/scenario-style.md` | Given/When/Then discipline for the Scenarios section |
| `references/plan-mode-handoff.md` | Plan-mode handoff procedure (shared — also read by `/optimus:jira` and `/optimus:prompt`) |
| `templates/product/` | Steering-cascade skeletons emitted by scaffold mode |
| *(shared)* `references/sdd-mapping.md` | Steering precedence and authoring boundary |
| *(shared)* `init/references/multi-repo-detection.md` | Multi-repo workspace detection (only outside a Git working tree) |
## Requirements
- A plugin-capable [Claude Code](https://code.claude.com/docs/en/plugins) or Codex host (see the [supported hosts and versions](../../README.md#supported-hosts-and-versions))
## License
[MIT](../../LICENSE)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou 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). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |