demo-doc: one house format for every demo design document

Every demo on this site is written up the same way. Once you've learned the format you can skim any of them: where the memory lives, how a request flows, how to run it, and how to tell it works.

demo-doc is the skill that enforces the format. Ask Claude to "document this demo" or "build a demo of X". It reads the code, fills the ten sections, and writes three outputs from one source.

The ten sections

Purpose & scope · Use cases · Architecture · Key flows · Backend design · Data model · Frontend design · Project layout · Run & verify · Next steps.

The order never changes. When a section doesn't apply it stays in place with a one-line "Not applicable", so section 9 is always Run & verify in every demo.

Why the CoALA strip

Each document opens with a five-stage strip that maps the demo onto the CoALA agent framework: which store is semantic memory, which call is retrieval, and what ends up in working memory. That strip ties the demos together. A RAG app and an agent loop end up described in the same vocabulary.

“A wrong port or model name in a design doc is worse than a gap. The skill writes TBD instead of guessing.”

Hand-drawn, on purpose

The figures are SVGs drawn by hand, with wobbly lines, handwriting labels, and one highlighted path per figure: the one the section is about. They follow the artifact-diagramming rules: draw the mechanism, label every arrow, and make one claim per figure. The rules sit in the skill's references/diagrams.md. The same files appear on GitHub, in the HTML page and here, and they switch to dark mode along with the page.

Built to be forked

Every demo document links to its repository: View code, Fork, Report an issue, Contribute. Run & verify starts with git clone, and Next steps closes with a Contribute note. The ideas table doubles as a list of first pull requests.

See it in use

The RAG demo on this site was written with this format.