A dual-agent playbook for shipping real software with AI coding agents — not another “prompt tips” page, but a single reference you can install on a repo: document schema, copy-paste prompts (builder, closeout, verifier), and failure-mode guardrails so merges stay human-gated and evidence-backed.
This repository is the open-source source for the Worksmith Labs reference site. The methodology is the product story; the code is MIT-licensed and yours to fork. The live experience is built and maintained by Brightline Labs.
| Live site | worksmithlabs.com |
| Authoritative scope & agent rules | PROJECT.md — read before opening a PR |
Repository — github.com/roymcfarland/agent_handoff_guide: git clone https://github.com/roymcfarland/agent_handoff_guide.git · Issues
Most teams don’t lack access to an AI that can write code — they lack a repeatable handoff: clear scope documents, a builder that stays in lane, and a verifier that checks against diffs and criteria instead of vibes. This site collects that workflow in one scrollable, tool-agnostic reference (no ranked “best model” drama, no SaaS signup wall).
Under the hood it’s a static React app with an optional Express shell if you want to self-host the built assets beside a tiny Node server.
The page is organized as nine sections — navigation mirrors this order:
- Overview — Framing and how the framework fits day-to-day engineering.
- Diagnosis — When ad-hoc agent use drifts and what to formalize first.
- Document schema — The handoff artifact structure agents and humans share.
- Install on repo — Dropping the framework into your tree and conventions.
- Prompt library — Scenario-oriented prompts (builder / closeout / verifier).
- Build & verify — Making “green CI” part of the contract, not an afterthought.
- Operate the framework — Cadence after the first install.
- META-PRs — Meta changes to the process itself (documented, reviewable).
- References — Curated links and papers behind verifier design, long context, and merge hygiene.
Long-form copy and prompt bodies live in client/src/lib/content.ts so UI code stays layout-focused; sections render via client/src/pages/Home.tsx and client/src/pages/sections/.
- React 19 + Vite 7 (SPA)
- wouter for routing, Tailwind CSS 4 + Radix/shadcn-style primitives for UI
- Express only as a static-file + SPA fallback for production self-host
- Vercel for the public deployment (
vercel.json+ SPA rewrites)
Full architecture, design language (“Engineer’s Notebook”), non-goals, and verifier rules for agents are in PROJECT.md.
pnpm install
pnpm devVite serves the app from client/ (see vite.config.ts for the port; default is 3000 unless something else is listening).
| Command | Purpose |
|---|---|
pnpm dev |
Local development (Vite, HMR) |
pnpm build |
Production client → dist/public + bundle server/index.ts → dist/index.js |
pnpm start |
Production server: NODE_ENV=production node dist/index.js |
pnpm preview |
Preview the built client with Vite |
pnpm check |
TypeScript (tsc --noEmit) |
pnpm format |
Prettier |
Copy .env.example to .env at the repository root (Vite reads from the root via envDir).
| Variable | Used by | Description |
|---|---|---|
VITE_SITE_URL |
index.html (build) |
Public origin without trailing slash (e.g. https://example.com). Drives rel="canonical", Open Graph / Twitter image URLs, and JSON-LD. If unset, relative paths like /og.jpg still work; set in production for strongest link previews. |
VITE_ANALYTICS_ENDPOINT |
Client | Base URL of an Umami-compatible instance, no trailing slash. |
VITE_ANALYTICS_WEBSITE_ID |
Client | Umami website ID. Both analytics vars must be set for the script to load. |
PORT |
server/index.ts |
HTTP port (default 3000). |
VITE_DEV_ALLOWED_HOSTS |
Vite dev only | Optional comma-separated extra hosts for the dev server. |
BUILT_IN_FORGE_API_URL |
Vite dev only | Optional; enables /dev-storage dev proxy in vite.config.ts. |
BUILT_IN_FORGE_API_KEY |
Vite dev only | Bearer token paired with the forge URL above. |
For pnpm start, NODE_ENV=production applies and Express serves dist/public next to dist/index.js.
vercel.json sets install/build commands, outputDirectory to dist/public, and SPA rewrites to index.html. Run pnpm run build so client output lands there. Set VITE_SITE_URL on the project so Open Graph, Twitter Cards, and the canonical URL use absolute links. Analytics env vars, if used, need the VITE_ prefix in Vercel.
| Path | Role |
|---|---|
client/src/ |
React app, routes, UI |
client/src/lib/content.ts |
Guide copy, prompts, structured section data |
client/src/components/diagrams/ |
SVG figures and shared diagram shell |
client/public/og.jpg |
Social preview image (Open Graph / Twitter, 1200×630) |
server/index.ts |
Static files + SPA fallback |
shared/ |
Shared types/modules |
dist/public/ |
Vite build output (gitignored) |
The inline boot script in client/index.html and client/src/contexts/ThemeContext.tsx both use the localStorage key theme (light | dark | system / absent for system). Keep them aligned if you change how themes stick.
Intent, out-of-scope work, and agent precedence live in PROJECT.md. If something in this README disagrees with PROJECT.md, trust PROJECT.md and fix the drift in the same PR.
MIT — see LICENSE. Copyright (c) 2026 Roy McFarland.