brainstorm

/brainstorm

Start a CollabDraft planning session for collaborative design exploration.

Usage

/brainstorm [topic]

If topic is omitted, ask the user what they'd like to brainstorm before proceeding.

Session Start

When this skill is invoked, perform the following steps in order:

1. Initialize the session

Run the session start script with the topic:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh" "<topic>"

This creates .collabdraft/session.json and the session-artifacts/ directory in the user's project.

2. Create the working spec

Create working-spec.md in the user's working directory with the structured template:

# <topic>

## Overview
*No content yet — will be populated as the design evolves.*

## Components
*No components identified yet.*

## Data Flows
*No data flows identified yet.*

## Interfaces
*No interfaces defined yet.*

## Open Questions
- What are the key requirements and constraints?

## Decision Log
*No decisions recorded yet.*

3. Detect Agent Teams availability

Check whether Agent Teams is available by running:

echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"

• If the output is 1 or true, Agent Teams is available. Use the teammate mode (step 3a).
• If the output is not_set or anything else, Agent Teams is not available. Use the subagent fallback mode (step 3b).

Tell the developer which mode is active: "Starting CollabDraft session in [teammate/standalone] mode."

3a. Teammate mode — start the working-draft teammate

Send a message to the "working-draft" teammate:

"Session started. Topic: <topic>. You own working-spec.md — it has been created with the standard template. Wait for inline updates from me."

3b. Subagent fallback mode

Agent Teams is not available. You will manage working-spec.md yourself using periodic subagent calls. See the "Subagent Fallback" section below for the protocol.

4. Brief yourself on session protocol

You are now the conversation agent for this CollabDraft session. Follow these rules for the duration of the session:

After each substantive exchange with the developer:

1. Identify what design information was discussed, decided, or changed
2. Send an inline update to the working-draft teammate (or apply it yourself in fallback mode)
3. Continue the conversation naturally — do not wait for the teammate's echo before responding to the developer

Inline update format — send structured messages to the working-draft teammate like:

• "Add component: [Name] — [description]"
• "Update data flow: [source] → [target] via [mechanism]"
• "Decision: [choice] over [alternative] — [rationale]"
• "Add open question: [question]"
• "Remove open question: [question] (resolved — see Decision Log)"

Conversation style:

• Be a collaborative design partner, not just a note-taker
• Ask clarifying questions when requirements are ambiguous
• Suggest alternatives and trade-offs
• Flag potential issues or conflicts in the emerging design
• Reference the working spec when relevant: "I've updated the spec to reflect that..."

Session End

When the user says /done or indicates they want to end the session:

In teammate mode:

1. Send a message to the working-draft teammate: "Session ending. Produce the final plan document as <topic-slug>-plan.md. Remove unresolved open questions (note them as deferred in the Decision Log), ensure the Decision Log is complete, and add an Implementation Notes section."
2. Wait for the teammate to confirm the plan is written
3. Run the session stop script:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh"
   

4. Tell the developer where to find their plan: ./<topic-slug>-plan.md

In fallback mode: Follow the session end protocol described in the "Subagent Fallback" section.

Subagent Fallback

When Agent Teams is not available (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is not set), you handle spec updates yourself instead of delegating to a teammate.

Update protocol in fallback mode:

• After every 2-3 substantive exchanges with the developer, update working-spec.md directly using the Edit tool
• Follow the same structured section schema defined in the working spec template
• Use targeted edits only — never rewrite entire sections
• Mentally track what has changed since the last update and batch related changes together

Session end in fallback mode:

• On /done, read the current working-spec.md
• Write the final <topic-slug>-plan.md yourself: remove unresolved open questions (note them as deferred in the Decision Log), ensure the Decision Log is complete, and add an ## Implementation Notes section
• Run bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh"

Important Notes

• Never rewrite entire sections of working-spec.md — use targeted edits to preserve diff legibility
• The spec should reflect the current state of the design at all times, not be a conversation log
• Keep the conversation flowing naturally; spec updates happen in the background
• If the developer asks to see the current spec, point them to working-spec.md