Synthetic Web Team
A portable agent team that reproduces Stanford Web Services practice inside whichever AI coding tool you already use.
The badge reads its own score from badge.json, which the site deploys — no gist, no secret, no service beyond shields.io. It will show inaccessible until the first deploy publishes the file.
Open Claude Code, Cursor, VS Code, Codex, or Antigravity in a Stanford project and get the working knowledge of a full SWS web team: strategy, information architecture, content design, UX, front end, accessibility, discoverability, and delivery. The output is a Stanford site that is compliant by default and that you can actually maintain.
Everything here is Markdown, YAML, and a small CLI. No application code, no starter templates, no design system fork.
Status
Early. The plan is complete and reviewed; the implementation is partway through.
| |
|---|
| Project plan | Done. PROJECT-PLAN.md |
| Scope | Static sites, content in the repo, no CMS. standards/scope.md |
| Standards (L0) | Complete for v1. 8 policy files, 7 patterns, prior art, 3 recipes, 4 hosting profiles, the footer fragment, reference versions |
astro-static recipe | Written, and executed end to end against a real build |
astro-ssr recipe | Written, extends astro-static. Not executed, and no SWS Astro project runs SSR, so its hosting half is reasoned rather than copied |
next-ssr recipe | Written, extends astro-static. Renamed from next-netlify on 2026-09-03. Not yet executed end to end |
| Hosting profiles | New. standards/hosting/: a capability contract plus GitHub Pages, Netlify, and Vercel |
| Shared skills | 8 of 8 done, including sws-github (provisions a repo and Pages deploy through gh) and sws-preflight (is this machine equipped?) |
| Role skills | 8 of 8 built, 11 of 11 stubs. 31 skills total, all validated |
| Documentation site | Working. site/, built by our own recipe, scores 100/100 with zero failures |
sws CLI | Working. preflight reports whether the machine has the tools to build at all. doctor and check run 13 check modules against 68 criteria. sws a11y runs axe and an interactive-state audit — hover and focus measured with a real mouse and a real Tab key — and sws perf measures a byte budget, all in real Chromium |
| Report delivery | Working. PR comment and a persistent "Site health" issue, both updated in place. Score trend, sparkline, HTML artifact, README badge |
| Install wizard | Working, agent-first, two-part. user scope installs the skills into your tools once per machine and is removable; project scope merges the contract into AGENTS.md and puts the standards and the per-site record under .sws/. Non-interactive by default off a TTY, --json result with machine-readable next steps, --answers input, idempotent re-runs that preserve project state |
| Copy-a-prompt install | Working. Five prompts on the site — install into your editor, start a new site, add to an existing project, review, update — each carrying an npx route and a git clone fallback |
| Publishable packages | Working, not yet published. Two packages — @su-sws/synthetic-web-team and @su-sws/synthetic-web-team-mcp — verified by installing the tarballs into a clean project with no repository present |
| Updates | Working. Re-install is the update: project state preserved, local edits reported as conflicts rather than overwritten, stale files reported not deleted, staleness nag in sws doctor |
| Recipe canary | Deliberately deferred, 2026-09-01. Not in production, so nobody is exposed to upstream drift yet. Revisit before the first pilot |
| Standards freshness CI | Planned, and the priority ahead of the canary. Keeps policy, prior art, and sourced facts from going stale |
| MCP server | Working. packages/mcp/. 5 tools, 26 resources, verified over the real stdio protocol |
End to end, verified: synthetic-web-team installs, an agent follows the recipe, then npm run build && sws a11y && sws perf && sws check reports 100/100 with zero automated failures — 52 criteria passing, none to fix, 8 unchecked. axe runs in real Chromium against every built route and finds 0 violations at WCAG 2.1 AA; the byte budget passes at 154 KB of 800. Every one of the 8 unchecked items is genuinely unautomatable — the manual WCAG checklist, ODA review, subdomain approval, MFA attestation, the DRA question — and each says so with a reason rather than being quietly dropped.
A green axe run is a floor, not a conformance claim. It covers roughly 30 percent of accessibility issues per ODA guidance, and this project says so in the report itself.
Install
Easiest: paste a prompt into your agent
Copy the install prompt from the site
and paste it into Claude Code, Cursor, VS Code Copilot, Codex, Zed — anything that
can run a command. It tells the agent how to install, what to read first, and
to ask you for the owner names and emails rather than inventing them, because
MinWeb requires real ones.
There are five, following the two-step shape: install into your editor,
then either start a new site or add to an existing project, plus review
an existing site without changing it, and update. Each names both the npx
route and a git clone fallback, so it stays correct even where the registry is
unreachable.
Or run it yourself and answer the questions
It installs in two parts. Once per machine, into whichever AI tools you use:
npx @su-sws/synthetic-web-team install
That writes the 31 skills to ~/.claude/skills/ and ~/.agents/skills/ and
nothing else — no standards, no AGENTS.md, nothing per-site, because at that
point there is no site. It touches no file it did not write, so unrelated skills
already in those directories are safe, and install --remove takes it back out.
Then once per project, in its root:
npx @su-sws/synthetic-web-team init # a new site, in an empty directory
npx @su-sws/synthetic-web-team add . # a project you already have
The command is required; every flag is optional. There is no bare form and
no default: install writes to your home directory while init and add write
into whichever directory you are standing in, and those are too different to
guess between. Run it with no command and it prints its help and writes nothing.
With a terminal attached each job asks what the site is, what it handles, who
owns it, and which AI tools you use, then shows you every file before writing
anything. A project gets no skills — they are already installed for every
project — so their absence there is correct.
It adds to what your project already has. The contract goes into AGENTS.md
between <!-- BEGIN:sws-agent-contract --> and <!-- END:sws-agent-contract -->,
the way Next.js adds its own block, so your rules and other tools' blocks stay
where they are. CLAUDE.md and GEMINI.md are exactly @AGENTS.md, and only
for the tools that do not read AGENTS.md themselves. The MCP server is added to
.mcp.json next to the servers you already have. Everything else goes under
.sws/: the standards in .sws/standards/, nothing at your root, and nothing in
.claude/, which many teams git-ignore.
Where a package.json is present it also adds @su-sws/synthetic-web-team to
your devDependencies, so that npx sws afterwards runs this CLI. Unscoped
sws on the public registry is an unrelated package, and without the local
dependency that is what you would get.
Or drive the installer yourself
The primary caller is an agent, so that is the first-class path. One command,
no prompts, one JSON document on stdout, stable exit codes:
npx @su-sws/synthetic-web-team init --json --answers '{
"siteName": "Stanford Bioengineering",
"unit": "Bioengineering",
"purpose": "Help prospective graduate students apply",
"url": "https://bioe.stanford.edu",
"businessOwnerName": "...", "businessOwnerEmail": "[email protected]",
"techAdminName": "...", "techAdminEmail": "[email protected]",
"collectsPersonalData": false, "authenticates": false
}'
Non-interactive is the default whenever stdin is not a TTY, so an agent
cannot hang on a prompt. With --json, stdout is exactly one JSON document and
every human-readable line goes to stderr.
Three fields in the result are the ones an agent should act on:
| Field | Why it matters |
|---|
next[] | What to do next, as data: read-contract, orient, follow-recipe, complete-manifest, verify. Each has a path or command and a why |
incomplete[] | Manifest fields that are still placeholders. Ask the user for these; do not invent them — MinWeb requires a named business owner and technical administrator with valid Stanford email |
counts | created / updated / merged / unchanged / preserved / moved. A re-run reports unchanged, so "already installed" is a truthful answer rather than a second claim of success |
Exit codes: 0 success or dry run, 2 bad input or no content found, 3 a human
declined at the confirmation prompt.
Re-running is safe. .sws/manifest.yml and .sws/acknowledged.yml are project
state and are preserved, never overwritten — everything else is content and is
rewritten from source.
Updating
Re-running the installer is the update. There is no separate update
command, because the content is vendored into your project rather than resolved
at runtime — so an update is a re-copy, and the only question is what it is
allowed to touch.
npx @su-sws/synthetic-web-team add .
Three guarantees make that safe to run at any time:
| Verdict | What happens |
|---|
preserved | .sws/manifest.yml and .sws/acknowledged.yml are never overwritten. They hold your owners, resolved versions, recorded divergences and accepted risks |
conflict | A file you edited is reported and left alone. --force overrides |
merged | Our part was added to your own file: the contract to AGENTS.md, the import to CLAUDE.md, the sws server to .mcp.json and the other MCP configs, a marked pointer to .github/copilot-instructions.md. The rest of the file is untouched, and a later update replaces only our part. Remove the sws server and updates leave it out |
moved | Files an earlier version put in standards/ at the root are moved into .sws/standards/, edits and all. Only files the install record lists: a standards/ folder of your own stays put. If your code or CI still reads standards/, as a footer generated from standards/fragments/global-footer.yml does, the move waits and deferred lists each reference, so the next build does not break. Change them and re-run |
orphan | A file we shipped before and no longer do is reported, not deleted, every run until you remove it |
.sws/installed.json records the hash of everything written, which is what lets
an update tell a local edit from an old version. Commit it. Delete it and you
lose conflict detection until the next install.
npx sws doctor tells you when a project is behind: content and tools ship in
one package, so the CLI's version is the standards version — no network call.
If you are a human
Same command without --json. It detects your editors, asks a handful of
questions, and shows you the file list before writing anything. --dry-run
reports what it would do and writes nothing; --interactive forces prompts even
without a TTY.
Nothing is published to npm yet. Until it is, install from a checkout — the
wizard finds its content beside itself or in the current directory:
git clone https://github.com/SU-SWS/synthetic-web-team
cd synthetic-web-team && npm install
cd /path/to/your/project
node /path/to/synthetic-web-team/packages/wizard/bin/wizard.mjs
Or copy the files by hand, which is all the wizard is really doing:
# From your project root. The contract is the marked block, appended so any
# AGENTS.md you already have keeps its content.
sed -n '/BEGIN:sws-agent-contract/,/END:sws-agent-contract/p' path/to/synthetic-web-team/AGENTS.md >> AGENTS.md
mkdir -p .sws && cp -r path/to/synthetic-web-team/standards .sws/standards
grep -qx '@AGENTS.md' CLAUDE.md 2>/dev/null || echo '@AGENTS.md' >> CLAUDE.md
# Skills go in your HOME directory, once, not in the project
cp -r path/to/synthetic-web-team/skills ~/.agents/skills
cp -r path/to/synthetic-web-team/skills ~/.claude/skills
Those two skill paths between them are read natively by Claude Code, VS Code Copilot, Cursor, Codex CLI, Gemini CLI, Zed, Antigravity, and Cline. No build step, no compiler, no plugin to install.
Two copies because no single path is read by every editor, and we deliberately have no compiler. If you only use one editor, delete the other directory. See docs/skill-paths.md.
To start a new site, hand your agent standards/recipes/astro-static/RECIPE.md and ask it to follow it.
Then check it:
npm install --prefix packages/cli
node packages/cli/bin/sws.mjs doctor --standards standards
doctor always exits 0, so it is safe anywhere. check is the CI form and exits non-zero only on a blocking finding, which today means exactly one thing: committed credentials.
What is in here
| Path | What it does |
|---|
AGENTS.md | The behavioral contract: the block between the sws-agent-contract markers, at most 150 lines, read by every tool. The rest of the file is about this repository and does not ship |
skills/ | The team: 31 skills, each one SKILL.md with two frontmatter keys. 8 built roles, 11 honest stubs, 12 shared |
standards/policy/ | Stanford requirements: MinSec, MinWeb, accessibility, privacy, brand, identity, procurement, escalation. Each file carries a reviewed: date |
standards/patterns/ | How SWS actually builds: Decanter, components, content, IA, forms, discoverability, plus conventions derived from reading 11 production repos |
standards/stack/ | reference-versions.yml, a dated baseline. Advisory — nothing installs from it. Plus performance-budget.yml, the byte budget sws perf enforces |
standards/recipes/ | Build contracts with machine-checkable acceptance criteria |
standards/fragments/ | Byte-exact compliance content, like the Global Footer link set |
|
Two published packages, not four. @su-sws/synthetic-web-team ships the content, the CLI
and the wizard together — one version number, so the CLI always knows which
standards version it carries. @su-sws/synthetic-web-team-mcp is separate only so CI does not
download an MCP SDK to run sws check. packages/cli and
packages/wizard are internal: they are published inside
@su-sws/synthetic-web-team, which is why there is no staging script and no empty-looking
package directory.
Five decisions that surprise people
Recipes, not starter templates. We do not ship or maintain application code. A recipe says what must be true and delegates boilerplate to the upstream scaffolder (npm create astro@latest), so you get current versions and we have nothing to keep updated. A template starts rotting the day it is committed and every consumer inherits the rot.
Install latest. Pin nothing. Recipes name no version numbers, with exactly one exception: Decanter 8 rather than 7, because they are architecturally different and getting it wrong fails silently. Standards are expressed as things to avoid, which age far better than versions to require.
Advisory, not blocking. Findings are reports, PR comments, and a visible score that trends. Exactly one thing fails a build: committed credentials, because that harm is irreversible. A tool that fails your build over a contrast ratio gets uninstalled by Friday, and then nothing is compliant.
The report is designed to find the reader rather than expecting the reader to find CI. A push to main rewrites one long-lived "Site health" issue in place — findable by someone who has never opened the Actions tab, and it notifies watchers. A pull request gets one comment, also updated in place, because a new comment per push is noise people mute. The score trend lives in that issue's body as an HTML comment, which is why it needs no database, no artifact that expires, and no commit churn.
Push to main deploys. Pull requests are first-class but never required, and nothing in the setup makes one mandatory. Many campus editors work through the GitHub web UI and will not open a pull request to fix a typo. With a CMS, git disappears entirely.
Recipes extend each other. next-ssr declares extends: astro-static and contains only its differences: three criteria that do not apply, two whose mechanism changes, and ten that are new. The 52 shared criteria live in one place, so they cannot drift between recipes. Four CI gates enforce the contract in both directions: every criterion maps to a check, is marked manual, or declares unimplemented: with a reason; every finding a check can emit has a criterion somewhere; every criterion naming a check has a check that emits its id; and every check: names a module that exists. Each gate was added after the previous set missed something real — the last two because five criteria named checks that emitted nothing and one named a module that had never existed.
Scoped to static sites with content in the repo. No CMS: not Storyblok, not decoupled Drupal. standards/scope.md is the declaration. The narrow scope is what makes the rest of the guidance testable — nothing arrives after the build that CI cannot see. It also has a genuine accessibility payoff: standards/patterns/content.md used to say content published after launch was the real risk, reachable only by sa11y in a CMS Visual Editor overlay. With content in git, every edit is a commit that runs sws a11y before it is public, so that gap mostly closes and the control moves somewhere stronger. The 30 percent ceiling on automated testing is untouched by this, and embedded third-party content is still outside the build. Out of scope is not forbidden, and the eleven CMS-backed SWS repos are not wrong — there is simply no tested recipe here yet, and saying so beats shipping guidance nobody has run.
Hosting is an axis, not a recipe. Recipes are framework- and build-shaped; hosts live in standards/hosting/ as a capability contract plus one profile each. This keeps two frameworks times three hosts from becoming six near-identical recipes. The contract is deliberately short, because MinWeb requires no response headers at all — not CSP, not HSTS — so hosting is not where compliance is won or lost, and a recipe implying otherwise is overreaching. Security headers ship as sensible defaults that cannot break a page; a CSP is optional and off by default, since it breaks pages at content-edit time and the person holding that problem is the one least able to diagnose it.
SWS runs two hosts, not one. storyblok-next-netlify (6 repos) is on Netlify; decoupled-drupal (5 repos, including library.stanford.edu) is on Vercel. That is two lineages and two decisions, neither a majority. Until 2026-09-03 this project asserted Netlify was the platform and Vercel "appears once", because hosting had been inferred from package.json — which does not record a deploy target. The Vercel family was nearly invisible to dependency inspection because it uses node-vault rather than a host build plugin, the more portable choice. That correction is kept in full, and it is the second time the third precedence clause produced the largest fix in a pass.
Prior art is step zero. SWS has built a lot of sites and most problems are solved. The agent checks existing work before inventing anything, under a rule with three clauses, the third of which is that prior art cannot tell you why a choice was made or where the team is going. Both need a person. That clause exists because ignoring it produced three wrong conclusions in an afternoon, written up as a record of error.
Compliance, concretely
Generated sites are built to satisfy Stanford's actual requirements rather than a generic checklist:
- WCAG 2.1 AA, with an honest statement that automation catches roughly 30 percent of issues per ODA guidance
- Global Footer and Identity Bar exactly as the Identity Guide requires, from a contract extracted from the upstream component
- MinWeb: named business owner and technical administrator, MFA on admin logins, HTTPS, no keys in Git, subdomain approved by University Communications
- MinSec, which applies to low-risk static sites too
- Siteimprove registration, which is required. Google Analytics is not
- No cookie banner, because none is required at Stanford
For anything with legal, policy, or procurement weight, this project names the responsible university office and the specific door to use rather than recommending a product. It will not grant an exception, approve a subdomain, sign off a launch, or interpret policy on the university's behalf.
Who this is for
SWS staff are the primary audience. This encodes how we already work, including the parts that live only in people's heads.
Stanford units building their own sites are the close second. If you are a department with no web developer, consider Stanford Sites first: it is free and already compliant. This project is for when you need something Stanford Sites cannot do.
Other universities are welcome. The architecture is not Stanford-specific; only standards/policy/ and standards/fragments/ are. Swap those and the rest works. If you do that, we would like to hear about it.
Stack
Astro or Next, Tailwind 4 via Decanter 8, npm (yarn fine, never converted), Playwright plus axe, GitHub Pages then Netlify. Optional Storyblok. No component workshop, because these sites have few components and one consumer.
Divergence is supported and expected. Every recipe lists its swap points with the cost of each, and deliberate departures get recorded rather than argued about.
Contributing
Standards changes need a reason and a date. If you correct something, say what was wrong and how you know, because the record of a mistake is usually more reusable than the fix.
Two rules with teeth:
- Never edit an
acceptance.yml criterion or a fragment to make a project pass. Fragments change when upstream changes.
- Every criterion must map to an implemented check. A criterion with no check is a wish. Delete it or implement it.
Releasing
Every push to main cuts a release. Patch by default:
| You want | Do this |
|---|
| A patch | Nothing. Push to main |
| A minor | Put [minor] anywhere in the commit message |
| A major | Put [major] anywhere in the commit message |
| No release | Put [skip release] in the commit message |
| A specific bump, by hand | Run the release workflow and pick patch, minor, major, or none |
| Publish the current version without bumping | Run it by hand with none |
.github/workflows/release.yml validates,
versions, tags, publishes and drafts release notes, in that order.
There is no npm token in this repository, and nothing to rotate. Publishing
uses npm trusted publishing over OIDC: npm authenticates the workflow by its
own short-lived identity, which is why the job asks for id-token: write. npm
caps granular tokens at 90 days and has been retiring the old non-expiring
automation tokens, so a stored secret would have been a recurring chore and a
standing liability. This has neither, and provenance comes free.
The trust is configured per package on npmjs.com, for
@su-sws/synthetic-web-team and @su-sws/synthetic-web-team-mcp separately, and
it names this repository and this workflow's filename. Renaming
release.yml or moving the publish steps elsewhere breaks publishing with an
authentication error that looks nothing like the cause — change the trusted
publisher settings first.
Both packages move together. @su-sws/synthetic-web-team-mcp depends on the root package, and
a caret range survives a patch bump but not a minor one — ^0.1.0 does not
match 0.2.0, so a published server would quietly resolve old standards.
scripts/set-version.mjs rewrites that range along
with the versions, which is the whole reason npm version is not used here. Run
it with --dry-run to see what a bump would do.
Ordering is deliberate: the gates run before anything is versioned, the version
is checked against the registry before anything is committed, and the tag is
pushed before anything is published. A failure at any point leaves the registry
untouched, because publishing to a public registry is the only step here that
cannot be undone.
License
GPL-3.0-or-later, matching Decanter.
Maintained by Stanford Web Services.
