GAIA — Generative Agile Intelligence Architecture

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

Why GAIA?

AI can generate code faster than any human. But speed without structure creates a different kind of technical debt — code that nobody can trace back to a requirement, architectures that no one reviewed, and features that were never validated against actual user needs. The faster you build, the faster you accumulate problems that slow you down later.

GAIA exists because maintainability matters. It brings the discipline of a real product team — analysts, architects, QA engineers, security experts — into AI-assisted development, so what you build is something you can actually maintain, scale, and hand off to others.

Without guardrails, every AI session starts from zero. There's no traceability from requirements to code, no architectural consistency across features, no review process, and no way to ensure two developers working on the same project follow the same standards. GAIA solves this by treating AI development the way serious software teams have always worked: with a structured lifecycle, enforced quality gates, and specialized roles — except the roles are played by AI agents that remember decisions across sessions.

What this gives you:

• A structured lifecycle, not ad-hoc prompting — 5 phases from analysis to deployment, with quality gates that enforce standards at every transition
• 26 specialized agents — each with a persona, domain expertise, and persistent memory that improves over time
• Enforced quality gates — 17 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
• Full traceability — every line of code traces back through stories, epics, architecture decisions, and requirements to the original product brief
• 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

Design Principles

GAIA is built on a few core beliefs about how AI-assisted development should work:

• Human-in-the-loop, always. AI agents propose, humans decide. Every workflow pauses at meaningful checkpoints for review. YOLO mode exists for experienced users, but the default is deliberate.
• Quality gates are not optional. Gates halt the workflow — they don't just warn. You can't create architecture without a reviewed PRD. You can't deploy without passing all reviews. This is intentional friction that prevents expensive mistakes.
• Agents remember. Each agent has persistent memory that accumulates decisions, patterns, and context across sessions. Your architect remembers why you chose PostgreSQL over MongoDB. Your QA engineer remembers the edge cases from last sprint. The more you use GAIA, the better it gets.
• Everything is traceable. From product brief to deployed feature, every artifact links to the ones that came before it. When something breaks in production, you can trace it back through code, story, epic, architecture, and the original requirement.
• Structure scales, prompting doesn't. A single prompt can produce impressive one-off results. But building a product over weeks or months requires accumulated context, consistent standards, and a process that doesn't reset every session.

Prerequisites

• Claude Code (requires Anthropic account)
• Node.js 20+
• 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 117 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

GAIA wraps Claude Code with a full product development lifecycle. Instead of prompting a general-purpose AI and hoping for consistency, you invoke structured workflows that coordinate specialized agents, enforce prerequisites, and produce traceable artifacts. Each workflow knows what inputs it needs, what outputs it produces, and what quality checks must pass before moving forward.

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 (37 commands). Sonnet handles structured generation, template-following, and status reporting (80 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
├── core/                 # Execution engine, protocols, shared tasks
│   └── engine/           # workflow.xml (7-step flow), task-runner.xml
├── lifecycle/            # 5 phases: analysis → deployment
│   ├── agents/           # 12 lifecycle agents
│   ├── workflows/        # 51 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 + 13 testing workflows

_memory/                  # Persistent agent memory (project root)
├── checkpoints/          # Workflow progress snapshots (sha256-verified)
└── *-sidecar/            # Per-agent persistent memory (26 sidecars)

At a glance

Configuration

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

framework_name: "GAIA"
framework_version: "1.60.0"
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 _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 (_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.