the fork report: OPENSPEC by Fission-AI
write the spec before the AI writes the code
the signal
i've been writing specs before code on every project i've touched this year. not because i'm disciplined. because the alternative, talking my way into a feature with an AI assistant turn-by-turn, kept producing work i had to throw out. the spec, written first and stored as a real document, was the only thing that survived contact with the model.
that workflow has a name: SDD (spec-driven development). and OPENSPEC is the framework that formalizes it. 3.1k+ forks. 44.1k+ stars.
the timing is a little funny. a lot of people converged on the same idea at once. you probably found your way to it through frustration, the same way i did. OpenSpec is what shows up when you arrive.
what it is
OPENSPEC is a lightweight layer that sits on top of your AI coding assistant. it introduces a structured workflow with explicit artifacts:
1. proposal (what are we building and why?)
2. spec (exact behavior, interfaces, constraints)
3. design (architecture, data flows, key decisions)
4. tasks (discrete implementation steps)
you kick off a feature by running `/opsx:propose`. OpenSpec guides you through filling out those artifacts. then you run `/opsx:apply` and your AI coding assistant (cursor, Claude Code, copilot) implements the tasks against the spec.
the key concept is delta specs. when you're adding a feature, you don't rewrite the entire product spec. you write a spec for what's changing: what's being added, modified, or removed. delta specs are small, focused, and version-controlled as files in your repo.
that last part matters. your specs live in git alongside your code. when something breaks, you can read the spec for the feature that introduced the bug. when you onboard someone new, you give them the spec directory, not just the code.
how it compares
OPENSPEC — spec as artifact: yes · version-controlled: yes (git) · works with any AI assistant: yes · phase separation: explicit (propose then apply)
github/spec-kit — spec as artifact: yes · version-controlled: yes · works with any AI assistant: yes · phase separation: rigid phase gates
Claude Code plan mode — spec as artifact: sort of · version-controlled: no · works with any AI assistant: no (claude only) · phase separation: implicit
README-driven dev — spec as artifact: partial · version-controlled: yes · works with any AI assistant: yes · phase separation: none
the closest peer is spec-kit (github's take, which i wrote about earlier this month). spec-kit is more thorough, with stricter phase gates and more ceremony. OpenSpec is lighter. you can iterate freely within a delta spec without triggering a full re-approval cycle.
Claude Code's plan mode is the most common alternative for people who use Claude Code. Claude generates a plan before coding, you approve it, it proceeds. but that plan lives in the conversation context, not as a versioned file. when the context window gets compacted or you start a new session, the plan is gone. OpenSpec externalizes that artifact so it persists.
README-driven development (write the README first, code to make it true) is the original version of this idea, but it stops at documentation. it doesn't give you a task breakdown or a structured workflow for implementing in steps.
the v1.3.1 release (April 2026) added path resolution fixes and telemetry reliability. active maintenance signal is good.
why it matters
the failure mode of AI coding assistants isn't intelligence. they can write good code. the failure mode is alignment. you ask for one thing, you get a slightly different thing, you don't notice until five features later when the divergence has compounded.
the root cause is usually that there was never a written spec. the AI inferred what you wanted from a conversational prompt, made reasonable but wrong assumptions, and coded to those assumptions. every subsequent conversation had to re-establish context.
OPENSPEC breaks the cycle by making the spec the artifact that persists, not the conversation. the AI implements the spec. you review the spec, not just the output. when something doesn't match, you have a document to point at, not a vague memory of what you asked for.
there's also a collaboration angle. if you're working with other builders, "here's the spec" is a more reliable handoff than "here's the conversation transcript." specs are meant to be read. conversation transcripts are not.
the meta-observation: most things i've shipped this year started with a spec, not a chat. the spec came first. the code followed.
what you can do with it today
5-minute win: install OpenSpec, run `/opsx:propose` on the next small feature you're planning to build. fill out the proposal and spec sections before touching code. notice how much clearer your own thinking gets when you have to write down the constraints before you start.
the build: for any feature over a day of work, require a delta spec. commit the spec to your repo before writing any implementation code. use the spec as your AI coding assistant's prompt. see how much less back-and-forth you need.
the retrospective: look at the last feature that took longer than expected or broke something. ask whether a spec would have caught the misalignment earlier. almost always, the answer is yes.
OpenSpec is not magic. it's discipline with tooling. but the tooling makes the discipline easier to keep.
links for the lab:
OPENSPEC on github: source, install guide, and the spec format documentation.
OpenSpec getting started guide: the walkthrough from proposal to implementation.
OPENSPEC docs directory: commands, CLI reference, supported tools.
spec-kit discussion in Fabric: the community converging on spec-driven approaches from multiple angles.
my selenium post: another "old discipline, new context" fork-report. spec-first dev is the same pattern applied to AI coding.
keep on forkin
