name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."

Brainstorming Ideas Into Designs

Overview

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.

The Process

Understanding the idea:
- Check out the current project state first (files, docs, recent commits)
- Verify before assuming - If unsure about behavior, search the codebase first rather than guessing
- Ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria

Exploring approaches:
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why
- For non-trivial architectural choices, use subagent to debate alternatives before committing:
- VS Code Copilot: runSubagent tool
- Claude Code: Task tool

Presenting the design:
- Once you believe you understand what you're building, present the design
- Break it into sections of 200-300 words
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
- Before writing any plan document, explicitly ask: "Does this design look complete? Any remaining questions or discrepancies before I write up the plan?"

After the Design

Output two documents:
1. docs/design/{feature-name}/spec.md - Human-facing specification
2. docs/design/{feature-name}/agent.spec.md - Agent-facing specification (for plan agent)

spec.md (Human-Facing)

Concise, decision-focused. No code. Link references only.

# {Feature Name} Specification

**Date:** YYYY-MM-DD
**Status:** Draft | Validated | Ready for Implementation

## Context
[1-2 sentences: what problem, why now]

## Decision
[What we're building and why this approach]

## Requirements
- [Key requirements in plain language]

## Constraints
- [Limitations, dependencies]

## Out of Scope
- [Explicitly excluded]

## Open Questions
- [ ] [Unresolved items]

## Success Criteria
- [ ] [How we know it's done]

## References
- [Link to relevant docs](https://...)
- [Link to API reference](https://...)

agent.spec.md (Agent-Facing)

Technical, implementation-ready. Code examples, file paths, patterns to follow.

# {Feature Name} - Agent Specification

## Requirements
- [Functional requirements with technical details]
- [Non-functional: performance targets, security constraints]

## Constraints
- [Technical constraints affecting implementation]

## Approach
[Technical approach with rationale]

## Design

### Architecture
[Component diagram or description]

### Key Components
| Component | Responsibility | Location |
|-----------|---------------|----------|
| ... | ... | `src/path/to/file.py` |

### Data Flow
[How data moves, with types/schemas if relevant]

### Code Patterns
[Existing patterns to follow]
```python
# Example from codebase showing the pattern
def existing_pattern():
    ...

File References

[Files the plan agent MUST read before planning]
- src/path/to/similar/feature.py - similar implementation pattern
- tests/path/to/tests/ - existing test structure
- src/models/schema.py:45-80 - relevant data models

Success Criteria

• [ ] [Testable criteria with specifics]
  ```

⚠️ MANDATORY: Review Checkpoint

After writing both files, prompt the user:

Specifications ready for review.

• docs/design/{feature-name}/spec.md - Human-readable summary
• docs/design/{feature-name}/agent.spec.md - Technical spec for planning

Please review and either:
1. Accept - Reply "approved" or "lgtm" to proceed
2. Edit - Modify the files, then reply "updated" so I can re-evaluate

I will not proceed until you explicitly accept.

If user edits:
1. Re-read modified files
2. Summarize what changed
3. Ask for confirmation again

If user accepts:
1. Update status to "Validated" in both files
2. Proceed to implementation setup (user commits when ready)

Implementation (if continuing):
- Ask: "Ready to set up for implementation?"
- Use using-git-worktrees to create isolated workspace
- Use writing-plans to create implementation plan from agent.spec.md

⚠️ CRITICAL: Use Parallel Agents for Code Exploration

When exploring the codebase, use task tracking and parallel agents (agent swarm) when available.

Task tracking by platform:

Agent dispatch by platform:

For code exploration tasks, prefer cheaper/faster models from the same family:

Why: Code exploration is parallelizable and doesn't require maximum reasoning capability. Save expensive models for architectural decisions and complex reasoning.

How:
- Dispatch multiple exploration agents in parallel
- Each agent explores a different area of the codebase
- Aggregate findings before making design decisions
- Use task tracking to monitor what each agent is exploring

Key Principles

• One question at a time - Don't overwhelm with multiple questions
• Multiple choice preferred - Easier to answer than open-ended when possible
• YAGNI ruthlessly - Remove unnecessary features from all designs
• Explore alternatives - Always propose 2-3 approaches before settling
• Incremental validation - Present design in sections, validate each
• Be flexible - Go back and clarify when something doesn't make sense
• Use agent swarms for exploration - Parallelize codebase exploration with cheaper models