🚀 Use this on your next project Take-home

In the workshop you did spec-driven development by hand — you settled the problem, wrote a spec and a plan as files, got sign-off before code, and corrected a wrong plan cheaply. This page hands you the tool that does exactly that, with structure and a repeatable lifecycle: OpenSpec.

You can follow this on your own, at your own pace — it doesn't depend on anything you saw on the beamer. Everything you need is right here.

1 · Why OpenSpec (and not something heavier)

Five frameworks reinvented the same four files. OpenSpec is the one we reach for because it fits how you already work:

  • One install, no second runtime. It's a single Node CLI — no Python/uv toolchain to set up first.
  • It plugs straight into OpenCode (the free agent from the workshop) with one command.
  • It leaves a paper trail — every change is a set of files in your repo the agent reads each session, not a chat that vanishes.

OpenSpec doesn't replace the fundamentals — it operationalises them. Everything below maps 1:1 to what you already did by hand.

2 · Install & wire it to OpenCode

Works the same on Ubuntu, macOS and Windows — it's just Node. You need Node.js 18+ (the same prerequisite OpenCode uses).

Install the CLI (global):

Copy
npm install -g openspec
openspec --version

Initialise it in your project and wire the OpenCode agent in one step:

Copy
cd your-project
openspec init --tools opencode

This creates an openspec/ folder and drops slash-commands into OpenCode, so the agent knows how to propose, apply and archive changes. Open OpenCode in the same folder and the commands are there.

3 · The lifecycle — the same three moves, every time

You already know these; OpenSpec just gives them names and a place to live.

① Propose

Describe what and why. OpenSpec writes a proposal, a design, spec requirements and a tasks list — your spec + plan, before code. Review here — changing your mind costs a paragraph.

② Apply

Work the tasks one by one with the agent, ticking - [ ] → - [x]. This is the build — grounded in files the agent re-reads each session.

③ Archive

openspec archive folds the change into your baseline specs. Your specs/ become the living source of truth the next change builds on.

How it maps to the workshop, beat for beat:

Placement default for reliable agent reads→/agents.md at repo root + work files in /.specification/changes/feature-name/ (mention this path in session chat)
Wrote spec.md — what & why→proposal + spec requirements
"Done means…" block→spec #### Scenarios
Wrote plan.md, grounded→design
Plan review gate before code→review the proposal before apply
Built task by task→tasks (- [ ] → - [x])
Reflected · done vs not-done→openspec archive → baseline

4 · Three ideas the lifecycle leans on

The four artifacts you already know, plus these three, are everything OpenSpec is about. Get these and nothing feels like magic.

Change as a unit

A change is one bounded piece of work — a proposal, its specs, its tasks — that you propose, apply, then archive. Not "some files", a discrete unit with a lifecycle.

Delta specs

A change says what's ADDED, MODIFIED or REMOVED against the current baseline — you don't rewrite the whole spec, you describe the diff.

Archive to baseline

Archiving folds the delta into your specs/, which become the source of truth. The next change starts from that updated baseline — the record compounds over the project.

5 · A real worked example to copy

This whole workshop — the pages you're reading right now — was built with OpenSpec. The change that produced it is in this very repository:

Copy
openspec/changes/workshop-sdd/

Recommended structure in your own repo: keep /agents.md at root, and keep change-specific files in /.specification/changes/feature-name/. When starting a session, include that folder path in chat.

Open it and read a real, non-toy example front to back:

  • proposal.md — the problem and scope
  • design.md — the decisions and trade-offs (including this take-home page)
  • specs/…/spec.md — requirements with #### Scenarios (the "done" definition)
  • tasks.md — the units of work, ticked off as they were built

Steal the shape. Point your agent at it and say "structure my change like this one".

6 · When to reach for it

Not every task needs a change. Use the full lifecycle when the work is worth auditability, governance, or parallelisation; skip it for prototypes, one-line fixes and exploration.

Simple tasks need a prompt. Complex ones need a spec.

Copied to clipboard!