optimus-claude

Brainstorm

Guide the user through a structured design conversation that produces a written, approved design document before any implementation begins. The output is a persistent file in the project that feeds into Claude Code plan mode and then into /optimus:tdd for test-first implementation.

The Hard Gate

No implementation until the design is approved. Do not invoke any implementation skill, write any production code, scaffold any project structure, or take any implementation action until you have written a design doc and the user has approved it. This applies to all tasks — even seemingly simple ones. Unexamined assumptions in "simple" projects cause the most wasted effort.

Step 1: Pre-flight

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md for workspace detection. If a multi-repo workspace is detected, process within the repo the user is targeting. If ambiguous, ask which repo.

Verify prerequisites

Check that .claude/CLAUDE.md exists. If it doesn't, stop and recommend running /optimus:init first — project context and coding guidelines shape design decisions.

Load these documents:

| Document | Role | |----------|------| | .claude/CLAUDE.md | Project overview, tech stack, architecture | | coding-guidelines.md | Quality standards that constrain the design |

Monorepo path note: Read the "Monorepo Scoping Rule" section of $CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md for doc layout and scoping rules.

Scan project structure

Explore the project's directory structure, key modules, and existing patterns. This grounds the design conversation in what actually exists — not assumptions.

Step 2: Gather Intent

JIRA context detection

Before asking the user for input, check for pre-existing JIRA context:

1. If the user's inline input matches a JIRA key pattern ([A-Z][A-Z0-9]+-\d+), check for docs/jira/<key>.md. If found, read it and use its Goal and Acceptance Criteria as the brainstorm input. If the file is not found, inform the user ("No task file found for [KEY] — run /optimus:jira [KEY] first to fetch it") and proceed with normal intent gathering below.

1. If no inline input (or no JIRA key match), check whether docs/jira/ exists and contains .md files. If so, read each file's YAML frontmatter and select the one with the most recent date field. Extract the issue field and the Goal section. Present to the user via AskUserQuestion — header "JIRA context", question "Found JIRA context: [ISSUE-KEY] — [Goal]. Use this as the basis for design?":
2. Use it — "Design around this JIRA task"
3. Ignore — "Describe a different task"

If the file's date frontmatter field is older than 7 days, add a note: "(This context is [N] days old — you may want to re-run /optimus:jira for fresh data.)"

If Use it: use the file's Goal and Acceptance Criteria as the brainstorm input. Proceed to clarifying questions (skip the intent-gathering prompts below). If Ignore: proceed with normal intent gathering below.

1. If no docs/jira/ directory or no files in it, proceed with normal intent gathering below.

Gather from user

If the user provided a description inline (e.g., /optimus:brainstorm "add authentication system"), use it. Otherwise, use AskUserQuestion — header "Design scope", question "What do you want to build or change?":

• New feature — "Build something new (e.g., 'Add user authentication')"
• Significant change — "Rework or extend an existing part of the system"

If the description is longer than ~3 sentences (e.g., a pasted spec, ticket, or acceptance criteria), distill it into a single-sentence goal and confirm with AskUserQuestion — header "Distilled goal", question "I've distilled your input to: '[single-sentence summary]'. Is this accurate?":

• Looks good — "Proceed with this goal"
• Adjust — "Let me refine the focus"

Clarifying questions

Before asking questions, identify your key assumptions about scope, constraints, and expected behavior. Surface them in your reply text before the first AskUserQuestion call so the user can correct or confirm them.

Ask up to 3 clarifying questions to fill critical gaps — one per AskUserQuestion call, prefer multiple-choice options. Focus on:

• Constraints the user hasn't mentioned (performance, compatibility, security)
• Scope boundaries (what's in, what's explicitly out)
• Integration points with existing code

Skip questions if the intent is already clear. Three is the maximum, not the target.

Step 3: Explore and Propose

Explore relevant code

Based on the user's goal, explore the codebase areas that the design will touch:

• Existing modules, patterns, and conventions relevant to the goal
• Dependencies and integration points
• Related tests (if any) that reveal expected behavior

Propose approaches

Present 2-3 approaches to the user:

## Approaches

### A: [Name]
[Brief description — 2-3 sentences]
- **Pros:** [key advantages]
- **Cons:** [key disadvantages]
- **Effort:** [Low / Medium / High]
- **Alignment:** [how well it fits existing patterns]

### B: [Name]
...

### C: [Name] (optional — only if genuinely distinct)
...

**Recommendation:** [Approach letter] — [one-sentence rationale]

Use AskUserQuestion — header "Approach", question "Which approach should I design in detail?":

• One option per approach, with the recommendation marked

If the user wants to combine aspects of multiple approaches or suggests a different direction, incorporate their feedback and present a revised approach before proceeding.

Step 4: Design

Based on the chosen approach, develop a detailed design. Cover each section as applicable — omit sections that don't apply to the task:

• Goal — single paragraph: what and why
• Approach — how it works, key decisions and their rationale
• Components — what gets created or modified, each component's responsibility
• Interfaces — how components interact (APIs, data flow, contracts, function signatures)
• Edge cases and risks — what could go wrong, mitigations
• Scenarios — conditional. 3–7 Given/When/Then scenarios that /optimus:tdd consumes as the behavior list. See $CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/scenario-style.md for inclusion signals and phrasing — read it before writing scenarios.
• Out of scope — explicit boundaries to prevent scope creep

Present the design in conversation. Use AskUserQuestion — header "Design review", question "Does this design look right?":

• Approve — "Write it to a design doc"
• Adjust — "I have feedback before writing"

If the user has feedback, refine the design and present it again. Iterate until approved.

Step 5: Write Design Doc

Read $CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/design-doc-format.md for the template.

Write the file

• Path: docs/design/YYYY-MM-DD-<topic-slug>.md — derive the slug from the goal (lowercase, replace non-alphanumeric characters with hyphens, collapse consecutive hyphens, strip leading/trailing hyphens, max 5 words). The slug must match [a-z0-9]+(-[a-z0-9]+)* — reject any slug that does not match this pattern
• Create the docs/design/ directory if it doesn't exist
• Fill the template with the approved design content
• Set Status to Approved

Self-review

After writing, read the file back and check for:

• TODOs, placeholders, or "TBD" markers
• Internal contradictions (e.g., a component listed in Components but missing from Interfaces)
• Requirements ambiguous enough to cause someone to build the wrong thing
• YAGNI violations — features or complexity the user didn't ask for
• If a Scenarios section was included: re-check it against $CLAUDE_PLUGIN_ROOT/skills/brainstorm/references/scenario-style.md (Discipline and Anti-patterns)

Fix any issues found. If a fix would change a design decision, ask the user first.

Step 6: Re