First (and Last?) Steps With OpenSpec

OpenSpec brings spec-driven development (SDD) to AI coding assistants. The idea is that we move away from vibe coding and use well-established practices for software development inside our AI coding tools. While I love the idea, my first experience was not that promising. Let us see what happened.

The little application I want to build

I want to build an app to gather travel destinations and photo spots, helping me plan tours and capture great shots. For that I want to use Python, Flask, Tailwind, PostgreSQL and OpenStreetMap. This is a technology stack that I know and where I can judge the generated code.

I use Claude Code on the command line with a standard seat of the teams plan.

Installation and setup

Make sure you have an up to date Node.js installation on your system. Is this not the case, you need to install Node.js first. When this is done, you can use the Node package manager to install OpenSpec as a global tool:

npm install -g @fission-ai/openspec@latest

We then can go to the directory in which we want to build our application and initialise the OpenSpec settings with this command:

openspec init

We then can go to the directory in which we want to build our application and initialise the OpenSpec settings with this command:

First step, first mistake

I followed the readme in the GitHub repository and started my new project with this command:

/opsx:propose “travel goals”

That was a bad idea, the OpenSpec started running and came up with a 20-point action plan to build an application. But since it only knew the two words travel goals, it had absolutely no context of what I wanted to do. While a few points were correct, most of this work was useless and I had to fix it by entering the thinking mode:

/opsx:explore

Now I could define what I want, specify the technology stack and that the agent should do the work following test-driven development (TDD) with end-to-end tests using Playwright. OpenStack complained a lot about that this is not being part of its plan, but it then updated the plan to everything I wanted. I could run questions on the plan, find holes and let it suggest options on how to solve certain problems. The options were sensible and after a few extra rounds, I was happy with the plan.

Lesson learned: For a new application, do not use /opsx:propose, use /opsx:explore.

Run the plan and be surprised

After another review of the plan, I told Claude Code to build the application with this command:

/opsx:apply

The implementation took a long time, but the output showed it followed the plan, run failing tests and implemented code to make them pass. As it reached the end, I got the commands to run the application and see the result for myself:

The start page showed a 404 error.
The registration form did not work.
The styling was completely ignored.

After an hour I got basically a nice plan with many points marked as done but no useful application.

Fix the application

I had to run a few iterations to fix the application. As soon as the registration worked, I could see how bad the rest looked and how many additional parts needed rework. After the third problem I found I asked Claude/OpenSpec why the end-to-end tests it wrote did not catch the problem and it answered with this explanation:

All Playwright E2E tests are marked @pytest.mark.skip and have never actually run.

As soon as these tests also run, they failed. Now I had to fix them as well, what lead to a spiral of death that run through my tokens without producing anything useful. The inevitable outcome of all this was that Claude Code stopped with this message:

There are no more tokens left.

My experiment with OpenSpec ended with a broken application that burned through all my tokens for the session trying to fix what it had broken in the attempts before. Definitely not what I had in mind.

My conclusion

As of March 2026, I see OpenSpec as an approach with potential that needs a lot of improvement, much better documentation and better help inside the AI coding tool to be of use to me. It had its moment where I was positively surprised by its suggestions to address certain obstacles and how to handle the usability aspects of the key features.

But it was too easy to make a mistake and OpenSpec ignored too many of my demands to deliver what I need. Maybe I used the tool wrong, but that only shows how much better it has to get to prevent users from making silly mistakes.