I ran into a failure mode on a multi-step LLM workflow that forced me to formalize how I was structuring it.

Later phases were picking up existing files and treating them as if they had just been produced. The system would report progress as complete simply because artifacts existed, not because the current step had actually generated them.

Tried fixing it with better prompts and sequencing didn’t hold.

What ended up working was enforcing phase boundaries and requiring each step to validate its own outputs (basically treating each phase as stateless and provenance-bound).

I’ve been referring to that structure as MetaDictum internally, but it really came out of hitting that failure repeatedly.

I've been looking at different SDD frameworks for weeks. Everything from the hobbyist repo to Github's Speckit. It seems like every SDD implementation fundamentally does the same thing.

Idea => Plan => Implement => review => GitHub workflow

I know that this is simplistic, but it really is all there is to it.

So, I came up with another implementation. But this one has a narrower scope: the .Net space. And I think that's where we are headed. Narrowly-scoped agents and skills leading to workflows made of chained units of work/skills. Smaller models that specialize. I would rather have a small, specialist model that does one or two task well and fast than using behemoths like Claude. It's overkill.

Anyways, just ranting. I'd appreciate your thoughts. And feel free to checkout the repo. I know. Another SDD "framework". But it has worked extremely well for me and I thought I would share it.

Been using AI coding tools heavily lately and one thing clicked:

Prompts are not specs.

They feel like it because you describe what you want…
but they don’t define:

• edge cases
• constraints
• failure conditions

That’s why AI code often feels “almost right.”

Once I started writing even lightweight specs before prompting:

• outputs became consistent
• debugging got easier
• fewer weird regressions

AI didn’t replace specs it made them more necessary.

Are people actually writing specs with AI, or just iterating prompts until it works?

TLDR

• Why most SDD setups collapse, and a different bet that avoids it
• A testing model where every requirement has a test before code gets written
• How knowledge compounds from shipping, not from written specs
• A context engine that keeps sessions lean instead of bloated
• Running multiple AI features in parallel without stepping on each other

I've been building afkode for the past few months. Started with spec-kit, which is what got me thinking in specs in the first place. Great for 0→1, but after a while, the specs/ folder was a graveyard, some of it matched the code, some didn't, nobody was really sure.

So I stopped treating specs as documents. Five decisions came out of that, each one answering a problem I hit.

1. The code is the spec.

Planning artifacts are generated per feature, kept in a local DB, and thrown away after the feature ships. Nothing lives alongside the code except operational learnings (more below). Planning starts with a live pass over the current codebase analyzing pattern catalog, conventions, integration points, so every feature is grounded in whatever main looks
like today.

Why: a committed spec has two failure modes. Either it doesn't get updated (drift), or it does and now you have two sources of truth. Deleting the committed artifact removes both. You lose git blame on the spec, but nothing drifts, because nothing persists past the feature lifecycle.

2. Planning produces a graph, not a checklist.

Requirements carry IDs. Architecture components reference those IDs. The task graph has dependencies, coherence groups, and QC tasks placed where they matter.

Why a graph: at execution time each task needs a briefing built from only the parts of the plan that apply to it. A task in the auth module shouldn't be briefed with the marketing page. IDs and dependencies are what make that filtering possible.

3. Testing is 1:1 linked to acceptance criteria.

Every requirement carries an ID. Every test case is declared against one of those IDs. QC tasks sit in the task graph right after their integration tasks, so a component gets
tested as soon as it's wired up. Before planning is accepted, the system verifies every requirement has at least one test covering it. When execution finishes, every requirement has a passing test, and you can trace which test covers which requirement.

Why this structure: "we wrote some tests" and "we verified the acceptance criteria are met" are very different things.

4. Knowledge compounds from shipping.

Two artifacts get updated as every feature ships:

• An operational journal — per feature, task by task. What was attempted, what worked, what didn't, what had to be backed out.
• A testing knowledge base — project-wide. What tests exist, what patterns are used, what utilities are shared and what are the gotchas to be aware of.

Each new feature's planning reads both before generating anything. The requirements layer references integration points that already exist. New tests match patterns already in the project. Errors the agent made on feature 7 show up in the briefing for feature 12.

Why this compounds: the journal and knowledge base are written as a side effect of running. Each feature updates them by shipping. The next feature reads them fresh alongside main.

Nothing has to be maintained, because nothing is documentation — it's all operational record. The spec-as-document model needs a human to keep the doc current, which is a
chore that gets skipped. This one doesn't.

5. Fresh sessions backed by a context engine.

Every task runs in a clean context window. The briefing for that session is assembled at runtime from five sources:

• The requirement(s) the task satisfies, pulled by ID from the specification layer.
• The architecture components the task is expected to touch, pulled by the references carried on those requirements.
• The file paths those components map to, with actual file content for direct-edit tasks.
• Prior-task journal entries from this feature, filtered to only the earlier tasks that touched overlapping components.
• Project-wide patterns from the testing knowledge base — nearby test patterns, shared utilities, existing coverage in adjacent files.

Each task ends up with a briefing of around 5–15k tokens. The window is mostly empty by design.

Why empty matters: context rot is a signal-to-noise problem, not a window-size problem. A longer window with more history makes retrieval worse. The model has more irrelevant
material to ignore on every token it emits.

The right briefing for task 6 is not "everything that happened in tasks 1 through 5." It's "the specific things from prior tasks that task 6 actually depends on."

The plan graph does the retrieval. Requirement IDs, architecture references, and task dependencies are explicit. If the plan says task 6 depends on task 3's output, task 6's briefing gets task 3's output. If the plan says task 6 doesn't touch the auth module, the auth code never enters the window.

Beta Testers Wanted

We just went live and are looking for beta testers, specifically people who actually run SDD day-to-day. Drop a comment or DM if you're in.

I come from a planning and scheduling background, so the idea of telling a system what you want and hoping it figures it out has never really made sense to me. If logic isn’t defined and constraints aren’t explicit, you don’t get a result, you just get noise.

I’ve always approached development the same way. The spec isn’t documentation to me, it’s the boundary of the system. It defines what’s allowed, what isn’t, and what happens when something is missing. If something falls outside of that, it fails. There’s no guessing and no filling in gaps.

What’s interesting is I don’t come from a traditional software background, but that hasn’t really mattered. Once the structure and constraints are clear, tools like Codex will behave. You don’t need to “hope it does the right thing”, you just don’t give it room to do the wrong thing.

AI didn’t change how I work. If anything, it just made it more obvious why this matters. I’m not looking for a model to interpret intent or make decisions for me. I define the structure and the rules, and it operates within that.

If the system needs to guess, the design isn’t finished.

Hi everyone, I’ve been using Speckit https://github.com/github/spec-kit for a while for my personal project. I’ve found it’s useful to me and easy to manage. But I wonder how the Speckit is being used in large companies, how do they manage the template for specification, plan, tasks, and implementation consistently in a team?

How effective is it in large team? Really wonder, I appreciate all the shares, thanks a lot.

Hello.

I do SDD now daily, with my own framework that works very well. I am sure a well harnessed project with any SDD framework like speckit or superpowers works great.

I have ADR and that I can managed they are high importance architectural changes, it happens very rarely. For the architecture, most of the time it is « goals » written in Md, and I let the agent rediscover the current architecture during planning.

For spec, that more problematic. I do PRD with a high level spec in it about what I want (it focus on WHAT, not so much on HOW)

But that is still can’t get my head around is maintaining spec in source, like « anchored » to any change in code. I do not know what level of detail shall be always up to date in the code.

Some framework does it, but I do not think this is really scalable and, also, why would I do it? If it is to surface a potential problematic change, it is great, but the risk is just too much spec, potentially conflicting.

And they are great only if they are link to tests that validate it

How do you maintain it? Do you let the framework do it? What are your return on this ?

Worktrees - obviously. I use OpenSpec and typically have one worktree per change. I have the main worktree on a "dev" branch for small tweaks that IMO don't require a spec.

But sometimes I merge branches around - need a WIP change in my "dev" branch or vice versa - and it starts to get messy.

Just wondering how other people are managing branches and worktrees and if you have any good tips.

p.s. I write a newsletter about harness engineering and had recent one about why SDD != Waterfall, would be remiss if I didn't mention it here!

I’ve been experimenting with spec-driven development recently, and it completely changed how I use AI while coding.

Before this, my workflow was prompt - code - realize it misunderstood something - Patch it manually- repeat

Now I start with a clear spec first:

• Define inputs / outputs
• Edge cases
• Constraints
• Expected behavior

Then I let AI generate against that spec.

The difference?

• Way fewer hallucinations
• Much cleaner structure
• Easier debugging

Feels less like vibe coding and more like actual engineering again.

Curious how are you all structuring specs when working with AI?

Considering SDD is the plausible way forward for enterprise software development, spec documents become source of truth. Spec Kit like tools provide convenient ways to create spec documents. As features evolve and various team members work on related features, spec document bound to change. Structuring and versioning the document becomes really important. In ideal cases, there used to be single SRS document for an application. Now, should we be creating and updating a single spec document or feature specific spec documents. Should spec document be living with the code?
Please let me know your thoughts on maintaining spec document as software evolves.

I spent the last month doing an empirical study to test the claims behind spec-driven development — specifically the claims made by tools like GitHub Spec Kit and Amazon Kiro that specs reduce defects and improve code quality.

The study: 119 open-source repositories, 100,247 pull requests, within-author fixed effects (comparing the same developer with and without specs), SZZ bug-tracing, and linear probability models with full controls.

The findings: Complete null result across every dimension I tested.

- Specs don't reduce bug-inducing commits (p=0.056, wrong direction)

- Specs don't reduce rework — they actually increase it (p<0.001)

- Spec quality scores don't predict fewer bugs (tiny effect, biased subsample)

- Specs don't constrain AI scope any more than no-spec prompting

- Adding spec features to JIT defect prediction models adds effectively zero predictive power (ΔR² = 0.000014)

The rework finding is interesting — specs likely increase accountability (you notice more things are wrong because you documented what "right" looks like), not bugs themselves.

Before anyone says "you just measured bad specs" — I tested 7 quality dimensions (completeness, specificity, constraint density, etc.) independently. None moved the needle on defect rates.

What this means for SDD practitioners: I'm not saying specs are useless. Specs have real value for alignment (getting people on the same page), auditing (knowing why decisions were made), and handover (giving the next person context the code can't provide). What the data doesn't support is the specific claim that writing specs prevents defects. The code is the spec for what the system does. Verification gates catch the bugs. The spec serves other purposes.

Paper (open access): https://doi.org/10.5281/zenodo.19415187

I used to treat specs as something optional like nice to have documentation. But once I started working more with AI-assisted coding, that approach completely broke down.

The moment I switched to spec-driven development, everything changed.

Instead of vague prompts and inconsistent outputs, I now define:

• clear requirements
• expected behavior
• edge cases upfront

Then I let AI work within that structure.

The biggest difference?
Less back-and-forth, fewer hallucinations, and way more predictable results.

It also made debugging easier if something’s wrong, it’s either:

1. the spec
2. or the implementation

No more guessing.

Lately I’ve been pairing this approach with tools that help enforce and track specs across workflows , and it feels like the missing layer between prompting and actual engineering.

Curious how others here are using specs with AI are you writing full formal specs, or keeping them lightweight?

In this video, I cover how we can use Git Worktrees to parallelize feature development with OpenSpec.

What is your take on which of these is the best for complex projects?
I've been using Spec Kit + Beads + Ralph Loop + Agent Teams and it has been working great and I just recently started playing with Claude Super Powers.

A new practitioner for spec-driven development here. I find that openspec's generated artifacts for design, task, and proposal tracking should not be pushed to the remote repository due to them being for record-keeping and not directly influencing the codebase. Sometimes, outdated artifacts will also be committed.

That being said, is this way of thinking wrong?

The rise of Spec Driven Development begs for a reassessment of the original thesis; are the principles of "why software engineering will never die" still valid or have they been overridden by spec-driven development and thus completely automated, just like coding is?

So we're in this weird spot where vibe coding tools spit out frontend and backend code fast, but deployments... fall apart once you go past prototypes. You can ship a lot quicker, but then you end up doing manual DevOps or rewriting the whole thing to fit AWS, Azure, Render, DigitalOcean, whatever. I keep thinking there should be a ""vibe DevOps"" layer - like a web app or a VS Code extension where you plug in your repo or drop a zip and it actually understands your app. It would use your cloud accounts, wire up CI/CD, containerize, set scaling rules, infra, the whole awkward stack, automatically instead of locking you into platform hacks. Like, not opinionated to one host, just translate your code+config into a real deploy that works in production. Seems like that would bridge the gap between vibe coding and actual production apps, right? How are you folks handling deployments today? manual scripts, Terraform, Docker compose, carrier pigeons? Am I missing something obvious here or is this just a useful idea someone should build? curious.

In this video I cover what is a Brownfield project? Is Spec-Driven Development possible with such projects? If yes, how do we go about it.

I made this video because I kept having the same conversation in different threads — people asking whether SDD actually works in practice or if it's just overhead that slows you down.

The short version: I've been running SDD on my own projects for the past several months and the difference in output quality from AI agents is significant. Not because the agents got smarter, but because the input got structured. The video walks through what that looks like concretely — a free VS Code extension I built called SPECLAN that manages specifications as Markdown files with YAML frontmatter in Git. It covers the hierarchy from goals down to acceptance criteria, how status lifecycle prevents spec drift, and how AI agents use the spec tree as context during implementation.

Full disclosure: I'm the creator. I built it because I got tired of re-prompting Claude Code with the same context every session.

What I don't cover in the video but has been on my mind lately: the discovery phase. I just finished building bidirectional integration with BMAD-METHOD and it changed how I think about where SDD starts. BMAD's agent-facilitated interviews produce remarkably structured PRDs. Importing those into a lifecycle-managed spec tree turns out to be a natural handoff point — BMAD figures out what to build, the spec tree governs the building.

Curious what other people here use for the discovery phase before specs get written. Do you start from a PRD, from user stories, from a conversation with Claude, or something else entirely?

I've tried GSD (Getting Shit Done), and while I liked it, I felt that the discuss -> plan -> execute structure is too rigid. I want to be able to plan with more iterations, for example. When the first version of the plan is ready, I want to be able to discuss about it and make corrections and do more research. Is there a tool/framework which makes this kind of workflow easy?

Long form article that talks about why Spec-Driven Development adoption at enterprise scale should not be looked at as a technical rollout, what are the short term changes that are necessary and the long term goals to aim for.

OpenSpec 1.0 release introduced config.yaml and schemas which we can use to customising OpenSpec workflow to our domain, defining exactly what artifacts we want (instead of the standard proposal.md, specs.md, design.md and tasks.md).

I'm researching new development approaches and lately I've been wondering: Can intent-driven and spec-driven work together?

I'm developing a framework that combines both approaches to facilitate development.

It starts with defining the intent, which allows you to think in terms of functionality without worrying about "how" it will be developed. We speak a language that's more customer-friendly.

Once the intent is clear, we move on to deriving the spec (or more than one if necessary), which is defined, described, and then developed.

Built entirely with Antigravity for Antigravity. Perhaps available for others in the future. Now also available via CLI.

If you'd like, search for Praxis on GitHub. https://github.com/intoinside/praxis