https://github.com/Fr-e-d/GAAI-framework
Turns AI coding tools into reliable software delivery systems. Drop a .gaai/ folder into any project — Discovery defines what to build, Delivery executes autonomously until criteria pass. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and more. No SDK. No package. Markdown + YAML + bash.
https://github.com/Fr-e-d/GAAI-framework
agentic-coding ai-agents ai-coding ai-developer-tools ai-governance ai-memory-system autonomous-agents claude-code codex-cli context-engineering cursor devtools gemini-cli opencode vibe-coding windsurf
Last synced: 7 days ago
JSON representation
Turns AI coding tools into reliable software delivery systems. Drop a .gaai/ folder into any project — Discovery defines what to build, Delivery executes autonomously until criteria pass. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and more. No SDK. No package. Markdown + YAML + bash.
- Host: GitHub
- URL: https://github.com/Fr-e-d/GAAI-framework
- Owner: Fr-e-d
- License: other
- Created: 2026-02-07T16:24:30.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T19:53:27.000Z (7 days ago)
- Last Synced: 2026-04-19T21:34:15.861Z (7 days ago)
- Topics: agentic-coding, ai-agents, ai-coding, ai-developer-tools, ai-governance, ai-memory-system, autonomous-agents, claude-code, codex-cli, context-engineering, cursor, devtools, gemini-cli, opencode, vibe-coding, windsurf
- Language: Shell
- Homepage:
- Size: 4.25 MB
- Stars: 127
- Watchers: 2
- Forks: 27
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code-toolkit - GAAI Framework - in governance layer (.gaai/ folder) -- backlog authorization, cross-session memory, decision tracking, QA gates, autonomous delivery daemon. Claude Code + Cursor + Codex CLI + Gemini CLI | (Ecosystem / Quick Setup with cc-safe-setup)
README
# 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 →](#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/ ← 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."*
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 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
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:
| Tool | Adapter |
|------|---------|
| Claude Code | `CLAUDE.md` + `.claude/commands/` |
**AGENTS.md compatible** — full GAAI capability via manual activation prompts:
| Tool | Adapter |
|------|---------|
| OpenCode | `AGENTS.md` |
| Codex CLI | `AGENTS.md` |
| Gemini CLI | `AGENTS.md` |
| Antigravity | `AGENTS.md` |
| Cursor | `.cursor/rules/*.mdc` |
| Windsurf | `AGENTS.md` |
| Any other | Read `.gaai/core/README.md` directly |
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](docs/reference/tool-compatibility.md)
---
## 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 agent following the files. There is no programmatic enforcement.
- The repo is freshly open-sourced. Community is just getting started.
---
## Documentation
- [Quick Start](docs/guides/quick-start.md) — first working Story in 30 minutes
- [What is GAAI?](docs/01-what-is-gaai.md) — the problem in full
- [Core Concepts](docs/02-core-concepts.md) — dual track, backlog, memory, skills, artefacts
- [Vibe Coder Guide](docs/guides/vibe-coder-guide.md) — fast daily workflow
- [Senior Engineer Guide](docs/guides/senior-engineer-guide.md) — governance, rules, CI
- [Skills Index](.gaai/core/skills/README.skills.md) — all 47 skills
- [Tool Compatibility](docs/reference/tool-compatibility.md) — Claude Code, OpenCode, Codex CLI, Gemini CLI, Antigravity, Cursor, Windsurf
- [Design Decisions](docs/architecture/design-decisions.md) — why GAAI is structured the way it is (ADRs + research basis)
---
ELv2 — see [LICENSE](LICENSE)
---
## Support This Project
If you find this framework valuable, please consider showing your support:
- **[Sponsor on GitHub](https://github.com/sponsors/Fr-e-d)**
---
Created by [Frédéric Geens](https://www.linkedin.com/in/fr%C3%A9d%C3%A9ric-geens-04162233/)