Design docs as source

Design docs as source is a pattern in which the durable artifact is a set of natural-language design docs, and code is regenerated when a doc changes.¹ Humans edit the docs, and the code is treated as disposable when the implementation will be invalidated often.¹

Overview#

Worked examples in the spec give the generator a demonstration, not only a wish.¹ Regenerated code is checked against a hand-audited reference.¹

Mechanism#

1. The repository is kept as a directed graph of design docs.¹
2. Every human change is an edit to a doc.¹
3. The docs are written around step-by-step worked examples.¹
4. Regeneration is anchored on a small fixed spine that the agents do not invent.²
5. The regenerated artifact is checked against a reference.¹

Applications#

The pattern applies when patching an implementation costs more than regenerating it from a spec.

Limitations#

The pattern concerns implementation code. A compiled wiki is not discarded and regenerated from scratch on each ingest, and an empty code branch is not a rule for every repository.

Worked example#

In the library described in the source paper, design docs form a graph, agents regenerate the code doc by doc, tests and reference models check the build, and the orchestrator logs where the prose was unclear.¹

1. The main branch holds almost no code: it is a folder of self-contained design docs that form a dependency graph.
2. Read-only agents infer the dependency edges between docs. An orchestrating agent then walks the graph in dependency order and gives each doc to its own coding agent.
3. Each doc is written around step-by-step worked examples, and every doc that carries numbers ends with a small preset whose expected outputs are stated exactly and checked by generated tests.
4. The regenerated build must reconcile against hand-audited reference models before it replaces the previous build.
5. The orchestrator logs where agents struggled with the prose, so humans know which docs to clarify. Humans only ever edit the docs.

See also#

• Thin harness, fat skills – the thin harness
• Skillify authoring – skills as folders, not as regenerated code
• Autoresearch loop – keep-or-discard of experiments, a different loop

References#

Footnotes#

1. https://arxiv.org/abs/2609.05364 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹

2. https://x.com/omarsar0/status/2096983084956852537 ↩