AY Framework - Agent Swarm for Claude Code

Multi-agent swarm framework for Claude Code.
Plan, build, review, test, ship -- with human-in-the-loop gates.

Stars Forks MIT License Release Cross-platform

Install /go Modes Runtimes


## What is this? AY Framework gives Claude Code a **structured brain** for building software. Instead of ad-hoc prompting, your AI agent follows a disciplined cycle: plan the work, build it, review it, test it, ship it -- with you approving only two things: **the plan** and **the code**. Everything else is autonomous. ``` You say: "Build a user authentication system" Claude: 1. Analyzes your codebase 2. Proposes agents (api-builder, db-architect, web-builder) 3. Creates 8 dependency-ordered tasks 4. Asks you to approve the plan <-- Gate 1 5. Builds task by task, commits atomically 6. Self-reviews for security + quality 7. Shows you the code <-- Gate 2 8. Tests, learns, moves to next task ``` Built by [AY Automate](https://ayautomate.com). Inspired by [gstack](https://github.com/garrytan/gstack).
## Install One command: ```bash npx ay-framework ``` Interactive prompt asks which runtime and where to install: ``` Which runtime? 1) Claude Code (~/.claude) 2) Cursor (~/.cursor) 3) Windsurf (~/.windsurf) 4) Codex (~/.codex) 5) Trae (~/.trae) 6) Kiro (~/.kiro) ``` Or skip prompts: ```bash npx ay-framework --global --yes # Claude Code, global, no prompts npx ay-framework --local --runtime=cursor # Cursor, this project only ``` Or clone and run setup: ```bash git clone https://github.com/walidboulanouar/ay-framework.git ~/.claude/skills/ay-framework cd ~/.claude/skills/ay-framework && ./setup ``` **What happens:** 1. Interactive prompt: **global** (`~/.claude`) or **local** (`./.claude`) 2. If `CLAUDE.md` exists: **injects** AY Framework section (never overwrites your config) 3. Installs 6 modes, 27 commands, tracking layer, templates, hooks 4. Creates `.ay/` directory for framework operational state **After install**, open Claude Code and say: > "I want to build [describe your project]" Claude analyzes your codebase (or asks questions if empty), generates agents and tasks, and the `/go` cycle begins.
## How It Works ### The 7-Layer Architecture ``` CLAUDE.md (the router) | reads project state, picks mode + agent + task | +-------------+-------------+ | | | MODE AGENT TASK (how to (what to (what to think) touch) build) | | | +-------------+-------------+ | SKILLS (domain knowledge) | TRACKING (BOARD, HANDOFFS, locks) | .ay/ (state + learnings) ``` ### The /go Cycle The main command. Fully autonomous except for **two human gates**. ``` OBSERVE ---- check for paused session, read BOARD, check locks | LOCK ------- create lock file, commit (prevents conflicts) | PLAN ------- research task, create plan folder, verify 8 dimensions | [HUMAN APPROVES PLAN] << Gate 1 | BUILD ------ follow sequence with typed checkpoints | [auto] = agent verifies itself | [human-verify] = shows result to you | [decision] = you pick the approach | SELF-REVIEW - fix mechanical issues, ask about hard ones | [HUMAN REVIEWS CODE] << Gate 2 | TEST ------- verify against plan + run suite | LEARN ------ capture deviations, gotchas, skill updates | UNLOCK ----- update tracking, delete lock, commit ``` **Human does two things: approve the plan, review the code.** Everything else is autonomous.
### Modes Six cognitive stances. Each mode changes **how** the agent thinks. No mixing. | Mode | File | Cognitive Stance | |:-----|:-----|:----------------| | **PLAN** | `CLAUDE-PLAN.md` | Expansive thinking. Map dependencies. Find risks. No code. | | **BUILD** | `CLAUDE-BUILD.md` | Focused execution. Follow task file. One sub-task at a time. | | **REVIEW** | `CLAUDE-REVIEW.md` | Paranoid. Find bugs and security holes. Fix-first. | | **QA** | `CLAUDE-QA.md` | Systematic. Diff-aware tests. Health score computation. | | **SHIP** | `CLAUDE-SHIP.md` | Checklist execution. Deploy, verify, rollback plan. | | **RETRO** | `CLAUDE-RETRO.md` | Data-driven. Metrics from git. Patterns. Improvements. | ### Agents Each agent owns **specific directories** and never writes outside its scope. This prevents conflicts when multiple agents work in parallel. ``` .claude/agents/ frontend-builder.md -- owns apps/web/ api-builder.md -- owns packages/api/ db-architect.md -- owns packages/db/ qa-tester.md -- owns test files only ``` Agents are generated automatically during **First Contact** based on your project structure. Or add them manually: ```bash ayf add agent api-builder packages/api/ ayf add agent web-builder apps/web/ ``` ### Commands | Command | What it does | |:--------|:-------------| | **`/go`** | **Full autonomous cycle** -- the main one | | `/goal ` | Sustained all-day work: decompose one objective into tasks, work them back-to-back | | `/plan N` | Plan task N with full research | | `/plan-review N` | Compound plan review: CEO-scope > design sanity > engineering, one human gate | | `/task-start N` | Start building task N | | `/task-done N` | Mark task N complete | | `/task-status` | Show all tasks with progress | | `/pipeline-view` | ASCII kanban board | | `/pause` | Save state for session handoff | | `/continue` | Continue from paused session | | `/review` | Code review (fix-first) | | `/review-pack N` | Generate an HTML review pack with screenshots + guided questions | | `/self-test N` | Walk `tests.md` via browser automation, write findings | | `/qa` | Run tests (diff-aware) | | `/ship` | Deploy with checklist | | `/learn` | Capture a learning | | `/verify-plan N` | 8-dimension plan quality check | | `/verify-done N` | Diff actual files vs task spec, score completeness | | `/fix` | Investigate + fix a bug (root cause > fix > verify > prevent) | | `/scaffold` | Generate boilerplate matching your project's patterns | | `/audit` | Security + performance + quality audit with severity report | | `/explain` | Explain code, architecture, or generate documentation | | `/refactor` | Safe refactoring with tests passing before and after | | `/spawn` | Launch sub-agents in isolated cmux workspaces | | `/ayf-brain` | Search learnings + DECISIONS + HANDOFFS (SQLite FTS) | | `/ayf-lint` | Warn when `CLAUDE.md` exceeds its size budget | | `/context-router` | Detect session signals and surface the right command | **27 commands that cover what others need 66+ for.** Each command is a compound workflow, not a single action. ### Tracking All coordination is **file-based**. No external tools. Git is the sync layer. ``` .ay/ tracking/ BOARD.md Pipeline kanban (BACKLOG > READY > IN PROGRESS > DONE) locks/ File-based mutex (task-01.lock = task is taken) HANDOFFS.md Agent-to-agent async messages AGENTS-LOG.md Who did what, when CHANGELOG.md What shipped DECISIONS.md Architecture Decision Records BLOCKERS.md What is stuck METRICS.md Sprint velocity plans/ Per-task plan folders retros/ Sprint retrospectives tasks/ Dependency-ordered task files ```
## First Contact When you first open Claude Code after installing, the framework detects whether your repo has code or is empty. **Existing repo:** Claude silently analyzes your stack, structure, and git history, then proposes agents and tasks tailored to your project. **Empty repo:** Claude asks three questions (what are you building, what tech stack, solo or team) and generates a full scaffold. Either way, nothing is created until you approve.
## Team Mode For shared repos where everyone should use the framework: ```bash # Recommended (gentle suggestion in CLAUDE.md) ./setup --team optional # Required (blocks Claude Code if framework not installed) ./setup --team required ``` Required mode creates a `PreToolUse` hook that checks for the framework on every session. If a teammate doesn't have it installed, Claude stops and tells them how to install.
## CLI The `ayf` CLI manages the framework after install: ```bash ayf init [flags] # Install into a project (--local --global --yes --runtime=) ayf scan # Scan project: stack, tools, config, suggestions ayf status # Components, pipeline, agents ayf doctor # Health check -- find missing files ayf add agent # Add a new agent definition ayf add skill # Add a new skill pack ayf add task # Add a new task file ayf upgrade # Update modes + commands to latest ayf release <bump> # Cut a release: bump, changelog, smoke, tag, publish ayf version # Show version ``` <br/> ## File Structure After install, your project has: ``` your-project/ CLAUDE.md # Router (the brain) Human/ # Offline HTML documentation index.html # Getting started + theme toggle onboarding.html # Session manager tiers + first-contact checklist setup-mcps.html # MCP server configuration autonomous-mode.html # /go cycle deep-dive janitor-agent.html # Background cleanup agent .ay/ # Framework operational state state.json # Project metadata tracking/ # BOARD, HANDOFFS, locks plans/ # Per-task plan folders retros/ # Sprint retrospectives tasks/ # Task files sessions/ # Pause/resume snapshots learnings.jsonl # Cross-session learnings ETHOS.md # Builder philosophy .claude/ # Claude Code integration CLAUDE-PLAN.md # 6 cognitive modes CLAUDE-BUILD.md CLAUDE-REVIEW.md CLAUDE-QA.md CLAUDE-SHIP.md CLAUDE-RETRO.md agents/ # Agent definitions commands/ # 27 slash commands skills/ # Domain knowledge packs hooks/ # Optimization hooks ``` <br/> ## What AY Framework has that gstack doesn't [gstack](https://github.com/garrytan/gstack) by Garry Tan is excellent for single-agent workflows -- code review, QA, shipping. AY Framework builds on that foundation and adds everything needed for **multi-agent project lifecycles**. ### Multi-Agent Swarm with Scoped Ownership gstack runs one agent at a time with different skills. AY Framework runs **multiple agents in parallel**, each owning specific directories. A `frontend-builder` never touches `packages/api/`. A `db-architect` never writes React components. Scope boundaries prevent conflicts automatically. ### Task Dependency Graph No task system in gstack. AY Framework has **dependency-ordered task files** with a full pipeline: ``` Task 01 (Foundation) ──> Task 02 (Schema) ──> Task 06 (Services) ──> Task 07 (CLI) └──> Task 03 (Clients) ──┘ └──> Task 08 (MCP) └──> Task 09 (Web Auth) ──> Task 10 (UI) ``` Tasks have clear inputs, outputs, verification criteria, and unblock relationships. Agents self-organize via the dependency graph -- no coordinator needed. ### File-Based Coordination Layer ``` .ay/tracking/ BOARD.md -- who is doing what (kanban) locks/ -- mutex: task-03.lock means "taken by api-builder" HANDOFFS.md -- async messages between agents DECISIONS.md -- architecture decision records BLOCKERS.md -- what is stuck and who owns it METRICS.md -- velocity tracking ``` gstack has learnings. AY Framework has a full coordination protocol: lock before build, write handoffs, update the board, log decisions. ### Human-in-the-Loop Gates gstack skills run autonomously. AY Framework's `/go` cycle has **two mandatory human gates**: 1. **Plan approval** -- Claude presents the plan, you say "go" or "change X" 2. **Code review** -- Claude presents the output, you say "ship" or "fix X" Everything between the gates is autonomous. You control the what, Claude handles the how. ### First Contact Protocol gstack lists available skills. AY Framework **analyzes your codebase** on first run: - Detects language, framework, tech stack - Maps directory structure - Reads git history for contributors - Proposes agents tailored to your project - Generates initial task breakdown For empty repos, it asks three questions and scaffolds everything. ### Plan Verification (8 Dimensions) Before any build starts, the plan is verified across 8 dimensions: 1. **Requirement coverage** -- every objective maps to a step 2. **Task atomicity** -- no step creates more than 5 files 3. **Dependency ordering** -- no forward references 4. **File scope** -- all files within agent's scope 5. **Test mapping** -- every requirement has a test 6. **Context fit** -- plan folder under 2000 lines 7. **Gap detection** -- no missing exports or error handling 8. **Rules compliance** -- all universal rules present If any dimension fails, the plan is fixed before execution. ### Self-Learning via Diff-from-Plan After every task, Claude compares what was planned vs what was actually built. Deviations are logged with reasons, impacts, and learnings. These compound across sessions -- future agents inherit the knowledge. ### Full Comparison | Feature | gstack | ay-framework | |:--------|:-------|:-------------| | Agent model | Single agent, skill switching | Multi-agent swarm, scoped ownership | | Coordination | None | BOARD + locks + HANDOFFS | | Task system | None | Dependency graph with ordered tasks | | Human gates | None | Plan approval + code review | | First contact | Lists skills | Analyzes codebase, generates setup | | Plan quality | None | 8-dimension verification | | Learning | Learnings file | Diff-from-plan + retro + learnings | | Session handoff | None | /pause + /continue with full context | | Retro | Basic retro skill | Data-driven: git metrics, JSON trends | | Deployment | /ship skill | Full checklist + rollback + monitoring | | CLI | None | ayf init, scan, status, doctor, upgrade, release, add agent/skill/task | | Team mode | Hook-based enforcement | Hook-based + CLAUDE.md injection | Both tools are complementary. You can use gstack's `/review` and `/qa` alongside AY Framework's lifecycle management. <br/> ## What AY Framework has that GSD doesn't [Get Shit Done](https://github.com/gsd-build/get-shit-done) (GSD) is a great collection of 66 commands across 15 runtimes. AY Framework takes a different approach -- fewer commands, deeper architecture. ### Structured Build Lifecycle vs Command Library GSD gives you 66 individual commands (`/gsd-add-tests`, `/gsd-refactor`, `/gsd-debug`, etc.). Each runs independently. AY Framework gives you **one cycle** (`/go`) that chains planning, building, reviewing, testing, and learning into a single autonomous loop. The 27 commands exist to control that cycle, not to be used in isolation. ### Multi-Agent Architecture vs Single-Agent Commands GSD commands run in one agent context. AY Framework creates **scoped agents** -- each owns specific directories, loads specific skills, and coordinates with other agents via file-based locks and handoffs. Two agents can work on different parts of the codebase simultaneously without conflicts. ### Task Dependency Graph GSD has no task system. AY Framework manages **dependency-ordered tasks** with a pipeline board. Tasks have explicit dependencies, verification criteria, and unblock relationships. The framework knows task 06 can't start until tasks 02, 03, 04, and 05 are done. ### Plan-Before-Build with Verification GSD commands execute immediately. AY Framework **plans first**: researches the task, gathers API docs, creates a plan folder with sequence, rules, tests, and schema files. Then verifies the plan across 8 dimensions before a single line of code is written. You approve the plan before build starts. ### .ay/ Operational State GSD installs commands and that's it -- no persistent state between sessions. AY Framework maintains `.ay/` with tracking (BOARD, HANDOFFS, locks), plans, retros, tasks, learnings, and session snapshots. Context carries across sessions. Pick up exactly where you left off with `/continue`. ### Data-Driven Retrospectives GSD has no retro system. AY Framework's **RETRO mode** computes metrics from git history -- commits, files changed, test ratio, health score, blockers hit, deviations from plan. Outputs both JSON (for trend tracking) and markdown (for humans). Compares against previous retros to show improvement or regression. ### Comparison Table | Feature | GSD | ay-framework | |:--------|:----|:-------------| | Commands | 66 individual commands | 27 compound commands (each replaces 3-5) | | Architecture | Flat command library | 7-layer swarm (router > mode > agent > task > skill > tracking > state) | | Agent model | Single agent | Multi-agent with scoped ownership | | Task management | None | Dependency graph + pipeline board | | Planning | None (execute immediately) | Plan folder + 8-dimension verification | | Human gates | None | Plan approval + code review | | State persistence | None | .ay/ with tracking, plans, retros, learnings | | Session handoff | None | /pause + /continue with full context | | Coordination | None | Locks + HANDOFFS + BOARD | | Retro | None | Git-based metrics, JSON trends | | First contact | Lists commands | Analyzes codebase, generates agents + tasks | | Runtime support | 15 runtimes | 6 runtimes (Claude, Cursor, Windsurf, Codex, Trae, Kiro) | AY Framework covers the same breadth with fewer, smarter commands -- and adds depth that flat command libraries can't match. <br/> ## Human Guides After running `npx ay-framework`, a `Human/` directory is installed in your project with offline HTML documentation. Open it in any browser — no internet required. ```bash open Human/index.html # macOS xdg-open Human/index.html # Linux ``` The guides cover: | Guide | What it covers | |:------|:---------------| | **Onboarding** | Getting started, session manager tiers (cmux / Codex app / tmux / iTerm2) | | **MCP Setup** | Connecting MCP servers, tool permissions | | **Autonomous Mode** | How `/go` works, the two human gates, when to intervene | | **Janitor Agent** | Background cleanup tasks, lock recovery, drift detection | The index page includes a **light/dark theme toggle** and a "why you matter" section on the philosophy behind human-in-the-loop design. All docs are self-contained HTML — no build step, no dependencies, no network calls. <br/> ## Requirements - **Claude Code** (any version) - **Git** (for tracking coordination) - **Node.js 18+** (only for the `npx` install path -- bash `./setup` works without it) Works on **macOS**, **Linux**, and **Windows** (Git Bash / WSL). <br/> ## Contributing 1. Fork the repo 2. Create a feature branch 3. Make your changes 4. Submit a PR We welcome contributions to modes, commands, templates, and documentation. ## License [MIT](LICENSE) -- AY Automate