AY Framework turns AI coding sessions into a gated, file-coordinated delivery loop

The problem is not only generating code

AI coding tools can quickly move from a vague request to a patch. The harder problem is retaining enough structure to make that work reviewable, resumable, and safe when several agents or sessions touch the same repository.

AY Framework is designed as a workflow layer for that problem. Its README describes a multi-agent framework that gives an AI coding environment a repeatable cycle: plan, build, review, test, ship, and capture what was learned. Rather than asking a developer to supervise every step, it places explicit human approval at two points: approving a plan and reviewing the resulting code.

This makes it most relevant to builders who want more than ad hoc prompts from Claude Code, or who need a documented way to coordinate AI-assisted tasks across a repository.

A router, modes, agents, tasks, and state

The project describes its architecture as seven layers. At the top, a CLAUDE.md file acts as a router: it reads project state and selects a mode, agent, and task. Modes define a cognitive stance for work such as planning, building, reviewing, QA, shipping, or retrospectives. Agents define ownership boundaries, tasks specify what to build, skills provide domain knowledge, and a tracking layer records coordination data in a .ay/ directory.

That division is practical. A planning mode is instructed to map dependencies and risks without writing code, while a build mode focuses on following a task one sub-task at a time. The framework also proposes that generated agents own specific directories. In the README example, a frontend builder owns apps/web/, an API builder owns packages/api/, and a database architect owns packages/db/.

Directory ownership is a simple answer to a common multi-agent failure mode: two workers edit overlapping files without a clear boundary. AY Framework's model is not a guarantee that conflicts cannot happen, but it gives the workflow an explicit place to declare who should modify which area.

/go is the central delivery loop

The primary interface is a /go command. Its documented sequence begins by checking for paused sessions, the task board, and existing locks. It then creates a lock, researches and plans a task, and asks a person to approve that plan.

After approval, the build phase uses typed checkpoints. Some are automated verification points; others ask a human to verify a result or make a decision. The sequence then runs a self-review, presents the code for human review, tests against the plan, records deviations and learnings, updates tracking, removes the lock, and commits the resulting state.

The important design choice is not merely that it has a review step. It is that the framework separates planning approval from code approval. That can make it easier to catch a wrong interpretation before implementation begins, while preserving a later checkpoint for inspecting the actual change.

The repository also documents individual commands for planning and task status, pausing and resuming, review, QA, shipping, learning, audits, explanations, and refactoring. These are presented as controls around the broader lifecycle rather than unrelated prompt shortcuts.

Coordination lives in the repository

AY Framework uses files, rather than an external coordination service, for its operational state. The documented .ay/tracking/ area contains a Markdown pipeline board, task lock files, handoffs between agents, agent logs, a changelog, architecture decisions, blockers, and metrics. It also stores task plans, retrospectives, session snapshots, and a JSON Lines learnings file.

The README frames Git as the synchronization layer. That choice has a useful property: workflow state can live alongside the project and be inspected through familiar repository tools. A task lock such as task-01.lock is legible without a dashboard, and a handoff or decision can be reviewed as part of the project history.

There is a tradeoff. File-based coordination depends on agents consistently honoring locks, scopes, and update conventions. The framework's value comes from the protocol it installs and asks agents to follow, not from an independent service enforcing every action.

Installation and runtime integration

The supplied package.json confirms that AY Framework is distributed as the ay-framework npm package, version 1.1.0, with an ay-framework executable mapped to bin/install.js. Its package contents include installation code, templates, hooks, documentation, and a license.

The README documents installation through npx ay-framework, including global or project-local installation choices and runtime selection. It lists Claude Code, Cursor, Windsurf, Codex, Trae, and Kiro as supported targets. For Claude Code setups, the documented installation creates or updates configuration and adds modes, commands, templates, hooks, and the .ay/ operational directory.

For existing repositories, the project says its first-contact flow analyzes the codebase and proposes agents and tasks. For empty repositories, it documents a short set of setup questions before generating a scaffold. In both cases, the README says creation waits for approval.

A workflow contract for AI-assisted work

The most useful idea in AY Framework is its attempt to make agent work observable between prompts. Tasks are dependency-ordered, plans have stated verification criteria, ownership is scoped, and work leaves behind locks, handoffs, decisions, and learnings. Those artifacts are useful even when a developer chooses not to run several agents in parallel.

Builders should inspect how these conventions fit their existing repository rules and review practices, particularly because the framework can inject configuration and create operational state. The project documents both optional and required team modes, with the required option using a PreToolUse hook to check installation.

To examine the templates, installer, and documented workflow in detail, visit MuLIAICHI/ay-framework.