# HANDOFF PROTOCOL — the contract for passing work between "owner" and "developer"
> This is the heart of the whole system. Every skill in this pipeline exists to make this two-way handoff smooth.
---
## The problem this solves
**The old way:** the owner has a picture in their head -> can't describe it well -> waits on UX/UI design -> waits on a dev to build a prototype -> sees it, it's not right -> loops back. Weeks lost.
**The new way:** the owner can vibe it themselves, see it working within the hour, edit it themselves.
But the **backend** (database, API, security, going live) still needs a developer.
So this system doesn't remove the developer — it makes **the line clear**, and **standardizes what crosses that line**.
---
## Where the responsibility line sits
| Owner side (can do it themselves) | Developer side (must be handed off) |
|---|---|
| Look, button placement, colors, copy | Connecting a real database |
| Screen order, usage flow | API / integrating with other systems |
| Sample (mock) data | Login and user permissions |
| Business rules ("turn red if over 30 days") | Security - real customer data |
| Trying out adding/moving/removing a button | Going live (deploy) - backups |
**Hard rule:** the owner can edit anything **visible** - the dev owns everything **invisible**.
---
## Direction 1 — Owner -> Developer
Invoked via the `/app-send` skill. The output is a zipped **Handoff Package**.
```
handoff-{project-name}-{YYYY-MM-DD}.zip
├── README-สำหรับนักพัฒนา.md <- read this first — summarizes what to do next
├── HISTORY.md <- the decision trail: what changed, why, who asked
├── prototype/ <- what the owner built
│ ├── index.html <- viewer only: device-frame shell for browsing screens, not the product
│ ├── screens.json <- screen list + order (present once the shell layout is used, 2+ screens)
│ ├── screens/ <- the actual designed screens — this is what the dev builds on
│ ├── shared/ <- style.css / layout.js / ui.js — shared look and behaviour used by every screen
│ ├── data/mock-data.json <- sample data — the dev builds the real schema from this
│ ├── LEVEL.md <- which level was reached, approved by whom and when
│ ├── screenshots/ <- 375px and 1280px evidence from level-4 testing
│ ├── README.md <- how to open the prototype (see condition 5 below)
│ └── เปิดดู.command <- double-click to open in a browser automatically (macOS)
├── SPEC.md <- what's needed, written in plain language
├── DATA.md <- data used: what fields, sample values
├── RULES.md <- every business rule (conditions, calculations, permissions)
├── TODO-DEV.md <- the backend work list for the dev, each item with a reason
└── OPEN-QUESTIONS.md <- what's still unclear/unconfirmed (never filled in with a guess)
```
`screens.json`, `screens/`, and `shared/` only exist when the prototype used the shell layout (2+ screens, per `PROJECT-STRUCTURE.md` section 3) — a single-screen prototype has no shell and `index.html` alone is the product.
**Conditions before sending (incomplete = not ready to send):**
1. The prototype opens and shows the real thing, not just a description of it.
2. Every item in `TODO-DEV.md` states **why it needs a dev** (what the owner specifically can't do themselves and why).
3. `OPEN-QUESTIONS.md` contains only genuinely unknown items — never filled in with a guessed answer. Every item must be traceable to the actual conversation with the owner: something the owner explicitly said they didn't know, or a decision that came up and was left unsettled. If the assistant believes something important was never raised at all, it does not belong in `OPEN-QUESTIONS.md` — it goes in a separate, clearly-labelled section headed `ข้อเสนอให้พิจารณา (ยังไม่เคยคุยกัน)`, so the developer can tell a genuine open question from an assistant-invented suggestion at a glance.
4. No real customer data, passwords, or keys of any kind are anywhere in the package.
5. `prototype/README.md` must instruct opening the prototype through a local server, or by double-clicking `เปิดดู.command` — it must never tell the developer to open `prototype/index.html` (or any screen file) directly by double-clicking the HTML. From level 3 onward the prototype loads `data/mock-data.json` via `fetch()`, which browsers block under `file://`, so opening the file directly renders a blank screen with no explanation.
---
## Direction 2 — Developer -> Owner
Invoked via the `/handback-to-owner` skill. The output is a zipped **Return Kit**.
```
return-{project-name}-{YYYY-MM-DD}.zip
├── README-สำหรับเจ้าของงาน.md <- plain language, no dev jargon: what was done, what can still be edited
├── app/ <- what remains editable, marked แก้ได้:/ห้ามแก้: in the code
├── รายงานตรวจสอบ.md <- findings from /security-review + /bug-hunt (plain language)
├── แก้ตรงไหนได้บ้าง.md <- self-edit guide: which line has the color, text, buttons
└── CHANGELOG.md <- what the dev changed from the original, and why
```
**Marking rule for code in the returned package** — so the owner feels safe editing it:
```html
```
**Conditions before returning:**
1. Has passed `/security-review`, with no outstanding "critical" findings.
2. Every block in the returned files carries an แก้ได้ or ห้ามแก้ marker — no exceptions.
3. `README-สำหรับเจ้าของงาน.md` contains no unexplained technical jargon.
4. Opening the file makes it work for real, with nothing extra for the owner to install.
---
## The full cycle (loops indefinitely)
```
Owner (sees only 3 commands) Developer
────────────────────────── ─────────────
/app-brief AI asks, owner answers -> BRIEF.md
/app-show sees the real thing + edits it themselves
│
├──── /app-send ────► 1-build connect DB / API / MCP / AI
│ 2-verify security + bug hunt + test
│ 3-deploy go live
│ 4-operate monitor + write the runbook
◄──── /handback-to-owner ───┤
│
/app-show keeps editing (colors, copy, buttons)
If it touches something marked ห้ามแก้ -> loop back to /app-send again
```
---
## Rules that prevent things from breaking (the most expensive lessons learned)
1. **Never send work that hasn't been seen rendered** — a description alone always gets misread.
2. **Never guess on someone else's behalf** — if something's unclear, write it into `OPEN-QUESTIONS.md` and ask, don't fill it in yourself.
3. **Never send real data across the line** — the prototype uses sample data only.
4. **A returned package must be genuinely self-editable** — if the owner opens it and is afraid to touch anything, the dev's work isn't actually done.
5. **One package = one topic** — never stuff three features into one package; it becomes unreviewable and the edit loop never ends.