What the site machine is
A Claude Code plugin that refuses to let a website ship until the process that built it has been proven. It is for anyone who builds small sites with an AI agent and wants them accessible, fast and honest — without taking the agent's word for it.
Why it matters
An agent that builds a site will also tell you the site is fine. It reports a Lighthouse score it never measured. It says the legal page exists when it does not. It skips the guidance it was told to read, and the result still looks finished.
Checking the finished page does not catch this. A page can pass every check and still come from a skipped process. The site machine checks the process instead: which steps ran, in what order, with what evidence on disk.
What this unlocks: you can let an agent build a whole site and trust the outcome, because the trust does not rest on the agent.
The one idea
The site machine is a gate: a list of steps in a fixed order, where each step closes only when code has verified evidence on disk — and the agent that wrote the site is never the one that certifies it.
Everything else on these pages elaborates that sentence. When lost, come back to it. Three consequences follow directly:
- Order is code. A file called
workflow.yamllists the steps and which ones must finish first. A command reads it and says what may happen next. - Verdicts are code. Each step names exit predicates (that is: small programs that answer yes or no about the site). A step closes only when all of them say yes.
- Refusals stop everything. When a predicate says no, the run halts (that is: enters a stopped state that blocks later steps and deploys until the failing step passes).
The closed loop. The actor and the gate are different programs; the gate never trusts the actor's report.
The parts, named
Seven things make up the machine. Each gets a page later; here they are in one list so the names are familiar.
| Part | What it is | Where |
|---|---|---|
| Workflow | The pipeline as a DAG (that is: steps with "must come after" arrows and no loops). 15 steps. | workflow.yaml |
| Gate | The command that reads the workflow, runs predicates and closes or halts steps. | tools/site-step.mjs |
| Predicates | 23 programs that each check one thing about the site: contrast, console errors, headers, legal texts, and so on. | tools/predicates/ |
| Actors | The seven Claude Code skills that do the creative work: brief, design, scaffold, review, jury, legal, publish. An eighth skill, Modern Web Guidance, is reference material they consult. | .claude/skills/ |
| Hooks | Two scripts, registered three times, that Claude Code runs around tool calls: one records what happened, one denies deploys during a halt and announces open runs. | hooks/hooks.json |
| Ledger | An append-only log of tool calls per site. Some predicates are proved from it, never from a claim. | <site>/run-log.jsonl |
| Receipt | A record written only by a real Lighthouse run. Publishing needs one newer than the last edit. | <site>/.claude/state/receipt.json |
Two more things sit beside the machine. patterns/ holds 656 UX checks, of which 31 dark and legal patterns are a hard fail. budgets.json holds the quality bar: Lighthouse performance ≥ 0.90, accessibility 1.0, LCP ≤ 2.5 s, CLS ≤ 0.1, ≤ 150 kB of script.
What it is not
Not a site generator
It builds nothing. Astro builds the site; the machine judges the build.
Not a URL linter
It grades a repository mid-build, against a run state it keeps in that repository.
Not a CI action
It runs on your machine, driven by an agent or by you, with a real Chrome.
Not a home for sites
Every site is its own private repo. The plugin directory never holds run state.
How to read this
The left rail groups the pages into four chapters. Pick by what you came to do:
Install the plugin
Steps with a check after each. Ten minutes if the accounts exist.
Drive a run
The daily loop: ask the gate, do the step, close it.
Architecture
What every file does and where state lives.
From idea to launch
The five phases of a run, with the architecture diagrams.
The workflow, step by step
All 15 steps, what each checks and who does it.
Life-cycle of a run
Halts, sign-offs, receipts, freshness — and one run walked end to end.
Command reference
Every command, what success prints, and the misconceptions to unlearn.
Glossary
Every dotted-underline term, defined once.
Terms with a dotted underline are explained where they first appear and again in the Glossary.