/gaia-create-prd

What it does

/gaia-create-prd creates a Product Requirements Document (PRD) through collaborative discovery. It conducts user interviews, elicits functional and non-functional requirements, maps user journeys, defines data requirements and integrations, runs an adversarial review, and produces a validated PRD with uniquely identified requirements (FR-001, NFR-001, etc.).

When to use it

• You have a product brief and are ready to define detailed requirements.
• You are starting the planning phase after completing analysis and research.

Prerequisites

• A product brief must exist. Pass the path as an argument. If missing, the command stops.
• Research artifacts improve quality. Market research, domain research, and tech research artifacts are incorporated if available.

Orchestration mode

When /gaia-create-prd 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-create-prd 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-create-prd .gaia/artifacts/creative-artifacts/product-brief-taskflow.md

What it does step by step

1. Load product brief Reads the product brief and indexes any available research artifacts. If a PRD already exists, warns before overwriting.
2. User interviews Asks about primary user types, their top 3 needs, and frustrations with current solutions.
3. Functional requirements Elicits features organized by priority (Must-Have, Should-Have, Nice-to-Have). Each gets a unique ID (FR-001, FR-002, ...), user story format, and testable acceptance criteria.
4. Non-functional requirements Defines performance, security, accessibility, scalability, reliability, and compliance requirements. Each gets a unique ID (NFR-001, ...) with measurable targets.
5. User journeys Maps key user flows with happy paths and error paths: entry point, steps, decision points, exit conditions.
6. Data and integrations Defines data entities, relationships, and external system integrations.
7. Constraints and success criteria Documents technical and business constraints, and defines success criteria with measurable outcomes.
8. Generate PRD Writes the full PRD using the standard template.
9. Adversarial review Runs an automated adversarial review and incorporates critical/high findings into the PRD.
10. Validation Runs quality checks and auto-fixes issues (up to 3 iterations).

Inputs

Outputs

Example session

> /gaia-create-prd .gaia/artifacts/creative-artifacts/product-brief-taskflow.md

Loading product brief...
Scanning research artifacts...
  Found: market-research.md, domain-research.md

User Interviews:
  Who are the primary user types?
> Team leads, individual contributors, project managers

Functional Requirements:
  Must-Have: FR-001 through FR-012 (12 requirements)
  Should-Have: FR-013 through FR-018 (6 requirements)
  Nice-to-Have: FR-019 through FR-022 (4 requirements)

Non-Functional Requirements:
  NFR-001 through NFR-008 (8 requirements)

Adversarial review: 2 critical findings incorporated.

PRD written to: .gaia/artifacts/planning-artifacts/prd.md
  22 functional requirements, 8 non-functional requirements

What to run next

• /gaia-create-ux -- design UX from the PRD.
• /gaia-create-arch -- design system architecture from the PRD.
• /gaia-edit-prd -- refine specific sections of the PRD.

Troubleshooting

"product-brief-path required"

Provide the path to your product brief as an argument. Run /gaia-product-brief first if you do not have one.

"An existing PRD was found"

A PRD already exists. Confirm to overwrite, or use /gaia-edit-prd to make targeted changes instead.

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