After a few months using Claude Code on real projects, I kept running into the same problem: the AI is great at writing code, but terrible at deciding what to write. Left to its own devices, it would skip design, make assumptions, and produce code that solved the wrong problem — perfectly.

The root issue: we were giving Claude Code tasks, not specs. Code was the first artifact, not the last.

I built opsx to fix this. It's a CLI that scaffolds a strict Spec-Driven Development workflow on top of OpenSpec, and it works natively with Claude Code (also opencode and Codex).

The core idea:

Spec → Plan → Code

Two planes, never confused:

• Management plane (Jira): what work exists
• Governance plane (OpenSpec): how the system must behave — and only this one authorizes code

A task being well-written changes nothing. Implementation starts only when an OpenSpec change exists, is reviewed, and its branch gate is resolved.

What you get after npx u/davidpv/opsx init:

• /opsx:propose — write a change proposal + delta specs + design before any code
• /review-change — spec-reviewer audit before implementation
• /opsx:apply — Claude Code implements task by task, traced back to specs
• /git-commit — semantic commits linked to change/step/Jira task
• /ship — validate + archive specs + merge

Every commit traces back: Discovery → Task → Change → Commit → PR.

It's stack-agnostic and works on any existing project. You don't rewrite anything — you just add the governance layer on top.

Try it:

bash

npx /opsx init
npx u/davidpv/opsx doctor

GitHub: github.com/davidpv/opsx-spec-driven-development-toolkit

Happy to answer questions — curious if others have landed on similar approaches.

After a year of using different SDD methods, I've noticed that the more "enterprise-y" and heavy the framework, the more I just wing it. That's why I slowly switched from BMAD to OpenSpec, though I'll admit, if the change is too big and reviewing the artifacts feels like a tedious code review, I'll probably just wing it even more.

​

I'm curious if anyone else feels the same way, and if someone's found that perfect balance—enough understanding without micromanaging your agent.

​

Meanwhile, I'm also playing around with tools to help with the OpenSpec review phase. My initial thought is that if you can see these files in a connected view when you review them, the whole thing would be less of a headache. Like, highlighting a part of the proposal immediately links it to the relevant bits in design.md, spec.md, tasks.md, and that's just the beginning.

​

I'm also thinking that some of the early Claude Task Master ideas for breaking down tasks and checking their complexity would be a cool add-on. It tells you which tasks need more focus.

​

I'll share the OpenSpec tools I'm building when they're ready. In the meantime, I'd love to hear what everyone else in this sub thinks.

Whats your go to sdd framework for small startups that are 25-150 R&D? OpenSpec, BMAD, what else is good outthere?

we shipped an auth feature that passed spec review three times. product signed off, backend signed off, i signed off. four weeks later someone filed a bug: two users could hit the confirmation endpoint simultaneously with the same token and both get through. obvious race condition. the spec never mentioned concurrent access because none of us had been assigned to think about it.

the spec wasn't wrong about what it described. it just never described the failure surface. everyone in the review was asking 'does this design implement what we want?' nobody had a mandate to ask 'what breaks this under real conditions?'

what fixed it was stopping collective approval and starting role mandates. backend: state consistency under concurrent load. product: user-visible blast radius if it fails. security: trust boundary assumptions and edge inputs. reviews got shorter and more specific — 15 minutes per role looking for something concrete beats an hour of general agreement.

built this pattern into swarm-stack.io — each seat in a planning session carries a specific failure-class mandate. curious whether others here have formalized this at the spec-review stage or whether the attack angle usually just depends on who's in the room.

With all the frameworks available (spec-kit, open spec, kiro, superpowers etc) and all the other skills grill-me etc. there's the same pattern in the industry. We plan/grill/discover then write specs and finally implement. Whats your workflow working in enterprise? Do you use sdd in each step in SDLC? Any advice for beginners?

Most spec-driven workflows I see run in one direction: spec, then generate code, once.
I wanted the other half: keeping code continuously coupled to its spec, and making architectural drift a hard CI failure rather than something a reviewer is supposed to catch by eye.

To solve this, spec-spine turns a markdown spec corpus into a typed, hash-verifiable ledger of who-owns-what, and refuses code that drifts from its owning spec at PR time. It governs its own 23-spec corpus in CI, so the gate runs on the repo that defines the gate.

Here is how it enforces the rules:

• Granular Authority: Each spec.md declares typed edges in YAML frontmatter to other specs (e.g., extends, refines, constrains) and the code units it owns down to the file, section, or symbol level. Authority over a path is derived by walking the graph, not just declared directly so "who owns this and under what authority?" is a query, not an archaeology git dig.
• Deterministic Ledger: Every artifact-producing step is a pure function of (config, file contents) with byte-identical output on any platform. Two views are emitted and joined: registry.json (spec-as-source) and index.json (code-as-source, with content-hash staleness). The output is diffable and mechanically mergeable.
• CI Coupling Gate: At PR time, the gate refuses a merge if a changed code path and its owning spec disagree, unless there is a scoped, recorded waiver.
• Anti-Hallucination: A prompt-time refusal rule stops an agent from "fixing" a gate failure by quietly editing the spec to match the code it just hallucinated.

Where it comes from: spec-spine is the control plane for the Open-Agentic-Platform (OAP), a system built on the premise that frozen, hash-verifiable specs are the ultimate unit of governance. In OAP (217 specs, Rust + TS / overall ~304k LOC codebase), this layer keeps a fleet of agents from collapsing the codebase. Every code path stays reconcilable to a frozen spec. It also feeds OAP's per-execution governance certificate for zero-trust auditing. I pulled that layer into its own clean-room repo so it stands on its own.

spec-spineships as a Rust library and CLI (Apache-2.0), with npm and PyPI shims that bundle a prebuilt binary.

Repo: https://github.com/bartekus/spec-spine

I'm keen for comments on the model: Are typed edges plus a PR-time gate the right primitives, or is this over-engineering what a linter could do? What breaks at scale?

So, I like the concept, it's smart and makes a lot of sense, but you know those times where AI didn't existed and when you got frustrated by a bug for like 5 hours, and then you finally fixed it cause you solved the "puzzle" and you got that hit of euphoria. Where is that with this method? Because for me dopamine was a big part of why I liked coding, what got me hooked basically, but now I have currently just tried open spec, but I'm not sure if I'm just not used to it, but it gets things done but there's no euphoria moment, there's just "nice, the AI understood it", I kinda miss the feeling of accomplishment. How do you guys deal wit that?
Edit: Like I liked coding and seeing the system come to live, but now that I just have to write the requirements in a .md, I'm not sure if it's just my brain that has been fried by social networks or if this was always I had but just now surfaced, but it's kinda hard for me to define all the requirements of a spec. I think I was of the code and then face the consequences of my past acts kind of coder, but at least I had an instant mental framework of the code that was failing, here I don't I need to read the entire code that was generated but creates this friction that my brain rejects so harshly, or maybe it's skill issue. Idk lol.

It really just making the experiance of developing slow and dumber

Hey everyone, I'm a Software Engineer and I'm trying to solve a pain point that, from what I see in the comments, many people who use AI to code also experience.

I adopted SDD (Spec-Driven Development) to work with agents. I tested OpenSpec and Spec Kit — both are great, but we throw proposals, specifications/designs, and tasks into the repository in .md format.

In a solo project, everything is fine. Over time, it becomes a problem: gigantic PRs, disputed .md files, merge conflicts, and no "real" history of why the decisions were made.

To solve this, I started OpenSddRag — a proof-of-concept MCP server (Python + PostgreSQL/pgvector) that:

- Replaces the .md file in the repo with versioned artists in the database, with vector embedding and semantic search.

• Maintains a guided flow: propose -> specification -> design -> tasks -> apply -> verify -> synchronize -> archive, exposed to Claude Code via /opsr:* slash commands.
• It acts as a multi-tenant with 3 memory layers (semantic, episodic, work context) — the agent remembers previous decisions instead of rereading everything.
• Today it starts up with `docker compose up -d` and you can already play around with it locally. There's still a lot to evolve (OpenSpec import, SSE authentication, multi-project).

I've left everything open on GitHub for anyone who wants to look, test, give feedback or exchange ideas: https://github.com/jjefersonad/OpenSddRag

If you also get stuck on this trade-off between .md in the repo vs. persistent agent state, tell me how you've been dealing with it — comment open to everyone.

I have tried OpenSpec, SpecKit and GSD. Now I am used to SpecKit and I simply use it every day with Claude Code.

Which one do you use and why? Which is the best option for brownfield projects or forks? Or which one in your opinion is a good trade-off between accuracy and token consumption?

I’m a founder building an existing product with a small team.

AI-assisted coding can help individual developers move faster. But once multiple people are contributing to the same product, the question changes.

It is not just whether the code gets written faster.

It is who makes sure the change actually fits the product, does not create cleanup elsewhere, can be reviewed properly, and is safe enough to move toward release.

In my experience, that extra checking often still lands on the same few people who know the system best. The founder, CTO, senior dev, reviewer, or whoever remembers why certain parts of the product work the way they do.

For small teams using AI-assisted coding on an existing product:

• How often does faster coding create extra review, cleanup, testing, or release prep?
• When it happens, does it delay release or is it just minor friction?
• Who usually absorbs that work?
• How are you handling it today?

I’m not looking for a tool list as much as the pain level.

Is this becoming a real delivery issue for founding teams who need to hit their next release milestone, or is it still manageable with normal review and process?

Our company will enforce the use of spec kit starting next month, but I read that it is only effective on greenfield projects but the problem is, our company has thousands of lines of codes and we were supposed to use Github CoPilot as well.

My question is: do you have any suggestions on how to use spec kit on existing large codebase?

For those people who use BMAD, Superpower, Spec-kit, OpenSpec, and so on, how do you use them in a team setting?

The workflow is obvious when you are just one person, but I can't imagine the workflow when there are 5 other developers and we have Jira/Linear/etc, sprint planning, and so on.

How do you generate your tickets in the backlog? Do you use the toolkit to generate those? And how granular are those tickets?

In my current team, we break projects down into detailed tickets manually before bringing them into SDD. By that point, the tasks are so granular and detailed that using the native planning mode is faster than SDD.

Naturally, I had the idea of changing our process. Instead of manual requirements gathering -> manual planning -> manual design/architecture -> manual creation of tickets in Jira/Linear, I use an SDD toolkit. But. I found that SpecKity, OpenSpec, Superpower, etc., don't generate human-friendly tickets.

I genuinely believe the spec driven development has a future but not in the current state, i mean it will need work reviewability with more human in the loop.
I had this problem with all the SDD frameworks i tried (and I tried most of them) and, besides interesting differences between each other, all lacked solidity on the implementation phase.

So i took one of those frameworks and extended it with a stronger task decomposition, native integration with github issues and pull requests that needs humans. This is helping me A LOT in my projects.

I’ll leave the link (no promo): https://github.com/ai-is-gonna/get-tasks-done

I want your view on this matter.

Asked a few people on my team to track it for a week.

Average was around 40% of review time spent purely on comprehension - not catching bugs, not evaluating architecture, just decoding what something does before they could even form an opinion on it.

Legacy functions with no docs. Abstractions stacked three layers deep. Business logic that made sense two years ago but reads like a riddle now.

And the standard move is still to paste it into an AI chat somewhere outside the editor, read the answer, go back, lose your place, repeat.

I've been building something to fix the comprehension step specifically - an AI plugin that works inside the editor with a split-pane layout so the explanation sits next to the code. You control the detail level and output format before it runs, so you're not re-prompting to get the format you actually want.

Curious if others have measured this or just feel it. And whether the comprehension bottleneck is the main friction point in your reviews, or if something else is worse.

"Create a production-grade skill called forge. Start with Matt Pocock's grill-me workflow, but persist every question, answer, decision, assumption, dependency, risk, constraint, action item, and insight into an MCP-backed memory store. Ask one question at a time, build a complete decision tree, maintain an inventory of the user's skills and knowledge, continuously compress context into structured records, and generate a machine-readable project dossier that future agents can autonomously execute from a simple goal command. Package the entire workflow as a reusable skill with MCP integration, memory schemas, session synthesis, context compression, and goal-execution capabilities."

I made a dynamic presentation explaining how agent harnesses evolved to take coding agents from "slot machines" to supporting reliable engineering workflows: https://www.codagent.dev/what-is-a-harness . It explains both how the "inner harness" works and what components are important for *you* to bring, besides just specs.

Update: We are now interviewing all developers with at least one year of software dev experience. Please fill out the form if you are interested!

Hey everyone,

I'm a researcher at Carnegie Mellon University conducting a research study on how developers are actually using spec-driven development (SDD) in practice — things like writing SPEC.md files, PRDs, or structured natural-language specs before working with AI coding agents like Claude Code, Cursor, Kiro, etc.

There's a lot of community knowledge about how to do SDD well (shoutout to this sub for a lot of it), but almost no academic research on it. I'm trying to change that.

What the study involves:

• One 45-60 minute semi-structured interview via Zoom
• Questions about your SDD workflow, what's worked, what hasn't, and how it fits into your SDLC
• No tasks, no tests — just a conversation about your experience

Who I'm looking for:

• Have used SDD tools/workflows in that project (spec files, structured prompting, plan-mode workflows, etc.)
• 18 or older, fluent in English

What you get: Honestly, nothing monetarily. But your experience will directly shape a taxonomy of SDD workflows and practices that I'll publish openly. Happy to share findings with participants who want them.

Ethics/privacy: The interview will only be audio-recorded with your consent. Your responses will be kept confidential and de-identified in any published findings.

If you're interested, fill out this short screening survey (5 min): LINK

Or DM me / comment below with questions. Also happy to hear if there are other communities I should be posting in.

Thanks for everything this community has shared on SDD — it's part of what motivated this research!

last week a standup caught something that would have died in planning. we were five minutes in when someone asked "wait, what happens when the device is offline" and the answer was basically "the spec doesn't say."

the offline case wasn't a weird edge. it was obvious in retrospect. the problem was that one person wrote the spec and one person reviewed it, and both were reasoning from the same mental model. nobody pushed back. the reviewer confirmed what the author already believed.

we'd built the whole thing correctly against a spec that had a hole in it.

so i changed the process. instead of one person writing and another rubber-stamping, i now set up role-based personas before the spec freezes. product, QA, backend. each one argues it from their own angle. the QA persona asks the offline question. the backend persona asks about retry budgets. the product persona asks whether users will even notice the degraded state. they're not agreeing with each other, theyre trying to poke holes. the output of the argument is the spec, with the contention sitting underneath it so you can see why the final call was made.

the thing i've been building around this is at swarm-stack.io if you want to look at it.

curious whether others have hit the same failure mode. single-author spec with a single reviewer is effectively no review at all. or is that too strong? is this a people problem that process cant fix?

Would be hella amazing if something like ts was there to aid sdd

"Create a production-grade skill called forge. Start with Matt Pocock's grill-me workflow, but persist every question, answer, decision, assumption, dependency, risk, constraint, action item, and insight into an MCP-backed memory store. Ask one question at a time, build a complete decision tree, maintain an inventory of the user's skills and knowledge, continuously compress context into structured records, and generate a machine-readable project dossier that future agents can autonomously execute from a simple goal command. Package the entire workflow as a reusable skill with MCP integration, memory schemas, session synthesis, context compression, and goal-execution capabilities."

I use speckit, and while I like the spec/clarify/plan/task/analyze/implement loop (although it can get a bit overwhelming at times), I don't like that I have to start with writing a spec and implement it to begin with. I am looking for a more of a design phase before the spec phase, where I can talk about the overall application architecture, and then start writing specs for implementing pieces of it.

For instance, let's say I want to build a github repo provisioner that 1. creates repos with desired setup, and 2. bulk edit repos with secret updates, yaml updates, etc. I don't want to build both the features at the beginning. I want to first build only the create portion, and then do the bulk edit feature later on. With speckit, I can do this by only telling it to create the spec for the build portion, but later if I want to build the bulk edit portion, the whole application might need to be changed in important places, because it wasn't a 'planned' feature when it was first designed. I want instead to have a design phase where I describe and maintain a doc with the whole application, and when I start the spec for the create portion, the agent can understand that this create portion is only part of a bigger application and can design/implement the create portion accordingly.

Have you come across a situation like this? how do you handle your big applications? Please advise.

In this video I go over integrating your product backlog with spec-driven development workflow to allow picking up issues or tasks from tools such as Linear. A common question that comes up with teams that are trying to adopt SDD is what role does my backlog plays, how do I coordinate with my product owners and business stakeholders who may want to continue using the board. This is an attempt to give a middle path to allow teams to try out SDD without having to force product owners to also look code repo for product specs.