No Vibe-Coding. Yes to Specification. OpenSpec 1.2: The New Workflow.

In the current reality of AI-assisted development, the most important artifact is not the code but the specification (we've talked about it earlier, see the retreat article). There are already several tools for working with specs:

Let's take a closer look at OpenSpec. An important note: version 1.2 was released in February 2026, featuring a major workflow overhaul. Most online tutorials describe the old approach with "phase gates" (/openspec:proposal → /openspec:apply → /openspec:archive). The new OPSX workflow is different – it’s more flexible and simpler. Everything below is based on the current version.

Let's break down how it works in practice. Our backend dev Zhila Bogdan built a small test project with it: a browser-based Pomodoro timer with session statistics. Not because the world needs more timers, but to demonstrate the methodology on something familiar.

But first, let's talk about why this is needed at all. Anyone who has worked with AI agents for more than one evening knows this: you spend two hours coding with AI, the feature is almost ready, and suddenly you notice the agent is suggesting things that contradict what it wrote thirty minutes ago. You scroll through the chat history trying to find where it all broke down. Usually, it's unclear, because every new prompt subtly shifted the agent's understanding. Early decisions were quietly overwritten, assumptions accumulated, and by the end, you don't have the system you planned – you have thirty rounds of improvisation. This is called vibe-coding, and the problem behind it is intent deviation.

This "drift of intent" isn't a bug in Cursor or Claude; it's a structural issue that arises whenever the "single source of truth" is a chat that will evaporate in an hour. OpenSpec solves this by adding a thin layer of specification between you and the agent. Not a 100-page PRD, but a couple of markdown files that record what we are building, why, and how. The framework is open-source (TypeScript), installs via npm, and works with Claude Code, Cursor, Copilot, and twenty other tools. No API keys, no subscriptions. Links: GitHub · Documentation · Discord

Alright, let's get to it. You'll need Node.js 20.19.0 or higher. Install the CLI:

npm install -g @fission-ai/openspec        

Go into your project folder and run:

openspec init        

It will ask which AI you are using and create the project structure:

• openspec/specs/ – for the current truth about the system
• openspec/changes/ – for proposed changes
• openspec/config.yaml – the control center

In config.yaml, there is a context: section where you describe the project for the machine. This is a nuance Bogdan initially underestimated. When writing for a colleague, you can say "we use React." A person will understand. An agent won't. It needs React 18, Zustand for state, Tailwind 3.4, React Router v6. It needs to know about barrel exports, that all API calls go through /api, that tests use Vitest, components are in PascalCase, hooks have the use prefix. Don't specify the TypeScript version and you'll get syntax that won't compile. Don't describe the architectural rules and the agent will go straight to the database from a component because it's more convenient that way.

For the Pomodoro timer, Bogdan described React with TypeScript, shadcn/ui with Tailwind for UI, state via useReducer, localStorage for session persistence, Vite, and a feature-based project structure. The key difference from the old project.md: the context from config.yaml is actively injected into every planning request. The agent cannot miss or forget it. There's also a rules: section where you can set rules for specific artifacts – for example "use GIVEN-WHEN-THEN in specs" or "include rollback plan in proposals." Instead of the old AGENTS.md (which the agent might or might not read), OpenSpec now uses skills – a standard that AI tools pick up automatically. During init, it installs skills for each command, and the agent knows how to behave without manual configuration.

Then comes the interesting part. You can run:

/opsx:explore        

And talk to the agent about architecture before you start building. It reads the codebase, finds problems, helps think through options. Nothing is created, nothing is committed. For the test timer Bogdan didn't need this, but on a legacy project this thing saves you from costly mistakes at the start.

Now, the proposal. You write what you want:

/opsx:propose create a browser-based Pomodoro timer.
Features: 25 minutes work / 5 minutes break, start-pause-reset buttons,
sound notification via Web Audio API, history of completed sessions
with date and duration, localStorage for persistence.

UI/UX requirements:
- Central element: circular progress bar (SVG) with digital timer
  inside, monospace font for digits to prevent width jumping
- Color states: work — warm accent (amber/orange), break —
  cool (teal/green), pause — muted (muted gray)
- Smooth transitions between states via CSS transition 300ms
- Control buttons below the timer: Lucide icons, no text,
  hover/active states, disabled state for inactive actions
- Session history: compact list below the timer, each card shows
  date, duration, type (work/break), scroll if > 5
- Adaptive: mobile-first, on phone the timer takes 80vw,
  on desktop max-width 420px centered
- Dark theme by default, light via system settings
  (prefers-color-scheme), shadcn/ui dark mode via class strategy
- Typography: Inter for UI, JetBrains Mono for timer digits
- Spacing: 8px grid, Tailwind standard indents
- No animations for animation's sake, only functional transitions        

OpenSpec generates four documents at once. proposal.md describes why and what's in scope. specs/ contains delta specs – not a wall of requirements but a surgical description of what's being added and what's changing. design.mddescribes the technical solution. tasks.md lays everything out in a checklist that the agent then follows line by line.

This is the core workflow: propose creates everything at once. If you need step-by-step control, you can enable the expanded profile via:

openspec config profile        

Then you get /opsx:new + /opsx:continue (one artifact at a time) and /opsx:ff (everything at once). For the test Pomodoro, core was enough – propose handled everything in a single pass.

The output is roughly 250 lines of Markdown. For comparison, GitHub Spec Kit generates 800 for the same task. But the volume isn't what matters. What matters is that you read the spec before the agent writes a single line of code. Maybe it decided the timer should sync with a server. Maybe it added authentication you didn't ask for. This is a plan review, not a code review. And it's cheap – fixing a suggestion in proposal.md takes a second, while reworking finished code can take hours.

Requirements are better written in GIVEN-WHEN-THEN format – the agent gets unambiguous, testable conditions, and then auto-tests can be generated from them almost for free.

Once the spec is ready, run:

/opsx:apply        

The agent takes tasks.md and works through the checklist. And here's the key difference from the old phase-based approaches: if during the process you discover the design needs tweaking, you simply open design.md or specs/, edit by hand or ask the agent, and continue with apply. The artifacts are just regular Markdown files in the change folder – they're not locked. There are no rigid phase gates, no "you can't go back." Tasks are decomposed and isolated; the agent doesn't try to do everything at once and doesn't lose the thread. It's a genuinely different experience compared to "make me a timer" in an empty chat.

If the expanded profile is enabled, before merging you can run:

/opsx:verify        

Automatic audit: are all tasks completed, does the code match the spec, are any scenarios missing? It comes with CRITICAL, WARNING, SUGGESTION marks. AI checks its own work against the agreed requirements. Not a replacement for code review, but a filter that catches the obvious before you spend time on it.

Before committing, you can also run CLI validation to ensure the specs are correctly formatted:

openspec update        

Then:

/opsx:archive        

The completed change goes to the archive, the main spec is updated. You have a living document that describes the system as it is right now, not six months ago.

But the real joy starts with iterations. Bogdan wanted to add productivity charts: how many pomodoros per day over the last week, average session length, streak of consecutive days. He made a new proposal:

/opsx:propose add a statistics dashboard: bar chart of pomodoros over the last 7 days,
average session duration, current streak of consecutive days, render via Recharts        

OpenSpec reads the current spec and generates a delta. What's added, what's changed, what's untouched. The agent knows the timer already exists, that there are control buttons, that session history is saved in localStorage. It doesn't need to make things up, and it doesn't break what's working.

You can run several changes in parallel – you started the dashboard, a bug came in, you do:

/opsx:propose fix-timer-drift        

In a separate folder, you close it, archive it, return to the dashboard. Contexts don't mix. In the expanded profile there's a dedicated command /opsx:new that creates a folder without generating artifacts, but for most cases propose is enough.

And here's a technical point that explains why this works at a deeper level than "keeping documents in order." AI agents have a context window of 130–200 thousand tokens. A regular chat fills it with noise: old messages, rejected suggestions, contradictions. Quality drops as it fills up. A delta spec takes up fewer than 2000 tokens. The agent gets clean instructions and maximum space to work with the code. The difference in output is tangible, especially on complex features where a bloated context makes the AI contradict itself.

A few things worth knowing:

• OpenSpec works best with models with strong reasoning – they recommend Claude Opus 4.5–4.6 or GPT-5.4.
• Before /opsx:apply, clear the context – the agent is more precise when it starts fresh and re-reads the spec.
• Minor bugs can be fixed without a proposal.
• Keep changes small: one propose per one feature, don't cram the timer, statistics, and settings into one change. Each propose creates a separate folder in openspec/changes/, and the more compact the scope, the more precise the agent and the easier it is to roll back if something goes wrong.
• If the implementation diverged from the spec, update the spec. An outdated spec is worse than no spec, it will lie to the agent in future sessions.

Specs live in git alongside the code. They go through PRs, through reviews. A new team member opens openspec/specs/ and understands what the system does, without reading thousands of lines. When Bogdan started, it seemed like extra overhead. Why write a spec when you can just ask the agent? But ten minutes on a spec saves hours of rework. The speed of code generation is only useful when the direction is right. OpenSpec doesn't slow you down – it ensures that when the agent runs fast, it runs where it needs to go. Even on the test Pomodoro this is noticeable, and on a real project with a dozen services the difference will be an order of magnitude.

Have you already tried a spec-driven approach? Are you using OpenSpec, Kiro, Spec-kit, or something of your own? Share in the comments – it's interesting to compare experiences.

We at EternaSoftware constantly research new approaches to development and implement those that genuinely accelerate the team without sacrificing quality. Spec-driven development is one of them. If you need a team that doesn't just write code but thinks about how to build it properly – come work with us.

#OpenSpec #SpecDrivenDevelopment #SoftwareArchitecture #OPSX #SDLC #AICoding #AIAgents #ClaudeCode #CursorAI #LLMs #DeveloperExperience #NoVibeCoding #ProductivityHacks #CodeQuality #CleanCode #EternaSoftware #OpenSource #TypeScript #TechInnovation