6 posts tagged with "Spec-first"

Most teams already write down what they are going to build. They open a ticket: "As a user I want a search box, so that I can find pets quickly." That sentence has served software teams for twenty years. At Conduction we write specs instead. The reason is simple: the developer reading the ticket is now an LLM, not a colleague, and an LLM needs a different kind of brief. This opener explains why, before the rest of the series gets into the how.

A spec tells you what one feature must do. But "build a search box" leaves a hundred questions unanswered that have nothing to do with search. Which data layer? Vue 2 or Vue 3? Where do modals live? Which licence header? Answering those per spec would be madness, and an AI would answer them differently every time. That is what ADRs are for. They are the standing context that every spec is built on top of. This part explains what they are, how they are written, and how Conduction splits them across the fleet.

In Part 1 you learned that a scenario describes behaviour in GIVEN / WHEN / THEN form. In Part 2 you wrote one. This part closes the loop. A scenario is a test you have not run yet, and OpenSpec gives you a mechanical way to prove that every scenario in a spec is exercised by a real browser test. The @e2e annotation and the gate that enforces it are what turn "write a spec" into a safe sandbox for AI. They are also the single biggest thing that separates spec coding from vibe coding.

Heads up — this is an optional, situational tutorial. Most developers will never need to run a retrofit. Day-to-day work in a Conduction app — writing changes, implementing tasks, opening PRs — doesn't touch any of the commands below. You can finish Parts 1 + 2 and go straight to the Hydra series or the Claude skills series without losing anything.

This part is only relevant in one specific case: an older Conduction app needs to be brought up to date with the current OpenSpec convention after the fact. A small number of our apps were built before openspec/specs/ and the @spec-tag convention existed — they have working code, but no specs and no annotations pointing from code to requirements. If one of those apps ever has to be brought into line with the convention, this is the playbook for it. We work through the retrofit playbook end to end.

OpenSpec is a lightweight framework for spec-driven development: first write down what a feature should do, only then write the code. In this twelve-minute module you'll learn what OpenSpec is, which concepts it builds on, and why we use it underneath almost every Conduction project. By the end you're ready for Part 2, where you'll actually write your first change.

Want the bigger picture first? For where this idea comes from and why it matters more in an AI world, start with Part 0: Why spec-first. This part dives straight into the concepts.

Your starting point. You don't need to build anything special to follow along. Just clone any Conduction app and read along in its openspec/ folder:

git clone https://codeberg.org/Conduction/openregister.git
cd openregister && git checkout development
ls openspec/          # specs/, changes/, changes/archive/

development is the branch active work happens on. We won't change anything in this part — we're just looking.

Time to see OpenSpec in action. In this part you'll create your first real change inside a Conduction project — from empty folder, through a spec-delta with a requirement and scenario, to a validated proposal ready for implementation. We do that with the Claude Code skills /opsx-new and /opsx-ff.