GroningenPHP - Spec-Driven Development: Music Sequencer

🎛️ Interactive Music Sequencer Case B

Build a browser beat-machine: four tracks — drums, vocals, melody, rhythms — that you turn on and off with clear buttons, sliders and switches. Simple to play with, satisfying to demo. You'll build it spec-first.

What you'll make A looping sequencer with four toggleable tracks and obvious controls.

The real lesson How settling intent → spec → plan → tasks before code makes review cheap and mistakes early.

The seven steps you'll follow

Every case runs the same seven steps, in two phases. The first four happen before a single line of code exists — that's the whole point. How far you push the build is up to you.

Before code you decide

1Intentwhat problem
2Specwhat & why
3Plan+ sign-off
4Tasksunits of work

After code agent · gate · human

5Implementagent writes
6Verifya check gates it
7Reviewa human reads

Guided happy path everyone starts here

Follow the steps in order. Each one ends with a checkpoint — don't move on until you see it.

Phase 1 · Before code

You decide

Steps 1–4 all happen before a single line of code exists. This is where the thinking lives.

Intent — what problem, is it even worth a spec?

In your workshop folder, start opencode. Ask the facilitator's question: "Could I one-shot this with a single prompt?" Four synced tracks, a loop clock, and on/off controls have enough moving parts that the answer is no. Start by creating agents.md (example) at repo root so rules are explicit: PHP-first where backend/domain logic exists, PSR-aligned standards, minimal JS unless clearly needed, and DDEV for dev/test.

✅ Checkpoint: you can say, in one sentence, what it is, and /agents.md exists with project rules.

Spec — what & why, as a file

Create spec.md (example) in /.specification/changes/feature-name/ — a file the agent reads every session, not a throwaway prompt. Fill in the skeleton; ask the agent to sharpen it, but you own the decisions.

Copy

# spec.md — Sequencer

## Problem
People want to make a beat in seconds, with no music theory.

## Why
A grid of on/off cells is instantly understandable and fun to demo.

## Boundaries
- Four tracks: drums, vocals, melody, rhythms
- Each track toggles on/off with a clear button/switch
- A shared loop plays enabled tracks in time
- One tempo slider

## Done means
Toggling a track on/off is instantly audible in the running loop.

✅ Checkpoint: spec.md exists in /.specification/changes/feature-name/ and contains only what and why — no implementation.

Plan — how, grounded, then signed off

Switch OpenCode to Plan mode (Tab). Ask it to write plan.md (example) in /.specification/changes/feature-name/: which files change, in what order, and the check that proves each part. Keep it grounded and aligned with agents.md: for this case JS is justified for browser audio, but keep it minimal outside that core, and run checks via DDEV.

Copy

We're building the app in spec.md. Stay in plan mode.
Write plan.md: files to create, in order, and for each step the
check that proves it works (run checks through DDEV). Use JS for the
audio loop and controls, keep everything else minimal. Do NOT write
code yet.

Plan review gate (3 min). Show your plan.md to a facilitator or a neighbour. "Is this plan right?" Changing your mind here costs a paragraph; after 200 lines it costs a rewrite. This is where review moved to — the moment the whole method is about.

✅ Checkpoint: plan.md is reviewed, every step names a check, and the DDEV run path is explicit.

Tasks — units of work, still no code

The last thing before code exists: turn the signed-off plan into tasks.md (example) in that same /.specification/changes/feature-name/ folder — small, ordered units the agent can execute and you can tick off. Stay in Plan mode.

Copy

Still in plan mode — no code yet. Break plan.md into tasks.md
of small tasks, in order, each one something you can verify on its
own. For example:
- [ ] a loop clock ticks at the tempo
- [ ] one track (drums) plays in time
- [ ] toggling a track on/off is audible on the next loop
- [ ] checks run in DDEV and pass

✅ Checkpoint: you have an ordered list of small tasks and nothing has been coded yet. Only now do you leave Plan mode.

Phase 2 · After code

Agent writes · a check gates it · a human reads it

Only now does code appear. You already made every decision — the rest is execution and checking.

Implement — the agent writes

Press Tab back to Build mode and let the agent work tasks.md one by one. Keep to agents.md: use JS where it is core to the sequencer, avoid unnecessary JS elsewhere, and run the dev loop in DDEV. Start with the loop clock and one track, then add the rest. Give the agent the acceptance scenario, not a testing lecture:

Copy

Add a check for this behaviour:
WHEN the drums track is switched off
THEN the scheduler produces no drum hits on the next loop.
Write it as a runnable test, then implement until it passes.

✅ Checkpoint (MVP): a loop is playing, and toggling any of the four tracks is instantly audible.

Verify — a check gates it, prose doesn't

Pick one rule that matters and make it a deterministic check, not a polite sentence in the spec. This is the gate the agent has to get past. Run it in DDEV so your check matches the team environment.

Prose (weak)"tempo should stay in a sane range"

Sensor (real)a test that rejects a tempo outside 40–240 BPM

✅ Checkpoint: you have at least one test that goes red when the rule is broken.

Review — a human reads it

You already agreed the plan, so this read is quick — you're checking the agent honoured it, not meeting the design for the first time. Also confirm consistency with your artifacts: agents.md rules followed, spec.md intent preserved, tasks.md executed, and DDEV checks green. This is where you'll often notice the plan was wrong. That's not failure — it's the point, and because you're at review (not release) the fix is a paragraph. A classic one for this case:

Plan said "create each track's audio node when the user clicks it on"

Reality building nodes on click drifts out of time and stutters mid-loop

Fix pre-build the audio graph up front; toggles just mute/unmute — one line in plan.md

Amend plan.md and let the agent redo that step. Then record what you couldn't finish — a plan that names its gaps is one a reviewer can trust:

Copy

## Done
- four tracks toggle in time, tempo slider works

## Not done, and why
- per-step pattern editing — out of scope for the MVP today

✅ Checkpoint: plan.md shows the corrected step and a Done / Not-done block.

"Waterfall's flaw was never having a plan. It was waiting months to find out the plan was wrong."

Stretch goals finished early? go deeper

All optional. Add each as a new spec requirement + plan step first — keep practising the loop.

Stop-gate — a check so the agent can't declare itself "done" while any test is red.
Per-track volume & mute — sliders wired to gain nodes.
Step grid — a 16-step pattern editor per track instead of a simple on/off.
Randomise / presets — one-click grooves that fill the grid.
Save & share a beat — encode the pattern in the URL.

Reflect

You wrote about a page of markdown before any code. Was it worth it here? Would it be worth it for a one-line CSS fix?

Simple tasks need a prompt. Complex ones need a spec. Writing the decision down turns a six-month bet into an experiment you can fail in an afternoon.

Level up — see it as a tool Optional · if time permits

Everything you just did by hand, there's a tool for: OpenSpec. Your facilitator may demo this on the beamer — and if the clock beat us to it, no problem, the take-home page below has the whole thing.

File placement defaults→/agents.md at root + change files in /.specification/changes/feature-name/ (include the path in session chat)

Your agents.md rules (PHP-first, minimal JS, DDEV)→carried into proposal.md + design.md

Your spec.md — what & why→openspec propose

Your "Done means…"→spec #### Scenarios

Your plan.md (files, order, checks)→design.md implementation plan

Your tasks.md checklist→tasks.md in change folder (- [ ] → - [x])

Building task by task→openspec apply

Reflect · spec becomes the truth→openspec archive

Archive result→delta folded into baseline openspec/specs/

Want to run the full lifecycle on your own project? The take-home guide walks you through install → propose → apply → archive, and points at the real change that built this workshop.

Use this on your next project