GroningenPHP - Spec-Driven Development: Trivia App

🧠 Trivia App Case A

Build a Kahoot-style trivia game a host can run in a meeting: people join from their phones with a code, answer questions, and watch their score climb. You'll build it spec-first — the plan gets settled before a single line of code.

What you'll make A joinable quiz with seeded categories, custom questions, and live scoring.

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 yourself the facilitator's question: "Could I one-shot this with a single prompt?" Joining + categories + scoring has enough moving parts that the answer is no. Start by creating agents.md (example) at repo root so your defaults are explicit: PHP-first, PSR-aligned, minimal JS, and DDEV as the dev/test loop.

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

Spec — what & why, as a file

Create spec.md (example) in /.specification/changes/feature-name/. This is a file the agent reads every session, not a chat message that vanishes. Fill in the skeleton — paste it to your agent and ask it to help you sharpen it, but you own the decisions.

Copy

# spec.md — Trivia

## Problem
A host needs a low-friction quiz for a meeting or video call.

## Why
Existing tools need accounts or installs; we want "join with a code".

## Boundaries
- 5–10 seeded categories, provided up front
- Host can add custom questions
- Players join with a short code, answer, and see their score

## Done means
A joiner submits an answer and their score updates on screen.

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

Plan — how, grounded, then signed off

Switch OpenCode to Plan mode (press 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 works. Keep it grounded and aligned with agents.md: PHP-first structure, JS only where it adds clear value, and checks you run via DDEV.

Copy

We're building the app in spec.md. Stay in plan mode.
Write plan.md: the files to create, in order, and for each step
the command or check that proves it works (run checks through DDEV).
Keep it small — a PHP entry point plus a questions store is fine.
Use JS only where it clearly improves UX. Do NOT write code yet.

Plan review gate (3 min). Show your plan.md to a facilitator or the person next to you. "Is this plan right?" Changing your mind here costs a paragraph. Changing it after 200 lines of code 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:
- [ ] questions store loads the seeded JSON
- [ ] host can start a session and get a join code
- [ ] a joiner submits an answer and their score updates
- [ ] 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 it consistent with agents.md: PHP-first for backend/domain work, JS only where it helps UX, and run the dev loop in DDEV. Grab the seeded questions so nobody stalls on content:

trivia-questions.json — 8 categories, ready to import.

When you specify behaviour, give the agent the acceptance scenario (the "oracle"), not a lecture on testing:

Copy

Add a check for this behaviour:
WHEN a joiner submits the correct answer
THEN their score increases by the question's points.
Write it as a runnable test, then implement until it passes.

✅ Checkpoint (MVP): you can open the app, join with a code from a second browser tab/phone, answer a seeded question, and see the score change.

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)"please don't allow empty questions"

Sensor (real)a test/validator that rejects an empty question

✅ 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 "the join code lives in the client, baked in when the app is built"

Reality the client bundle is built without it → the code can never arrive

Fix move the join code to the server — 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 own gaps is one a reviewer can trust:

Copy

## Done
- join-by-code, scoring, 6 seeded categories

## Not done, and why
- live presenter view — needs websockets, out of scope 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.
Timed rounds & leaderboard — countdown per question, ranked results at the end.
Import questions from CSV — with a validator that rejects malformed rows.
Custom category — let the host add a category, enforced by a test for its rules.
Live presenter view — the "not done" item from the Review step, via websockets/SSE.

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