/gaia-brainstorm

What it does

/gaia-brainstorm facilitates a structured brainstorming session for a new project idea. It guides you through vision articulation, target user identification, competitive landscape analysis, and opportunity synthesis, then produces a ranked list of opportunity areas with a parking lot for deprioritized ideas.

When to use it

• You have a business idea and want to explore it before committing to a product brief.
• You want to identify opportunity areas, target users, and competitive positioning for a new concept.

If you already know what you want to build, skip brainstorming and go directly to /gaia-product-brief.

Prerequisites

None. This is often the first command you run on a new project. If prior brainstorm output exists under .gaia/artifacts/creative-artifacts/, it will be incorporated.

Orchestration mode

When /gaia-brainstorm starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches. See the orchestration contract for details.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-brainstorm skill declares orchestration_class: conversational in its SKILL.md frontmatter. Conversational skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-brainstorm

Starts an interactive brainstorming session.

/gaia-brainstorm AI-powered code review tool

Seeds the session with your project idea.

What it does step by step

1. Discover context Checks for prior brainstorming output under .gaia/artifacts/creative-artifacts/. If found, incorporates existing insights.
2. Elicit project vision Asks you four questions, one at a time:
   1. What is the business idea or problem?
   2. Who are the target users?
   3. What pain points does this address?
   4. What makes this different from existing solutions?
3. Competitive landscape Based on your answers, analyzes direct and indirect competitors and maps competitive positioning. Uses your input and general knowledge only (no web access required).
4. Opportunity synthesis Synthesizes 3-5 opportunity areas, each with a description, estimated impact, and supporting evidence. Ranks by impact and feasibility. Ideas that did not make the top list are captured in a Parking Lot with reasoning and revival conditions.
5. Generate output Writes the brainstorm artifact with all sections: vision, users, pain points, competitive landscape, ranked opportunities, parking lot, and next steps.
6. Validation Runs an automated quality check to verify all required sections are present and substantive.

Inputs

Outputs

Output schema

The finalize.sh checklist enforces the following H2 section names verbatim against the produced artifact at .gaia/artifacts/creative-artifacts/brainstorm-{slug}.md. Authors (human or sub-agent) must reproduce these headings exactly — the optional numbered/lettered outline prefix is accepted (e.g. ## 1. Vision Summary, ## 1b. Vision Summary, ## 1.2 Vision Summary), but the section name itself must match.

• ## Vision Summary
• ## Target Users
• ## Pain Points
• ## Competitive Landscape
• ## Differentiators
• ## Opportunity Areas
• ## Next Steps
• ## Parking Lot

A missing required section causes the matching SV-NN check to FAIL with the heading name in the violation line. The heading_present() helper (shared at plugins/gaia/scripts/lib/heading-present.sh) accepts every variant listed above — so do not editorialize the section name to satisfy the gate, just use one of the documented heading forms.

Example session

> /gaia-brainstorm AI-powered code review tool

Checking for prior brainstorm output... none found.

1. What is the business idea or problem you want to explore?
> Developers waste hours on manual code reviews that could be
   partially automated with AI.

2. Who are the target users?
> Engineering teams at mid-size companies (50-500 devs).

3. What pain points does this address?
> Slow review cycles, inconsistent feedback quality, reviewer fatigue.

4. What makes this different from existing solutions?
> Learns team-specific patterns, integrates with existing PR workflow.

Analyzing competitive landscape...
  Direct: CodeRabbit, Codacy, SonarQube
  Indirect: GitHub Copilot, manual review checklists

Synthesizing opportunities...

Opportunity Areas (ranked):
  1. Team-specific pattern learning (HIGH impact, HIGH feasibility)
  2. Review-cycle time reduction (HIGH impact, MEDIUM feasibility)
  3. Junior developer mentoring via review feedback (MEDIUM, HIGH)

Parking Lot:
  - Auto-fix suggestions -- deprioritized (high complexity, regulatory risk)
    Revival: when LLM reliability reaches enterprise-grade thresholds

Artifact written to:
  .gaia/artifacts/creative-artifacts/brainstorm-ai-code-review.md

What to run next

• /gaia-product-brief -- convert the brainstorm into a structured product brief.
• /gaia-market-research -- validate the competitive landscape with deeper research.
• /gaia-domain-research -- explore domain-specific context.
• /gaia-tech-research -- evaluate technologies before the brief.

Troubleshooting

Fewer than 3 opportunity areas

The validation check requires at least 3 opportunity areas. Provide more detail about your target market and pain points to generate additional angles.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands