Free eBook Spec-Driven AI Development

I am glad to share that an excerpt from my book, Spec-Driven Development: Engineering with Intent, is featured in Manning Publications’s new free ebook, Spec-Driven AI Development.

And it is completely free. If you are exploring Spec-Driven Development or looking to adopt AI-native software engineering, this is a great place to start.

Free eBook Spec-Driven AI Development (Manning) was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

For AI coding agents, accurately specifying your intent is the whole ballgame! Spec-Driven Development: Engineering with intent teaches you how to close the gap between what you mean and what your agents actually build.

Spec-Driven Development was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Excited to announce that my book, “Spec-Driven Development: Engineering with Intent,” is now live on Manning Publications MEAP.

Buy the book: Spec-Driven Development: Engineering with intent

The first three chapters are live, and there is a 50% off sitewide sale running from Aug 31 to Sept 14.

The book covers how we can close the gap between our ideas and AI agent-generated implementations by articulating our intent clearly using approaches including Spec-Driven Development, Ralph Loops, and more. While seeing a coding agent generate a prototype from a single-line prompt may be impressive, getting a coding agent to deliver production-ready software is a completely different ball game. In this book, we look at what it takes to engineer context effectively for coding agents so that they are not constantly bottlenecked on us, yet deliver software that is aligned with what we want.

Software engineering is ultimately about how we collaborate as a team, and this book looks at coding agents as members of the team at our table rather than just tools on the desk.

One of the advantages of MEAP is that you get to read the book as I write it. Please do share your thoughts and feedback. This will help shape the book as it evolves.

My new book about Spec-Driven Development: Engineering with intent (Manning Publications) was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

The advantage of using BDD techniques such as capturing our intent in Gherkin syntax is that we can generate Cucumber tests that then guide the coding agent to build the application.

There are two main goals in this walkthrough:

1. Using a spec which is only in text or markdown to get the coding agent to build an application that is completely aligned with our intent — and call it done only when it has actually completed.
2. Achieving spec as source, as described in Birgitta’s article on martinfowler.com about spec-driven development tools.

The overall guideline of the harness is to “make it easy to ‘do the right thing’ and work at the spec level, rather than the code level,” as mentioned in my InfoQ article on enterprise spec-driven development.

The Template

Code for this walkthrough is the behavior-driven-template. This is a subset of the intent-driven-template, scoped down to help us demo BDD only and focus on it.

The Sample Application: PollCast

We start with an empty repository initialized with OpenSpec and switched to a custom behavior-driven schema. PollCast is an application that allows users to cast their vote against polls created by other users. The product intent and the technology stack both go into the context section of OpenSpec's config.yaml:

schema: behavior-driven

context: |
  PollCast is an intuitive web application allowing users to instantly create,
  share, and track custom polls. To prevent spam without the friction of
  passwords, the platform features a streamlined UI where participants simply
  cast votes using their email address as a unique identifier, guaranteeing
  highly accurate and duplicate-free poll results.

  Tech stack: Node.js, server-side rendered Express, JSON file store to begin with.

With that context in place, the first slice is what we type into the coding agent — allow users to vote for a poll that already exists:

/opsx:propose Allow users to vote for a poll that already exists.

Rules:
- A vote cannot be modified once it is cast.
- A duplicate vote cannot be cast for the same email ID —
  email ID is the unique identifier.

A Behavior-Driven OpenSpec Schema

The behavior-driven schema is close to the standard OpenSpec schema — it generates a proposal, spec, design, and tasks — with two deliberate differences:

1. The spec template contains fenced regions of Gherkin. Instead of a plain markdown template, the spec has fenced sections where Given/When/Then scenarios are articulated in Gherkin syntax. OpenSpec already supports this syntax in prose, but fencing the Gherkin means we can lint it, ensure it is syntax-valid, and generate acceptance tests from it.
2. The tasks put acceptance tests first. The generated task list ensures the acceptance test suite is created before the application itself is built.

When the change proposal for poll voting is created, the spec includes a fenced Gherkin feature — including the rule that there are no duplicate votes on the same email ID — and the agent reports that the Gherkin has been extracted and linted as clean syntax. Two things make this work:

• Rules in config.yaml state that the spec artifact cannot be marked as generated until linting is fully done, and enforce a one-to-one mapping between the specification inside OpenSpec and the extracted Gherkin file.
• To learn how to run the gherkin-lint npm module, the agent is directed to fetch its documentation through the context7 CLI.

From Plain Text to Deterministic Tests

This brings us to the first question: how do we take a text file and ensure it guides the coding agent to build an application aligned with the intent articulated in the spec?

First, commit the spec and start a fresh session — I always like to commit the spec and begin the apply step in a new clean session so the coding agent has fresh context to work with. Running opsx apply then works through the tasks, and because of how the tasks are structured, the first thing that appears is an acceptance test folder containing Cucumber.js step definitions.

A quick primer if you are unfamiliar with BDD: Gherkin is just the syntax — the Given/When/Then scenario and feature structure. It is a ubiquitous language for business and product teams to collaborate on; it puts a specification in a standard format, and because Given/When/Then is nice to create tests from, it is very helpful for us. Cucumber is the tool that generates test cases from that Gherkin by defining a step for each line. We are using Cucumber.js since this is a JavaScript application; in Python you would use Behave, in Java JBehave or similar — each language has its own frameworks for step definitions.

Put the spec and step definitions side by side and the mapping is direct: a line like “a poll exists with options cats and dogs” in the spec has its programmatic equivalent as a function in the step definitions. Running these as tests produces a report showing every scenario in the spec passing — and the application has been built to satisfy them.

Why not just use something like the Playwright CLI? I use the Playwright CLI quite a bit, but it introduces an amount of non-determinism. Step definitions, on the other hand, are repeatable — the coding agent only changes a few things for each new feature, and it doesn’t burn a lot of tokens because you are just re-running code that is already built.

The alignment works in both directions. If I edit only the markdown spec — say Alice votes for dogs instead of cats — and re-run the acceptance tests, they fail: the vote was recorded for cats but the spec now expects dogs. The coding agent now has a deterministic signal to go and correct the code. The acceptance tests are always in line with the OpenSpec plain-text file.

The piece putting this together is the cucumber.cjs configuration, which was authored using an acceptance test authoring skill. That skill is currently built for Cucumber.js and JavaScript-based UI applications - it knows how to create a page object model, for example - and you can adapt it to the nature of your application and technology stack.

Here is a short summarizing this flow:

Two Rules and a Hook

How do we make the coding agent finish building the application and only then call it done?

• Rule 1 — in the claude.md file itself: acceptance tests must always pass. Only after that can the agent call the work done. This is what turns the plain-text spec into a deterministic definition of done rather than letting the agent reward-hack its way to "complete."
• Rule 2 — specs and code are never modified together. Without this rule, an agent that has modified code first can reward-hack rule 1: it modifies the spec to get the tests passing and reports “the spec is good, the tests pass, no problem” — but the fundamental principle is gone, because we did not use the spec as source.

Rule 2 is not just a guideline sitting in claude.md. A hook called Zone Guard enforces it as a deterministic check: within a git commit or within a session - depending on the approach you take - it will never allow a single piece of change to include both the spec and the code.

Spec as Source Harness Guidelines

The second question comes from Birgitta’s article on martinfowler.com and her framing of spec-anchored versus spec as source — which I compared OpenSpec against in an earlier post, concluding OpenSpec has the potential to be spec-anchored because of its source-of-truth specification. As an experiment, can we take it all the way to spec as source?

For spec as source, the spec is the only main source file that humans edit over time — humans never touch the code. As an extension, no vibe coding is allowed either: I cannot just ask the agent to modify the code and leave the spec behind. That is where the trouble usually starts — the spec builds the first version of the application, but the moment code is modified by hand, spec and code drift apart.

First, archive the completed change. The specification carries the delta format — added, removed, modified markers — so that when it is synced and archived it moves into the source-of-truth specification. The acceptance tests still pass; only their path changes, from inside the change folder to the source-of-truth specification.

Now, in a new session, let’s go against the grain of the harness — the new-engineer-on-the-team scenario:

Help me change the src folder directly to allow users to modify votes
by submitting with the same email again. No need to create OpenSpec proposal.

This deliberately contradicts the first specification, which disallows duplicate votes. Because the rules are in place, the agent pushes back and says a spec has to be created. Forcing it through with “bypass and move forward” doesn’t work either: the agent cannot complete the feature, because the acceptance test asserting a user must not be able to vote more than once with the same email ID is now broken by the modified code. The agent itself reports that the requested feature directly contradicts the existing spec, and that the path forward is to modify the spec first. The resolution: revert the changes and start afresh with a proper OpenSpec change proposal for the capability.

This is exactly what I articulated in my InfoQ article on enterprise spec-driven development: doing the right thing — writing the spec first — must be easy, and going against the grain of the harness — writing code first and leaving the spec behind — should be hard. Both are taken care of here, and the only way forward is an OpenSpec change proposal.

The new proposal’s spec again has fenced Gherkin, this time carrying the modified marker for the changed feature. Running the acceptance tests at this point shows the original scenarios still passing and the new scenarios as undefined — the modification is not yet done. There is more nuance here, such as calculating the effective test suite so that contradicting tests (the original feature and its modification) are not run together — a topic for a separate video.

Here is a short summarizing spec as source:

BDD Does Not Replace TDD

Because we are doing behavior-driven development does not mean TDD is not required. BDD takes care of the outside-in — the spec is always from the point of view of the user, and it drives the application from the outside. Test-driven development helps you go inside-out. Both are necessary to put an application together well; TDD is simply not covered here to keep the focus of this walkthrough on BDD.

Does this mean we have completely achieved spec as source? Not necessarily — there are a few more things to complete — but the two questions we set out with are answered: a markdown spec, given a programmatic equivalent through Cucumber.js step definitions, drives the application through tests that tell the coding agent when it is actually done; and the harness rules — acceptance tests must always pass, specs and code are never modified together — keep both humans and agents from inadvertently modifying code first.

Video Walkthrough

References

• Behavior-Driven Template — intent-driven-dev/behavior-driven-template
• Intent-Driven Template — intent-driven-dev/intent-driven-template
• Birgitta’s article on martinfowler.com — Exploring Gen AI: Spec-Driven Development Tools
• InfoQ — Enterprise Spec-Driven Development
• Earlier post on spec-anchored vs spec as source — Which Spec-Driven Development Tool Should You Choose?

Originally published at https://intent-driven.dev on July 17, 2026.

Behavior-Driven Development and Spec-Driven Development with OpenSpec was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

This post extends the OpenSpec + OpenCode walkthrough with two new skills added to the intent-driven-template: adversarial authoring and glossary. Both are aimed at getting your specifications into good shape before they reach human review.

The Problem These Solve

Specs written by a single model carry that model’s blind spots, and we often have to intervene by handing these specifications to another model to avoid bias. A second issue with specifications authored by agents is the inconsistency in terminology across sessions. Each model may have its own way of expressing the spec. And also, each human reviewing it may also have their own inputs. We need a way to both reduce model bias and remain consistent by building domain-specific terminology to achieve better specifications. These two skills address that directly.

1. Adversarial Authoring — Cross-Model Review Inside the Workflow

The adversarial-authoring skill wires two sub-agents into the proposal phase: one author, one reviewer. A common setup is having one model write the proposal and another model review it - Claude writing and GPT reviewing, or vice versa.

For example, if we use this skill to author proposal.md, this also produces council notes: what the author subagent wrote, what the reviewer subagent challenged, and how each challenge was resolved - accepted, rejected, and why.

This matters because:

• Different models surface different assumptions and biases
• Over-specification gets caught before it reaches you
• The decision trail is visible, not buried in a chat session

Keep it to two or three sub-agents. More than that and the output becomes noise.

The glossary skill runs during the design phase and maintains a file of domain and technical terms with precise definitions scoped to your application.

Consider a common scenario: an agent designing an import layer for inconsistent legacy CSV data might coin a term like translation boundary service — verbose, invented, and unfamiliar to your team. The right term is anti-corruption layer (ACL), a Domain-Driven Design context mapping pattern introduced by Eric Evans: “an isolating layer to provide your system with functionality of the upstream system in terms of your own domain model” — a concept your engineers already know. This way we can reduce inconsistency where one person calls ACL a translation boundary and others may use some other term. And each of these may be slightly different. When we agree on the concept we are using that leads to clear specifications.

Why this helps over time:

• Terms defined once are reused by the agent in every subsequent spec
• Engineers at different experience levels converge on the same language
• Agents are part of your team — shared terminology applies to them too

A single precise term like idempotent or anti-corruption layer carries more information than a paragraph of approximation.

The same applies to terminology specific to your organization or industry. In a run club, a sweeper (or tail runner) is the volunteer who runs at the back of the pack — matching the pace of the slowest participant, ensuring no one is left behind or lost, and relaying updates to the lead group or organizers. An agent designing a run club management feature might describe this role as a “designated rear-of-pack participant welfare coordinator” — verbose and imprecise. Your team calls it a sweeper. Define it once in the glossary — with its responsibilities scoped to your club’s rules — and the agent will use that term in every spec it writes after that.

Putting It Together

These skills complement the ones we discussed in our previous post. Adversarial authoring reduces model bias. Glossary enforces terminological consistency. Combined with grill-me for interrogating the plan upfront - covered in the previous post - the spec that arrives at your desk should require our review, and much less cleanup.

The intent-driven schema automatically sequences all of this. You don't have to remember to run the review; it's built into the workflow.

Video Walkthrough

References

• Intent-Driven Template — intent-driven-dev/intent-driven-template
• Adversarial Authoring skill — .agents/skills/adversarial-authoring
• Glossary skill — .agents/skills/glossary
• OpenSpec — Fission-AI/OpenSpec
• Anti-Corruption Layer — Wikipedia; Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software (2003), Chapter 14: Maintaining Model Integrity
• Previous post — Spec-Driven Development with OpenSpec and OpenCode

Originally published at https://intent-driven.dev on June 27, 2026.

Better Specs with Adversarial AI and Glossary Skills was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

In my earlier article, I walked through keeping a Linear backlog in sync with OpenSpec as an agent moved a change through Propose, Apply, and Archive. That workflow worked, but it relied on modifying OpenSpec itself.

This revisit achieves the same workflow without touching OpenSpec at all. The Linear sync now lives entirely in a skill — openspec-linearized - that runs on stock OpenSpec.

What the Skill Does

The skill overlays Linear issue management onto the OpenSpec change lifecycle while keeping a clear ownership boundary:

• Linear owns the business context — goals, acceptance criteria, and stakeholder-facing status.
• The repository owns the technical design and implementation.

Initial Configuration

In order to let the coding agent know about which Linear project, team and label we want to associate this repository with, the skill asks us for the details and stores them in openspec/linear.yaml. Once this file is created when we subsequently ask the coding agent to pick up an issue from Linear, it exactly knows where to look.

Mapping Linear issue status with OpenSpec change proposal phases

• Propose — Binds a Linear Backlog issue as the business brief, and moves it to Todo. proposal.md stays lean, with Linear metadata in its frontmatter.
• Apply — Moves the story to In Progress while the tasks are implemented.
• Archive — Completes the OpenSpec archive first, then mirrors the finalized specs into Linear Project Documents (titled OpenSpec: <capability>) and moves the issue to Done.

Video Walkthrough

References

• openspec-linearized skill — intent-driven-dev/openspec-schemas
• Earlier walkthrough — Linear MCP + OpenSpec: A Spec-Driven Development Workflow
• OpenSpec — Fission-AI/OpenSpec

Originally published at https://intent-driven.dev on May 29, 2026.

Linear and OpenSpec was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

The intent-driven-template wires OpenSpec, OpenCode, and a set of OpenCode skills into an end-to-end Spec-Driven Development workflow. This post walks through each step the template sets up - from openspec init to the custom schema that ties it all together.

1. OpenSpec Setup

Start by initializing OpenSpec in the project:

openspec init

Then pick the new, continue, verify, and any other commands you need beyond what is included in the core profile. Profiles were introduced in OpenSpec 1.2.

2. OpenSpec Git Discipline

The template ships an openspec-git-discipline skill that enforces a single rule: every OpenSpec state change must cross main before the next lifecycle phase depends on it.

That means the proposal must be on main before apply starts, and implementation must be merged back to main before archive runs. The skill defines explicit gates around propose, continue, apply, and archive so the agent stops and asks rather than silently violating the rule.

The reasoning behind these gates — especially when running parallel changes in worktrees — is covered in OpenSpec, Git WorkTrees, and OpenCode.

3. Proposal — Grill Me Before You Create proposal.md

During the proposal step, the template uses Matt Pocock’s grill-me skill to interrogate the plan one question at a time, walking down each branch of the design tree until there is a shared understanding between the user and the agent.

This pulls open questions out into the proposal before specs are written, rather than discovering them later.

4. Design — C4 Diagrams

In the design step, the template uses the c4-diagrams skill to clarify architecture before detailed design. The skill produces system context, container, component, dynamic, or deployment diagrams - only the levels that answer a real question - in plain ASCII or Mermaid.

The skill also gates on purpose, format, and rigor up front, requires assumptions and open questions to be called out alongside the diagram, and refuses to drift into detailed design until the diagram is approved. This is especially useful in the brownfield context — see Spec-Driven Development with Brownfield Projects for more on that.

5. ADR — Recording the Architectural Decisions

The design step almost always surfaces architectural decisions worth keeping. The template uses an architectural-decision-records skill to draft each ADR with explicit context, considered options, decision, and consequences - supporting MADR full, MADR minimal, Nygard, Y-Statement, and custom styles.

ADRs are kept outside the change so they persist after the change is archived. The reasoning behind that choice — and why specs alone are not enough — is covered in Architectural Decision Records with Spec-Driven Development.

6. Superpowers for Worktree-Based Parallelism

The template uses Obra’s Superpowers in two places:

• During the explore phase, Superpowers’ brainstorming skill kicks in automatically.
• During bulk apply, our openspec-bulk-apply-change skill leverages Superpowers' worktrees and subagents skills to run multiple OpenSpec changes in parallel - each in its own worktree and SubAgent - without them stepping on each other.

The mechanics of doing this with OpenSpec — proposing on main, applying inside worktrees, and merging before archive - are covered in OpenSpec, Git WorkTrees and OpenCode.

7. Bringing It Together — The intent-driven Schema

proposal -> specs -> design -> adr -> tasks

OpenSpec uses schemas to control which artifacts are generated during the proposal phase. The template activates the intent-driven schema from intent-driven-dev/openspec-schemas, which produces five artifacts in order:

Schemas are what make all the previous steps fit together as a single workflow rather than a pile of separate tools — the schema is what tells OpenSpec to ask for an ADR after design, and tasks only after that. Custom schemas were introduced in the OpenSpec 1.0 release, where config.yaml first opened up workflow customization.

Video Walkthrough

References

• Intent-Driven Template — intent-driven-dev/intent-driven-template
• Template skills — .agents/skills
• OpenSpec — Fission-AI/OpenSpec
• Matt Pocock’s grill-me skill — mattpocock/skills
• Obra’s Superpowers — obra/superpowers
• intent-driven schema — intent-driven-dev/openspec-schemas

Originally published at https://intent-driven.dev on May 10, 2026.

OpenCode and OpenSpec was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Architectural decisions deserve a durable log so that future change proposals can leverage prior reasoning during design — not rediscover it. OpenSpec with the default spec-driven schema captures that reasoning in design.md while a change is in flight, but once the change is archived, only specs.md is carried forward into openspec/specs/. The design rationale stays behind in the archive, out of reach of future proposals. The new spec-driven-with-adr schema closes that gap by keeping Architectural Decision Records outside the change, alongside specs, so every architectural decision persists and the current state of the architecture stays visible to future proposals.

The Default spec-driven Schema

OpenSpec ships with a default schema called spec-driven that produces four artifacts per change: proposal.md, specs.md, design.md, and tasks.md. When a change is archived, only specs.md is preserved - it is synced into openspec/specs/ and lives on. The proposal, design, and tasks are archived with the change under openspec/changes/archive/... and are not considered when the next change is proposed.

For more on how schemas plug into this pipeline, see the earlier post on OpenSpec Custom Schemas.

Why This Matters for Architectural Decisions

The rationale behind an architectural choice usually lives in design.md. Because design.md is archived with the change, that rationale becomes invisible to future proposals. New changes then get designed in the dark - the same trade-offs get re-litigated, fresh designs can quietly contradict prior ones, and the team loses the ability to see why the architecture looks the way it does.

How spec-driven-with-adr Differs

The spec-driven-with-adr schema adds an ADR artifact that lives outside the change, outside the openspec/ folder. Every change can write one or more ADRs (when there are significant architectural changes or decisions being made), and those records persist after the change is archived.

That gives the workflow two things the default schema does not:

• A durable record of every architectural decision — context, options considered, choice, and consequences — captured at the moment the decision is made.
• A visible current-state view of the architecture that future change proposals can read and design against.

The intent matches the rest of OpenSpec: keep the reasoning close to the code so future contributors — human or agent — can read the why without spelunking through pull requests, Slack, or memory.

Specs and ADRs Together Represent Current State

The earlier Source of Truth post framed openspec/specs/ as the living spec representing the current state of the system. The spec-driven-with-adr schema extends that same idea to architectural reasoning:

• Specs represent the current state of the application’s overall functionality — what the system does today.
• ADRs represent the current state of the application’s architecture — how and why the system is built that way today.

Both are durable, and both are read by future change proposals during design. Proposals, designs, and tasks are scaffolding that gets archived once a change ships; specs and ADRs are the load-bearing artifacts that future changes design against.

A Small Example

Suppose an early change picks Postgres over DynamoDB for the primary store. With the default schema, that decision is reasoned through in design.md - the alternatives considered, the cost and operational trade-offs, the consequences for query patterns - and then archived once the change ships. With spec-driven-with-adr, the same reasoning is captured as an ADR that persists outside the change.

A few months later, someone proposes “add full-text search”. During design, the agent (or human) reading sees the storage ADR, knows the system is on Postgres, and naturally evaluates pg_trgm and tsvector before reaching for a separate search service to infer the same from code. Without the ADR, that proposal can easily start by re-debating the storage choice, or worse, silently introduce a second store that contradicts the original decision.

Video Walkthrough

References

• Architectural Decision Records — adr.github.io
• spec-driven-with-adr schema — openspec-schemas
• Previous post — OpenSpec Custom Schemas

Originally published at https://intent-driven.dev on April 29, 2026.

Architectural Decision Records with Spec-Driven Development using OpenSpec was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Git WorkTrees let you check out multiple branches simultaneously in separate directories — each with its own working state. Combined with SubAgents in OpenCode, this unlocks genuine parallel feature development inside a Spec-Driven Development workflow.

The key is knowing where each step of the OpenSpec workflow belongs: proposal on main, implementation in worktrees, archive after merge.

Propose on the Main Branch

Always run /opsx:propose (or /opsx:explore + continue) on the main branch, never inside a worktree branch.

OpenSpec’s proposal step analyses your active changes alongside the source-of-truth specifications to detect conflicts and gaps. If you propose from a worktree branch, OpenSpec only sees that branch’s delta — it loses visibility into other in-flight changes and the authoritative specs on main. Proposing on main keeps everything in view.

Once a proposal is created, you can immediately start on the next proposal for a different feature, still on main. Proposals are lightweight — they don’t touch implementation yet.

Apply with SubAgents and WorkTrees

With proposals ready on main, hand each one off to a SubAgent with its own WorkTree. Each SubAgent works in an isolated branch, applying its change independently. Because worktrees share the same git object store, you get true parallelism without duplicating the repository.

Before a worktree branch is eligible to merge, run Verify inside that same SubAgent session. Verify checks that the implementation matches the proposal’s spec, design, and task artifacts. Running it within the worktree ensures verification before merge so that we can address any issues flagged in the report within that worktree.

Merge First, Then Archive

Once a worktree branch passes Verify, merge it back to main before running Archive. Archive syncs the change’s delta specs into the source-of-truth specifications on main. If you archive while still on a worktree branch, the spec merge runs against an incomplete view of main — other merged features aren’t visible yet — and conflicts become likely.

The rule: merge → archive, in that order, every time. You can Archive each change individually after its merge, or merge all completed worktrees first and then run Bulk-Archive in one pass.

Commit Discipline

More commits means more recovery points. Aim to commit at every logical boundary:

• After the change proposal is created, or after each proposal artifact is generated individually (spec, design, tasks)
• After each logical code change inside the worktree branch
• After running Archive (the spec sync is a meaningful state change)

There is no such thing as too many commits in this workflow. If a SubAgent session goes wrong mid-apply, a dense commit history gives you a clean point to resume from rather than starting over.

Video

For a reference skill that automates the bulk-apply workflow, see the openspec-bulk-apply-change skill.

For worktree-based skills, Superpowers is worth exploring — it provides a skill framework designed to work with git worktrees.

Originally published at https://intent-driven.dev on April 1, 2026.

Git Worktrees with OpenSpec was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

What is a Brownfield Project?

The term “Legacy code” has many definitions, the most relatable IMHO is how Michael Feathers defines it in his book Working Effectively with Legacy Code. Any code that does not have tests is effectively legacy.

Similarly “Brownfield”, in the context of SDD, can be defined as projects that were not built based on specs. The only artifact that is available to us is the implementation or the code itself.

Can We Reverse-Engineer Specs?

In theory, we can reverse-engineer it. A quick way to achieve it is by using tools like repomix to pack the code into smaller sizes and give it to an LLM along with context of the SDD tool we are using. This can help generate the overall spec.

In practice, however, AI-generated specs are often inaccurate. The model doesn’t fully capture the original developer’s intent or the subtle nuances embedded in the code. The result is a spec that looks plausible on the surface but diverges from reality. This can’t be trusted as a foundation for future development.

The Issues with Reverse-Engineering

Reverse Engineering the spec itself can be quite involved. And even if we do, reviewing the specs may not be practical.

In the context of Test-Driven Development, when dealing with legacy code which does not have tests, should we start by writing all the tests first? That is not practical. In Feathers’ work in Working Effectively with Legacy Code the approach taken is largely to cover the area of code change with tests to first establish current behavior (characterization tests). Then we can test drive the remaining code.

Similarly it is a lot more practical to incrementally author specs for brownfield projects.

There is also the problem of alignment loss. A reverse-engineered spec is a derived artifact. When new features are developed against a misaligned spec, the risk of regressions and unintended side effects rises sharply, because the spec no longer reflects the real ground truth of the system.

Why Incremental is Better

The incremental approach focuses specs on a single, upcoming change rather than attempting to capture the whole codebase at once. Before making a modification, you author a spec for just that area — the change you are about to make. This is far more economical: the scope is bounded, the context is fresh, and the resulting spec accurately reflects intent.

Over time, this practice compounds. Each change leaves behind a spec that covers its slice of the system. As spec density grows in frequently touched areas, those sections start to behave like greenfield zones. The coverage builds naturally where it matters most.

For a deeper look at how this applies at scale, see my article on Enterprise Spec-Driven Development on InfoQ.

Brownfield Spec-Driven Development with OpenSpec

Use a Custom Profile and the Explore → Continue Workflow

When applying SDD to brownfield projects with OpenSpec, prefer using a custom OpenSpec profile over the default propose command. For more information on custom profiles, please see OpenSpec 1.2 release blog post.

The recommended workflow for brownfield is:

1. /opsx:explore - explore the change and understand the codebase before any spec is written
2. Review the exploration output
3. /opsx:continue (or fast-forward through artifacts) - progress through proposal, spec, design, and tasks one at a time

In brownfield projects reviewing each artifact individually gives you more control over what gets generated thereby keeping the spec grounded in the real codebase.

Pass Codebase Context During Explore with Repomix MCP

During the explore phase, pass context about the existing codebase using Repomix MCP. This educates the AI on the brownfield codebase before spec writing begins, so the resulting artifacts reflect the actual system rather than assumptions.

Example command:

/opsx:explore I would like to remove the maybe option in RSVP, use repomix mcp to understand existing code

Repomix packages your codebase into a format the AI can consume directly, giving the explore phase accurate grounding in what already exists.

For large codebases, tools like Repomix are especially helpful in managing context window usage.

Conclusion

Incremental approach gives you control, accuracy, and progressively growing coverage, without requiring a big upfront investment in reverse-engineering specs that may not hold up. You start where the work is, build specs that reflect genuine intent, and let the brownfield gradually transform over time.

To see this in action, watch the video below. It walks through a real-world example demonstrating how to use RepoMix to package an existing codebase, feed it to an AI model for analysis, and then author a targeted spec for the next change.

Video

Originally published at https://intent-driven.dev on March 10, 2026.

Spec-Driven Development with Brownfield Projects was originally published in Intent Driven Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.