/gaia-product-brief

What it does

/gaia-product-brief facilitates a collaborative discovery session to produce a product brief -- the document that captures vision, target users, problem statement, proposed solution, key features, scope, risks, competitive landscape, and success metrics. It incorporates insights from any prior brainstorm or research artifacts.

When to use it

• After brainstorming (/gaia-brainstorm) when you are ready to formalize the idea.
• When you already know what you want to build and want to jump straight to the brief.

Prerequisites

• A brainstorm artifact should exist. The command checks for .gaia/artifacts/creative-artifacts/brainstorm-*.md. If missing, it will still run but results improve with prior research.

Orchestration mode

When /gaia-product-brief 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.

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

Why Mode B is better for this command

The /gaia-product-brief skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural 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-product-brief

/gaia-product-brief TaskFlow

What it does step by step

1. Discover inputs Scans for prior brainstorm, market research, domain research, and technical research artifacts. Summarizes what upstream context was found.
2. Vision statement Collaboratively crafts the product vision. Asks: "What is the core vision for this product?"
3. Target users Defines user personas with name, role, goals, pain points, and context.
4. Problem statement Articulates the core problem, grounded in user research and market findings.
5. Proposed solution Defines the high-level solution approach, key features, and differentiators.
6. Scope, risks, and competitive landscape Sets in-scope/out-of-scope boundaries, documents risks and assumptions, and summarizes competitive positioning.
7. Success metrics Defines measurable KPIs and success criteria (quantitative and qualitative).
8. Generate output Writes the product brief with all nine required sections.
9. Validation Runs quality checks to verify all 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/product-brief-{slug}.md. Authors (human or sub-agent) must reproduce these headings exactly — the optional numbered/lettered outline prefix is accepted (e.g. ## 1. Vision Statement, ## 1b. Vision Statement, ## 1.2 Vision Statement), but the section name itself must match.

• ## Vision Statement
• ## Problem Statement
• ## Proposed Solution
• ## Target Users
• ## Key Features
• ## Success Metrics
• ## Scope and Boundaries
• ## Competitive Landscape
• ## Risks and Assumptions

A missing required section causes the matching section-validation 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-product-brief TaskFlow

Scanning upstream artifacts...
  Found: brainstorm-taskflow.md (5 sections indexed)
  Found: market-research.md (6 sections indexed)
  Missing: domain-research, tech-research

What is the core vision for this product?
> A task management platform that learns team workflows
   and automates repetitive coordination.

(continues through all sections...)

Product brief written to:
  .gaia/artifacts/creative-artifacts/product-brief-taskflow.md

Validation: all 9 required sections present. PASS.

What to run next

• /gaia-create-prd -- expand the brief into a full PRD.
• /gaia-market-research -- if competitive landscape needs deeper validation.
• /gaia-domain-research -- if domain context is still thin.

Troubleshooting

"Run /gaia-brainstorm first"

The pre-start gate checks for a brainstorm artifact. Run /gaia-brainstorm first, or proceed -- the brief will be less informed but still valid.

Validation failed -- missing section

The brief requires all nine sections. If a section is missing, the command will attempt to auto-fix. If it persists after 3 attempts, you will be asked to add the missing content manually.

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