The standard for building software with AI agents.
When agents write the code, done is not the last message of the run. Done is a state of the system that can be proven.
Read it: podmanifesto.org · Full text: manifesto.md
The process this document argues for is packaged as installable skills and Claude Code
plugins — sshlg-skills:
npx sshlg-skills installThe implementation is evidence that this process can run. It is not the authority for the manifesto: the four-field protocol, the three graphs and the seam walk survive every tool and package name in that repository changing.
DONE
What became true.
PROOF
What was executed or observed, and where the result lives.
SCOPE
The commit, environment, requirements, and surfaces covered.
NOT VERIFIED
What was not checked, could not be checked, or remains uncertain.
NOT VERIFIED: none within the stated scope is a valid answer. Silence is not.
| Path | What it is |
|---|---|
manifesto.md |
The canonical text. Everything else renders it; nothing else restates it. |
index.html |
The published document at podmanifesto.org. |
assets/fonts/ |
Geist for the prose and JetBrains Mono for the display and telemetry, self-hosted under the SIL OFL. |
assets/figures/ |
The five diagrams, generated by tools/build-figures.py. |
assets/logo-512.png |
The turnstile as a raster, for the surfaces that will not take an SVG — the icon fallback and the iOS home screen. favicon.svg is the same mark and the only one with a dark-surface variant. |
assets/style.css |
The stylesheet, opening with this page's own token block — the one place a colour or a radius may be written. assets/main.js is the small progressive-enhancement script. No frameworks; the only off-origin request the page makes is the analytics beacon. |
llms.txt |
The document indexed for language models and crawling agents. |
404.html |
The missing-address page, written as a four-field report against itself. |
tools/ |
The checks below and the figure build. contrast-sweep.js measures composited colour, so it needs a real browser — check-render.py gives it one in CI, which is not the same as needing a person. |
CHANGELOG.md |
What changed in the canonical text, and the rule that it does not change without a version. |
CONTRIBUTING.md |
How to argue with the document, and how to submit a translation. |
GOVERNANCE.md |
Who decides canonical changes, versions and releases. |
SECURITY.md / SUPPORT.md |
Private vulnerability reporting and the route for every other question. |
CITATION.cff |
Machine-readable citation metadata for the current version. |
docs/DOCMAP.md |
The authoritative home and propagation rule for each repository fact. |
CNAME |
The custom domain served by GitHub Pages. |
"The site matches the text", "the references resolve" and "the page still looks like the
pack" are commands with exit codes here, not sentences in a commit message. All of them
run on every push (.github/workflows/checks.yml):
python3 tools/check-parity.py --verbose # every canonical sentence of manifesto.md is on the page,
# and the case count it states is computed, not restated
python3 tools/check-html.py # the page closes every element it opens
python3 tools/stamp-assets.py --check # every asset URL carries the hash of its current contents
python3 tools/check-links.py # every reference resolves, and every cited line range exists
python3 tools/stamp-dates.py --check # every published date — sitemap lastmod, JSON-LD
# dateModified, the masthead, llms.txt — is the date
# git records for the files it describes
python3 tools/check-render.py # the properties only a browser can see: the document
# survives into print, and every text/background pair
# clears the WCAG AA floor in both themes, measured on
# composited colour rather than asserted from the tokens
python3 tools/check-live.py # the PUBLISHED site matches this repository — the served
# robots.txt, the deployed bytes, every asset, the 404.
# `--self-test` runs its rules offline against planted cases
python3 tools/negatives.py # 25 planted defects across the 12 gates that read this
# tree, each required to refuse its own; a green nobody
# watched fail is not evidence. `check-live.py` is the
# thirteenth and is not in here — its subject is the live
# site, which cannot be planted in a temp directory, so
# its rules are decided offline by its own `--self-test`
python3 tools/check-currency.py # every citation this document CHARACTERISES still says what
# is claimed of it — a permalink resolves forever, so
# resolution alone cannot detect a receipt gone stale.
# `--self-test` runs the rules offline against planted cases
python3 tools/check-downloads.py # the install count in the colophon, resummed from npm
# over a window that must end on a day that is over;
# `--self-test` decides its rules offline
python3 tools/check-version.py # every place the document states its version agrees, and
# equals the newest tag — so the citable address points at
# the text that is on the page
python3 tools/check-pack.py # no colour or radius literal outside the token block;
# reduced motion has a path
python3 tools/build-figures.py --check # every figure's geometry is asserted, not eyeballed
python3 tools/inline-figures.py --check # the inlined figures match the generated ones
bash scripts/check-docs.sh --self-test # the governance and UX documentation gate is shown
# refusing a planted missing-file defect
bash scripts/check-docs.sh # required documentation homes, structured metadata,
# current version and CI wiring agree
python3 docs/ux/lint.py # public-reader scenarios obey the shared UX contractNo style pack. The page is the first design it ever had, restored after three
alternatives were built and read: a paper field with a faint grid, mono chrome
over a grotesk body, one green accent, light and dark. The masthead is centred —
the one change from the original, because a founding document is issued rather
than marketed and its title does not sit in a corner. The colour tokens live in
one block at the top of assets/style.css, which is what check-pack.py holds
the rest of the stylesheet to.
The five diagrams are plates, not flowcharts: a station is a name set in the
text face on a hairline, mono is kept for what a plate uses it for (lane labels,
indices, relation names, state tags), and state is carried by a dot and a
bracketed tag rather than by a box. tools/build-figures.py generates them and
asserts the geometry; the real font metrics are verified in a browser.
Asset URLs carry a content hash (/assets/style.css?v=…). A deploy once shipped
while browsers went on serving the previous stylesheet, so the URL now changes
whenever the file does and no cache can answer with the old bytes.
The site is static and readable with JavaScript disabled. It makes exactly one third-party
request — the cookieless Cloudflare Web Analytics beacon, written into the page because the
edge's automatic injection was enabled and silently not happening. Nothing else is fetched
from anywhere but this origin, and check-live.py fails if that stops being true. The text is
addressed to two readers: a person, and the agent that will quote it.
The live page moves with the version; the tag does not. If a quotation has to stay reachable, cite the tag:
https://github.com/ssheleg/pod-manifesto/blob/v1.1/manifesto.md
The canonical text does not change without a new version and an entry in
CHANGELOG.md. Corrections to the site, the tooling or the prose about the
document are not versions and are not listed there.
Citation tools can read CITATION.cff. Human and machine citations should
still use the versioned source address above so the quoted text cannot move.
The licence says argue with it, and an invitation with no address is decoration:
CONTRIBUTING.md says what a useful objection looks like, where to put
it, and how to submit a translation. GOVERNANCE.md names the decision
boundary; CODE_OF_CONDUCT.md and SUPPORT.md name
the participation and routing boundaries.
Text: CC BY 4.0 — quote it, translate it, adopt it, argue with it; keep the attribution and the link. Site code: MIT.
Sergey Sheleg (Siarhei Sheleh) — github.com/ssheleg