---
name: website-workflow
description: A website workflow from "one-line need + reference image" to "verified live, videos delivered". A portable skill file for AI coding agents; no step moves on without evidence.
---

# Website workflow (portable edition)

By Ray Tsai. A public write-up of the workflow I use — feel free to copy it and adapt it into your own.
It contains no private paths, accounts, keys or channel identifiers; substitute your own where needed.

## Principles

1. **One writer per deliverable.** Other agents review; they never edit the same files at the same time.
2. **Done means evidence.** Screenshots, test reports, file hashes, live read-backs, delivery receipts — never "I'm done".
3. **No made-up facts.** Experience, numbers, testimonials and partners need a source; if it can't be verified, leave it out.
4. **People decide, agents execute.** The need, trade-offs, acceptance, publishing and outbound messages are authorized by a person.
5. **Safety limits.** No spending, no new accounts, no outbound messages, no private material sent to third-party generators — unless explicitly authorized.

## Stages and gates

| # | Stage | Gate (must pass to continue) | Artifact |
|---|---|---|---|
| 1 | Need + reference | The request is recorded word for word; the reference is actually downloaded and reviewed frame by frame | Frame sheet, effect map |
| 2 | Brief | Success criteria, hard limits and acceptance tests written and approved | Brief |
| 3 | Assign a writer | Exactly one writer; acknowledgement and working directory received | Assignment record |
| 4 | Design & build | All content in one config file; assets original or licensed | Source commits |
| 5 | Mobile fit | No overflow or clipping at 360/375/390/414 | Screenshots |
| 6 | Automated QA | Everything in the checklist below passes | QA report |
| 7 | Recordings | Desktop, mobile (labelled as a simulation), side-by-side with the reference | 3 videos |
| 8 | Freeze & review | Fixed commit + clean build + per-file SHA-256; reviewer checks the same version | Manifest, review |
| 9 | Publish & read back | One deployer publishes; anonymous read-back of pages, asset hashes and key text | Live verification |
| 10 | Deliver | Videos and summary sent to the agreed channel; check for duplicates first; read back attachment names and sizes | Delivery receipt |
| 11 | Iterate | Feedback goes to the same writer; repeat stages 4–10 | Revision log |

## Breaking down a reference (stage 1)

- Extract a frame every 0.5 s into a contact sheet; describe the composition, motion, rhythm and what sits in front or behind.
- Build an "effect → our content" map: what to borrow, what not to, and where your own data replaces theirs.
- Never ship the reference file itself; use your own colors, type, icons and numbers.

## Content and variants

- Copy, links and facts live in one config file (e.g. `content.ts`), with the source of each fact noted next to it.
- If you need two versions (e.g. a portfolio and a résumé), generate both from the same content plus a small "variant differences" config — never maintain two copies.
- Each version has its own canonical URL and language links; don't let one link back to the other by mistake.

## Motion

- Play only when in view; pause when off-screen or when the tab is hidden.
- Always provide static versions for `prefers-reduced-motion`, no JavaScript, and no 3D/WebGL support, with all content readable.
- Rotating or scrolling numbers need a fixed, readable text list next to them.
- Keyboard can pause and step; touch can drag; buttons are at least 44px.

## Automated QA checklist (stage 6)

- Widths 360, 375, 390, 414, 820, 1440: `scrollWidth === clientWidth`, nothing past the right edge.
- Zero console and network errors.
- Every external link actually opens (record status codes; flag social sites' anti-bot responses separately).
- Text contrast ≥ 4.5:1.
- Keyboard: skip link, focus rings, tab order.
- Reduced motion and JavaScript off: all text visible.
- No internal notes, test URLs or fake data in the build output.
- Videos: playable, expected duration and size, `preload="none"` + poster so the first screen stays fast.
- Privacy: no local paths, account IDs, keys, or private channel/message identifiers in public files.

## Recordings (stage 7)

- Record in real time with headless Chrome (e.g. a CDP screencast assembled by timestamp) — don't fake smoothness with frame-by-frame rendering.
- Desktop 1440×900; mobile 390 wide with a mobile user agent, **clearly labelled as a simulation, not a real device**.
- Comparison: reference on the left, result on the right, same height, labelled, with a link to the reference source.
- Keep each video ≤ 10 MB; encode with `-movflags +faststart` so it streams on the web.

## Freeze, publish, read back (stages 8–9)

```sh
# Per-file manifest sorted with LC_ALL=C so it's reproducible
cd dist && LC_ALL=C find . -type f | LC_ALL=C sort | sed 's#^\./##' \
  | while read f; do printf '%s  %s\n' "$(shasum -a 256 "$f" | cut -d' ' -f1)" "$f"; done > ../manifest.txt
```

- Rebuild once; the manifest hash must not change.
- Name exactly one deployer so nothing is published twice.
- After publishing, fetch pages and assets without logging in and compare hashes file by file.

## Delivering to a chat channel (stage 10)

- Before sending, check whether the same content was already sent (keep the previous receipt).
- Send once: a short summary plus the three videos (mind the channel's attachment size limit).
- Read the message back, compare attachment names and sizes, and store that as the receipt.
- Public documentation describes the mechanism only — never private channel or message IDs.

## Prompt templates

### Prompt 1: from a need to a reviewable site

```
You are the only writer for this website.
Need: <one paragraph>
Reference: <link> — download it and break it down frame by frame; list what to borrow and what not to.
Facts and assets: use only <folder or document>; if something can't be verified, leave it out.

Deliver:
1. A brief: success criteria, hard limits, acceptance tests.
2. The build: all copy and facts in one content file; two languages; every animation with reduced-motion and no-JS static fallbacks.
3. QA: no overflow at 360/375/390/414/820/1440; zero console errors; links actually open; keyboard and touch work.
4. Recordings: desktop 1440, mobile 390 (labelled as a simulation), and a side-by-side with the reference.
5. A receipt: what changed, the source of every fact, QA results, open items.

Limits: no deploying, no spending, no outbound messages.
```

### Prompt 2: revise, publish, deliver

```
Revise the same website using the feedback below (you are still the only writer):
<feedback list>

1. Attach a screenshot or test evidence for every item; rerun the full QA and recordings.
2. Freeze: commit, clean build, per-file SHA-256 manifest (sorted with LC_ALL=C).
3. Hand the same version to a reviewer; once it passes, the single deployer publishes it.
4. After publishing, read back anonymously: both language home pages, asset hashes, key text.
5. Send the desktop, mobile and comparison videos to <channel>, read back attachment names and sizes as a receipt; check first that they weren't already sent.

Report: commits, manifest, test counts, video paths, anything not yet verified.
```

## Further reading

- The full multi-agent coordination method (roles, handoffs, acceptance): https://github.com/rick-ray-wldd/orca-coordination-handbook (MIT, community material).