Building excellent websites — an open guide for AI agents

A quality guide for AI agents that build and change websites. Hand it to your agent with the brief. It teaches the agent to find and fix defects before you have to point them out: build the site, inspect it in a browser, measure it, and keep improving it until it can show you why the site is ready.

It is open source under the MIT licence and platform-neutral — any website, any agent. Your platform’s own documentation covers how to author, publish and restore; the guide covers what good work requires and how to prove it.

What it covers

• A session contract — what the agent decides, what it asks you, and the only four statuses it may report: target met, exceptions remain, defects remain, verification incomplete.
• A build loop for new sites, redesigns and migrations, and a change loop for the years after, with checks scaled to what a change can reach.
• The checks no score makes — visitor tasks, migration fidelity, design at four widths, keyboard and reflow, loading, discoverability.
• The numbers — a median of 100 in all four Lighthouse categories on mobile and desktop, contrast ratios, target sizes, Core Web Vitals.
• Scripts — three Lighthouse runs per device reduced to medians, and a rendered-page check with axe, console and request failures. Versions are pinned, so a before and an after compare.
• One report — evidence, status, publication and how to undo the change, plus a count of what you had to correct yourself.

Hand it to your agent

Paste this with your brief:

Build or improve this website with the quality guide at
https://github.com/cityofcode-io/agent-operated-websites and the brief.
Run its preflight and build loop. Find and fix routine defects yourself;
ask me about intent and consequential tradeoffs. Hand me the guide's
report with evidence, status, publication and recovery.

$ git clone --depth 1 https://github.com/cityofcode-io/agent-operated-websites.git website-audit && cd website-audit && npm ci && npx playwright install chromium

What it does not claim

The guide describes the job; it does not make any platform necessary for doing it well — spun.ink included. It does not promise four perfect scores for every site: a required third-party embed can cost points, and the guide says how to record that as an exception instead of hiding it. Whether it reduces the corrections you have to make is not measured yet. Observed agent sessions will test that, and the guide changes when they find something.

Written and maintained by the team behind spun.ink. It grew from moving cityofcode.io onto spun.ink and the Lighthouse pass that followed.