waitlist-launch — Waitlist Launch Workflow
Extracted from the fare-waitlist production deployment (2026-07, early-fare.hengshiou.com, reference implementation:
/Users/xiuxiu/Documents/Personal/1_Projects/fare-waitlist).
Core philosophy: KV is the single source of truth for the list, anti-abuse costs no KV writes, all public settings use runtime vars, no traffic before analytics, copy builds trust through anti-sales.
Three Role Files (load on demand, do not read all at once)
| File | Role | When to Read |
|---|---|---|
references/architecture.md | Information Architect | Read before starting: pre-interview checklist, six-stage flow, API/KV contract (copyable), var vs secret boundary, tool permission table, verification manual, known pitfalls |
references/copywriting.md | Marketing Specialist | Read when writing page copy, share copy, OG images, planning traffic channels: H1 pain-point formulas, lede structure, consent formula, anti-sales guidelines, channel playbook + ref attribution codes |
references/operations.md | Product Manager | Read during pre-launch verification and post-launch operations: gate checklist (must/should two levels), success vs vanity metrics, retention cadence, decision boundaries, iteration backlog template |
Execution Flow (orchestrator perspective)
- Pre-Interview: Ask the user the 9 questions from
architecture.md§1. Do not start work without answers. Special note: The community handle must be verified (grep the user's existing website source code or ask the user to confirm), do not guess using model memory. - Reconnaissance: If it's an existing repo, check with
git logfirst; verify the wrangler login account and zone permissions. - Phased Implementation (detailed steps and Done definitions in
architecture.md§2):- Phase 1: Basic site setup (Worker + assets + KV + custom domain)
- Phase 2: Resend list sync (best-effort + ops/sync idempotent backfill)
- Phase 3: Three-layer anti-abuse (honeypot → native rate limiting → Turnstile, all without KV writes)
- Phase 4: Personal brand footer (subtle, visual weight lower than CTA)
- Phase 5: Exposure layer (og:image → referral → analytics, in order, all modifying index.html)
- Phase 6: Deployment verification (smoke checklist + cache-buster)
- Copy: Use the formulas in
copywriting.mdfor each copy slot (H1/lede/bullets/consent/proof card/share phrase). The honest opt-out sentence must be real. - Launch Gate: Check off each item in
operations.md§1. If any "must" item fails, do not launch. Do not start traffic before analytics. - Post-Launch: Channels use ref codes for attribution (
copywriting.md§4), retain after the list reaches 100, show social proof count only after the threshold is met (operations.md§3).
Tasking Discipline (when multiple subagents)
- Multiple tasks modifying the same file (typical: all three exposure sub-tasks modify index.html) → dispatch sequentially, never in parallel.
- Each subagent task assignment must include: which files only to modify, Done definition, request for actual test evidence (screenshot/curl output), no commit/deploy.
- Orchestrator verifies each task's diff + visually inspects key deliverables (images must be Read-viewed), commits one by one, then does one unified deploy + online smoke test after all tasks are complete.
- Delivery report includes four things: branch, commit hash, deployed or not, worktree cleaned or not.
Manual Steps for the User (cannot be automated, notify early)
- Build Turnstile site in CF dashboard (get site key + secret)
- Build Web Analytics site in CF dashboard (get beacon token; wrangler OAuth has no RUM permission, the API cannot create it)
- Resend: Create an audience, generate a dedicated API key (don't reuse from other sites), verify sender domain DNS
- Custom domain: on first attach, may need to confirm DNS/certificate in the dashboard
Write the code with runtime vars first (/api/health dynamically supplies the frontend), then fill in vars/secret after the above credentials are ready, redeploy to take effect — no code changes needed. This prevents "waiting for credentials" from blocking development.
Most Common Pitfalls (full list in architecture.md §5.3)
- Headless Chrome for OG screenshot:
--force-device-scale-factor=1(retina produces 2x) +--virtual-time-budget=4000(wait for webfont), visually inspect the result (fallback font, title orphan). - Edge cache returning old HTML after deploy → verify with
?cb=<timestamp>. - After Turnstile is online, curl cannot test /api/join → contract tests (normal/duplicate/honeypot three cases) can only be done locally with
wrangler dev(no secret → automatic skip). - Honeypot/rate limiting return soft success but no refCode (don't give info to bots); already-on-list returns "already" + same refCode (idempotent).
- Plaintext API keys appearing in conversation/file → immediately switch to secrets.