GAAI — Governed Agentic AI Infrastructure

A .gaai/ folder you drop into any project. Markdown + YAML + bash. No SDK. No package. No external services.

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

See It in Action

You:        /gaai-discover
Discovery:  "What do you want to build?"
You:        "Add rate limiting — 100 req/min per user, 429 on exceeded."
Discovery:  "Got it. Checking memory for existing middleware patterns..."
            → Generates Epic E03 + Story E03S01 with acceptance criteria
            → Runs validation: artefact complete, criteria testable, no scope drift
            → Adds to backlog: status: refined
Discovery:  "Done. E03S01 is ready. Run /gaai-deliver when you're ready."

You:        /gaai-daemon
            → Launches the Delivery Daemon (polls backlog, delivers in parallel via tmux)
Delivery:   → Reads E03S01 from backlog
            → Loads middleware conventions from memory
            → Planning Sub-Agent: produces execution plan
            → Implementation Sub-Agent: adds rate-limiting middleware
            → QA Sub-Agent: all acceptance criteria PASS
            → Story marked done, PR merged to staging
Delivery:   "E03S01 complete. No further Stories in backlog."

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.

/gaai-deliver delivers a single Story in the current session. /gaai-daemon launches a background daemon that polls the backlog and delivers multiple Stories in parallel (each in its own tmux session). See Delivery Daemon →

Full walkthrough in Quick Start

Why GAAI

AI coding tools are fast — but without governance, speed creates drift: agents touch code they shouldn't, forget decisions from prior sessions, and ship features no one can verify against criteria. GAAI adds the missing layer.

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.

How It Works

Discovery — you talk to the Discovery Agent in your current session. Clarify what to build. Output: a Story with acceptance criteria in the backlog. Discovery reasons. It does not execute.

Delivery — always runs in an isolated process. /gaai-daemon launches the Delivery Daemon, which runs each Story in its own claude -p session via tmux — a completely separate OS process with no Discovery residue and no conversation history bleed. The Delivery Agent orchestrates specialized sub-agents (Planning, Implementation, QA) per Story. Real-time visibility via tmux attach. No improvisation. No scope drift. No context contamination.

The delivery workflow is portable to sub-agent-capable AI coding runtimes. Claude Code is the reference implementation — the daemon uses claude -p because Claude Code was the first coding agent to expose sub-agent primitives (isolated contexts per sub-task, required for Planning → Implementation → QA separation). Discovery and governance work with any AI coding tool.

The backlog is the contract. Nothing gets built that isn't in it.

your-project/
└── .gaai/
    ├── core/                  ← framework engine (auto-synced from your project)
    │   ├── README.md          ← start here (human + AI onboarding)
    │   ├── GAAI.md            ← full reference
    │   ├── QUICK-REFERENCE.md ← daily cheat sheet
    │   ├── VERSION
    │   ├── agents/            ← Discovery + Delivery + Bootstrap agent specs
    │   ├── skills/            ← 47 execution units
    │   ├── contexts/rules/    ← framework rules
    │   ├── workflows/         ← delivery loop, bootstrap, handoffs
    │   ├── scripts/           ← bash utilities
    │   ├── hooks/             ← git hook dispatcher + core hooks
    │   └── compat/            ← thin adapters per AI tool
    └── project/               ← your project data (never overwritten by updates)
        ├── agents/            ← custom project agents
        ├── skills/            ← custom project skills
        ├── scripts/           ← project-specific scripts
        ├── hooks/             ← project-specific git hooks
        ├── workflows/         ← custom workflow overrides
        └── contexts/
            ├── rules/         ← project rule overrides
            ├── memory/        ← persistent memory (decisions, patterns, context)
            ├── backlog/       ← execution queue (active, blocked, done)
            └── artefacts/     ← stories, epics, plans, reports

No SDK. No npm package. No pip install. Markdown + YAML + bash. Readable by humans and any AI tool.

Install (30 seconds)

Copy the .gaai/ folder into your project. That's it.

Download from GitHub, drop .gaai/ into your project root, and tell your AI tool: "Read .gaai/core/README.md and bootstrap this project."

Paste this into your AI tool's chat:

Install the GAAI framework into my current project.

Determine {user-tool} by identifying which AI coding tool is running this
prompt. Valid values: claude-code | cursor | windsurf | other.
If you cannot determine it, ask the user before proceeding.

Then run:
  rm -rf /tmp/gaai
  git clone https://github.com/Fr-e-d/GAAI-framework.git /tmp/gaai
  bash /tmp/gaai/.gaai/core/scripts/install.sh --target . --tool {user-tool} --yes
  rm -rf /tmp/gaai

After install, show the user the next steps exactly as printed by the
installer.

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

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

Delivery Daemon

/gaai-deliver delivers a single Story in the current session. /gaai-daemon launches the Delivery Daemon, which delivers Stories autonomously. Requires a git repo with a staging branch:

• Polls the backlog for refined stories
• Launches parallel Claude Code sessions in tmux (default: 3 slots, configurable)
• Coordinates across devices via git push
• Monitors health, retries failures, archives completed work
• Auto-opens a monitoring dashboard (tmux split: daemon config + active deliveries)

Setup (one-time):

bash .gaai/core/scripts/daemon-setup.sh

Usage:

/gaai-daemon                        # start daemon (3 slots, auto-opens monitor)
/gaai-daemon --max-concurrent 3     # 3 parallel deliveries
/gaai-daemon --status               # live monitoring dashboard
/gaai-daemon --stop                 # graceful shutdown

/gaai-deliver = one Story, current session. /gaai-daemon = background daemon, parallel delivery.

Requires: git repo, staging branch, Claude Code CLI (claude in PATH), python3, tmux (recommended) or Terminal.app (macOS fallback).

Note: The Delivery Daemon requires the claude binary regardless of which AI tool you use for Discovery. Discovery and governance work with any tool — autonomous delivery requires Claude Code CLI.

Tested on: macOS (Apple Silicon). Linux and WSL (Windows) are expected to work but not yet validated — issues and feedback welcome.

Works With

Deep integration — slash commands, auto-loaded context, SKILL.md auto-discovery:

AGENTS.md compatible — full GAAI capability via manual activation prompts:

One canonical source (.gaai/). Thin adapters per tool. No duplication. Discovery, governance, and manual delivery work with any AI coding tool. The delivery workflow is portable to sub-agent-capable AI coding runtimes — Claude Code is the reference implementation today.

Full compatibility details

Honest Trade-offs

• Discovery is conversational and intentionally lightweight. It helps you structure what you know — it does not replace deep product research or collaborative brainstorming across a team.
• Trivial tasks still need a backlog item. You can make it a one-liner, but the gate is always there.
• The framework relies on the ag