Human Guides / Building a Large App

Building a Figma-like app
with ay-framework

What happens when a user runs npx ay-framework in an empty folder and just starts talking to Claude

Empty repo → Working app 5 agents in parallel 3× faster than sequential Human approves twice, agents do the rest
Step 1 of 6
User runs one command in an empty folder
That's it. No config files, no agents to define, no architecture to think about yet.
1

Run the installer

The user creates an empty folder and runs a single command. Claude Code is already open.

Terminal — ~/projects/my-design-tool
$ mkdir my-design-tool && cd my-design-tool
$ npx ay-framework

AY Framework v1.4.0 — Agent swarm for Claude Code
──────────────────────────────────────────────
Mode: Local (this project)

Install hooks? [Y/n]: Y

Installing...

+ CLAUDE.md (agent guide baked in)
+ 6 mode files (PLAN, BUILD, REVIEW, QA, SHIP, RETRO)
+ 20 commands (/go, /plan, /fix, /spawn, /verify-done...)
+ Tracking layer (BOARD, HANDOFFS, locks...)
+ git post-checkout hook (.ay/ worktree sync)
+ .ay/state.json initialized

At any moment, check live state with:
AY=$(dirname $(git rev-parse --git-common-dir))/.ay
cat $AY/tracking/BOARD.md
cat $AY/tracking/HANDOFFS.md

Next: open Claude Code, say what you want to build, run /go
Step 2 of 6
User just says what they want
No spec doc. No wireframes. No tech stack decision. Just a sentence.
You Build me a collaborative design tool. Think Figma but simpler — canvas, shapes, text, real-time collaboration, export to PNG.
Claude (First Contact) Got it. Let me analyse what you're asking for and propose how to structure the build.

What I understand:
— Canvas-based design editor (shapes, text, layers)
— Real-time collaboration (multiple users, same canvas)
— Export to PNG
— Web app (browser-based)

I'm going to propose 5 agents, each owning a clear slice:

🎨 canvas-agent — the drawing surface (HTML Canvas / Fabric.js)
🔧 toolbar-agent — tools panel, shape tools, text tool
🔴 collab-agent — real-time sync (WebSocket / Yjs)
📤 export-agent — PNG export, asset management
🖼️ shell-agent — app shell, routing, auth, layout

Each builds in its own isolated git branch simultaneously. Want me to set this up?
You Yes, go ahead.

← That's the only approval the human gives at this stage. Everything else is autonomous.

Step 3 of 6
Claude sets up the whole project
While the human gets a coffee, Claude creates the task board, agent definitions, and all git worktrees.
Claude (First Contact Protocol running)
✓ Detected: empty project, web app intent
✓ Chose stack: Next.js 14, TypeScript, Tailwind, Fabric.js, Yjs
✓ Created .ay/state.json

Creating 24 tasks on BOARD.md...
Task 01 — App shell + routing (shell-agent)
Task 02 — Auth (login/signup) (shell-agent)
Task 03 — Canvas setup + pan/zoom (canvas-agent)
Task 04 — Rectangle + ellipse tools (canvas-agent)
Task 05 — Text tool (canvas-agent)
Task 06 — Layers panel (toolbar-agent)
Task 07 — Toolbar: select, move, resize (toolbar-agent)
Task 08 — Color picker + fill/stroke (toolbar-agent)
Task 09 — WebSocket server (collab-agent)
Task 10 — Yjs CRDT sync (collab-agent)
Task 11 — Presence cursors (collab-agent)
Task 12 — PNG export (export-agent)
... 12 more tasks

✓ Created 5 agent definition files
✓ Created 5 git worktrees (one per agent)
✓ .ay/ symlinked in all worktrees
✓ post-checkout hook installed

⟶ Ready to spawn 5 agents. Launching...
🌿 main
conductor
~/projects/my-design-tool/
→ orchestrates, monitors, merges PRs
🌿 agent/shell
shell-agent
.claude/worktrees/shell/
→ .ay/ symlinked (shared board)
🌿 agent/canvas
canvas-agent
.claude/worktrees/canvas/
→ .ay/ symlinked (shared board)
🌿 agent/toolbar
toolbar-agent
.claude/worktrees/toolbar/
→ .ay/ symlinked (shared board)
🌿 agent/collab
collab-agent
.claude/worktrees/collab/
→ .ay/ symlinked (shared board)
🌿 agent/export
export-agent
.claude/worktrees/export/
→ .ay/ symlinked (shared board)
Step 4 of 6 — the key insight
5 real Claude processes work at the same time
Each agent is a separate Claude Code process in its own terminal window. They don't know about each other's code — they coordinate only through BOARD.md, HANDOFFS.md, and locks.
🖼️ shell-agent
agent/shell
Building: Next.js app shell, layout, routing, auth pages
WORKING · Task 01, 02
🎨 canvas-agent
agent/canvas
Building: HTML Canvas + Fabric.js, pan/zoom, shape rendering
WORKING · Task 03, 04
🔧 toolbar-agent
agent/toolbar
Building: Tool panel, select/move/resize, color picker
WORKING · Task 07, 08
🔴 collab-agent
agent/collab
Building: WebSocket server, Yjs CRDT sync, presence cursors
WORKING · Task 09, 10
📤 export-agent
agent/export
Building: PNG export pipeline, canvas-to-blob conversion
WORKING · Task 12

Conductor (the main Claude session) monitors all 5 with fleet-scan.sh every 4 minutes. If one gets blocked on a permission prompt, it answers it. If one drifts from spec, it flags it.

HANDOFFS.md — agents leaving notes for each other
[10:14] canvas-agent → toolbar-agent
Subject: Canvas element IDs — use fabric object.id not index
Detail: Fabric.js doesn't give stable array indices when objects are reordered.
I added an id generator (nanoid) to every shape on creation. Your toolbar
should target objects by object.id, not canvas.getObjects()[idx].

[10:31] collab-agent → all
Subject: Yjs doc key — use "canvas" not "document"
Detail: I initialized the Y.Doc with key "canvas". WebSocket provider
is at ws://localhost:1234. All agents syncing canvas state should use
this key. canvas-agent: I left a yjsProvider export in lib/collab.ts.

[10:45] shell-agent → canvas-agent
Subject: Canvas route is /editor/[fileId]
Detail: Auth is done. The canvas lives at /editor/[fileId]. User object
is in session.user. FileId comes from URL params. I created a stub
EditorLayout that expects a <Canvas /> component at src/components/Canvas.tsx

READY

#05Text toolcanvas-agent
#06Layers paneltoolbar-agent
#11Presence cursorscollab-agent
#13File managershell-agent

IN PROGRESS

#03Canvas + pan/zoomcanvas-agent 🔒
#07Select/move/resizetoolbar-agent 🔒
#09WebSocket servercollab-agent 🔒
#12PNG exportexport-agent 🔒

DONE

#01App shell + routing✓ merged
#02Auth✓ merged
#04Rect + ellipse✓ merged
#08Color picker✓ merged
#10Yjs CRDT✓ merged
Step 5 of 6
Human reviews once, agents fix automatically
After each major slice is built, the conductor runs /self-test and packages a review. The human opens one HTML file in a browser.
Conductor Claude Canvas slice is done. I ran self-test (11/12 checks pass — text tool cursor is misaligned). I've packaged a review with a screenshot of the canvas, the failing test, and two questions.

👉 Open review-pack-canvas.html in your browser.
You [opens browser] Looks great. The cursor thing is fine for now. Ship it.
Conductor Claude Got it. Creating PR, running drift check, merging. Starting next batch: text tool, layers panel, presence cursors — all three in parallel.

← The human's total input so far: 3 sentences. Everything else was agents.

Step 6 of 6
Working app in a fraction of the time
Here's the real difference. Sequential means tasks queue up. Parallel means walls of tasks collapse at the same time.
Traditional (one developer, sequential)
Shell
Auth
Canvas
Shapes
Text
Toolbar
Collab
Export
8 tasks end-to-end · ~16 hours
ay-framework (5 agents in parallel)
shell-agent
Shell
Auth
Files
canvas-agent
Canvas + Shapes
Text tool
toolbar-agent
Select+Color
Layers
collab-agent
WebSocket+Yjs
Cursors
export-agent
PNG Export
Same 8+ tasks · ~5 hours · 3× faster
🎨

Canvas editor

Shapes, text, layers, pan & zoom

🔴

Real-time collab

Yjs CRDT, presence cursors, WebSocket

🔐

Auth + file manager

Login, signup, files list

📤

PNG export

Canvas-to-blob, download button

✅

Self-tested

Each slice reviewed before merge

📝

Clean history

One PR per agent slice, no conflicts

TL;DR — the whole thing in one view
What the user actually does
From empty folder to working Figma-like app. Human input highlighted.
The complete flow
👤 USER: npx ay-framework # 30 seconds
👤 USER: build me a Figma-like tool # 1 sentence
🤖 CLAUDE: First Contact → 24 tasks → 5 agents → 5 worktrees
👤 USER: yes, go ahead # approval #1
🤖 AGENTS: 5 Claudes working in parallel, writing to their own branches
🤖 AGENTS: leaving HANDOFFS for each other, updating BOARD as they go
🤖 AGENTS: self-testing each slice, packaging review packs
👤 USER: looks good, ship it # approval #2 (per major slice)
🤖 CLAUDE: drift check → PR → merge → next batch of tasks
...
✓ Working Figma-like app. 5 hours. 3× faster than sequential.