A0.2 · framework · design 2
The four artifacts
Every rung is carried by four plain-text artifacts, and each answers exactly one question: a roadmap, a spec, the user stories, and the agent brief. Four files, four questions, no overlap. Select one to see what it answers.
The four artifacts · select one
What each artifact answers
Each artifact answers exactly one question. The roadmap.md answers what ships, and
in what order. The spec answers what we build and how we know it is right. The
user stories answer what the user gets, as concrete acceptance criteria. The
agent brief — an .llms.md file — answers how the agent
builds it. Four files, four questions, no overlap.
Keeping the questions separate keeps the artifacts honest. A spec that also lists build steps drifts from the behaviour it should pin down; a brief that re-states acceptance criteria duplicates the stories and rots when they change. Each artifact is derived from, or planned against, the spec — so the four stay consistent by construction, not by diligence.
- roadmap.md
- The delivery plan: the chapter's rungs and their order. Answers what ships, and when. Re-planned freely.
- spec
- The definition and proof of one rung: the behaviour to build and the invariants that must hold. The single source of truth.
- user stories
- Acceptance criteria derived from the spec — Given/When/Then examples a person can read and sign off.
- agent brief (.llms.md)
- The implementation plan for a Claude agent: references, execution topology, and agent stories. Answers how it gets built.
The triad: one spec, two derived
Three of the four artifacts move together as a triad: the spec, its user stories, and its agent brief. The spec is the contract; the stories are how a person accepts it; the brief is how the agent builds it. Stories and brief are both derived from the spec, which is why a rung can be correct by definition — the acceptance a human signs and the plan the agent follows come from the same source.
The fourth artifact, the roadmap, sits outside the triad: it decides which rung the triad is for, and when. Select a face of the triad to see the question it answers.
The triad · select a face
Four artifacts, one question each, and a triad that cannot disagree with itself: that is how a rung stays defined, accepted, and built from a single source.
References
Primary sources for this design, and where it connects in the course.
Sources
- The
llms.txtconvention — machine-readable, agent-facing documentation. - Cohn, M. — User Stories Applied — stories and their acceptance criteria.
- Adzic, G. — Specification by Example — deriving checks from a shared spec.