Part 3 of our series on intent-driven development. Read Part 1 (spec-driven development with Kiro) and Part 2 (mastering the CLAUDE.md file) first. 

Part 1 of this series established the principle: in AI-assisted development, the spec is the source of truth, not the code. Part 2 covered the CLAUDE.md file — the context layer that ensures every AI session starts from the same shared understanding of the project. 

This post is where it becomes concrete. We'll walk through exactly how we used OpenSpec with Claude Code on a real client project — from the first proposal to a deployed feature. What each stage produced. Where human review happened. What the AI did, and what it didn't. 

No lines of code were written manually. Here's the honest account of what that actually looks like. 

Why OpenSpec 

Our team had been using a different spec tool prior to this project — Spekit. It worked. But when comparing the two in practice, OpenSpec had meaningful advantages: cleaner folder structures, MD files generated correctly and consistently, and critically, a single workflow that handles both greenfield builds (starting from scratch) and brownfield modernisation (upgrading an existing system) without needing a separate approach for each. 

The transition made sense. And on the client project, we had the right conditions to run the full workflow properly: a defined stack, a detailed brief, and a lead architect who had already thought through the folder structure, the standards, and the constraints. 

OpenSpec runs on Node.js 20 or above. Installation is global, setup takes minutes, and the entry point is a single command: openspec init. 

Stage 0: Before the First Proposal 

Before anything in OpenSpec runs, two things have to exist. 

The CLAUDE.md file. As covered in Part 2, this is the project brief the AI reads at the start of every session. This file captured the approved tech stack, the folder structure the lead architect defined, the API data flow and fallback behaviour, MCP configuration, and the explicit list of things the AI must not do. It was written before the first proposal was raised — not after. 

The baseline folder structure. The project's folder conventions were locked in advance. Everything had to flow from a defined common base. Deviations weren't acceptable. The AI needed to know this before it touched anything, which is why it was in the CLAUDE.md file rather than mentioned once in a prompt and forgotten. 

With those in place, the workflow could run cleanly. Without them, the stages below produce something — but not necessarily what you intended. 

Stage 1: The Proposal 

The OpenSpec workflow begins with a proposal. Not a chat prompt — a structured description of what you intend to build, which the tool uses to generate a spec file. 

For a demonstration of the basic flow, the proposal was minimal: "Create a basic web page for OpenSpec." One headline. From that input, OpenSpec generated a full proposal file — scoped requirements, selected options for language and structure, documented in the OpenSpec changes folder. The team reviewed it, confirmed it matched the intent, and the proposal became the input for the next stage. 

On the client project, the proposal was more specific. The first feature was scoped to foundation setup only: one screen, correct stack, no extra UI. The CLAUDE.md file was referenced directly. The proposal said: stay within this file, use this stack, build exactly this and nothing more. 

That constraint — narrow scope, explicit reference to the brief — is what makes the proposal useful. A broad proposal produces a broad spec. A scoped proposal produces an executable one. 

The proposal file lives inside the OpenSpec changes folder. It's reviewable, editable, and the team can update it before moving forward if something is wrong. The cost of catching a misunderstanding at the proposal stage is minutes. The cost of catching it after implementation is much higher. 

Stage 2: The Design Spec 

With the proposal approved, OpenSpec generates the design spec. This is the document that captures how the feature fits into the system — the technical decisions, the component relationships, the data flow for this specific feature. 

The spec for the foundation setup specified the view structure, how data would be fetched from the API endpoints documented in the CLAUDE.md file, and the component hierarchy that matched the approved folder structure. 

The spec is generated, not executed. There's a review step between generation and implementation. The team reads it. If the spec misrepresents the requirement, or proposes a technical approach that conflicts with the project's standards, it gets corrected here. This is the checkpoint that doesn't exist in unstructured AI development — the moment where a human confirms that the AI's interpretation of the requirement matches the actual intent before a single file is created. 

This review is where engineering judgment earns its place in the workflow. The AI generates a coherent, structured document. Whether it's the right document is a human call. 

Stage 3: The Task List 

After the spec is approved, OpenSpec generates the task list. Every file to be created, every dependency to be installed, every component to be configured — laid out in sequence, each task defined precisely enough that completion is unambiguous. 

For the web page demonstration, the task list covered HTML structure, CSS setup, folder layout, style and theming, header, and sidebar. Each item is a checkbox. The AI works through them in order, and the team can see exactly what has been done and what remains. 

The task list is the spec made executable. If a task description is ambiguous — if two developers reading it would implement different things — that ambiguity gets corrected in the task file before apply runs. Correcting a task description is trivial. Correcting implemented code that followed the wrong interpretation is not. 

Stage 4: Apply 

Apply is the command that starts implementation. It runs only after proposal, spec, and tasks have been reviewed and approved. Not automatically. Not assumed. The human team confirms that every stage is correct before the AI builds anything. 

Once apply runs, the AI works through the task list. Files are generated, code is written, configuration is set up — all of it tracked against the approved spec. When implementation is complete, every generated file traces back to an approved task, which traces back to the approved spec, which traces back to the approved proposal, which reflects the brief in the CLAUDE.md file. 

That chain is what makes the output reviewable and the process repeatable. Nothing in the codebase exists because the AI thought it was a good idea. Everything exists because a human approved it at the spec stage. 

Handling Changes Mid-Project 

Midway through the client project, a requirement changed: Keycloak was out, Auth0 was in. 

In a prompt-based workflow, this kind of change is a problem. You'd need to re-explain the authentication context, verify that Keycloak assumptions hadn't propagated into parts of the code you weren't looking at, and manually confirm that the new library was integrated consistently. 

In the OpenSpec workflow, the change is handled in two steps. First, update the CLAUDE.md file — remove Keycloak, add Auth0, update the relevant library and flow documentation. Second, raise a new proposal for the authentication change. The new proposal generates a new spec. The new spec generates new tasks. The previous state is archived before any changes run. 

The archive command is what makes this safe. Before any implementation runs, the current state is saved. If the new approach has a problem, the previous draft is intact. Branching from any prior point is always possible. This is the OpenSpec equivalent of a commit history — not just for code, but for the entire spec and task structure that produced it. 

What Still Requires Human Judgment 

The honest part of this post: the AI didn't replace engineering thinking. It replaced the typing. 

Someone had to write the CLAUDE.md file — making the decisions about stack, structure, restrictions, and data flow that the AI then executed against. Someone had to scope the proposals correctly, which requires understanding the project well enough to know what belongs in the first feature and what should wait. Someone had to review the specs and recognise when the AI's interpretation of a requirement was technically coherent but architecturally wrong. 

And someone still has to decide when requirements have changed enough to warrant a new proposal versus when the existing spec can be updated in place. That judgment isn't in the workflow — the workflow just gives you the infrastructure to act on it safely. 

The workflow removes the mechanical work. It doesn't remove the need to know what you're building. What it gives you is a process where every decision is explicit, every review is real, and the AI executes against a brief the team has actually approved — rather than a prompt that was reasonable in the moment and unclear three sessions later. 

The Brownfield Extension 

Everything above describes a greenfield build. For existing applications, the workflow adds one step at the front: explore. 

The explore command analyses the existing codebase before any changes are proposed. It maps what's there — the structure, the patterns, the components — so that proposals are written with an accurate picture of what the system already contains. Alongside this, tools like CodeGraph can be used to generate a comprehensive analysis of the codebase that feeds into the CLAUDE.md context for the modernisation project. 

The principle is the same: you don't change what you haven't understood. The explore step ensures that the AI isn't proposing to rewrite things that didn't need rewriting, or introducing patterns that conflict with what's already in production. 

The Full Picture 

Spec-driven development with OpenSpec isn't a magic shortcut. It's a governed process that happens to be fast when it's set up correctly. 

The three posts in this series cover the three layers that make it work: 

• The principle: specs are the source of truth, not code 

• The context layer: the CLAUDE.md file that grounds every session in shared project knowledge 

• The execution layer: the OpenSpec workflow that moves from proposal to implementation through explicit human review gates 

Together, these layers produce software that's traceable, consistent, and built exactly the way you specified — because you specified it before the AI was asked to build anything. 

This is the third post in our series on intent-driven AI development. Start from the beginning →