Common Workflows

Each recipe is a multi-command workflow for a specific scenario. Commands are listed in order; run them sequentially. Branching notes describe common variations.

1. Greenfield project -- bootstrap to first sprint

Start from an empty directory and reach a running sprint.

  1. /gaia-init -- bootstrap .gaia/config/project-config.yaml with your stack, platforms, and CI settings.
  2. /gaia-brainstorm -- explore the problem space and capture initial ideas.
  3. /gaia-product-brief -- synthesize ideas into a structured product brief.
  4. /gaia-create-prd -- produce a full PRD with functional and non-functional requirements.
  5. /gaia-create-arch -- design the system architecture from the PRD.
  6. /gaia-create-epics -- break the architecture into epics and stories.
  7. /gaia-create-story -- create detailed story files for priority stories.
  8. /gaia-sprint-plan -- select stories for the first sprint.
  9. /gaia-dev-story -- implement the first story end-to-end.

Branching

Skip steps 2--3 if you already have a clear product vision and can write the PRD directly. Add /gaia-threat-model and /gaia-infra-design between steps 5 and 6 for security-sensitive projects.

2. Existing codebase -- onboard with GAIA

Apply GAIA to a project that already has code but no GAIA artifacts.

  1. /gaia-init -- create the project configuration.
  2. /gaia-brownfield -- deep discovery: scans the codebase, detects the stack, maps the directory structure, runs multi-scan gap analysis, and generates starter artifacts.
  3. /gaia-document-project -- produce a comprehensive project-documentation.md for AI context.
  4. /gaia-create-arch -- formalize the discovered architecture into a GAIA architecture document.
  5. /gaia-test-gap-analysis -- scan existing tests against requirements to find coverage gaps.

Branching

If the existing project has no tests, run /gaia-atdd after creating stories to generate acceptance test skeletons. If the project has a Figma design, run /gaia-create-ux to capture UX specs.

3. Add a feature to an in-progress project

Triage and route a new feature, enhancement, or fix through only the affected artifacts.

  1. /gaia-add-feature -- describe the change. GAIA classifies it as patch, enhancement, or feature, then cascades updates through the PRD, architecture, epics, test plan, threat model, and traceability matrix as needed.
  2. /gaia-create-story -- create story files for any new stories the cascade produced.
  3. /gaia-sprint-plan -- plan the new stories into the next sprint, or use /gaia-correct-course to inject them into the current sprint.
  4. /gaia-dev-story -- implement each new story.

Branching

For urgent hotfixes that cannot wait for sprint planning, use /gaia-correct-course to inject the story into the current sprint. For minor changes under a day of work, consider the Quick Fix recipe instead.

4. Implement a story end-to-end with full review

The standard implementation-to-done flow for a single story.

  1. /gaia-dev-story E3-S7 -- implement the story with TDD, commit, push, create PR, wait for CI, merge.
  2. /gaia-review-all E3-S7 -- run all six reviews (code, QA, security, test automation, test review, performance). Each review updates the story's Review Gate table.
  3. /gaia-check-review-gate E3-S7 -- verify all six gates are PASSED. If any failed, fix the issues and re-run the failing review.

Branching

If a review fails, fix the code and re-run only the failing review command (e.g., /gaia-review-security E3-S7), or re-run all reviews with /gaia-review-all E3-S7 --force to re-evaluate everything.

5. Run a quick fix without full lifecycle

For changes under a day that touch fewer than five files.

  1. /gaia-quick-spec fix-login-redirect -- answer two questions (what changed, which files) and get a lightweight five-section spec.
  2. /gaia-quick-dev fix-login-redirect -- implement the spec with auto-detected stack developer, commit, push, and PR.

Branching

If the quick-spec escape hatch fires (more than 5 files or 1 day), the command offers to escalate to the full lifecycle via /gaia-create-prd. Follow its suggestion.

6. Deploy a release with full pre-deploy checklist

The full deployment pipeline from release planning to post-deploy verification.

  1. /gaia-release-plan -- create a staged rollout strategy with environment progression and success metrics.
  2. /gaia-rollback-plan -- define rollback criteria and procedures for each environment.
  3. /gaia-deploy-checklist -- verify all pre-deployment quality gates.
  4. /gaia-deploy -- execute the deployment through the promotion chain: pre-deploy gate, adapter-mediated deploy, health check, and post-deploy smoke test.
  5. /gaia-post-deploy -- verify post-deployment health and metrics.

Branching

If post-deploy verification fails, consult the rollback plan produced in step 2. For hotfix deployments, skip steps 1--2 and go directly to the deploy checklist.

7. Recover from interruption

Resume work after a session break, context loss, or crash.

  1. /gaia-resume -- lists active checkpoints, reads the selected one, validates it against current file state, and surfaces a Proceed / Start fresh / Review prompt if drift is detected.
  2. If the checkpoint is valid, GAIA resumes the interrupted command from the last completed step.
  3. If drift is detected (files changed since the checkpoint), review the differences and decide whether to proceed or start fresh.

Branching

If no checkpoint exists, GAIA cannot resume. Run /gaia-help to get a context-sensitive suggestion for the best next command based on which artifacts already exist.

8. Audit existing test coverage

Find and fill gaps in your test suite.

  1. /gaia-test-gap-analysis -- scan test suite against requirements to identify which acceptance criteria lack test coverage. Produces a gap report.
  2. /gaia-fill-test-gaps -- triage gaps by severity, propose remediation actions, and execute approved remediations.
  3. /gaia-trace -- regenerate the traceability matrix to verify that all requirements now have test coverage.

Branching

Run /gaia-test-gap-analysis --mode verification to cross-reference generated test cases against actual execution results (JUnit XML, LCOV) instead of just planned coverage.