# GAAI — Governed Agentic AI Infrastructure
A `.gaai/` folder you drop into any git project. Markdown, YAML and bash, with a vendored Python runtime and a few Node helpers. No SDK. No package to install. 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 →](#delivery-daemon)
> [Full walkthrough in Quick Start](docs/guides/quick-start.md)
---
## 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.
| vs. | Difference |
|-----|-----------|
| AGENTS.md / cursor rules | Solves one session. GAAI adds cross-session memory, scope authorization, and structured delivery. |
| BMAD-METHOD | 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 (GitHub) | Spec-driven pipeline (spec → plan → tasks → implement). GAAI adds governance enforcement, multi-agent delivery with QA gates, structured cross-session memory, and automated daemon delivery. |
---
## 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/ ← 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 — nothing is fetched when you install. Governance is markdown, YAML and bash: readable by humans and by any AI tool. Delivery also needs `python3` and `node` on PATH, plus the vendored PyYAML runtime shipped in `.gaai/core/vendor/` — the one binary in the tree.
---
## 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."*
Option A — Ask your AI tool to do it
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/).
Option B — CLI
```bash
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 or Codex sessions in tmux (default: 3 slots, configurable)
- Coordinates across devices via git push
- Monitors health, retries failures, archives completed work
- Runs inside a private tmux server whose socket is digest-bound to the repository, so a second checkout can never join or clobber the lifecycle
- Offers an on-demand monitoring dashboard (tmux split: daemon config + active deliveries)
**Setup (one-time):**
```bash
.gaai/core/scripts/daemon-setup.sh
```
Invoke it **directly**. `daemon-setup.sh` and `daemon-start.sh` are executables carrying a
`#!/bin/bash -p` shebang: prefixing either with a plain `bash` interpreter is refused with
`entry_authority_invalid`, because a non-privileged interpreter has already applied `BASH_ENV`
and imported exported functions before the script's first instruction. The only alternative is
an absolute, verified Bash invoked `--noprofile --norc -p