proto-specs

Publishes prototype application specifications, not source code. Each app subdirectory holds a SPEC.md precise enough that an engineer or coding agent with zero access to the private reference implementation can build a functionally faithful version from the document alone — status codes, field names, validation predicates, rate limits, error shapes, and concurrency guarantees pinned down exactly. An acceptance checklist at the end of each spec is the success criteria (and doubles as a test plan).

The bet: publish the design instead of the source, and use fixed specs + checklists as a re-runnable benchmark for how well a coding agent turns a complete spec into working software with no reference implementation.

Private reference apps for the specs exist but are not linked here (descriptive / portfolio context only) — see proto-poker and proto-retro.

What's in the repo

Static site — Markdown + HTML, no app backend and no client-side JavaScript. Served from the root of main on both hosts, so a push updates both from the same commit. The deep links below point at GitHub Pages, but the whole tree resolves identically under proto-specs.vercel.app:

poker — no-signup, real-time planning poker estimation tool
retro — no-signup, real-time team retro board tool

The landing page is data-driven

index.html is compiled, not hand-written. build.py fills __TOKEN__ holes in template.html from the content in data/site.yaml and writes the finished page; PyYAML is the only dependency. Each project card's SPEC.md and architecture.html links are derived from its slug rather than repeated, so the two can't drift apart, and the build validates before it writes — required fields, duplicate slugs, malformed links, and whether the files a derived link points at actually exist. python3 build.py --check exits non-zero when the committed page is stale.

Neither host runs that build, which is why the generated index.html is committed alongside its inputs: Vercel and GitHub Pages both serve the repo root as-is, so the built page has to be in the commit. Content edits are a two-file diff by design, and the page ships finished — no JSON payload, no rendering in the browser.

Cleanroom runs so far

Both specs have driven real cleanroom builds against their acceptance checklists. Each run below was given only SPEC.md — no access to the original app — and built both poker and retro:

Harness Model Comments
Claude Code Sonnet 5 Working implementation on the first attempt, both apps
Grok Build Grok 4.5 Both apps built, tests included, ~10 minutes each
Antigravity CLI Gemini 6 Flash Both apps built in 10 minutes or under

That is evidence the specs are precise enough to reproduce usable implementations across model providers and coding harnesses — not a formal multi-run scoreboard. Architecture will vary by agent; the checklist is what defines pass/fail.

The Grok and Antigravity rows are backed by an actual artifact — see spec-cleanroom, which archives both agents' full source and tests built from these same specs, plus a cross-comparison review of the two implementations. The Claude Code run's output wasn't preserved as a separate artifact.

Architecture docs — browsing only, not for cleanroom builds

Each spec'd app also has an architecture.html mapping the private reference implementation's actual file layout and function names. Published for human/portfolio browsing only — deliberately kept out of the cleanroom-build path. Handing it to a coding agent would bias the build toward the original layout instead of testing whether the spec alone is sufficient.

License

MIT (LICENSE in the repo).