# AY Framework

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

## On Session Start

1. Read this file.
2. Resolve `.ay/` (see **.ay/ — Operational State** below).
3. Run **Self-Inventory** (the 4 questions below) before any non-trivial task.
4. If `BOARD.md` has no task rows → run **First Contact Protocol**. Otherwise load
   project context and read `BOARD.md`.
5. Read `.ay/tracking/HANDOFFS.md` (last 5 entries) and check `.ay/tracking/locks/`.
6. Determine mode / agent / task, load the mode file from `.claude/`, then start
   (or run `/go` to auto-pick a task).

## Self-Inventory — Before Every Task

Most agent failures come from **assumptions**, not complexity. Answer first:

1. **What tools do I actually have?** → check, don't assume. If a tool is missing,
   say so — don't invent workarounds.
2. **How much context is left?** → at >75%, checkpoint to `.claude/checkpoint.md`,
   summarize large results, and delegate remaining big reads.
3. **What am I NOT allowed to do?** → re-read **Build Constraints** below.
4. **What should I delegate?** → if the output would flood context you won't reuse
   (logs, searches, big file reads), spawn a subagent.

**Verify, never assume.** Read a file back after writing it; check exit codes, not
just that a command ran; run the test; re-read source before acting; search all
references before concluding "nothing else changes". For high-stakes conclusions,
spawn a subagent with only the observable state and ask it to refute you.

**Before marking done:** output exists (Read it back), it's correct (test/lint
passed), nothing else broke (searched references), and success was confirmed
directly — not inferred from the absence of an error. If uncertain, say so.

## .ay/ — Operational State

`.ay/` is the swarm's shared state: always on disk, one source of truth,
**gitignored** — it never appears in a commit or PR diff. Resolve it from any
worktree (never hardcode `$(pwd)/.ay`):

```bash
AY="$(dirname "$(git rev-parse --git-common-dir 2>/dev/null)")/.ay"
```

A `post-checkout` hook symlinks `.ay/` into new worktrees so relative paths work too.

Coordination files — **each file's own header documents its schema; read it before
writing**:

| Path | Purpose |
|---|---|
| `.ay/tracking/BOARD.md` | Kanban — source of truth for task status |
| `.ay/tracking/HANDOFFS.md` | Async agent-to-agent messages (schema-validated) |
| `.ay/tracking/BLOCKERS.md` | What is stuck and why |
| `.ay/tracking/AGENTS-LOG.md` | Append-only activity log |

Read-only references (don't restate them here): `.ay/tasks/`, `.ay/plans/`,
`.ay/learnings.jsonl`, `.ay/state.json`, `DECISIONS.md`, `CHANGELOG.md`, `METRICS.md`.

**Lock protocol — before writing any code:** check `.ay/tracking/locks/`; if a lock
for your task exists, stop and pick another. Otherwise create
`locks/task-{N}.lock` (agent + ISO timestamp), build within your scope, then delete
it. Before every commit, verify `.ay/` is not staged
(`git diff --name-only HEAD | grep '^\.ay/'`) and that your lock still exists.

## First Contact Protocol

Trigger when `BOARD.md` has no task rows — a fresh install. Do **not** rely on
`state.json` existing; the installer pre-creates it.

- **Repo has code:** silently analyze (package manifest, top-2-level structure,
  existing docs, git log), then present the stack + recommended scope-bound agents
  and ask to set up.
- **Repo empty:** ask what they're building, the tech stack, and team size; then
  propose agents plus a 5–15 task breakdown with dependencies.

Present the plan for approval **before creating anything**. After approval, generate
agents + tasks, initialize tracking, and write `.ay/state.json` with `project`,
`stack`, `initialized`, `framework_version`, `agents`, `total_tasks`.

## Modes (cognitive stances)

One stance at a time — no mixing. BUILD does not plan; REVIEW does not write new code.

| Mode | File | When |
|------|------|------|
| Plan | CLAUDE-PLAN.md | Architecture, task breakdown |
| Build | CLAUDE-BUILD.md | Write code, follow task files |
| Review | CLAUDE-REVIEW.md | Security + quality, fix-first |
| QA | CLAUDE-QA.md | Unit / integration / e2e |
| Ship | CLAUDE-SHIP.md | Deploy checklist + rollback |
| Retro | CLAUDE-RETRO.md | Metrics, patterns, improvements |

## Commands

`/go` (full autonomous cycle) · `/goal <objective>` · `/plan N` · `/task-start N` ·
`/task-done N` · `/task-status` · `/pipeline-view` · `/pause` · `/continue` ·
`/review` · `/qa` · `/ship` · `/learn` · `/verify-plan N` · `/plan-review N` · `/ayf-lint`

## The /go Cycle

`OBSERVE → LOCK → PLAN → [human approves plan] → BUILD (typed checkpoints) →
SELF-REVIEW → [human reviews code] → TEST → LEARN → UNLOCK`

The human does two things: approve the plan and review the code. Everything else is
autonomous.

## Sustained Work

For work that outlasts a single task, agents have two autonomous drivers:

- **`/goal <objective>`** — for a **big one-off objective**. It records the goal to
  `.ay/goal.md`, decomposes it into 3–8 READY tasks on the BOARD, then works them
  back-to-back (lock → build → verify → DONE → next) until all are done or the
  session ends. `/goal status` reports progress (X of Y tasks done). Use it to make
  all-day headway on a large goal without babysitting each task.
- **`/loop [interval] <command>`** — for **recurring monitoring**. It re-runs a
  command on a schedule (e.g. `/loop 5m /qa` to keep tests green, or watch a deploy).
  Omit the interval to let the model self-pace.

Rule of thumb: `/goal` drives a queue toward completion; `/loop` repeats the same
check indefinitely. Both respect the lock protocol and stop cleanly under context
pressure (`/pause` snapshots state to `.ay/sessions/` for resume).

## Hooks

Installed hooks live in `.claude/hooks/` (copied from `hooks/` by the installer) and
are wired into `.claude/settings.json`:

- **`session-start.sh`** (SessionStart) — verifies the install, loads state, throttled
  update check, and registers the context-pressure hook on first run.
- **`pre-commit-check.sh`** (PreToolUse on `git commit`) — denies commits without an
  active task lock; warns on out-of-scope staged files (scope fence).
- **`context-pressure.sh`** (UserPromptSubmit) — reads context-window usage each turn.
  At ≥60% it advises `/compact`; at **≥ the pause threshold it auto-pauses**: it writes
  a resumable snapshot to `.ay/tracking/context-snapshot-{ts}.json` (current task id,
  last completed phase, staged files, timestamp) and prints a `🛑 PAUSED` message with
  resume instructions — once per session. The threshold is configurable in
  `.ay/config.json` via `"context_pressure_threshold"` (fraction like `0.8` or a whole
  percent like `80`; default `0.8`).

All three degrade gracefully: if they can't read the signal they stay silent and never
block a prompt or a commit unexpectedly.

## Agents

Each agent owns specific directories and NEVER writes outside its scope. Agent files
in `.claude/agents/` declare: scope (dirs owned), skills (2–3 packs), shared-file
protocol, and handoff protocol.

## Working With the Human

The human tests by running the app, not reading diffs. So: ship working software;
make it run and verify before saying "done"; say what to test rather than explaining
what you did; fix errors before reporting; test the full flow; UI must look right;
use real data (never Lorem ipsum); handle empty / loading / error states.

## Build Constraints

- Lock before build; never touch a locked task.
- Never push — only commit, atomically. The human manages pushes.
- Never hallucinate APIs — verify signatures via `opensrc path <pkg>`
  (npm / PyPI / crates / GitHub) or real docs.
- Run the full build before committing; `/pause` before context dies.

## Human Guides

Offline operator docs live in `Human/` — open `Human/index.html` in any browser (no
server). Covers onboarding, autonomous mode, MCP setup, and the janitor agent.

## ETHOS

Read `ETHOS.md` for the builder philosophy behind all agent behavior.