ay-framework — Human Guide

New here?

Start here — 5 steps to your first agent swarm

From empty folder to working app with parallel agents. ~15 minutes of setup, then agents do the rest.

1

Install the framework

Run in your project folder (new or existing).

$ npx ay-framework

2

Set up MCPs so agents can test autonomously

Without MCPs, agents only write code. With MCPs they test login flows, call APIs, verify database state, send emails. One-time setup. → MCP Setup Guide

3

Tell Claude what you want to build

Open Claude Code in your project. Say what you want — one sentence. The operator handles breakdown, agent spawning, and coordination. → See how it works

4

Answer plan-phase questions once

Framework, database, auth, real-time, deploy target. All decisions go into DECISIONS.md — no agent ever asks you the same thing twice. → See the plan flow

5

Step away — agents work autonomously

Agents build, test with MCPs, self-verify, write reports. Come back to ready-to-review PRs. → Understand autonomous mode

The honest question

If agents can build anything on their own — why do you need to be here?

Agents know how. Only you know what and whether.

🎯

You decide what gets built

Agents execute tasks with precision. But which tasks matter — which features move the needle, which problems are worth solving — is a judgment call that requires knowing your users, your market, your instincts. Agents have no skin in the game.

✦

You are the taste

An agent can generate a thousand UIs. It cannot tell you which one feels right. Aesthetic judgment, brand voice, the instinct that something is off — these are yours. They are not transferable to a model.

⚖️

You carry the accountability

When a feature ships broken, when a customer is hurt, when something goes wrong — you answer for it. Agents don't. That accountability is the engine behind good judgment. It's also why you can't fully outsource decisions.

🔮

You see the future they can't

Agents are brilliant at the present task. You are the one who knows where this needs to go in six months — what constraints are coming, which technical debt will bite, what the user actually wants versus what they asked for. Vision is yours.

The goal of ay-framework is not to replace you. It is to make you 10× more effective by handling every part of the work that doesn't require being you.

All Guides

Everything in one place

Open any file directly — all work offline.

Read this first

🚀

Onboarding

Your role, what was installed, how to pick a session manager, and a step-by-step checklist to go from zero to first agent swarm.

New usersSetupYour role

Required for auto-testing

🔌

MCP Setup

Give agents the ability to test UIs, call APIs, verify DB state, and send emails. One-time setup that unlocks full autonomous operation.

PlaywrightHTTPSupabaseEmail

Step away safely

🤖

Autonomous Mode

What happens when you walk away. How agents test their own work, what they write when stuck, and how you review on return.

Self-testingReportsBlockers

Common first project

🗄️

Supabase Setup

Connect your Supabase project in under 5 minutes. Credentials, type generation, and how agents verify their own DB writes.

Operator dispatching tasks to agents in their own terminals. Error handling, verifier agents, drift detection — all visual.

Agents lie about being done. Janitor checks actual commits, corrects BOARD.md, flags false-done tasks.

BOARD.mdDriftVerification

Big picture

🏗️

Building a Large App

Figma-like app from empty repo using 5 parallel agents. Shows the full orchestration and 3× speedup vs sequential.

ExampleParallelWorktrees

With MCPs installed

What agents verify without asking you

Each MCP unlocks a category of autonomous testing. Agents use these to confirm their own work actually works before reporting done.

Playwright MCP

UI Testing

Agent navigates to /login, fills email+password, submits, verifies redirect to /dashboard. Confirms button states, error messages, responsive layout.

Playwright MCP

Form Flows

Agent fills signup form with real data, submits, checks confirmation, clicks verify link, confirms account active.

HTTP / Bash

API Endpoints

Agent calls POST /api/users, verifies 201 response, checks schema, confirms idempotency on second call returns 409.

Supabase MCP

Database State

After writing a user, agent queries the DB to confirm the row exists with correct values — not just "the insert ran."

Mailpit (local)

Email Delivery

Agent triggers password reset, reads inbox via API to confirm email arrived, subject is correct, link in body is valid.

Supabase MCP

Auth Verification

Agent checks auth.users after signup to verify user was created, email confirmed, metadata fields set correctly.