feat: Add /workflows:brainstorm command and skill (#101)

* feat(workflows:plan): Add smart research decision logic

Previously, /workflows:plan always ran all 3 research agents (repo-research,
best-practices, framework-docs) regardless of task complexity. This wasted
tokens and time for simple tasks like UI tweaks or bug fixes with clear causes.

Now the workflow:
- Always runs repo research first (fast, local)
- Makes an informed decision about external research based on:
  - Signals gathered during idea refinement (familiarity, intent, risk)
  - Repo research findings (existing patterns, CLAUDE.md guidance)
- High-risk topics (security, payments, external APIs) always trigger research
- Strong local context allows skipping external research
- Announces the decision and proceeds, user can redirect if needed

This makes the planning workflow smarter about when web research adds value.

* feat: Add /workflows:brainstorm command and skill

Add brainstorming workflow to explore requirements and approaches
before planning implementation:

- New `/workflows:brainstorm` command for collaborative dialogue
- New `brainstorming` skill with process knowledge and techniques
- Update `/workflows:plan` to detect brainstorm output and skip
  idea refinement when relevant brainstorm exists
- Add brainstorm to README workflow commands table

The brainstorm → plan flow enables:
- Phase 0: Assess requirement clarity
- Phase 1: Understand the idea via repo research + dialogue
- Phase 2: Explore 2-3 approaches with trade-offs
- Phase 3: Capture design to docs/brainstorms/
- Phase 4: Handoff to /workflows:plan

plugins/compound-engineering/commands/workflows/brainstorm.md

@@ -0,0 +1,115 @@
+---
+name: workflows:brainstorm
+description: Explore requirements and approaches through collaborative dialogue before planning implementation
+argument-hint: "[feature idea or problem to explore]"
+---
+
+# Brainstorm a Feature or Improvement
+
+**Note: The current year is 2026.** Use this when dating brainstorm documents.
+
+Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/workflows:plan`, which answers **HOW** to build it.
+
+**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
+
+## Feature Description
+
+<feature_description> #$ARGUMENTS </feature_description>
+
+**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
+
+Do not proceed until you have a feature description from the user.
+
+## Execution Flow
+
+### Phase 0: Assess Requirements Clarity
+
+Evaluate whether brainstorming is needed based on the feature description.
+
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**
+Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
+
+### Phase 1: Understand the Idea
+
+#### 1.1 Repository Research (Lightweight)
+
+Run a quick repo scan to understand existing patterns:
+
+- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
+
+Focus on: similar features, established patterns, CLAUDE.md guidance.
+
+#### 1.2 Collaborative Dialogue
+
+Use the **AskUserQuestion tool** to ask questions **one at a time**.
+
+**Guidelines (see `brainstorming` skill for detailed techniques):**
+- Prefer multiple choice when natural options exist
+- Start broad (purpose, users) then narrow (constraints, edge cases)
+- Validate assumptions explicitly
+- Ask about success criteria
+
+**Exit condition:** Continue until the idea is clear OR user says "proceed"
+
+### Phase 2: Explore Approaches
+
+Propose **2-3 concrete approaches** based on research and conversation.
+
+For each approach, provide:
+- Brief description (2-3 sentences)
+- Pros and cons
+- When it's best suited
+
+Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
+
+Use **AskUserQuestion tool** to ask which approach the user prefers.
+
+### Phase 3: Capture the Design
+
+Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>.md`.
+
+**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
+
+Ensure `docs/brainstorms/` directory exists before writing.
+
+### Phase 4: Handoff
+
+Use **AskUserQuestion tool** to present next steps:
+
+**Question:** "Brainstorm captured. What would you like to do next?"
+
+**Options:**
+1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
+2. **Refine design further** - Continue exploring
+3. **Done for now** - Return later
+
+## Output Summary
+
+When complete, display:
+
+```
+Brainstorm complete!
+
+Document: docs/brainstorms/YYYY-MM-DD-<topic>.md
+
+Key decisions:
+- [Decision 1]
+- [Decision 2]
+
+Next: Run `/workflows:plan` when ready to implement.
+```
+
+## Important Guidelines
+
+- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
+- **Ask one question at a time** - Don't overwhelm
+- **Apply YAGNI** - Prefer simpler approaches
+- **Keep outputs concise** - 200-300 words per section max
+
+NEVER CODE! Just explore and document decisions.

plugins/compound-engineering/commands/workflows/plan.md

@@ -22,44 +22,97 @@ Do not proceed until you have a clear feature description from the user.
 
 ### 0. Idea Refinement
 
-Before running research, refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
+**Check for brainstorm output first:**
+
+Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
+
+```bash
+ls -la docs/brainstorms/*.md 2>/dev/null | head -10
+```
+
+**Relevance criteria:** A brainstorm is relevant if:
+- The topic (from filename or YAML frontmatter) semantically matches the feature description
+- Created within the last 14 days
+- If multiple candidates match, use the most recent one
+
+**If a relevant brainstorm exists:**
+1. Read the brainstorm document
+2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
+3. Extract key decisions, chosen approach, and open questions
+4. **Skip the idea refinement questions below** - the brainstorm already answered WHAT to build
+5. Use brainstorm decisions as input to the research phase
+
+**If multiple brainstorms could match:**
+Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
+
+**If no brainstorm found (or not relevant), run idea refinement:**
+
+Refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
 
 - Ask questions one at a time to understand the idea fully
 - Prefer multiple choice questions when natural options exist
 - Focus on understanding: purpose, constraints and success criteria
 - Continue until the idea is clear OR user says "proceed"
 
+**Gather signals for research decision.** During refinement, note:
+
+- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
+- **User's intent**: Speed vs thoroughness? Exploration vs execution?
+- **Topic risk**: Security, payments, external APIs warrant more caution
+- **Uncertainty level**: Is the approach clear or open-ended?
+
 **Skip option:** If the feature description is already detailed, offer:
 "Your description is clear. Should I proceed with research, or would you like to refine it further?"
 
 ## Main Tasks
 
-### 1. Repository Research & Context Gathering
+### 1. Repository Research (Always Runs)
 
 <thinking>
-First, I need to understand the project's conventions and existing patterns, leveraging all available resources and use paralel subagents to do this.
+First, I need to understand the project's conventions and existing patterns. This is fast and local - it informs whether external research is needed.
 </thinking>
 
-Runn these three agents in paralel at the same time:
+Run repo research to understand the codebase:
 
 - Task repo-research-analyst(feature_description)
+
+**What to look for:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency. These findings inform the next step.
+
+### 1.5. Research Decision
+
+Based on signals from Step 0 and findings from Step 1, decide on external research.
+
+**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
+
+**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.
+
+**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
+
+**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
+
+Examples:
+- "Your codebase has solid patterns for this. Proceeding without external research."
+- "This involves payment processing, so I'll research current best practices first."
+
+### 1.5b. External Research (Conditional)
+
+**Only run if Step 1.5 indicates external research is valuable.**
+
+Run these agents in parallel:
+
 - Task best-practices-researcher(feature_description)
 - Task framework-docs-researcher(feature_description)
 
-**Reference Collection:**
+### 1.6. Consolidate Research
 
-- [ ] Document all research findings with specific file paths (e.g., `app/services/example_service.rb:42`)
-- [ ] Include URLs to external documentation and best practices guides
-- [ ] Create a reference list of similar issues or PRs (e.g., `#123`, `#456`)
-- [ ] Note any team conventions discovered in `CLAUDE.md` or team documentation
+After all research steps complete, consolidate findings:
 
-### Research Validation (Optional)
+- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
+- Note external documentation URLs and best practices (if external research was done)
+- List related issues or PRs discovered
+- Capture CLAUDE.md conventions
 
-After research agents complete, briefly validate alignment:
-
-- Summarize key findings from research
-- Ask if anything looks off or is missing
-- User can confirm or request additional research on specific topics
+**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
 
 ### 2. Issue Planning & Structure