Skip to content
/
Tier A A11 Governance

GAAI Framework

gaai-framework · Fr-e-d/GAAI-framework · ★ 142 · last commit 2026-05-24

Dual-track governed delivery system: Discovery defines scope, Delivery executes in isolated OS processes, backlog-as-contract prevents scope drift, persistent memory enables cross-session learning.

Best whenDiscovery and Delivery must never share a context window — OS-process isolation (not just worktrees) is required for reliable agent governance.
Skip ifDelivery Agent writing code (must be sub-agent), Merging PRs to production without human review
vs seeds
bmad-method(multi-agent skills-based workflow) but adds OS-process isolation between Discovery and Delivery (the most stringent iso…
Primitive shape 75 total
Commands 9 Skills 61 Subagents 3 Hooks 2
00

Summary

GAAI Framework — Summary

GAAI (Governed Agentic AI Infrastructure) is a drop-in .gaai/ folder framework (Markdown + YAML + bash, no SDK, no package) that implements a dual-track architecture — Discovery (conversational, scope-defining) and Delivery (autonomous, execution-only) — with structured backlog management, persistent cross-session memory, 61 skills, and a background delivery daemon that runs parallel story deliveries via tmux.

Problem it solves: AI coding tools are fast but without governance produce "drift" — agents touch code they shouldn't, forget decisions from prior sessions, and ship features nobody can verify against acceptance criteria. GAAI enforces scope authorization, structured delivery with QA gates, and cross-session decision memory.

Distinctive trait: Discovery and Delivery never share a context window — Delivery runs as a separate OS process (claude -p via tmux), completely isolated from Discovery residue. The backlog is the contract: nothing gets built that isn't in it. The delivery daemon polls the backlog and delivers multiple stories in parallel (up to 3 concurrent claude -p sessions), each running Planning → Implementation → QA sub-agents sequentially.

Target audience: Solo founders, senior engineers, and small teams with product clarity who need an AI that ships reliably without going off-script. Explicitly not for collaborative product discovery or complex external brainstorming.

Production-readiness: Active (v2.39.0, 142 stars, last commit 2026-05-24). Battle-tested per README: "176 stories, 177 decisions, 84,000 lines of TypeScript."

Differs from seeds: GAAI is closest to BMAD-METHOD (multi-agent roles with skills) but adds what BMAD lacks: cross-session persistent memory, backlog-as-contract enforcement, a background daemon for autonomous parallel delivery, and hard OS-process isolation between Discovery and Delivery contexts. The successor to ai-governor-framework by the same author (Fr-e-d).

01

Overview

GAAI Framework — Overview

Origin

Created by Frédéric Geens (Fr-e-d). The successor to the archived AI-Governor-Framework by the same author. Version 2.39.0 as of analysis date. ELv2 license (non-OSI, source-available). Built and battle-tested on a real TypeScript project: "176 stories, 177 decisions, 84,000 lines of TypeScript."

Philosophy

From the README:

"GAAI turns AI coding tools into reliable agentic software delivery systems."

"Built for developers who already have product clarity — solo founders, senior engineers, small teams who know what to build and need an agent that ships it reliably without going off-script. If you've ever said 'the agent broke something it wasn't supposed to touch,' this is for you."

The core insight is dual-track separation:

"Two slash commands. Two isolated contexts. Discovery reasons — it never executes. Delivery executes — it never decides scope. They never share a context window — Delivery runs as a separate OS process (claude -p via tmux), so system prompts can't contaminate each other. The backlog is the contract between them."

Comparison Table (from README)

vs. Difference
AGENTS.md / cursor rules Solves one session. GAAI adds cross-session memory, scope authorization, structured delivery.
BMAD-Method BMAD simulates a multi-agent Agile team. GAAI is lighter on Discovery, more rigid on Delivery governance.
LangGraph / AutoGen / CrewAI Code-first orchestration for building AI systems. GAAI governs the use of AI coding tools. Different abstraction level.
Spec Kit Spec-driven pipeline. GAAI adds governance enforcement, multi-agent delivery with QA gates, structured memory, and automated daemon delivery.

Honest Trade-offs (from README)

"Discovery is conversational and intentionally lightweight. It helps you structure what you know — it does not replace deep product research." "Trivial tasks still need a backlog item. The gate is always there." "The framework relies on the agent following the files. There is no programmatic enforcement." "The repo is freshly open-sourced. Community is just getting started."

License

ELv2 (Elastic License v2) — source-available, non-OSI. Commercial use on third-party platforms may require a commercial license.

02

Architecture

GAAI Framework — Architecture

Distribution

  • Type: standalone-repo (drop .gaai/ into project)
  • License: ELv2
  • Language: Shell (bash), Markdown, YAML

Install Methods

# Option A: Ask AI tool to install
# Paste prompt into AI chat → AI clones and runs install.sh

# Option B: CLI
git clone https://github.com/Fr-e-d/GAAI-framework.git /tmp/gaai && \
  bash /tmp/gaai/.gaai/core/scripts/install.sh --wizard && \
  rm -rf /tmp/gaai

The installer copies .gaai/ and deploys the right adapter per tool (CLAUDE.md, AGENTS.md, .cursor/rules/).

Required Runtime

  • Claude Code CLI (claude in PATH) — required for delivery daemon
  • python3
  • tmux (recommended for daemon)
  • git with staging branch

Directory Structure

your-project/
└── .gaai/
    ├── core/                          ← framework engine
    │   ├── README.md
    │   ├── GAAI.md                    ← full reference
    │   ├── QUICK-REFERENCE.md
    │   ├── VERSION                    ← 2.39.0
    │   ├── agents/                    ← Discovery + Delivery + Bootstrap agent specs
    │   │   ├── discovery.agent.md
    │   │   ├── delivery.agent.md
    │   │   ├── bootstrap.agent.md
    │   │   ├── README.agents.md
    │   │   ├── AGENT-SKILLS.md
    │   │   └── sub-agents/
    │   ├── skills/                    ← 61 execution units
    │   │   ├── discovery/ (8 skills)
    │   │   ├── delivery/ (10 skills)
    │   │   ├── cross/ (43 skills)
    │   │   └── skills-index.yaml
    │   ├── contexts/rules/            ← framework rules
    │   ├── workflows/                 ← delivery loop, bootstrap, handoffs
    │   ├── scripts/
    │   │   ├── install.sh
    │   │   └── daemon-setup.sh
    │   ├── hooks/                     ← git hooks (post-commit, pre-push)
    │   └── compat/                    ← thin adapters per AI tool
    │       ├── claude-code.md
    │       ├── cursor.mdc
    │       ├── windsurf.md
    │       ├── commands/              ← 9 slash commands
    │       └── adapters/
    └── project/                       ← project data (never overwritten by updates)
        ├── agents/                    ← custom project agents
        ├── skills/                    ← custom project skills
        ├── contexts/
        │   ├── memory/                ← persistent memory
        │   ├── backlog/               ← execution queue (active/blocked/done)
        │   └── artefacts/             ← stories, epics, plans, reports
        └── hooks/

Target AI Tools

Deep integration (slash commands, SKILL.md auto-discovery):

  • Claude Code (primary)

AGENTS.md compatible:

  • OpenCode, Codex CLI, Gemini CLI, Antigravity, Cursor (.mdc), Windsurf, any other

Delivery Daemon Requirements

  • Claude Code CLI (claude)
  • git repo with staging branch
  • tmux (or Terminal.app on macOS)
  • python3
03

Components

GAAI Framework — Components

Commands (9 Claude Code slash commands)

Command Purpose
/gaai-discover Discovery agent: clarify what to build, generate Epics + Stories with acceptance criteria, validate artefacts
/gaai-deliver Delivery agent (single story, current session): Planning → Implementation → QA sub-agents
/gaai-daemon Launch delivery daemon: polls backlog, delivers multiple stories in parallel via tmux
/gaai-bootstrap Initialize GAAI in a project: detect tool, create context files, load conventions
/gaai-status Show backlog status, active deliveries, decision count
/gaai-audit Audit framework health, detect drift, validate memory integrity
/gaai-ask Ask framework context without triggering a delivery
/gaai-switch Switch between GAAI project contexts
/gaai-update Update GAAI core from upstream

Agents (3 named agents)

Agent Track Role
discovery.agent.md Discovery Conversational; reasons about scope; generates Epics + Stories; never executes code
delivery.agent.md Delivery Execution-only; reads Story from backlog; orchestrates sub-agents; never decides scope
bootstrap.agent.md Bootstrap One-time setup; loads project conventions into memory

Sub-Agents (specialists)

Per specialists.registry.yaml — delivery sub-agents include Planning, Implementation, QA Review. Each runs in its own isolated context window.

Skills (61 total)

Category Count Examples
Discovery 8 create-prd, generate-epics, generate-stories, validate-artefacts, review-story-alignment, review-input, refine-scope, discovery-high-level-plan
Delivery 10 implement, qa-review, evaluate-story, prepare-execution-plan, delivery-high-level-plan, browser-journey-test, ci-watch-and-fix, compose-team, coordinate-handoffs, remediate-failures
Cross-cutting 43 memory-retrieve, decision-extraction, memory-store, build-skills-index, plus 39 others

Skills are pure execution units (no decision-making, no product reasoning, isolated context windows).

Git Hooks (2)

Hook Event Purpose
post-commit post-commit Dispatcher: runs .d/ hooks
pre-push pre-push Dispatcher: runs .d/ hooks

Memory System

Path Purpose
.gaai/project/contexts/memory/ Persistent decisions, patterns, conventions
.gaai/project/contexts/backlog/ Active / blocked / done stories
.gaai/project/contexts/artefacts/ Stories, epics, plans, reports

Adapters (5 tools)

claude-code.md, cursor.mdc, windsurf.md, opencode (via AGENTS.md), codex-cli (via AGENTS.md)

05

Prompts

GAAI Framework — Prompts

Prompt 1: Delivery Agent (delivery.agent.md)

Technique: Role-constraint persona with explicit "does NOT do" list, backlog-as-single-source-of-truth rule, OSS substrate phrasing rules, and non-negotiable story selection algorithm.

---
type: agent
id: AGENT-DELIVERY-001
role: delivery-orchestrator
responsibility: coordinate-sub-agents-to-deliver-validated-stories
track: delivery
---

# Delivery Agent (GAAI)

The Delivery Agent is the **orchestrator of the delivery track**. It coordinates a team of specialized sub-agents to turn validated Stories into working software.

It does not implement. It does not write tests. It does not produce plans.

It evaluates, composes, coordinates, and escalates.

## What the Delivery Orchestrator Does NOT Do

The Delivery Agent must never:
- Write code or tests
- Produce implementation plans
- Run QA reviews directly
- Modify acceptance criteria or scope
- Fill missing context with assumptions
- Implement without a validated Story
- **Merge its own PRs to production/main** (`gh pr merge` targeting `main` or `production` is FORBIDDEN — the human merges to production after review). Self-merge to **staging** is PERMITTED after the diff-sanity check passes.

## Story Selection (Non-Negotiable)

The backlog is the single source of truth. **Never infer story selection from git branch, artefact existence, or working directory.**

Selection algorithm:
1. If a story ID was passed as argument → use that story. Verify `status: refined` or `in_progress`.
2. If no argument → pick the first story with `status: refined` in `active.backlog.yaml` (top-to-bottom).
3. A story with `status: done` is done — regardless of what branches, artefacts, or files exist.

Prompt 2: Skills Index Discovery Rules (skills/README.skills.md)

Technique: Progressive disclosure protocol with Phase 1/2/3 loading discipline, "load minimum needed, not everything" directive.

# GAAI Skills — Index

> Agents decide. Skills execute.

## Invocation Rules

1. Skills are **never invoked implicitly** — an agent always selects and invokes explicitly
2. Skills execute in **isolated context windows** — no shared state between skills
3. Skills **never chain** other skills — only agents orchestrate
4. Skills **never access memory** autonomously — context is always provided by the agent
5. Skills **never make product or architectural decisions** — they execute only

## Discovery Protocol

### Phase 1 — Filter by frontmatter (read SKILL.md frontmatter only)

Read `skills-index.yaml` for a fast aggregated view.
Use `metadata.category` to scope to the right directory first.
Read `description` to confirm relevance — it is the single most important field.
Do **not** load all skills — load only SKILL.md files whose description matches your task

### Phase 2 — Load full SKILL.md

Load the full body only for skills confirmed relevant in Phase 1.
Budget: <5,000 tokens per skill, <500 lines.

### Phase 3 — Load references/ (execution only)

Load files in references/ or assets/ only during execution, never at discovery time.
09

Uniqueness

GAAI Framework — Uniqueness

Differs from Seeds

GAAI is most similar to BMAD-METHOD (multi-agent roles with skills, structured workflow phases) but adds three capabilities BMAD lacks: (1) OS-process isolation between Discovery and Delivery contexts — the most stringent isolation in the entire corpus, (2) cross-session persistent decision memory that survives between sessions, and (3) a background delivery daemon that autonomously delivers stories from a backlog in parallel via tmux. Unlike claude-flow's MCP-server architecture (which requires external tooling), GAAI is "Markdown + YAML + bash. No SDK. No package." Unlike taskmaster-ai's task decomposition tree (which has no scope enforcement), GAAI's backlog-as-contract pattern refuses to build anything not in the backlog. Like spec-kit (spec → tasks → implementation), GAAI adds governance layers on top of this basic pipeline.

Key Differentiators

  1. OS-process isolation (not just worktree): Delivery runs as a separate claude -p process. No conversation history, no Discovery prompts, no user instructions can contaminate the delivery session. This is the only process-level isolation in the corpus.
  2. Backlog-as-contract: The agent cannot improvise work. Everything must be a refined story before Delivery will pick it up.
  3. Delivery daemon with parallel execution: Up to 3 concurrent story deliveries via tmux. No other markdown-based framework achieves this.
  4. 61 skills: The largest SKILL.md-based skill library in the non-SDK frameworks (superpowers has 14, spec-driver has 24, BMAD has 34).
  5. Decision extraction: After every QA PASS, decisions are formalized into structured memory. Cross-session pattern learning without a vector database.
  6. Cross-device coordination via git: The backlog state is git-committed, enabling daemon coordination across multiple machines.
  7. Author lineage: Direct successor to AI-Governor-Framework by the same author (Fr-e-d/Frédéric Geens). AI Governor's archived README explicitly redirects to GAAI.

Positioning

GAAI occupies the "governed agentic delivery system" niche — the intersection of structured product management (Epic → Story → AC) and AI agent execution governance. It is the most sophisticated Markdown+YAML framework in the corpus, closest to a proper engineering system rather than a prompt collection.

Observable Failure Modes

  • Backlog tax: Every task, however trivial, requires a backlog entry. Teams working on quick fixes may find this friction high.
  • Claude CLI hard dependency: The delivery daemon requires claude binary in PATH. Vendor lock-in at the process level, not just the prompt level.
  • ELv2 license: Non-OSI. Commercial products building on GAAI may need a commercial license.
  • No programmatic enforcement: The README explicitly admits "the framework relies on the agent following the files." Scope enforcement is procedural, not mechanical.
  • Daemon tmux dependency: tmux required for parallel delivery; not available in all environments (CI, Docker, etc.).
  • Freshly open-sourced: "The repo is freshly open-sourced. Community is just getting started."

Explicit Antipatterns (from design)

  • Delivery Agent writing code (belongs to Implementation sub-agent)
  • Merging PRs to production (human must merge to production; staging is permitted)
  • Inferring story selection from git branch or artefact existence
  • Discovery Agent executing code changes
  • Filling missing context with assumptions
  • Storing project-specific data in .gaai/core/ (auto-synced to OSS)
04

Workflow

GAAI Framework — Workflow

Normal Development Loop

DISCOVERY PHASE (current session, interactive)
/gaai-discover
  → "What do you want to build?"
  → Discovery Agent clarifies intent
  → memory-retrieve: load relevant patterns
  → generate-epics + generate-stories skills
  → validate-artefacts: acceptance criteria check
  → Story added to backlog: status=refined
  → "E03S01 ready. Run /gaai-deliver when ready."

DELIVERY PHASE (isolated process)
/gaai-deliver  (single story, current session)
  → Read Story from backlog
  → Planning Sub-Agent: produce execution plan
  → Implementation Sub-Agent: write code vs acceptance criteria
  → QA Sub-Agent: validate all acceptance criteria PASS
  → decision-extraction: formalize durable decisions → memory
  → Story marked done, PR merged to staging

DAEMON DELIVERY (background, parallel)
/gaai-daemon
  → Poll backlog for 'refined' stories
  → Launch parallel claude -p sessions in tmux (default: 3 slots)
  → Monitor health, retry failures, archive completed work
  → Dashboard: tmux split with daemon config + active deliveries

Phase-to-Artifact Map

Phase Artifact
Discovery Epics + Stories in .gaai/project/contexts/artefacts/
Discovery validation Backlog entry with status=refined
Delivery planning Execution plan
Delivery implementation Code changes + PR
Delivery QA QA report (PASS/FAIL per acceptance criterion)
Post-delivery Decisions in .gaai/project/contexts/memory/

Approval Gates

Gate Trigger Type
Discovery scope clarification During /gaai-discover freetext-clarify
Story acceptance criteria validation validate-artefacts skill (automated) automated
QA gate (mandatory) qa-review skill automated (PASS/FAIL)

Delivery Isolation

Each Delivery session runs as:

claude -p "Read .gaai/project/contexts/backlog/<story>.yaml and deliver it."

This is a separate OS process — no conversation history, no Discovery context, no contamination. The delivery daemon manages up to 3 concurrent such processes via tmux.

Backlog Status Lifecycle

draft → refined → in-delivery → done / blocked

Only refined stories are picked up by the delivery daemon.

06

Memory Context

GAAI Framework — Memory & Context

State Storage

Storage Path Purpose
Decisions .gaai/project/contexts/memory/ Durable decisions (DECs) extracted post-delivery; architectural patterns; cross-session conventions
Backlog .gaai/project/contexts/backlog/active.backlog.yaml Active/blocked/done stories; status lifecycle
Artefacts .gaai/project/contexts/artefacts/ Epics, stories, plans, QA reports
Strategic frame .gaai/project/contexts/memory/strategic-frame.md High-level product vision, non-negotiable constraints

Persistence Model

  • Project-scoped: All memory lives in .gaai/project/ which is never overwritten by GAAI core updates
  • Cross-session: Memory persists across sessions; each session starts by calling memory-retrieve skill to load relevant context
  • Versioned: Lives in git, tracked as code

Memory Retrieval Pattern

Agent startup → memory-retrieve skill
  → Load strategic-frame.md
  → Load relevant DECs by tag/domain
  → Load recent backlog context
  → Build minimal context bundle (<X tokens)

The memory-retrieve skill implements "load minimum needed, not everything" discipline.

Decision Extraction (post-delivery)

After every QA PASS, the decision-extraction skill formalizes the key decisions made during delivery into the memory store:

  • What architectural choice was made (and why)
  • What patterns were established
  • What constraints were discovered

Cross-Session Handoff

Explicit backlog state: story status (refined/in_progress/done/blocked) persists across sessions. The daemon picks up from where the previous session left off.

Compaction Handling

Not explicitly documented for Claude Code's compaction. The backlog file persists on disk, so context loss doesn't lose delivery state. The daemon monitors health and retries failures.

Core vs Project Memory

  • .gaai/core/ — auto-synced with upstream GAAI OSS releases; never holds project-specific data
  • .gaai/project/ — project-specific; never overwritten by updates
07

Orchestration

GAAI Framework — Orchestration

Multi-Agent

Yes — GAAI's core architectural innovation is dual-track separation + sub-agent specialization:

  1. Discovery Agent — conversational, reasoning, never executes
  2. Delivery Agent — orchestrator, never decides scope
  3. Sub-agents (per story delivery): Planning, Implementation, QA Review

Orchestration Pattern

Hierarchical:

  • Discovery Agent → backlog → Delivery Agent → Sub-agents
  • The Delivery Agent is the orchestrator for each story delivery
  • Sub-agents (Planning → Implementation → QA) are sequential within a delivery

Parallel at the daemon level:

  • /gaai-daemon runs up to 3 concurrent Delivery sessions (each as separate claude -p OS process via tmux)

Isolation Mechanism

OS-process isolation — the most stringent in the corpus:

claude -p "Read .gaai/project/contexts/backlog/<story>.yaml and deliver it."

Each Delivery session runs as a separate Claude Code CLI process with no shared context. Discovery residue, conversation history, and user instructions cannot contaminate the delivery session.

This is architecturally stronger than git-worktree isolation — it's memory/context isolation at the process boundary.

Execution Mode

  • /gaai-discover: interactive-loop (current session)
  • /gaai-deliver: one-shot (current session, single story)
  • /gaai-daemon: background-daemon (polls backlog, launches parallel deliveries, monitors health)

Multi-Model

No — single model (Claude Code / claude -p). All agents use the same underlying model.

Consensus Mechanism

None — the Delivery Agent is the single authority for delivery decisions within a story. The QA agent produces a PASS/FAIL verdict; the Delivery Agent acts on it.

Prompt Chaining

Yes — extensive:

  • Discovery: intent → Epics → Stories → validate-artefacts → backlog
  • Delivery: Story → execution plan → implementation → QA review → decisions → memory

Crash Recovery

Yes — the delivery daemon monitors health and retries failures. The backlog status field tracks in-flight stories (in_progress) so crashed deliveries can be retried.

Relationship to AI Governor Framework

GAAI is the successor. The key additions vs AI Governor:

  1. OS-process isolation (none in AI Governor)
  2. Persistent memory (file-based in AI Governor, structured in GAAI)
  3. 61 skills (none in AI Governor)
  4. Delivery daemon (manual protocols in AI Governor)
  5. Backlog-as-contract (no backlog in AI Governor)
08

Ui Cli Surface

GAAI Framework — UI / CLI Surface

Claude Code Slash Commands (9)

Command Purpose
/gaai-discover Start Discovery session
/gaai-deliver Deliver single story in current session
/gaai-daemon Launch background delivery daemon
/gaai-bootstrap Initialize GAAI in new project
/gaai-status Show backlog + daemon status
/gaai-audit Framework health check
/gaai-ask Query context without triggering delivery
/gaai-switch Switch between project contexts
/gaai-update Update GAAI core from upstream

Daemon Monitor Dashboard

/gaai-daemon --status opens a tmux monitoring dashboard:

  • Split pane: daemon config + active deliveries
  • Live view of each concurrent story delivery
  • Health monitoring + retry status

From README:

"Auto-opens a monitoring dashboard (tmux split: daemon config + active deliveries)"

No Web Dashboard

No browser-based dashboard. Monitoring is via tmux and claude CLI output.

Delivery Daemon CLI

/gaai-daemon                        # start (3 slots, auto-opens monitor)
/gaai-daemon --max-concurrent 3     # explicit concurrency limit
/gaai-daemon --status               # live dashboard
/gaai-daemon --stop                 # graceful shutdown

Cross-Device Coordination

The daemon coordinates across devices via git push — backlog status changes are committed and pushed, allowing another instance on a different machine to pick up stories.

Observability

  • Backlog YAML files serve as execution state (no separate audit log format)
  • Decision memory in .gaai/project/contexts/memory/ is the persistent audit trail
  • tmux session for live daemon monitoring

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k
A11 Governance

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k
A11 Governance

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k
A11 Governance

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k
A11 Governance

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k
A11 Governance

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k
A11 Governance

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…