/gaia-create-epics

What it does

/gaia-create-epics decomposes your PRD and architecture into implementation-ready epics and user stories. Each story includes acceptance criteria, size estimate, priority, risk level (from the test plan), and dependency declarations. Stories are ordered by dependency topology first, then business priority.

When to use it

• Your PRD, architecture, and test plan are complete, and you are ready to break the work into implementable units.

Prerequisites

• PRD must exist at .gaia/artifacts/planning-artifacts/prd.md with "Review Findings Incorporated" section.
• Architecture must exist at .gaia/artifacts/planning-artifacts/architecture.md with "Review Findings Incorporated" section.
• Test plan must exist at .gaia/artifacts/test-artifacts/test-plan.md (mandatory gate).
• UX design is optional but improves story quality for UI work.

Orchestration mode

When /gaia-create-epics 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-epics 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-epics

What it does step by step

1. Load upstream artifacts Indexes the PRD (requirements), architecture (components), test plan (risk areas), and UX design (if available).
2. Detect mode Brownfield mode creates stories for gaps only. Greenfield mode creates stories for all features.
3. Define epics Groups related features into logical epics with name, description, goal, and success criteria.
4. Break down stories For each epic, creates user stories with: title (user story format), description, acceptance criteria, size (S/M/L/XL), priority (P0/P1/P2), risk level, and dependency declarations (depends_on / blocks).
5. Dependency topology Validates no circular dependencies exist. Orders stories by dependency topology, then by business priority within each tier.
6. Generate output Writes the epics-and-stories document.
7. Validation Quality checks and auto-fixes.

Inputs

Outputs

Example session

> /gaia-create-epics

Loading PRD (22 FRs, 8 NFRs), architecture (7 ADRs), test plan...
Mode: greenfield.

Epics defined:
  E1: User Authentication (4 stories)
  E2: Task Management (6 stories)
  E3: Team Collaboration (5 stories)
  E4: Reporting and Analytics (3 stories)

18 stories total, dependency topology validated (no circular deps).

Written to: .gaia/artifacts/planning-artifacts/epics-and-stories.md

What to run next

• /gaia-readiness-check -- validate all artifacts are ready for implementation.
• /gaia-sprint-plan -- plan the first sprint from the stories.

Troubleshooting

"test-plan.md not found"

The test plan is a mandatory gate. Run /gaia-test-strategy to create it.

"Architecture review findings not found"

The architecture needs a "Review Findings Incorporated" section from its adversarial review. Re-run /gaia-create-arch.

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