GAIA — Generative Agile Intelligence Architecture

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

GAIA gives you a team of AI agents with distinct personas, structured workflows that follow a proven product lifecycle, built-in quality gates, checkpoint/resume for long-running sessions, and persistent agent memory across conversations.

Installation

Using npx (recommended)

npx gaia-framework init .

This clones the latest GAIA release from GitHub and installs it into the current directory.

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

# Skip interactive prompts (uses defaults)
npx gaia-framework init --yes ~/my-project

Requirements: Node.js 18+ and git.

Using the shell script directly

# Clone the repo
git clone https://github.com/J-louage/Gaia-framework.git

# Install into your project
bash Gaia-framework/gaia-install.sh init ~/my-project

# Or use a local copy as source
bash gaia-install.sh init --source ~/Gaia-framework ~/my-project

The script resolves sources in this order: --source flag, $GAIA_SOURCE env var, script's own directory, GitHub clone.

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 with .gitkeep files
4. Creates .resolved/ directories for pre-built configs
5. Prompts for project name and user name, writes them to global.yaml
6. Copies CLAUDE.md to your project root (the framework instruction file)
7. Installs 99 slash commands to .claude/commands/
8. Appends GAIA entries to .gitignore

Updating an existing installation

# Via npx
npx gaia-framework update .

# Via shell script
bash gaia-install.sh update ~/my-project

Update refreshes all framework files (engine, agents, workflows, skills, knowledge, commands) while preserving your global.yaml configuration, agent memory, resolved configs, and CLAUDE.md.

Changed files are backed up to _gaia/_backups/{timestamp}/ before overwriting.

Validating and checking status

# Check installation integrity (32 checks)
npx gaia-framework validate .

# Show version, module list, command count, sidecar status
npx gaia-framework status .

Installer options

gaia-install.sh <command> [options] [target]

Commands:
  init       Install GAIA into a project
  update     Update framework files (preserves config and memory)
  validate   Check installation integrity
  status     Show installation info

Options:
  --source <path>   Local GAIA source directory
  --yes             Skip confirmation prompts
  --dry-run         Show what would be done without making changes
  --verbose         Show detailed progress
  --help            Show help

Getting Started

After installation, open your project in Claude Code:

cd ~/my-project
claude

Then type /gaia to launch the orchestrator. Gaia presents a categorized menu and routes you to the right agent or workflow.

5 essential commands

First-time setup

After installing GAIA into your project, run /gaia-build-configs to generate pre-resolved configuration files. This speeds up every future workflow activation by eliminating runtime config resolution.

Architecture

_gaia/
├── _config/              # Global config, manifests, agent registry
│   ├── global.yaml       # Project settings — single source of truth
│   └── manifest.yaml     # Module registry
├── _memory/              # Persistent agent memory + checkpoints
│   ├── checkpoints/      # Workflow progress snapshots
│   └── *-sidecar/        # Per-agent persistent memory (9 sidecars)
├── core/                 # Execution engine, protocols, shared tasks
│   ├── engine/           # workflow.xml, task-runner.xml, error-recovery.xml
│   ├── tasks/            # 17 standalone review/utility tasks
│   └── workflows/        # Brainstorming, party mode, advanced elicitation
├── lifecycle/            # Product lifecycle (5 phases)
│   ├── agents/           # 11 lifecycle agents
│   ├── workflows/        # 34 workflows across 5 phases + anytime + quick-flow
│   ├── templates/        # PRD, architecture, story, sprint plan templates
│   └── teams/            # Pre-built team compositions
├── dev/                  # Developer tooling
│   ├── agents/           # 6 stack-specific developers + base
│   ├── skills/           # 8 shared skills with sectioned loading
│   └── knowledge/        # Stack-specific patterns (Angular, React, Flutter, etc.)
├── creative/             # Creative intelligence
│   ├── agents/           # 6 creative agents
│   ├── workflows/        # 7 creative workflows
│   └── data/             # Methods, frameworks, story types
└── testing/              # Test architecture
    ├── agents/           # Test Architect (Sable)
    ├── workflows/        # 12 testing workflows
    └── knowledge/        # 20+ testing knowledge fragments

At a glance

Agents

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

Orchestrator

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

Fast-track workflows for small changes that skip the full lifecycle ceremony.

Creative Workflows

Testing Workflows

Anytime Workflows

Available at any point in the lifecycle.

Review & Utility Tasks

Standalone tasks that can be run anytime without a full workflow. These are single-step operations for reviews, audits, and document utilities.

Code & Security Reviews

Editorial & Documentation

Framework

Shared Skills

Skills are loaded just-in-time by developer agents. Each skill is divided into sections so only the relevant portion is loaded (keeping context usage low).

Knowledge Fragments

Stack-specific and domain-specific knowledge loaded on demand.

Developer Knowledge (by stack)

Testing Knowledge (by tier)

Output Artifacts

Every workflow writes its output to a specific artifact directory:

docs/
├── planning-artifacts/         # PRDs, research, architecture, epics
├── implementation-artifacts/   # Sprint plans, stories, reviews, changelogs
├── test-artifacts/             # Test plans, traceability, accessibility
└── creative-artifacts/         # Design thinking, innovation, pitch decks

Checkpoint & Resume

Long-running workflows save checkpoints to _gaia/_memory/checkpoints/. If your session is interrupted or context is lost, run /gaia-resume to pick up from the last completed step.

Completed workflow checkpoints move to _gaia/_memory/checkpoints/completed/.

Agent Memory

Each agent has a persistent memory sidecar that survives across sessions:

_gaia/_memory/
├── architect-sidecar/
├── devops-sidecar/
├── orchestrator-sidecar/
├── pm-sidecar/
├── security-sidecar/
├── sm-sidecar/
├── storyteller-sidecar/
├── tech-writer-sidecar/
└── test-architect-sidecar/

Agents store decisions, patterns, and context they learn about your project. This memory accumulates over time, making agents more effective the more you use them.

Configuration

global.yaml

The single source of truth for project settings at _gaia/_config/global.yaml:

framework_name: "GAIA"
framework_version: "1.0.2"

user_name: "your-name"
project_name: "your-project"
project_root: "{project-root}"

output_folder: "{project-root}/docs"
planning_artifacts: "{project-root}/docs/planning-artifacts"
implementation_artifacts: "{project-root}/docs/implementation-artifacts"
test_artifacts: "{project-root}/docs/test-artifacts"
creative_artifacts: "{project-root}/docs/creative-artifacts"

The {project-root} placeholder is resolved at runtime. After changing global.yaml, run /gaia-build-configs to regenerate resolved configs.

Pre-resolved configs

Each module (core, lifecycle, creative, testing) has a .resolved/ directory for pre-built config files. These eliminate runtime config resolution overhead. Generate them with /gaia-build-configs.

Teams

Pre-built team compositions for different project types:

Typical Workflow

A full product lifecycle from idea to deployment:

/gaia-brainstorm           → brainstorm the idea
/gaia-product-brief        → create a product brief
/gaia-market-research      → validate market fit
/gaia-create-prd           → write the PRD
/gaia-create-ux            → design the UX
/gaia-create-arch          → design the architecture
/gaia-create-epics         → break into epics and stories
/gaia-readiness-check      → verify everything is ready
/gaia-sprint-plan          → plan the first sprint
/gaia-dev-story            → implement stories
/gaia-code-review          → review the code
/gaia-qa-tests             → generate tests
/gaia-security-review      → security audit
/gaia-release-plan         → plan the release
/gaia-deploy-checklist     → pre-deploy verification
/gaia-post-deploy          → post-deploy health check
/gaia-retro                → sprint retrospective

For small changes, skip the ceremony:

/gaia-quick-spec           → rapid tech spec
/gaia-quick-dev            → implement it

License

MIT