A0.2 · framework · design 1
The two-layer model
The framework has two layers, and keeping them apart is the whole discipline. A roadmap plans how a chapter's rungs ship; a spec defines each rung and proves it. Both sit on the framework-free domain core. Select a layer to see what it owns.
The framework · select a layer
Roadmap over specs
The two layers answer different questions. The roadmap layer answers how we deliver: it cuts a chapter's work into thin, robust rungs and orders them so value lands early and often. The spec layer answers what we build and how we know it is right: for each rung, a precise definition and the checks that prove it. Beneath both sits the framework-free domain core the rungs accrete into, behind the Portal facade.
They change at different rates and for different reasons. A roadmap is re-planned often — priorities move, a rung splits, an estimate slips — without touching a single definition of behaviour. A spec changes only when the behaviour itself changes, and when it does, the roadmap re-plans around it. Conflating the two is how projects drift: a plan that also defines behaviour cannot be reordered without fear, and a spec that also tracks the schedule rots the moment the schedule moves.
- Roadmap layer
- Delivery: milestones, iterations, and the order of rungs. Lives in a
roadmap.md. Re-planned freely; defines no behaviour. - Spec layer
- Definition and proof: the spec, its user stories, and the agent brief. The single source of truth; edited only by feedback.
- Domain core
- The framework-free logic the rungs build, behind the Portal facade. Every surface above depends on it; it depends on nothing above.
Deep dive: Anatomy of a roadmap.md dissects the roadmap layer in the concrete — its milestones, the rungs that ship value, and a definition of done.
The spec is the single source of truth
One rule makes the two layers stable: the spec is the single source of truth, and only feedback edits it. The roadmap plans the spec; the user stories and the agent brief are derived from it; and when a demo or a review surfaces something, the change lands in the spec — never in a story or a brief on its own. Everything downstream is regenerated from that one edit.
This is what makes a rung correct by definition. Because the stories and the brief are views of the spec, they cannot silently disagree with it; because feedback edits the spec rather than the code, the definition and the implementation stay in step. The diagram shows the four relationships — plan, derive, derive, and edit — that every rung runs through.
The four relationships · select one
Two layers, one source of truth: plan in the roadmap, define in the spec, derive the rest, and let feedback edit only the spec. That asymmetry is what keeps an agent-built system honest.
References
Primary sources for this design, and where it connects in the course.
Sources
- Humble, J. & Farley, D. — Continuous Delivery — planning delivery as a stream of thin, releasable increments.
- Beck, K. — Extreme Programming Explained — small batches and the cost-of-change curve.
- Adzic, G. — Specification by Example — a single, living source of truth.