Getting Started
Bootstrap a new project, get context-sensitive help, onboard an existing codebase, or resume a previous session.
7 commandsGAIA 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-planhalts 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 theGAIA_STRICT_LIFECYCLE=0env var. -
test-strategy vs test-plan filename naming.
/gaia-test-strategy --planwritestest-strategy.md, but downstream gates (especially/gaia-create-epics) requiretest-plan.md. The finalize step now writes a siblingtest-plan.mdalias automatically so the naming mismatch is resolved at the producer side. Pre-fix projects may have a manualcp test-strategy.md test-plan.mdin their workflow — you can remove it. -
/gaia-sprint-reviewis NOT YOLO-able by design. The skill declaresyolo_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 invokefinalize.sh. -
Greenfield bootstrap:
/gaia-sprint-planneeds per-story files first. On a fresh project,/gaia-sprint-planrequires individual story files under.gaia/artifacts/implementation-artifacts/epic-*/stories/. The intended bootstrap flow is to run/gaia-create-story E1-S1for each story you want to sprint, then invoke/gaia-sprint-plan. A future/gaia-create-story --bulkmode will let you materialize all stories fromepics-and-stories.mdin one call. -
Default artifact paths are
.gaia/, notdocs/. The canonical layout is.gaia/artifacts/<phase>-artifacts/and.gaia/config/project-config.yaml. Legacy projects underdocs/continue to work via the three-tier path resolver, but any new project should expect the.gaia/layout.
Command categories
Discovery & Research
Brainstorm product ideas, conduct market and domain research, evaluate technologies, and produce a product brief.
6 commandsPlanning
Create and edit PRDs, architecture docs, UX designs, threat models, infrastructure plans, and break work into epics and stories.
14 commandsSprint Management
Plan sprints, track status, manage scope changes, run retrospectives, and review technical debt.
8 commandsDevelopment
Implement user stories with TDD, create quick specs, fix validation issues, and triage findings.
7 commandsTesting
Design test strategies, generate acceptance tests, automate test coverage, run tests across environments, and analyze gaps.
17 commandsReviews
Pre-merge quality gates: code, security, performance, accessibility, mobile, API, and dependency reviews.
12 commandsValidation
Validate artifacts against your codebase, check story completeness, verify framework consistency, and manage ground truth.
9 commandsDeployment
Deploy to environments, verify post-deployment health, plan rollbacks, cut releases, and generate changelogs.
7 commandsConfiguration
View and edit project configuration, manage CI pipelines, configure tool adapters, and set compliance regimes.
16 commandsDocumentation & Editorial
Generate project documentation, split and merge large documents, summarize content, and get editorial reviews.
9 commandsCreative & Collaboration
Run design thinking sessions, brainstorming, multi-agent discussions, pitch decks, and storytelling workshops.
11 commandsInternal Skills
Behind-the-scenes skills loaded automatically by other commands. Not invoked directly, but documented for reference.
16 skillsCommon Workflows
Step-by-step recipes for frequent multi-command workflows: greenfield bootstrap, brownfield onboard, quick fixes, full deploy, and more.
8 recipesFirst 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.
tutorialtest-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