GAIA Framework Documentation

GAIA (Generative Agile Intelligence Architecture) is a plugin for Claude Code that brings a full software-delivery lifecycle to your terminal. It provides slash commands for every phase of a project -- from brainstorming a product idea, through planning, architecture, sprint management, implementation, testing, code review, and deployment.

Each command is a self-contained workflow that reads your project artifacts, performs its task, and writes its outputs back into well-defined locations under your .gaia/artifacts/ and .gaia/config/ directories (the canonical layout; legacy projects under docs/ and config/ continue to work via the framework's three-tier path resolver). Commands are composable: the output of one is the input of the next, forming a coherent chain from idea to production.

This documentation covers every command available in the GAIA plugin -- both the user-invocable slash commands you type directly and the internal skills that GAIA calls behind the scenes.

First time using GAIA?

Read the First 30 Minutes with GAIA walkthrough to go from zero to your first sprint. Or jump straight in: run /gaia-init to bootstrap your project configuration, then /gaia-help to see what to do next based on your project's current state.

The GAIA Lifecycle

Every GAIA project flows through five phases. Each phase has its own commands and produces specific artifacts. You do not need to run every command in every phase -- GAIA adapts to your project's needs.

# Phase Key Commands Artifacts Produced
1 Analysis /gaia-brainstorm, /gaia-market-research, /gaia-domain-research, /gaia-tech-research, /gaia-product-brief brainstorm-{slug}.md, market-research.md, product-brief.md
2 Planning /gaia-create-prd, /gaia-create-ux, /gaia-val-validate prd.md, ux-design.md
3 Solutioning /gaia-create-arch, /gaia-create-epics, /gaia-threat-model, /gaia-infra-design, /gaia-trace architecture.md, epics-and-stories.md, threat-model.md, traceability-matrix.md
4 Implementation /gaia-sprint-plan, /gaia-dev-story, /gaia-review-all, /gaia-atdd, /gaia-sprint-review, /gaia-sprint-close sprint-status.yaml, story files under .gaia/artifacts/implementation-artifacts/, review reports
5 Deployment /gaia-release-plan, /gaia-deploy-checklist, /gaia-deploy, /gaia-post-deploy release-plan.md, deploy-checklist.md, post-deploy health report

For a hands-on walkthrough of Phases 1--4, see the First 30 Minutes tutorial. For multi-command recipes, see Common Workflows.

See the full activity diagram -- an interactive one-page view of every command, gate, and decision point across all five phases. Every box links to that command's documentation.

How to use this documentation

Commands are organized into 13 categories that mirror the phases of a typical project. Each category page lists every command in that group with a one-line summary. Click through to a command's detail page for full documentation: what it does, when to use it, prerequisites, step-by-step workflow, inputs, outputs, examples, and troubleshooting.

Commands labeled user-facing are ones you invoke directly by typing the slash command in Claude Code. Commands labeled internal are called automatically by other commands -- you will never need to type them, but understanding what they do can help when debugging or customizing workflows. Commands labeled deprecated still work but redirect to a newer replacement.

If you encounter GAIA-specific terminology -- terms like story, sprint, artifact, or gate -- see the Glossary.

Common pitfalls

These are the highest-impact friction points dogfood-testing surfaced. Each one has a documented workaround or escape hatch.

  • Strict-mode lifecycle gates have an escape hatch. When /gaia-create-arch, /gaia-dev-story, or /gaia-sprint-plan halts on a missing prerequisite (e.g., no threat model, no traceability matrix), you can either run the missing skill OR record a bypass via --bypass <skill> --reason "<text>". For a temporary OFF-switch on a single invocation, set the GAIA_STRICT_LIFECYCLE=0 env var.
  • test-strategy vs test-plan filename naming. /gaia-test-strategy --plan writes test-strategy.md, but downstream gates (especially /gaia-create-epics) require test-plan.md. The finalize step now writes a sibling test-plan.md alias automatically so the naming mismatch is resolved at the producer side. Pre-fix projects may have a manual cp test-strategy.md test-plan.md in their workflow — you can remove it.
  • /gaia-sprint-review is NOT YOLO-able by design. The skill declares yolo_steps: [] because its three stakeholder-confirmation boundaries (Steps 3a, 4a, 8) require human judgment. For unattended pipelines, script the boundary writes directly: sprint-state.sh transition --sprint <id> --to review, write the sprint-review artifact + Val sentinel, then invoke finalize.sh.
  • Greenfield bootstrap: /gaia-sprint-plan needs per-story files first. On a fresh project, /gaia-sprint-plan requires individual story files under .gaia/artifacts/implementation-artifacts/epic-*/stories/. The intended bootstrap flow is to run /gaia-create-story E1-S1 for each story you want to sprint, then invoke /gaia-sprint-plan. A future /gaia-create-story --bulk mode will let you materialize all stories from epics-and-stories.md in one call.
  • Default artifact paths are .gaia/, not docs/. The canonical layout is .gaia/artifacts/<phase>-artifacts/ and .gaia/config/project-config.yaml. Legacy projects under docs/ continue to work via the three-tier path resolver, but any new project should expect the .gaia/ layout.

Command categories

Getting Started

Bootstrap a new project, get context-sensitive help, onboard an existing codebase, or resume a previous session.

7 commands

Discovery & Research

Brainstorm product ideas, conduct market and domain research, evaluate technologies, and produce a product brief.

6 commands

Planning

Create and edit PRDs, architecture docs, UX designs, threat models, infrastructure plans, and break work into epics and stories.

14 commands

Sprint Management

Plan sprints, track status, manage scope changes, run retrospectives, and review technical debt.

8 commands

Development

Implement user stories with TDD, create quick specs, fix validation issues, and triage findings.

7 commands

Testing

Design test strategies, generate acceptance tests, automate test coverage, run tests across environments, and analyze gaps.

17 commands

Reviews

Pre-merge quality gates: code, security, performance, accessibility, mobile, API, and dependency reviews.

12 commands

Validation

Validate artifacts against your codebase, check story completeness, verify framework consistency, and manage ground truth.

9 commands

Deployment

Deploy to environments, verify post-deployment health, plan rollbacks, cut releases, and generate changelogs.

7 commands

Configuration

View and edit project configuration, manage CI pipelines, configure tool adapters, and set compliance regimes.

16 commands

Documentation & Editorial

Generate project documentation, split and merge large documents, summarize content, and get editorial reviews.

9 commands

Creative & Collaboration

Run design thinking sessions, brainstorming, multi-agent discussions, pitch decks, and storytelling workshops.

11 commands

Internal Skills

Behind-the-scenes skills loaded automatically by other commands. Not invoked directly, but documented for reference.

16 skills

Common Workflows

Step-by-step recipes for frequent multi-command workflows: greenfield bootstrap, brownfield onboard, quick fixes, full deploy, and more.

8 recipes

First 30 Minutes

A narrative walkthrough taking you from zero to your first sprint, touching every major phase of the GAIA lifecycle. A brownfield companion covers onboarding an existing codebase.

tutorial

test-environment.yaml Reference

Full schema reference for the Test Execution Bridge manifest -- canonical path, every field, copy-ready examples for Node, Python, Go, Java, Flutter, Bash, and Rust.

reference