# ay-framework

> Agent swarm framework for Claude Code. Plan, build, review, test, ship — with human-in-the-loop gates.

**Status:** Released | **Language:** Shell | **License:** MIT
**Repo:** https://github.com/liwala/ay-framework

## The Problem

Ad-hoc prompting drifts. Agents skip planning, mix concerns, and lose context across sessions. Without a structured cycle and clear gates, you end up reviewing half-baked code instead of approving a plan you trust.

## What It Does

- Autonomous /go cycle: observe, lock, plan, build, self-review, test, learn, unlock
- Two human gates only: approve the plan, review the code
- Six cognitive modes — PLAN, BUILD, REVIEW, QA, SHIP, RETRO — never mixed
- Scoped agents that own specific directories to prevent parallel-write conflicts
- Auto-generated agents and tasks from your project structure (First Contact)
- Tracking layer: BOARD, HANDOFFS, lock files, atomic commits per task
- Six runtimes: Claude Code, Cursor, Windsurf, Codex, Trae, Kiro
- Injects into existing CLAUDE.md without overwriting your config

## Quick Start

```bash
npx ay-framework

# or skip prompts:
npx ay-framework --global --yes              # Claude Code, global
npx ay-framework --local --runtime=cursor    # Cursor, this project

# then in your agent:
"I want to build [describe your project]"   # triggers /go cycle
```