Day 3: Choose your adventure

3 Days of Spec-Driven Development · Day 3 of 3 · five lessons on four pages, three exercises, a wrap-up · about three hours: 180 minutes including the opener

Specs win. Fix the code, or fix the spec and cascade.

the Linked-Intent Development README (jszmajda/lid), read 2026-09-22

Two days ago you had a chat window. You now have a spec with criteria that can fail, a runner that goes to green on its own, and a critic that audits the result. Today is about handing that to five other people. You will meet three spec frameworks, install exactly one, run one deliberately vague feature brief through it, take a late requirement on the chin, and leave with a comparison card your team can read without taking this course. Pick your track in Lesson 3; your choice sticks for the rest of the day.

Watch this first

Before you start

Day 3 works in day3-work, a copy of your lane at the course root. The shipped sandbox/ is never edited, so what a track wrote is a diff against it. Exercise 1 opens with this block, pasted from the course root. It makes work/ for your answers, copies your lane to day3-work, moves you into it, and copies in the Change C brief and the blank map as ../work/map.md, never over a map you have started. If day3-work already exists, run rm -rf day3-work first: cp -R into an existing folder nests a second copy inside it.

mkdir -p work && cp -R sandbox/swift day3-work && cd day3-work
cp ../day-3-choose-your-adventure/starter/change-c-brief.md .
{ [ -f ../work/map.md ] || cp ../day-3-choose-your-adventure/starter/map-template.md ../work/map.md; }
ls change-c-brief.md ../work/map.md

mkdir -p work && cp -R sandbox/kotlin day3-work && cd day3-work
cp ../day-3-choose-your-adventure/starter/change-c-brief.md .
{ [ -f ../work/map.md ] || cp ../day-3-choose-your-adventure/starter/map-template.md ../work/map.md; }
ls change-c-brief.md ../work/map.md

Start Claude Code there with claude. day3-work is the day's project root, the folder holding CLAUDE.md, read from ./CLAUDE.md, and your framework is initialized in it. Setup blocks are pasted from the course root; every other Day 3 command runs from inside day3-work. Starters are at ../day-3-choose-your-adventure/starter/; answers go in ../work/.

To reset, quit Claude Code, then from inside day3-work run your lane's line.

cd .. && rm -rf day3-work && cp -R sandbox/swift day3-work && cd day3-work

cd .. && rm -rf day3-work && cp -R sandbox/kotlin day3-work && cd day3-work

It re-copies the shipped lane, leaves you inside it, and leaves ../work/ untouched. Then, in Exercise 1 or 2, re-run that page's setup copy lines (everything after its cd day3-work) and your track's install-and-init steps from Exercise 1. OpenSpec on your PATH and the LID plugins at user scope survive the reset; BMAD lives in the project, so you run its installer again. A fresh copy has no Change C, so in Exercise 3 run your track's install-and-init from Exercise 1, then Exercise 2 through its self-check (its checkpoint saves time), then cd .. and Exercise 3's setup block. Do not reset between exercises: each one continues from what the one before left.

The day in order

Eight pages after the video. Lessons 1 and 2 share a page, so the five lessons take four pages.

1. Lessons 1 and 2: Why a framework, and what they share 16 min
2. Lesson 3: Meet the three 12 min
3. Exercise 1: Install your track and map what it wrote 25 min
4. Exercise 2: Run Change C through your track 55 min
5. Lesson 4: Pick by the failure you actually have 15 min
6. Exercise 3: A late change, then the card you hand your team 25 min
7. Lesson 5: Adopting without a rewrite 12 min
8. Day 3 wrap-up: recap, ten review questions, three challenges 10 min

Ticks need JavaScript and stay in this browser.

Starter files

Each exercise copies the file it needs from ../day-3-choose-your-adventure/starter/ at the step that needs it, so your framework never reads Change C's acceptance suite while it plans and builds. Exercise 3's two late-change assertions are the exception: its setup copies them in, your framework can read them, and step 3's red, before any code changes, proves they bite.

• README.md — what each file is for, and which step copies it where.
• change-c-brief.md — the statement-periods feature brief, with two ambiguities it does not mark.
• map-template.md — the blank five-question map Exercise 1 copies to ../work/map.md.
• fixtures/cycle-config.tsv — the cycle-configuration fixture, identical in both lanes.
• acceptance/ — the hidden Change C suite and the two late-change assertions, in both lanes.
• late-change.md — the three-sentence late requirement for Exercise 3.
• comparison-card.md — the blank eight-question card.
• checkpoints/ — each track's reference planning artifacts, for when planning overruns Exercise 2's 25-minute checkpoint.
• vendored/ — the offline snapshot of each framework, for a blocked network.
• track-notes/ and answers/ — page material, never copied into day3-work.

Videos and reading

No video is required to finish an exercise.

• Recommended videos — the opener and the lesson clips, with segments.
• Reading — the articles, docs and repositories behind the lessons.

Sources

• The day's quote is from the Linked-Intent Development README, read 2026-09-22.
• cc-core-08 — a project's CLAUDE.md is read from ./CLAUDE.md or ./.claude/CLAUDE.md, from Memory.
• cc-core-31, cc-core-32 — claude --version, and the version checked against here, Claude Code 2.1.280 on 2026-09-22, from the Claude Code changelog.
• openspec-01 — the npm install, from OpenSpec installation; openspec-03 — Node.js 20.19.0 or later, from the npm registry entry; openspec-04 — release 1.13.1, dated 2026-09-17, from the OpenSpec releases.
• lid-01, lid-02, lid-03 — LID's marketplace is added and its two plugins installed in Claude Code with /plugin, from the LID repository; lid-obs-01 — commit 831c1959 was still the tip of its main branch, observed on the build machine on 2026-09-22; lid-obs-02 — the LID plugins install at user scope, observed on the build machine on 2026-09-22.
• bmad-01, bmad-05 — the install command and Node.js 20.12 or later, from Install BMAD; bmad-06 — uv with Python 3.11 or later is required, and bmad-build and bmad-build-auto halt without it, from the BMAD changelog (v6.11.0), and the Python 3.11 or later from the requires-python line of _bmad/scripts/render_skill.py in the vendored bmad-6.12.0 snapshot, whose SNAPSHOT.md says it cannot supply uv; bmad-obs-01 — the npm package was at 6.12.0 on its latest tag, observed on the build machine on 2026-09-22; bmad-obs-05 — a BMAD install writes its _bmad/ tree and 29 skills under .claude/skills/ into the project, observed on the build machine on 2026-09-22.
• The setup block above was run on the build machine on 2026-09-23, once per lane, each from its own fresh copy of the course root.