First 30 Minutes with GAIA — Full Lifecycle End-to-End

This tutorial walks the entire GAIA lifecycle from a fresh project to a closed sprint: bootstrap → discovery → planning → solutioning → first sprint (implement, review, transition, close) → planning the next sprint. The first twelve steps get you to your first story being implemented; Steps 13-21 take that story through reviews, mark it done, run the sprint review, triage findings, write the retro, close the sprint, and plan the next one.

This walkthrough takes you from a blank directory to a running sprint. Each step builds on the previous one, producing an artifact that feeds the next command. By the end, you will have a product brief, a PRD, an architecture document, a backlog of stories, a planned sprint, and your first story implemented with tests.

Have an existing codebase? Use the First 30 Minutes (Brownfield) companion instead -- it collapses Steps 2--7 below into a single /gaia-brownfield invocation that reverse-engineers the PRD, architecture, and epics from your code, then re-joins this walkthrough at Step 8.

Overview

The walkthrough follows GAIA's lifecycle phases: Analysis (steps 1--4), Planning (steps 5--6), Solutioning (steps 7--9), Implementation (steps 10--16), and Sprint Management (steps 17--21). Deployment is covered separately in the Recipes page.

Step 1 -- Install the plugin

Install the GAIA plugin into your Claude Code environment. Refer to the GAIA repository README for platform-specific installation instructions. Once installed, all /gaia-* commands become available in any Claude Code session.

Expected duration: 2 minutes.

Step 2 -- Bootstrap your project

/gaia-init

GAIA asks a series of discovery questions -- project name, tech stack, platforms, compliance regimes, environments, and CI platform. Your answers are saved to .gaia/config/project-config.yaml, the single configuration file that every other GAIA command reads.

Artifact produced: .gaia/config/project-config.yaml

Expected duration: 3 minutes.

Step 3 -- Explore the problem

/gaia-brainstorm

Describe what you want to build. GAIA facilitates a structured brainstorming session, helping you explore the problem space, user needs, and potential solutions. The output captures your ideas in a format that the next commands can consume.

Artifact produced: .gaia/artifacts/creative-artifacts/brainstorm-{slug}.md

Expected duration: 5 minutes.

Step 4 -- Capture the vision

/gaia-product-brief

Synthesize the brainstorm into a structured product brief covering vision, target users, the core problem, proposed solution, scope boundaries, risks, competitive landscape, and success metrics.

Artifact produced: .gaia/artifacts/planning-artifacts/product-brief.md

Expected duration: 5 minutes.

Step 5 -- Produce requirements

/gaia-create-prd

The PM agent (Derek) transforms your product brief into a full Product Requirements Document. The PRD contains functional requirements (FRs), non-functional requirements (NFRs), user journeys, data requirements, integrations, and success criteria. Every functional requirement gets a unique identifier that flows through the rest of the lifecycle.

Artifact produced: .gaia/artifacts/planning-artifacts/prd.md

Expected duration: 5 minutes.

Step 6 -- Design the user experience (UI projects)

/gaia-create-ux

If your project has a user interface (compliance.ui_present: true in your config), the UX designer agent (Christy) reads the PRD and produces a UX design document covering personas, information architecture, wireframes, interaction patterns, and accessibility guidelines. Run /gaia-design-review to drive stakeholder approval before moving to architecture.

Headless service? Skip this step. When compliance.ui_present is false (or the project has no UI layer), GAIA bypasses UX prerequisites automatically.

Artifact produced: .gaia/artifacts/planning-artifacts/ux-design.md

Expected duration: 5 minutes.

Step 7 -- Design the system

/gaia-create-arch

The architect agent (Theo) reads the PRD and produces an architecture document covering technology selection, system components, data architecture, API design, infrastructure, security architecture, and architecture decision records. Each decision traces back to a PRD requirement.

Artifact produced: .gaia/artifacts/planning-artifacts/architecture.md

Expected duration: 5 minutes.

Step 8 -- Break into deliverable units

/gaia-create-epics

GAIA breaks the architecture into epics and stories. Each epic groups related stories that together deliver a significant capability. Each story gets acceptance criteria, a risk rating, and dependency links.

Artifact produced: .gaia/artifacts/planning-artifacts/epics-and-stories.md

Expected duration: 3 minutes.

Step 9 -- Check implementation readiness

/gaia-readiness-check

Validates that all planning and testing artifacts are complete, consistent, and free of cross-artifact contradictions before you start implementing. The architect and devops agents assess readiness; two mandatory quality gates (traceability matrix and CI setup) must pass.

Expected duration: 2 minutes.

Step 10 -- Prepare individual stories

/gaia-create-story E1-S1

Creates a detailed story file for a specific story from the epics-and-stories document. The file includes YAML frontmatter (status, risk, dependencies), acceptance criteria, subtasks, a Definition of Done checklist, and a Review Gate table. Repeat for each story you want to work on.

Artifact produced: .gaia/artifacts/implementation-artifacts/epic-E1-*/stories/E1-S1-*.md

Expected duration: 2 minutes per story.

Step 11 -- Pick what to work on

/gaia-sprint-plan

The sprint manager agent (Nate) selects stories from the backlog based on priority, dependencies, and velocity. The sprint is committed atomically to .gaia/state/sprint-status.yaml, which becomes your source of truth for the iteration.

Artifact produced: .gaia/state/sprint-status.yaml

Expected duration: 2 minutes.

Step 12 -- Implement your first story

/gaia-dev-story E1-S1

The full implementation workflow: plan approval, TDD (red/green/refactor), code writing, test execution, commit, push, PR creation, CI wait, and merge. GAIA selects the right stack developer agent based on your project's tech stack and walks through each step with you.

Artifacts produced: source code, test files, PR, review reports

Expected duration: varies by story complexity.

Step 13 -- Verify Definition of Done

/gaia-check-dod E1-S1

Parses the story's DoD checklist and reports which items are checked vs unchecked. A green DoD is a precondition for the next step (running the full review battery).

Artifacts produced: none (read-only check; updates the story's DoD section indirectly via the upstream gates).

Expected duration: under 1 minute.

Step 14 -- Run all 6 reviews

/gaia-review-all E1-S1

Dispatches six review sub-agents in parallel against the just-implemented story: code review, security review, QA tests, test automation, test review, and performance review. Each writes a review report and updates the corresponding row of the story's Review Gate table to PASSED, FAILED, or UNVERIFIED via review-gate.sh. Reviews that require execution evidence (QA tests, test automation, test review) cite the runner exit code as --execution-evidence JSON when the Test Execution Bridge is enabled.

Artifacts produced: code-review-{key}.md, security-review-{key}.md, qa-tests-{key}.md, test-automate-review-{key}.md, test-review-{key}.md, performance-review-{key}.md in .gaia/artifacts/implementation-artifacts/ (per-story reviews/ subdir on the per-story layout) plus optional evidence/*.json when the bridge is on.

Expected duration: 5-10 minutes for the parallel battery.

Step 15 -- Transition the story to done

/gaia-check-review-gate E1-S1
# (all 6 PASSED → COMPLETE)
${CLAUDE_PLUGIN_ROOT}/scripts/transition-story-status.sh E1-S1 --to review
# (verify the review gate one more time)
${CLAUDE_PLUGIN_ROOT}/scripts/transition-story-status.sh E1-S1 --to done

review-gate-check reads each Review Gate row and exits 0 for COMPLETE, 1 for BLOCKED, 2 for PENDING. The story transitions through in-progress → review → done — each transition is the boundary writer that atomically updates the story file frontmatter, .gaia/state/sprint-status.yaml, the per-epic shard, and story-index.yaml.

Artifacts updated (4-surface atomic write): story file frontmatter, .gaia/state/sprint-status.yaml, per-epic shard at .gaia/artifacts/planning-artifacts/epics/epic-{slug}.md, and .gaia/state/story-index.yaml.

Expected duration: under 1 minute.

Step 16 -- Repeat for the rest of the sprint

Loop Steps 12-15 for every other story in the sprint. The bridge runs unit/integration tests across all stories as you go, and each story's reviews accumulate evidence the sprint review will consult. Use /gaia-sprint-status at any time to see the dashboard (sprint id, done/total counts, points burned, risk-flagged stories).

Expected duration: 1-3 days for a typical 5-story sprint.

Step 17 -- Run the end-of-sprint review

/gaia-sprint-review

Two parallel tracks: Track A dispatches Val to text-validate every story and review against the sprint's goals using the per-goal rubric; Track B re-runs the configured per-stack execution review. The composite verdict (PASSED / FAILED / UNVERIFIED) is reduced by compose-verdict.sh: PASSED routes to /gaia-sprint-close; FAILED transitions the sprint to correction and emits action items routed to /gaia-correct-course.

Artifacts produced: .gaia/artifacts/implementation-artifacts/sprint-review/sprint-review-{sprint_id}-{date}.md plus the Val dispatch sentinel at .gaia/memory/checkpoints/sprint-review-{sprint_id}-val-dispatched.json.

Expected duration: 5-15 minutes (most time is in the Val dispatch).

Step 18 -- Triage findings

/gaia-triage-findings

Scans in-progress and completed story files for development findings and triages each one into a new backlog story, an existing story, or dismissal. The tech-debt review phase runs automatically as part of triage. This step is a mandatory prerequisite for sprint close -- the close gate checks for a triage sentinel and refuses to proceed without it.

Artifacts produced: new backlog story files (when findings are triaged to new stories), triage sentinel at .gaia/memory/checkpoints/triage-findings-{sprint_id}-completed.json, updated .gaia/artifacts/implementation-artifacts/tech-debt-dashboard.md.

Expected duration: 5-10 minutes.

Step 19 -- Write the retrospective

/gaia-retro

Walks went-well, didn't-go-well, and action items. Step 7 (Val sidecar write) is REQUIRED before finalize under GAIA_FINALIZE_SENTINEL_REQUIRED=1 — see the retro Step 7 note. Action items land in .gaia/state/action-items.yaml for the next planner to consume.

Artifacts produced: .gaia/artifacts/implementation-artifacts/retrospective/retrospective-{sprint_id}-{date}.md, updated .gaia/state/action-items.yaml, appended .gaia/memory/sm-sidecar/velocity-data.md.

Expected duration: 10-15 minutes (mostly facilitation).

Step 20 -- Close the sprint

/gaia-sprint-close

Atomically writes status: closed + closed_at to .gaia/state/sprint-status.yaml, archives a copy under .gaia/artifacts/implementation-artifacts/sprint-archive/sprint-{N}-closed-{date}.yaml, and emits a sprint_closed lifecycle event to .gaia/memory/lifecycle-events.jsonl. This is the sanctioned boundary-write replacement for any manual yq -i edits on sprint-status.yaml.

Artifacts produced: updated .gaia/state/sprint-status.yaml, .gaia/artifacts/implementation-artifacts/sprint-archive/sprint-{N}-closed-{date}.yaml, appended .gaia/memory/lifecycle-events.jsonl.

Expected duration: under 1 minute.

Step 21 -- Plan the next sprint

/gaia-action-items
/gaia-sprint-plan

/gaia-action-items resolves open action items from the retro (route each item by type: clarification, implementation, process, automation). Items routed to /gaia-create-story become new backlog stories. /gaia-sprint-plan then selects from the (now-updated) backlog for the next sprint, applying sizing and priority rules.

Artifacts produced: new backlog stories under .gaia/artifacts/implementation-artifacts/epic-{slug}/{key}-{slug}/story.md (per-story layout), seeded next-sprint .gaia/state/sprint-status.yaml.

Expected duration: 15-30 minutes for action-items + planning combined.

You are now back at Step 12 for the next sprint. Welcome to the loop.

What to read next

The GAIA Lifecycle -- the five-phase diagram showing how all commands connect.
Common Workflows -- multi-command recipes for brownfield onboarding, quick fixes, deployments, and more.
/gaia-help -- context-sensitive help that suggests the best next command based on your project's current state.