Adding Spec-Driven Workflow to an Existing Project Without Burning Months

You inherited a codebase with no specs. Three years of decisions, buried in code, Slack threads, and one person's memory. The agent you bring in to help guesses at everything. Output drifts within an hour.

Adding spec-driven workflow to an existing project feels heavy. The docs are missing. The code is the only source of truth. Writing specs for existing behavior sounds like months of archaeology.

It is not. The trick is to spec going forward, not backward.

What to spec first

Do not try to document the entire system. Pick the next change you are about to make.

The change itself becomes the first spec. What behavior does the change add. What does it modify. What does it remove. Three sections, two paragraphs each. Done.

The rest of the system stays unspoken. The spec captures only what is changing. When the change archives, the spec merges into your source-of-truth directory. One folder now has documented behavior. The rest is still code-only, and that is fine for now.

Over months, the spec directory grows. Each change adds a piece. Eventually you have documented the parts that change often, which are the parts that need documentation most.

The thirty-minute setup

Install OpenSpec globally. Initialize it in your project. The init creates the directory structure: specs/ for the source of truth, changes/ for proposed modifications, config.yaml for project settings.

Pick one small change you have on the backlog. Something that would take a day to implement manually. Use it as the test case.

Tell your agent to propose the change. /opsx:propose add-feature-x. The agent reads your project context, asks a few clarifying questions, and produces a folder with proposal, specs, design, and tasks.

You review the proposal. If it matches your intent, you proceed. If not, you correct and re-propose. The back-and-forth happens before any code is written.

The propose-apply-archive loop

Three commands cover most work.

/opsx:propose creates the change folder. Proposal explains why and what. Specs describe behavior changes. Design covers technical approach. Tasks is the implementation checklist.

/opsx:apply runs the tasks. The agent works through each one, checking them off as it goes. If implementation reveals the design was wrong, you update the artifact file and continue. No restart from scratch.

/opsx:archive finalizes the change. Delta specs merge into the main specs directory. The change folder moves to archive with a date prefix. Future readers can see why this change happened and what trade-offs were considered.

The loop is short. A small feature goes through it in a day. A larger one takes longer but the structure stays the same.

What changes about review

Without specs, code review is mostly about what the code does. The reviewer reads the diff, infers intent, and checks if the implementation matches the inferred intent. The inference is where review misses happen.

With specs, code review splits into two questions. Does the code match the spec. Does the spec match the intent.

The first question is mechanical. The reviewer reads the spec, reads the code, and confirms each requirement is implemented. Faster, more thorough.

The second question is where the real review happens. Was the spec right. Did the design consider the right trade-offs. Did we miss a requirement. This is the conversation that should have happened before code, and now it can because the spec exists.

When the workflow is too heavy

The thirty-minute setup is for the team committing to spec-driven. Not every change needs it.

For a typo, skip it. Edit the file.

For a CSS tweak with no logic, skip it. Edit the file.

For an experiment you will delete in a day, skip it. The spec is overhead.

The judgment is whether the change introduces behavior that someone will need to understand later. If yes, spec it. If no, just edit.

The mistake is spec-ing everything. The bigger mistake is spec-ing nothing. Most production code lies between, and most production code benefits from a one-paragraph spec before the implementation.

What teams get wrong adopting this

Three patterns repeat.

Teams try to spec the existing system first. They spend a month writing specs for code that already works. The work feels productive. It produces no new features. They abandon the workflow because it "added overhead without value".

Teams let the agent write specs without review. The agent produces plausible specs. The specs are wrong in subtle ways. The wrongness propagates into implementation. The team blames the workflow.

Teams apply the workflow to throwaway work. Prototypes, demos, experiments. The spec ceremony slows down the iteration. The team concludes the workflow is too slow.

The fix in all three cases is the same. Spec going forward, not backward. Review every spec the agent writes. Apply the workflow only to work that will outlive the week.

The smallest test

Install OpenSpec today. Initialize it in your current project. Pick the next change on your backlog. Run /opsx:propose on it.

If the proposal matches your intent, you have a working workflow. If it does not, you found the misunderstanding before code. That is the value proposition.