GAIA — Generative Agile Intelligence Architecture

WARNING: This framework is currently in BETA. Workflows, commands, and APIs may change without notice. Use in production at your own risk.

AI agent framework for Claude Code that orchestrates software product development through 25 specialized agents, 62 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 101 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/            # 16 standalone review/utility tasks
│   └── workflows/        # Brainstorming, party mode, advanced elicitation
├── lifecycle/            # Product lifecycle (5 phases)
│   ├── agents/           # 11 lifecycle agents
│   ├── workflows/        # 36 workflows across 5 phases + anytime + quick-flow
│   ├── templates/        # 16 document templates (PRD, architecture, API docs, brownfield, etc.)
│   └── 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

Testing workflows are integrated into the main lifecycle — they are not optional standalone tools. Key integration points:

Anytime Workflows

Available at any point in the lifecycle.

Brownfield Onboarding (Deep Dive)

The brownfield onboarding workflow (/gaia-brownfield) is a comprehensive 9-step process that transforms an existing codebase into a fully documented developer knowledge base. It detects project capabilities during scanning and conditionally generates specialized documentation.

Step 1 — Deep Project Discovery scans the codebase and sets capability flags:

Steps 2–4 are conditional — they only run when the corresponding capability is detected:

Steps 5–10 always run:

Design rules:

• All diagrams use Mermaid syntax — no ASCII art
• All API docs use Swagger/OpenAPI format
• Flow diagrams limited to 3–5 key flows per document
• NFR baselines are measured from the codebase, not estimated

Output artifacts (up to 11, depending on detected capabilities):

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

Adversarial Review (/gaia-adversarial)

The adversarial review is a cynical, critical examination designed to find flaws, gaps, and weaknesses in any document or design. It deliberately assumes nothing works as claimed and attacks from 10 different perspectives:

Output: A ranked findings report with severity (critical/high/medium/low), confidence (certain/likely/possible), a threat summary of the top 3 issues, and an overall risk assessment. The review only identifies problems — it does not suggest fixes.

When to use it: The adversarial review is integrated as an optional prompt at 4 key lifecycle points:

At each point you can accept or skip. It can also be run independently anytime with /gaia-adversarial on any artifact.

Lifecycle-Integrated Reviews

In addition to the adversarial review, several other tasks are integrated into the lifecycle at natural trigger points:

Review Gate members (required — story cannot move to done without all 6 passing):

Optional prompts (offered at natural lifecycle points — user can accept or skip):

All reviews can also be run independently anytime on any artifact or codebase.

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

Templates

Document templates in _gaia/lifecycle/templates/ provide standardized structures for workflow outputs. Each template has YAML frontmatter (template, version, used_by) and placeholder sections that agents fill during execution.

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.20.0"

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 Workflows

Greenfield — New project from idea to deployment

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

# Phase 2: Planning
/gaia-create-prd           → write the PRD (optional: adversarial review)
/gaia-create-ux            → design the UX (optional: accessibility review)

# Phase 3: Solutioning
/gaia-create-arch          → design the architecture (optional: API review, adversarial review)
/gaia-test-design          → create test plan (optional: scaffold test framework)
/gaia-create-epics         → break into epics and stories (optional: edge cases, adversarial review)
/gaia-trace                → generate traceability matrix
/gaia-ci-setup             → scaffold CI pipeline
/gaia-readiness-check      → verify everything is ready (optional: adversarial review)

# Phase 4: Implementation (repeat per sprint)
/gaia-sprint-plan          → plan the sprint (optional: mobile testing)
/gaia-create-story         → create detailed stories
/gaia-validate-story       → validate story completeness
/gaia-fix-story            → fix issues from validation
/gaia-atdd                 → write acceptance tests (REQUIRED for high-risk stories)
/gaia-dev-story            → implement stories
/gaia-code-review          → review the code          ─┐
/gaia-qa-tests             → generate tests             │
/gaia-security-review      → security audit              │ Review Gate
/gaia-test-automate        → expand test coverage        │ (all 6 must
/gaia-test-review          → review test quality         │  PASS before
/gaia-review-perf          → performance review         ─┘  story → done)
/gaia-triage-findings      → triage dev findings into backlog
/gaia-retro                → sprint retrospective

# Phase 5: Deployment
/gaia-release-plan         → plan the release
/gaia-deploy-checklist     → pre-deploy verification (optional: a11y testing)
/gaia-post-deploy          → post-deploy health check

Brownfield — Onboard an existing project

# Onboarding (scans codebase, generates knowledge base)
/gaia-brownfield           → deep project discovery (10 steps)
                              1. Scan codebase → project-documentation.md
                              2. API documentation (if APIs detected)
                              3. UX assessment (if frontend detected)
                              4. Event catalog (if messaging detected)
                              5. Dependency map
                              6. NFR assessment & baselines
                              7. Performance test plan
                              8. Gap-focused PRD (gaps only, not existing features)
                              9. Architecture with as-is/target diagrams
                             10. Epics/stories for gaps + developer knowledge base

# Phase 3: Readiness
/gaia-test-design          → create test plan (optional: scaffold test framework)
/gaia-trace                → generate traceability matrix
/gaia-ci-setup             → scaffold CI pipeline
/gaia-readiness-check      → verify everything is ready (optional: adversarial review)

# Phase 4: Implementation (repeat per sprint)
/gaia-sprint-plan          → plan the sprint (optional: mobile testing)
/gaia-create-story         → create detailed stories
/gaia-validate-story       → validate story completeness
/gaia-fix-story            → fix issues from validation
/gaia-atdd                 → write acceptance tests (REQUIRED for high-risk stories)
/gaia-dev-story            → implement gap stories
/gaia-code-review          → review the code          ─┐
/gaia-qa-tests             → generate tests             │
/gaia-security-review      → security audit              │ Review Gate
/gaia-test-automate        → expand test coverage        │ (all 6 must
/gaia-test-review          → review test quality         │  PASS before
/gaia-review-perf          → performance review         ─┘  story → done)
/gaia-triage-findings      → triage dev findings into backlog
/gaia-retro                → sprint retrospective

# Phase 5: Deployment
/gaia-release-plan         → plan the release
/gaia-deploy-checklist     → pre-deploy verification (optional: a11y testing)
/gaia-post-deploy          → post-deploy health check

Quick Flow — Small changes, minimal ceremony

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

License

MIT