GAIA — Generative Agile Intelligence Architecture

AI agent framework for Claude Code that orchestrates software product development through 25 specialized agents, 64 workflows, and 8 shared skills — from initial research all the way to deployment.

Why GAIA?

Using Claude Code alone, you prompt an AI assistant. With GAIA, you manage a team of AI specialists that follow a proven product lifecycle:

• Structured lifecycle — 5 phases from analysis to deployment, with quality gates that enforce standards at every transition
• 25 specialized agents — each with a persona, domain expertise, and persistent memory that improves over time
• Built-in quality gates — 17 enforced gates that HALT workflows when standards aren't met (not advisory — hard stops)
• 6-gate review process — every story passes code review, QA, security, test automation, test review, and performance review before completion
• Checkpoint/resume — long-running workflows survive context loss with sha256-verified checkpoints
• Brownfield support — onboard existing codebases with automated discovery, documentation generation, and gap analysis

Prerequisites

• Claude Code (requires Anthropic account)
• Node.js 18+
• Git

Quick Start

# Install GAIA into your project
npx gaia-framework init ~/my-project

# Open in Claude Code
cd ~/my-project && claude

# Generate pre-resolved configs (one-time setup)
/gaia-build-configs

Then try your first workflow:

# Describe a small feature and get a tech spec in 30 seconds
/gaia-quick-spec

# Implement it immediately
/gaia-quick-dev

Or launch the orchestrator to explore all capabilities:

/gaia

5 essential commands

Installation

Using npx (recommended)

npx gaia-framework init .

# Install into a specific directory
npx gaia-framework init ~/my-new-project

# Skip interactive prompts
npx gaia-framework init --yes ~/my-project

Using the shell script

git clone https://github.com/jlouage/Gaia-framework.git
bash Gaia-framework/gaia-install.sh init ~/my-project

What the installer does

1. Copies the _gaia/ framework into your project
2. Creates docs/ artifact directories (planning, implementation, test, creative)
3. Creates memory sidecar directories
4. Prompts for project name and user name → writes to global.yaml
5. Copies CLAUDE.md to your project root
6. Installs 104 slash commands to .claude/commands/
7. Appends GAIA entries to .gitignore

Updating

npx gaia-framework update .

Update refreshes all framework files while preserving your configuration, agent memory, and CLAUDE.md. Changed files are backed up to _gaia/_backups/{timestamp}/.

Validating

npx gaia-framework validate .   # 32 integrity checks
npx gaia-framework status .     # version, module list, command count

How It Works

5-phase product lifecycle

Phase 1: Analysis → Phase 2: Planning → Phase 3: Solutioning → Phase 4: Implementation → Phase 5: Deployment
   (Elena)           (Derek/Christy)      (Theo/Zara/Soren)      (Nate/Dev Agents)        (Soren)

Every phase has quality gates — enforced checks that halt the workflow if prerequisites aren't met. You can't create an architecture without a reviewed PRD. You can't start a sprint without a readiness check. You can't deploy without passing all reviews.

Entry points

Model assignment

Each command declares which Claude model to use. Opus handles deep reasoning, architectural decisions, and complex analysis (27 commands). Sonnet handles structured generation, template-following, and status reporting (77 commands). Claude Code auto-selects the model per workflow.

Execution modes

Workflows support three modes: normal (pauses for confirmation at each checkpoint), YOLO (auto-proceeds without pausing), and planning (presents a structured execution plan for approval before any steps run). You can switch between normal and YOLO mid-workflow.

Agents

Every agent has a name, persona, and specialization. Activate any agent directly with /gaia-agent-{name} or let the orchestrator route you.

Lifecycle Agents

Developer Agents

All developer agents extend a shared base with common dev patterns. Each adds stack-specific knowledge.

Creative Agents

Testing Agent

Workflows

Workflows are structured multi-step processes. Each has a workflow.yaml config, instructions.xml with step-by-step guidance, and a checklist.md for quality gates.

Phase 1: Analysis

Phase 2: Planning

Phase 3: Solutioning

Phase 4: Implementation

Phase 5: Deployment

Quick Flow

Creative Workflows

Testing Workflows

Testing workflows are integrated into the main lifecycle — they are not optional standalone tools.

Anytime Workflows

Review & Utility Tasks

Framework Utilities

Typical Workflow

Greenfield — new project from idea to deployment

# Phase 1: Analysis
/gaia-brainstorm             → brainstorm the idea
/gaia-product-brief          → create a product brief

# Phase 2: Planning
/gaia-create-prd             → write the PRD
/gaia-create-ux              → design the UX

# Phase 3: Solutioning
/gaia-create-arch            → design the architecture
/gaia-test-design            → create test plan
/gaia-create-epics           → break into epics and stories
/gaia-trace                  → generate traceability matrix
/gaia-ci-setup               → scaffold CI pipeline
/gaia-readiness-check        → verify everything is ready

# Phase 4: Implementation (repeat per sprint)
/gaia-sprint-plan            → plan the sprint
/gaia-dev-story              → implement stories
/gaia-run-all-reviews        → run all 6 review gates
/gaia-retro                  → sprint retrospective

# Phase 5: Deployment
/gaia-deploy-checklist       → pre-deploy verification
/gaia-post-deploy            → post-deploy health check

For brownfield projects (existing codebases), start with /gaia-brownfield — a 6-step orchestration that scans your codebase, generates documentation (APIs, UX, events, dependencies, NFR baselines), creates a gap-focused PRD, and maps the architecture. Then continue from Phase 3 above.

Architecture

_gaia/
├── _config/              # Global config, manifests
│   ├── global.yaml       # Project settings — single source of truth
│   └── manifest.yaml     # Module versions
├── _memory/              # Persistent agent memory + checkpoints
│   ├── checkpoints/      # Workflow progress snapshots (sha256-verified)
│   └── *-sidecar/        # Per-agent persistent memory (9 sidecars)
├── core/                 # Execution engine, protocols, shared tasks
│   └── engine/           # workflow.xml (7-step flow), task-runner.xml
├── lifecycle/            # 5 phases: analysis → deployment
│   ├── agents/           # 11 lifecycle agents
│   ├── workflows/        # 36 workflows across 5 phases
│   └── templates/        # 18 document templates
├── dev/                  # Developer tooling
│   ├── agents/           # 6 stack-specific developers
│   ├── skills/           # 8 shared skills (sectioned loading)
│   └── knowledge/        # Stack-specific patterns
├── creative/             # 6 creative agents + 7 workflows
└── testing/              # Test Architect + 12 testing workflows

At a glance

Configuration

The single source of truth is _gaia/_config/global.yaml:

framework_name: "GAIA"
framework_version: "1.27.25"
user_name: "your-name"
project_name: "your-project"

After changing global.yaml, run /gaia-build-configs to regenerate pre-resolved configs. Each module has a .resolved/ directory that eliminates runtime config resolution overhead.

Checkpoint & Resume

Long-running workflows save checkpoints to _gaia/_memory/checkpoints/ with sha256 checksums of all files touched. If your session is interrupted, run /gaia-resume — it validates file integrity before resuming from the last completed step.

Agent Memory

Each agent has a persistent memory sidecar (_gaia/_memory/*-sidecar/) that stores decisions, patterns, and context across sessions. Agents become more effective the more you use them. Run /gaia-memory-hygiene periodically to detect stale or contradicted decisions.

Limitations

• Single-user only — GAIA uses markdown files for state management (stories, sprint status, architecture docs). Multiple team members editing the same project will run into file conflicts.
• Claude Code required — GAIA is built specifically for Claude Code and cannot run on other AI coding assistants.
• Context budget — Complex workflows can consume significant context. The framework enforces a 40K token budget per activation with just-in-time loading to manage this, but very large projects may hit limits.

Contributing

Contributions are welcome. Please open an issue to discuss your idea before submitting a PR.

By contributing, you agree that your contributions will be licensed under the same AGPL-3.0 license and that you grant the project maintainers the right to relicense your contributions under a commercial license (CLA).

License

AGPL-3.0

The open-source framework is licensed under the GNU Affero General Public License v3.0.