turbo-start-web-agent
AGENTS.md4 starsChanged 47 days agoMITView on GitHub
A marketing-site template where a non-technical client edits content through an AI agent while developers keep working in git. This file is the rulebook every agent — human-directed or autonomous — follows in this repo. It is read natively by Codex, Cursor, GitHub Copilot/VS Code, Zed, Jules, Gemini CLI, Devin, Warp, Amp, and most of the rest of the ecosystem. Claude Code does not read this file directly; it reads CLAUDE.md, which imports this one. 1. Static-only rendering. Content in…
- Deletes or force-pushes
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
- compose-pageSkill
- design-a-blockSkill
- find-skillsSkill
- humanizerSkill
- no-em-dash-copySkill
- sync-changesSkill
- write-a-skillSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
constonly: Never let or var, except where a loop genuinely reassigns. - Distinctive: line 39
Commit the work you were asked to do — a branch publishes nothing.
- Very specific: line 113
Why this works as a guarantee, not a request: every content file passes through remarkContentLockdown …
- Very specific: line 174
After editing, run pnpm content:check (§5), then view the page.
- Distinctive: line 279
Add to whichever file fits.
- Very specific: line 354
After that fix, sync-changes still listed the platform's own PR control as a route in prose while the one copy-pasteable command in the …
- Distinctive: line 371
When a fix lands in one workflow, look for the other one.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — turbo-start-web-agent
A marketing-site template where a non-technical client edits content through
an AI agent while developers keep working in git. This file is the rulebook
every agent — human-directed or autonomous — follows in this repo. It is read
natively by Codex, Cursor, GitHub Copilot/VS Code, Zed, Jules, Gemini CLI,
Devin, Warp, Amp, and most of the rest of the ecosystem. Claude Code does not
read this file directly; it reads CLAUDE.md, which imports this one.
1. Golden rules
- Static-only rendering. Content in
content/is data, not code. It may only compose named Blocks (capitalized tags) with literal prop values — noimport/export, no function calls, no raw HTML elements, no runtime expressions. This is enforced at build time, not by convention — see §3. - Compose before extend. Almost every task is composing existing Blocks
from
catalog.jsoninto MDX (§3). Only touch schemas or components (§4) when no existing Block can express the content. - Design tokens only. Blocks and primitives reference the CSS custom
properties defined in
artifacts/web/src/app/globals.css— never a raw hex code or a px value. Re-theming a client site means editing token values there, never renaming or removing a token (every Block references them by name). - The build is the gate — run
pnpm run checksbefore delivering. That one command is the whole gate (§5), and it is what CI runs, so green locally means green there. Fix the content, not the schema. A green build is necessary but not sufficient — check the rendered page before calling a change done. Where you have a browser, click through it (nav, footer, every linked page). Where you do not, serve the build and assert on the returned HTML for the strings you changed; that catches wrong-content far better than a green build alone, even without a screenshot. constonly. Neverletorvar, except where a loop genuinely reassigns.- kebab-case filenames. Exports keep PascalCase (component names, types).
- Being asked for a change authorizes the commit, not the pull request.
Commit the work you were asked to do — a branch publishes nothing. Then
pause and ask before opening the PR, which is outward-facing. Where a
platform's own instructions require opening the PR immediately, follow
the platform: its instructions outrank this file, and the PR was never
the gate — merging is. Never a direct push to
main, and never merge your own PR. Commit trailers areRequested-by:andAgent:; neverCo-Authored-By:or a session URL. Delivery channels differ per platform (some have nooriginremote at all) — see.agents/skills/sync-changes/SKILL.md.
2. Where things live
The Next.js app is a workspace package under artifacts/web/ — nearly
everything below is relative to that directory, not the repo root.
| What | Path |
| Page content (MDX) | artifacts/web/content/pages/*.mdx |
| Blog posts (MDX) | artifacts/web/content/blog/*.mdx |
| Site name and description (YAML, not MDX) | artifacts/web/content/settings/site.yml |
| Site navigation (YAML, not MDX) | artifacts/web/content/settings/navigation.yml |
| Site footer (YAML, not MDX) | artifacts/web/content/settings/footer.yml |
| Site-wide announcement bar, above the header (YAML, not MDX) | artifacts/web/content/settings/announcement.yml |
| Overscroll easter-egg lines (YAML, not MDX) | artifacts/web/content/settings/overscroll.yml |
| Block schemas (Zod — the source of truth) | artifacts/web/src/lib/blocks/schemas.ts |
| Block catalog (generated prop reference) | artifacts/web/src/lib/blocks/catalog.json |
| Block components | artifacts/web/src/components/blocks/*.tsx |
| Block component registry | artifacts/web/src/components/blocks/index.ts |
| Content lockdown (the enforcement mechanism) | artifacts/web/src/lib/content/remark-content-lockdown.ts |
| Content pipeline config (Velite) | artifacts/web/velite.config.ts |
| Design tokens | artifacts/web/src/app/globals.css |
| Allowed image hosts | artifacts/web/next.config.mjs (images.remotePatterns) |
| Live Block reference/preview | artifacts/web/content/pages/blocks-gallery.mdx, served at /blocks-gallery |
| Catalog/gallery generators | artifacts/web/scripts/generate-catalog.ts, artifacts/web/scripts/generate-gallery.ts |
Verify commands (delegate into artifacts/web) | root package.json |
Deeper how-to procedures belong in .agents/skills/, not in this file. Seven
skills ship in this repo today, six written for it and one installed from
elsewhere (see skills-lock.json):
| Skill | Use it for |
.agents/skills/compose-page/SKILL.md | The full page-composition workflow: locating the right MDX file, choosing Blocks from catalog.json, writing frontmatter (including the blog-only fields §3 doesn't cover), and composing Blocks with literal props. |
.agents/skills/sync-changes/SKILL.md | Session-start git discipline: pull before editing, branch → commit → PR, never push to main, and how to confirm a push actually reached the remote on platforms where the shell has no git credentials. |
.agents/skills/design-a-block/SKILL.md | Before writing or editing any component a visitor sees: which type role, which token, which button variant — and what the system deliberately omits. §4 has the mechanics; this has the design decisions already made. |
.agents/skills/find-skills/SKILL.md | How to review and install a third-party skill safely before adding it to .agents/skills/ and skills-lock.json. |
.agents/skills/write-a-skill/SKILL.md | Asked to remember a rule or save a convention: write it here as a skill rather than into your platform's own memory, where only one person on one platform would ever see it. |
.agents/skills/no-em-dash-copy/SKILL.md | Writing or editing any copy a visitor reads: this site uses commas, colons, parentheses or full stops where an em dash would go. |
.agents/skills/humanizer/SKILL.md | Writing or editing any copy a visitor will read: the AI tells to remove before it ships — inflated claims, sales language, stock vocabulary, filler, and the rest. Third-party, pinned in skills-lock.json. |
Codex, Cursor, Copilot/VS Code, Zed, and most of the rest of the ecosystem
read only this file and never load .agents/skills/ — for those platforms
the table above, not the skill files themselves, is the documentation.
Claude Code also loads these by description at the paths shown.
.claude/skills/ is a generated, byte-identical mirror of .agents/skills/
for Claude Code, refreshed by pnpm harness (§5) — edit skills under
.agents/skills/, never under .claude/skills/ directly.
3. Compose (the common case)
To add or change a page: write MDX under artifacts/web/content/pages/,
choose Blocks from artifacts/web/src/lib/blocks/catalog.json (the
machine-readable prop reference generated from schemas.ts), and drop them
into the MDX body as tags. No imports, no wiring — Blocks are injected into
every content file automatically.
<Hero
variant="centered"
title="Your website, editable by any AI agent"
primary={{ label: "Read the docs", href: "/about" }}
/>Why this works as a guarantee, not a request: every content file passes
through remarkContentLockdown (artifacts/web/src/lib/content/remark-content-lockdown.ts),
a remark plugin wired into the Velite MDX pipeline (artifacts/web/velite.config.ts).
It walks both the MDX tree and every {…} expression and rejects anything
that isn't a pure literal — the build fails, with an error naming exactly
what was rejected and what to do instead. That is what makes "an agent may
only edit content" true regardless of what an agent (or a compromised one)
attempts, instead of a rule an agent could simply choose to break.
The concrete constraints you will hit:
- No
import/exportstatements. Blocks are injected into every content file; content never wires up its own dependencies. - No function calls, member access, identifiers, or operators in
{…}expressions. Only literal values survive: strings, numbers, booleans, arrays, objects, template strings (no interpolation), and nested JSX.{someVariable}and{formatDate(x)}both fail the build. - No raw HTML elements and no hyphenated or namespaced tag names. Only
capitalized Block names (
<Hero>, not<div>or<my-widget>) are allowed as JSX tags. If you need a layout raw Markdown can't produce, that's a new Block (§4), not raw HTML. - No prop names beginning
on. Any prop starting withon(case insensitive) is treated as an event handler and rejected outright — content carries copy and structure, never behavior. A prop likeonboardingStepstrips this too; rename it (e.g.steps). - URL-bearing props must be plain literal strings with a safe scheme.
Any prop named
href,src,action,url,to,cite,ping,srcset,formaction,poster, or ending inurl/href/srcis checked. Allowed:http:,https:,mailto:,tel:, or a relative/anchor/query path (/about,#section,?query,./file). Rejected:javascript:,data:, protocol-relative//host, and any interpolated or computed value — write the URL out literally. - Arrays and objects are expression attributes, never quoted strings:
primary={{ label: "…", href: "/…" }}, notprimary="{...}". - Image
srcprops are stricter than linkhrefs (seemediaSrc()inschemas.ts): a relative path served from/public, or anhttpsURL onimages.unsplash.com,assets.ui.sh, or a*.public.blob.vercel-storage.comsubdomain — the exact hostsnext.config.mjs'simages.remotePatternsallows. Anything else passes the schema but throws at render, becausenext/imagerefuses an unconfigured host. - Frontmatter carries
title,description,draft(defaultfalse— excludes the entry from a production build and the sitemap; see README.md for theVERCEL_ENV/PREVIEW_DRAFTSpreview-vs-production distinction), andnoindex(publishes the page but excludes it from the sitemap). - Site chrome (site name, header nav, footer, announcement bar, overscroll
easter egg) is not MDX — it's YAML at
artifacts/web/content/settings/site.yml,navigation.yml,footer.yml,announcement.yml, andoverscroll.yml.site.ymlholds the site's name and description; the header, the root metadata, and the blog index all read from it, so no.tsxfile names the brand. Never reintroduce one. Everyhrefamong them is checked by the sameisSafeUrlrule via a Zod.refine()invelite.config.ts, because YAML never passes through the MDX lockdown remark plugin above. - The announcement bar is not the Banner Block. The announcement bar
(
announcement.yml) is site-wide chrome rendered above the header on every page — the switch a client's agent flips for a single site-wide notice isenabled: true/falsethere, never deleting the content.Banner(a Block, chosen fromcatalog.jsonlike any other) is for an in-page callout composed into one page's own content, and can never render above the header — see its.describe()incatalog.jsonfor the same distinction.
After editing, run pnpm content:check (§5), then view the page.
4. Extend (rarer, governed)
Adding a genuinely new Block — one no composition of existing Blocks can express — has five touch points, all of which must move together:
- Schema — add a Zod schema to
artifacts/web/src/lib/blocks/schemas.tsand register it in theblockSchemasarray. Any URL prop must use thesafeUrl()helper; any image prop must usemediaSrc(). Both pair a.refine()(the actual runtime check) with a.describe()restating the rule in prose —z.toJSONSchema()silently drops.refine()predicates, so without the paired.describe()the generated catalog would tell an authoring agent the prop is a bare, unchecked string. - Component — add the matching component to
artifacts/web/src/components/blocks/and register it inblockComponents(artifacts/web/src/components/blocks/index.ts). Every Block component callsparseBlock(name, schema, props)first; that's the render-time half of validation, and its error names the Block and every bad prop path. - Registry regeneration — run
pnpm catalog(fromartifacts/web/, orpnpm --filter @workspace/web run catalogfrom the root). This regeneratescatalog.jsonfromschemas.tsand adds a stub section toblocks-gallery.mdxfor the new Block. - The registry guard test —
artifacts/web/src/lib/blocks/schemas.test.ts("blockSchemas and blockComponents register the exact same Block names") fails the build if a schema has no matching component (renders nothing) or a component has no matching schema (never validated). It readsindex.tsas source text rather than importing it, because Node's--experimental-strip-typestest runner cannot import a.tsxfile. - The gallery example.
pnpm catalogwrites an emptystatus="todo"stub so it can run the moment a Block is registered. Replace it with a real usage example incontent/pages/blocks-gallery.mdx.gallery:checkfails while a stub remains: an empty entry is not drift — regenerating reproduces it exactly — so nothing else catches it, and the gallery is what the next author reads before deciding whether your Block already covers their case.
pnpm catalog:check and pnpm gallery:check both run in CI — a Block added
without running pnpm catalog fails the build, which is the drift check
working as intended.
5. Verify
From the repo root, one command runs every gate below, in this order, and stops at the first failure:
pnpm run checksRun it before delivering any change. .github/workflows/ci.yml runs this
same script rather than its own list of steps, so there is no version of the
gate that passes here and fails there. Run an individual one while iterating
if you like — each delegates into artifacts/web, except the first:
pnpm run harness:check # generated per-platform surfaces are in sync with AGENTS.md, harness.config.json, and .agents/skills/
pnpm run skills:check # every third-party skill under .agents/skills/ is pinned in skills-lock.json, and still hashes to what was reviewed
pnpm run content:check # frontmatter, MDX syntax, and the content lockdown
pnpm run brand:check # the site's name from content/settings/site.yml appears nowhere under src/
pnpm run catalog:check # catalog.json is in sync with src/lib/blocks/schemas.ts
pnpm run claims:check # this file, README.md and the skills do not misstate how many Blocks exist, or which
pnpm run gallery:check # blocks-gallery.mdx has a section for every registered Block
pnpm run lint # biome check (artifacts/web, plus scripts/ and harness.config.json at the root)
pnpm run test # lockdown, loader, and Block-prop unit tests, plus the harness generator's own tests
pnpm run typecheck
pnpm run build # renders every page; bad Block props fail hereThis is the exact sequence CI runs (.github/workflows/ci.yml), in the same
order. A second workflow, .github/workflows/pr-hygiene.yml, runs on the
pull request itself rather than the code: it fails a body mangled into
literal \n escapes, an empty description, or a commit carrying a vendor
attribution trailer. It reports rather than blocks: a finding does not stop a
merge, so read it. Its commit-trailer findings can only be cleared by amending
the commit, which is the reason to get Requested-by: and Agent: right when
the commit is made. It has no local equivalent because there is no
pull request to inspect until one exists — run
node --experimental-strip-types scripts/pr-hygiene.ts with PR_BODY set
to try a body by hand. All of it must pass before a change is considered done — but passing
is not the same as correct: always click through the built site afterward.
Regenerating the platform surfaces. pnpm harness regenerates
CLAUDE.md and the .claude/skills/ mirror
from AGENTS.md, harness.config.json, and
.agents/skills/ (see scripts/harness-gen/) — run it any time you edit
any of those three inputs, including after adding, editing, or removing a
skill under .agents/skills/, then include the regenerated files in your
change (§1 rule 7 still applies: land them via a PR, not a direct commit).
pnpm harness:check (above) is the read-only version CI runs:
it writes nothing and fails naming exactly which generated file is out of
date or which file under .claude/skills/ is stale.
6. Incidents and quirks
What actually went wrong here, kept short on purpose. Every agent reads this
file, and Codex truncates project docs past 32 KiB silently — so this
section holds only lessons that apply whatever platform you are on. Anything
true of one platform lives in that platform's runbook under
docs/platforms/, which is where an operator connecting it will look:
Codex having no git remote (codex.md), a public repo hiding
a broken GitHub connection and org settings needing a paid plan
(claude-code.md), scoping a v0 import to a subdirectory (v0.md), and
SSO-gated preview URLs (docs/platforms/README.md).
Add to whichever file fits. Record what happened, not just the rule — a rule sticks when it carries the story.
A green build is not a rendered page. Several defects here passed
typecheck, lint, and build cleanly and were only visible once rendered:
prose with every margin dropped, a Block indented out of line with the text
beside it, literal backticks around inline code, a table-of-contents entry
highlighting the wrong section. Rule 4 asks you to check the rendered page;
these are why.
Schemas enforce shape, not meaning. Asked to drop a stat, an agent hit
statsSchema's exactly-four rule, correctly refused to widen the schema, and
substituted MIT / "License for client reuse" into a Block titled "The
numbers behind the pitch." Every gate passed; the section read as three
numbers and a licence. No schema change catches that. It is the clearest
argument for why the review step is not ceremony.
On a pull request, the file list is the truth and the prose is a claim.
An agent ran the dev server to verify its work — correctly — which rewrote a
generated file. It committed that side effect as its own refactor: commit
with a plausible rationale, then titled the whole pull request after it and
never mentioned the change that had been requested. Every check passed,
because none of them read English. pr-hygiene now catches malformed
descriptions; nothing catches untrue ones. Read the diff.
The prose is not always the agent's, either: v0's Create PR control writes
its own title and body and discards what the agent wrote, describing a
four-word copy change as "Update UI components and layout design" (#28) and
an overscroll line as "Sync UI enhancements and component updates" (#30) —
the same boilerplate both times. pr-describe rewrites such a body from the
commits, which is where the real description already was.
A platform's own instructions outrank this file. Codex reported that its environment tells it to open a PR immediately after committing, contradicting rule 7's pause, and correctly followed the platform. Nothing here is sovereign. Write rules whose failure is tolerable: the pause is a nicety, and the merge gate — enforced by GitHub, not by instruction — is what actually protects the live branch.
A safety check that fails is information. git push --force-with-lease
was refused because a remote-tracking ref was stale. The response was
git fetch && git push --force-with-lease, which defeats the protection:
fetching refreshes the ref, so the lease compares the remote against itself
and always passes. Pin the SHA you actually looked at
(--force-with-lease=<branch>:<sha>) rather than working around the refusal.
An approval prompt only catches what the approver can recognise. A PR
body was passed as --body "…\n…"; shells do not expand \n inside double
quotes, so the description rendered as one run-on line of visible escapes.
The broken command was displayed for approval and approved, because nothing
about it looks wrong unless you already know the quoting rule. Fixed at the
source — write the body to a file and use --body-file — and gated by
pr-hygiene.
A rule that assumes a capability fails silently on platforms that lack
it. Three rules written here turned out to encode one platform's abilities
as if they were universal: "open a PR with gh pr create" (Codex ships no
gh), "verify write access by pushing a throwaway branch" (Codex cloud has
no git remote at all), and "amend the commit and force-push" (a shell with no
git credentials cannot). Each read
as a neutral instruction and each dead-ended an agent that was otherwise
doing everything right — the failure looks like agent incompetence and is
actually a rule written from one vantage point. When writing a rule, name
the capability it needs and give an alternative for platforms without it, or
write it so the requirement never arises. Getting a commit trailer right at
commit time needs no force-push; fixing it afterwards does.
The correction to that third example is itself the lesson repeating. "v0
cannot force-push" was one observation of one code path -- a shell with no
credentials -- written down as a property of the platform. On 2026-08-27 v0
amended a pushed commit and force-pushed the branch through its own GitHub
integration (head_ref_force_pushed on #38). A capability claim needs the
path it was observed on attached, or it outlives the thing it described.
Prose alone does not undo this: an agent runs the command it can see.
After that fix, sync-changes still listed the platform's own PR control as
a route in prose while the one copy-pasteable command in the file was gh pr
create. On 2026-08-26 an agent on v0 pushed its branch, ran that command,
and reported the repository connection as broken — with v0's Create PR
button visible in its own toolbar. Where a rule has a per-platform answer,
put the precedence before any command, and mark every shell example with the
route it belongs to.
A pull_request workflow can run a version of itself that no longer
exists. Both the workflow file and the code it checks out come from GitHub's
computed merge ref, which can lag the base branch — so a fix to a CI script has
no effect on any pull request whose branch predates it, and the check reports
success. pr-describe hit this on #34, running a script fixed and merged
thirty-three seconds earlier; pr-hygiene hit the identical thing on #47 six
hours later, because the fix had been applied to one workflow and not to its
sibling. Both now use pull_request_target with ref: base.ref, which is the
only arrangement where an open pull request is guaranteed the current check.
When a fix lands in one workflow, look for the other one.
A resumed session brings a stale clone with it. Continuing a chat from a
previous day reuses its container: the checkout is as old as the session, and
the conversation still holds work you believe is unlanded but which merged
hours ago. A branch whose merge base was 17 commits behind produced a pull
request that conflicted by re-adding an FAQ entry already on the live branch,
with git status looking healthy throughout. Verify your base before editing
— see .agents/skills/sync-changes/SKILL.md step 1.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

