Why I built OpalSpec

OpalSpec is a Spec-Driven development framework, but I did not build OpalSpec because I thought the world needed another.

There are already really good spec-driven development tools and workflows out there. If one of those tools works for you, that is great, but for me, OpalSpec came from a more personal place.

I have found a way of working with AI coding agents that felt genuinely effective. Not perfect or magical but consistently better than jumping straight from a change idea/definition to generated code. My workflow has always been simple, I would stay in the loop, ask the agent to help me clarify the problem, shape a plan, propose a design, and only then move into implementation. I would review the requirements, challenge the design, adjust the direction, and later review the code.

The steps were usually the same, but the depth (of Agent work) changed depending on the change. Some changes only needed a light pass, while others needed more questioning, more design input, and more careful review before I trusted the implementation.

That worked really well but the problem was that it was mostly living in prompts, custom instructions, skills, habits, and memory. It was effective, but informal. I could repeat it because I knew what I meant, but it was not especially portable or consistent. If I changed tool, changed project, or came back to something later, parts of the process could get lost.

OpalSpec was my attempt to capture that workflow and make it easier to repeat.

Not to turn it into a rigid process. More to take something I was already doing manually and give it just enough structure that I could reuse it, improve it, and carry it between projects.

The workflow already existed

The workflow behind OpalSpec has always been very human-led.

I would usually start by explaining what I wanted to change, then ask the agent to help me think it through. Sometimes that meant generating requirements and sometimes it meant asking me questions first. Sometimes it meant pointing out ambiguity in what I had asked for and that last part turned out to be really valuable.

When an agent asks a good clarifying question, it can force you to think about something you had not considered yet. What should happen in this edge case? Is this behaviour meant to replace the old flow or sit alongside it? Should this be configurable? What does success actually look like? An agent with good context that understands intent can give you new perspectives on how we solve problems.

Importantly, I still review the output. The agent could propose requirements, but I had to decide whether they were right. It could suggest a design, but I had to read it and decide whether the approach made sense. It could implement the code, but I still had to review the diff, run tests, and decide whether the change was acceptable.

The human-in-the-loop part is still key to how I think about AI-assisted development.

For me, the goal is not to remove the developer from the process. It is to give the developer better leverage while keeping them responsible for the direction, judgement, and quality of the work.

How SDD helped

A spec gives the agent something better than a loose prompt. It captures the intent of the change, the expected behaviour, the decisions that have already been made, and relevant constraints.

This makes the agent’s output better.

It also gives the human a better checkpoint before the code changes. I can read the requirements and ask if this actually what I want. I can read the design and determine if it's the correct approach. I can catch issues when they are still cheap to fix.

Spec-driven development creates a moment between idea and implementation where the direction can be reviewed. In AI-assisted coding that moment is very useful because agents are fast and they can generate a lots of code quickly, but speed is only useful if it is pointed in the right direction. Specs help with that direction.

Why I did not just use another framework

I looked at other SDD tools and frameworks, and there are many I like, and have used extensively, but none of them quite matched my preferred workflows.

Some felt more rigid than I wanted and some seemed to assume every change should follow the same path. I can see why those approaches are useful in certain situations, but they did not quite fit the way I was working.

I wanted something more flexible because not every change is the same.

Some changes are simple and only need a quick requirements and design pass before implementation. Some are complex enough that the agent should interrogate me first. Some need tasks because the work is large or risky. Some benefit from a second review before code is touched. Some deserve documentation afterwards because future contributors will need to understand how the system works and other changes do not need much process at all.

I did not want a framework that made every change feel heavier. I wanted something that gave me options, but still let me choose the right level of structure for the work in front of me, and because I already had a working set of instructions and habits, it made more sense to build around that workflow than to bend another framework into something different.

The value of asking questions first

One of the most useful parts of this style of working, and a concept gaining a lot of traction today is letting the agent ask questions before requirements and design are written.

When I already have a clear idea, generating requirements directly is fine. But for more complex or fuzzy changes, I have found it much better to let the agent push back a little first. The questions often expose hidden assumptions.

They can reveal that I have not thought about error handling, permissions, migration, backwards compatibility, user experience, or test coverage. Sometimes the question itself is more valuable than the answer because it changes how I think about the feature.

That is one of the places where AI-assisted development feels more like collaboration. The agent is not deciding what to build and instead I am making the decisions, but it is helping me think through the problem space before I commit to a direction.

That is a big part of why I wanted OpalSpec to support both paths. Generate requirements when the direction is clear, or ask questions first when the direction needs shaping.

The value of a second pass

For complex changes I've always used a second Agent for design review.

I kept finding that the first agent would get most of the way there - solid requirements, approach and design. Maybe 90%.

But then a second pass would catch something important, for example:

• A missing edge case.
• A risk in the migration path.
• A test that should exist.
• A simpler way to structure the implementation.
• A place where the design was slightly too vague.

That remaining 10% can matter a lot.

This is where the optional preflight step in OpalSpec comes from. It was something I was already doing manually when the change felt risky enough. I did not want it to be mandatory, because not every change needs it, however when the change is large, complex, or important, having a second agent review the plan before code is changed can be a game changer and avoids future rework.

Again, the human is still in the loop.

The second agent is not the authority, its just another reviewer. It gives me another perspective before I decide whether the spec is ready to build from.

Why I avoided a master spec

One design choice I made quite deliberately was not to sync everything back into a single master spec.

I understand why some people prefer this. For me, it felt like unnecessary overhead and gives both humans and AI another artifact to reconcile. It increases the amount of context the agent may need to process and creates one more thing that can drift from the code. If a master spec does drift it can become less helpful than the smaller, change-focused specs it replaced.

The code always remains the executable truth - although I appreciate it does not capture intended behaviour. Potentially my opinion will change on this over time.

This does not mean specs are disposable. They are valuable because they capture the intent and decisions around a change at the time the change was made. They explain what we were trying to do and why. That is useful context for future humans and future AI sessions.

I see documentation with the code as the longer lived explanation of how the system works now, these should included intended behaviour, and how the code satisfies that.

So the distinction I settled on was:

• Specs guide the change.
• Code proves what exists.
• Docs explain intended behaviour and how the system works.

That model felt lighter and more honest to me than trying to keep a single master spec perfectly synchronised with a moving codebase.

Better workflows

Effective AI-assisted software engineering is not about better prompts, it is about better workflows.

A good workflow gives the agent the context it needs, gives the human clear points to review and redirect, and leaves behind enough history that future contributors are not starting from nothing.

That does not require a huge process.

In fact too much process can work against it. The useful part is not the number of documents. The useful part is whether the right thinking happens at the right time, and whether the output of that thinking is captured in a way that can be reused.

For me, SDD has been effective because it creates that shape.

• It helps separate thinking from building.
• It makes the agent’s output more relevant.
• It gives me more confidence before implementation starts.
• It creates a record of why a change exists.
• It gives future humans and AI agents more context to work with.

So why did I build OpalSpec?

I had a workflow that worked, but it was too informal.

I was already using AI to help plan, question, design, review, and implement. I was already staying in the loop. I was already reviewing the specs and the code. I was already using second-pass reviews for harder changes. I was already trying to keep enough context around that future me, or another contributor, could understand what had happened.

OpalSpec was a way to make that workflow more consistent and portable.

It is not meant to be a one true way to do spec-driven development. It is not meant to replace other SDD frameworks. It is not something I'm looking to push on my teams.

It is a small framework around a way of working that I found useful which is human-led, AI-assisted, spec-guided, and flexible enough to adapt to the change in front of me.

If you want to check out the workflow: https://opalspec.dev/workflow