A4 · chapter overview
The spec layer
A roadmap ordered the work; a spec defines it. The spec layer is what we build and how we accept it — examples that double as checks, invariants that must always hold, and a traceability chain that makes “done” a closure rather than an opinion.
A3 produced a delivery plan: thin-but-robust rungs, each pointing at a spec it does not contain. This chapter is that spec — how to write one precisely enough that a Claude Author can build it and an Operator can accept it by proof, correct by definition. Every technique lands on the Portal's real rung triads — a spec, its stories, and the brief an agent builds from.
Where we are
The course is one argument carried across eight parts. The first four are now in hand: A0 framed the method, A1 made the case for thin, provable slices, A2 turned a vision into a backlog of them, and A3 planned that backlog's delivery as a roadmap. A4 is where each rung the roadmap points at becomes a precise, provable specification. The remaining parts — the agent brief, reliability, and the Portal exemplar — build on top of it.
The arc below walks the eight parts. Select one and the readout reports its title, what it delivers, and whether it is built — the same orientation this landing exists to give. The default selection is A4, the part you are reading.
The course arc — eight parts, A0 to A7
A0–A3 settled why, what, which slices, and in what order they ship; A4 settles what each slice is and how it is proven. The spec is the single source of truth the roadmap points at.
The journey so far
A0 — Foundations framed the method in three questions: why an agile agent workflow works, what we are building, and who does the work. It named the two roles the rest of the course runs on — the human Operator (judgement, decomposition, acceptance) and the Claude Author (fast, well-specified implementation).
A1 — Why an Agile Agent Workflow made the case. Neither no-plan vibe-coding nor an all-plan big-bang ships reliable software; the unit that does is a thin, provable slice. A1.05 — Correct by definition named what “done” means — a closure over traced, executed checks — the idea A4.6 makes operational, and A1.04 — Two layers drew the line: the roadmap is how we deliver, the spec is what we build and prove.
A2 — Decomposition produced the backlog: value not tasks, the Connextra form, INVEST, Given/When/Then acceptance, splitting, and ordering into a value ladder. A3 — The roadmap layer then planned that backlog's delivery — thin-but-robust rungs grouped into milestones, each pointing at a spec. A4 writes the spec each rung points at.
The principle
A roadmap rung names a slice and points at a spec. It says deliver this next, but it does not define what the slice is, or how anyone would know it is done.
On the Portal
A rung's spec triad — f6.N.md, f6.N.stories.md,
f6.N.llms.md — defines the slice by example, states the invariants it must
never break, and traces every deliverable to an accepting check.
The roadmap answers when a slice ships; the spec answers what it is and how it is proven — and feedback edits the spec, never the built page.
The spec layer, in five questions
The spec layer is a small set of artifacts with a single job: define a slice precisely enough to be built by an agent and accepted by proof. Five questions fix what it is, why it exists, who owns it, when it changes, and how it operates — the deep overview the seven modules then unpack.
.stories.md) — the single source of truth for
what we build and prove, written as worked examples, not abstract requirements.Each question is unpacked across the seven modules below: by-example and the-triad take the What; spec-anatomy the How of writing one; to-stories and invariants the What-and-Why of proof; traceability the closure; and the workshop runs the whole sequence on the Portal's engine.
The chapter modules: A4.1–A4.7
Seven teaching modules carry the spec layer end to end — from examples-as-specification to a worked spec of the Portal's engine. They build in order: making examples the specification, the spec triad, the anatomy of a spec, deriving the stories file, invariants, the traceability chain that closes “done”, and the workshop that specifies a real chapter. Every example is verbatim from the Portal's real rung triads.
Specification by Example
Concrete examples become the specification — ambiguity removed before a line of code, documentation that cannot drift from the system.
The triad: spec, stories, agent brief
Which artifact answers which question — what & why & done, who wants what, how to build with proof gates.
Anatomy of a spec
A real spec read section by section: Goal, Rationale, Scope, Deliverables, Invariants, Definition of Done — constraining the build without over-specifying.
From stories to a .stories.md
Deriving the stories file from the spec, so every deliverable is realized by a story and every story names the invariants it exercises.
Invariants
Properties that must always hold — an invariant (true for every value, always) told apart from an acceptance check (true for one scenario).
Traceability — correct by definition
The chain from deliverable to story to check & invariant that makes completion close by a rule, not a claim.
Workshop — specifying Portal's engine
The full sequence run on the engine chapter: a spec and a .stories.md whose traceability chain closes.
Each module is a hub with its own deep-dive subpages — the same shape A1, A2, and A3 take. The modules are being authored now; this landing links each one as it ships. Until then, revisit A3 — The roadmap layer, whose rungs point at the specs this chapter defines.
References
The sources this chapter draws on for examples-as-specification, stories, and acceptance, and where the layers it sits between are defined in the course.
Sources
- Adzic, G. — Specification by Example — concrete examples as the executable specification; living documentation that cannot drift.
- Cohn, M. — User Stories Applied — stories as the conversation a spec records, and the acceptance that closes them.
- Gherkin reference — Given/When/Then as the structured form an example-as-check takes.
Related in this course
- A3 · The roadmap layer — the rungs that point at the specs this chapter writes.
- A1.05 · Correct by definition — the closure A4.6 makes operational.
- A1.04 · Two layers: roadmap and specs — the roadmap/spec separation A4 expands.
- A2.04 · Acceptance with Given/When/Then — the stories a spec is built from.
- A0.2.2 · The four artifacts — the per-rung artifacts, of which the spec is the source of truth.
- Companion · Phoenix (F6) — the real chapter whose rung triads are this chapter's worked examples.
- Companion · Functional Programming in Elixir — the Portal’s Elixir and OTP foundations.