r/SpecDrivenDevelopment • • 12d ago

The shift toward AI-driven "vibe coding" and spec-driven development in modern tech agencies.

0 Upvotes

​Most dev teams are finding that pure prompt-and-pray coding leads to messy, unmaintainable codebases.

The real shift in 2026? Spec-driven development.

​When we build web automation tools at Enreach Enterprises, we don't just chat with an AI and hope for the best. We write clean structural specs first, let the AI handle the boilerplate, and use human judgment for architecture and security.

​Speed is great, but code integrity wins enterprise trust. How is your team balancing AI velocity with quality control?

#VibeCoding #SoftwareDevelopment #TechTrends #AIAutomation


r/SpecDrivenDevelopment • • Aug 05 '26

A Competitive Analysis of Spec Design Methedologies

Thumbnail webcloudstudio.com
2 Upvotes

I asked claude to honestly rate the various approaches for specification driven development by categories and features it chose. Here is the analysis it produced. Popular methodologies first then all methedologies. Source documents are at the bottom if you wish to reproduce the analysis. Please link additional documents in the comments that should be included and i will periodically update. Or run it yourself :)


r/SpecDrivenDevelopment • • 21d ago

Specs are the hardest part of AI-assisted development to actually understand and collaborate on. Sutra fixes that

Thumbnail
sutrasdd.app
0 Upvotes

AI generates a PRD or Specs in minutes, but what you get back is usually a wall of text with a lot of hidden assumptions.

Stakeholders skim it, engineers read it differently, and the AI builds whatever it thinks you meant.

I'm a PM, and I built Sutra (means Rules in Buddhism) to make Specs easy to see and track from idea to code:

\- Visual story maps. Your spec becomes an Epic → Flow → Story map, built by hand or generated from a prompt or PRD.

\- Security evaluation. Catches risks in the spec before any code is written.

\- Decision log. Records whether each decision was made by the AI or a human.

\- Sandboxed code generation. Writes a test, builds until it passes, then opens a PR.

\- Drift analysis. Shows where the code has strayed from the spec.

\- Token cost tracking. See what each part of the build costs and where you can cut.

Questions for this group:

\- What's the hardest part of working with specs on your AI projects?

\- Which of these features would you actually use?

would really appreciate any feedback. 🙏


r/SpecDrivenDevelopment • • Jun 11 '26

I hate DDD for 98% of the projects

Thumbnail reddit.com
2 Upvotes

It really just making the experiance of developing slow and dumber


r/SpecDrivenDevelopment • • Jun 05 '26

Senior devs: how much of your code review time is actually just figuring out what the code is doing in the first place?

1 Upvotes

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.


r/SpecDrivenDevelopment • • 18d ago

Goodbye LoadRunner and JMeter

Thumbnail
youtube.com
0 Upvotes

r/SpecDrivenDevelopment • • May 25 '26

Spec as part of your workflow - Define, refine and lock down your spec across stakeholders

0 Upvotes

I have been seeing a transitioning where people/team loosing the habit of spending time in sprint refinement instead every one focus on what features to get added to the software but with half baked requirements, all they need is features without a clear definition.

Seeing the above issue, drft is been built to solve this and I am able to see that it can potentially improve the agentic SDLC.

The problem isn't the agent. It's the requirement. No review gate. No locked spec and at the end that the requirements drifted

So built something simple to manage the:
**DRIFT.**
Not another coding tool. Just a framework for locking in what you actually want before the agent starts building.

The workflow which I find useful is,

  1. You or the PM describe what needs to be built (doesn't have to be perfect).

  2. Your AI agent refines it into a clear spec.

  3. You or the PM read the spec. You/PM approves it (or ask for changes).

  4. Your agent reads your codebase and writes a plan for how to build it.

  5. Your team member approves the plan

  6. Now your coding agent starts. It knows exactly what you want and how to build it.

  7. Every one in the team is in sync without any drift.

Everything is versioned. You can audit it later. You know what got approved when.

Does it slow things down? A tiny bit. Do you ship the wrong feature anymore? No.

Works with Claude/ Cursor/ Codex or any agent.

Happy to jump in with anyone who wants help getting set up or figuring out if it fits their workflow.

https://drft.build


r/SpecDrivenDevelopment • • Aug 08 '26

SpecJudge v0.4.0: it no longer requires spec-kit — and the reason that became safe is a mechanism I built for something else entirely

0 Upvotes

Up to this release SpecJudge answered exactly one question: you finished writing your spec, which model should implement it? If there was no .specify/ directory it refused outright with exit code 2. Which is defensible as a scope decision and turned out to be a bad one, because most repositories have never run Spec-Driven Development and nearly all of them have written down something — an AGENTS.md, a CLAUDE.md, a .cursorrules, a folder of decision records — and refusing to read any of it meant walking away from real signal on principle.

So it now reads spec-kit artifacts (including plan.md, which had been sitting next to the spec unread the whole time), agent-context files including nested ones in a monorepo, editor rules, and decision records under docs/adr and friends. Read together, never one instead of another, because your spec describes the work you're about to do and your AGENTS.md describes how demanding the codebase is to work in at all, and neither one contains the other.

The part that I think is actually interesting is why this became safe now and wouldn't have been a release ago. Mixing formats used to imply deciding, in advance, how much to believe a .cursorrules relative to a spec — five sets of trust rules, each evolving separately, each a place to be quietly wrong. Then 0.2.0 shipped the requirement that every rated dimension cite a fragment that exists in the input, with anything ungroundable returning unsupported and dropping out of the calculation entirely. That was built as a hallucination check, but it removed the need for format-specific trust as a side effect: the source stopped mattering, only what's citable does. A thin source produces a thin profile on its own, with no per-format logic anywhere in the codebase. I did not design it for this and I'm still slightly annoyed at how well it worked out.

When nothing in the input describes the work, you now get an answer plus an honest label on it: a warning that this is a floor — how demanding the repository is to work in — rather than a recommendation for a specific piece of work, and a concrete suggestion to describe what you're about to build, even as a paragraph. That's exposed in --json as environment_only, alongside sources_read for which kinds of source fed the assessment. Schema 1.1, both fields additive, 1.0 consumers unaffected.

Two implementation notes for anyone with a large repo. Context sources share one budget rather than each getting their own, because twelve separate caps of 8000 characters is a 96k-character prompt and therefore not a cap at all; a 200-character .cursorrules costs 200 characters and leaves the rest for a long root AGENTS.md. Files nearest the root are kept first, at most twelve are read, and whatever gets left out is reported rather than silently dropped. And context files that announce they were generated by a tool are skipped, since generated context mostly restates what the code already shows while taking budget from the hand-written file next to it.

pip install --upgrade specjudge, nothing to do on upgrade — a project with .specify/ artifacts is read exactly as before.

GitHub: github.com/JoaquinRuiz/SpecJudge


r/SpecDrivenDevelopment • • 21d ago

The Myth of the "Waterfall" and spec-driven development

16 Upvotes

I'm in the middle of redesigning the SDLC at work to accommodate AI. Having been doing more and more complex AI development for the past two years delivering production-quality code, its pretty clear to me that Spec-driven development gives the best results. One of the arguments from the portion of the development staff that doesn't want to use AI is that spec-driven development is nothing more than an updated "waterfall", and that's bad.

Having been a working professional before the agile manifesto was published, it was really clear that the agile folks were attacking something that never existed. Even the original Royce paper was arguing *against* using a fixed specification, and advocated for iterations.

This isn't my paper, but it lays out the argument very well.

http://www.bawiki.com/wiki/Waterfall.html

What looks like has happened over the years is many people use agile concepts as an excuse to not do any sort of planning or testing. The one lesson they took away was "waterfall (planning/design) is bad", so they just wing everything and almost nothing is automated. All manual front end testing. Almost no automated tests, preferring manual code reviews instead. Not only is the software not designed ahead of time, but there's no requirements, no architecture, no design of any kind, just coders banging out code until it kinda works. Of course all companies are unique, but I've consulted for dozens of software companies over the years, and the companies with no SDLC process greatly outnumber the ones with one.

Which comes to my task of creating a SDLC process that uses AI to create production quality code. If you through AI at a bad process, its going to create bad code. Spec-driven development frameworks at least keeps programmers on a reasonable path to success, which at least in my experience creates way better code than I've seen humans create.


r/SpecDrivenDevelopment • • Aug 08 '26

I built an AI Pomodoro app entirely spec-first — every feature got a written spec before a single prompt. Here's what changed.

Thumbnail ai-promodoro.vercel.app
2 Upvotes

I've been experimenting with spec-driven development: instead of prompting an AI agent with vibes, you write a real spec first (user story, requirements, API contract, acceptance criteria), let the agent implement it, then validate against the spec and update your roadmap. Loop until MVP.

The app is a Pomodoro timer where you describe your goal conversationally and the AI proposes a task plan sized in pomodoros ("2🍅 ≈50m"). There's a focus coach mid-session, sound cues, PWA install support, and since it's publicly hosted, a Cloudflare Turnstile gate + per-IP daily rate limit on the AI routes so strangers can't drain my DeepSeek credits.

Stack: Next.js 16, Bun, DeepSeek API, Upstash Redis. No database — plan state lives client-side.

What actually surprised me:

  1. \*\*Specs didn't slow me down\*\*. Six features in, the AI agent was dramatically better when implementing a spec vs reading my mind. Code review became "does this match section F3?" instead of squinting at diffs.

  2. \*\*The spec caught drift.\*\* When the model under-filled a response schema (returned 3 tasks when asked for 3 steps instead of the spec'd 4–8), it was obviously a contract bug, not "weird AI behavior."

  3. \*\*Re-planning after every feature\*\* (updating mission/roadmap docs) is the part everyone skips and the part that prevents the codebase from rotting.

Happy to answer questions about the spec format or the abuse-guard setup — both were more interesting to build than the timer itself.

\\- Live: \\\[https://ai-promodoro.vercel.app\\\](https://ai-promodoro.vercel.app)

\\- Source (the \\\`specs/\\\` folder is the real content): \\\[https://github.com/adotey7/ai-promodoro\\\](https://github.com/adotey7/ai-promodoro)


r/SpecDrivenDevelopment • • Jun 27 '26

what "level" of AI-assisted coding are you actually at? (autocomplete → not touching the code)

2 Upvotes

saw this framework recently and it's been a useful mirror, curious where this sub lands.

the idea (Dan Shapiro's, modeled on self-driving levels): there are 6 levels, 0 to 5.

0: autocomplete, you write everything

1: you delegate tiny tasks, review all of it

2: AI writes across files, you read every line

3: you stop writing, you review the PRs it opens

4: you write a spec, walk away, check if tests pass (code = black box)

5: nobody writes or reviews code, specs in / software out

the spicy claim is that ~90% of devs are stuck oscillating between 2 and 3 and don't realize it. you climb a bit, get tired of reviewing endless diffs, drop back to "let me just write it myself." every level feels like the top.

what makes 3→4 hard imo isn't the tooling, it's trust. going from "i read the code" to "i trust a spec + external tests" is a mental jump most people (me included, some days) won't make.

genuinely curious, not rhetorical: what level are you at, and what's keeping you from the next one? and if anyone's living at 4-5 in a real codebase (not a demo), how's it actually going at 3am when prod breaks?


r/SpecDrivenDevelopment • • Jul 16 '26

Enterprise what to choose?

3 Upvotes

We tried spec-kit but it's way too heavy and there's not much brainstorming. Then we tried open spec which is lightweight but it's working almost entirely in the dumb region. Superpowers I had some success it but didn't test that too much. Grill me seems to be hitting the dumb zone too quickly and the workflowas Matt's been using is the other way around, I don't want to create a prd I want the prd to be fed into the framework. I heard get your shit done is gaining some steam. Whats your choice?


r/SpecDrivenDevelopment • • May 02 '26

Specs are not requirements

3 Upvotes

I like openspec, but I can accept how it gives feeling that spec can be updated at scales.

For me, specs are disposable. What are not and could be maintained are requirements. The difference is that requirements explain what needs to be done and spec say how it would be implemented and tested.

I do not know any SDD framework that maintains a set of requirement aligned with the code. Do you ?


r/SpecDrivenDevelopment • • Sep 27 '26

¿Desarrollo basado en especificaciones SDD + Antigravity esta muerto ?

3 Upvotes

SSD en Antigravity dejaron de usarlo ? hoy actualice agy y antigravity agentico y no pude usar SDD como lo dice la documentacion:

  1. Go to the project folder: cd public_html                                                                                                                                                                                            │

│  2. Start using slash commands with your coding agent:                                                                                                                                                                                  │

│     2.1 /speckit.constitution - Establish project principles                                                                                                                                                                            │

│     2.2 /speckit.specify - Create baseline specification                                                                                                                                                                                │

│     2.3 /speckit.plan - Create implementation plan                                                                                                                                                                                      │

│     2.4 /speckit.tasks - Generate actionable tasks                                                                                                                                                                                      │

│     2.5 /speckit.implement - Execute implementation                                                                                                                                                                                     │

│     2.6 /speckit.converge - Assess the codebase and append remaining work as tasks  

Con las nuevas actualización de antigravity para:

Antigravity CLI 1.2.11
Antigravity 2.0 (agent first) Versión 2.17.0

No he podido usar SDD, solo la nueva feature de antigravity de /plan

¿Antigravity ya lo dejo de usar para sus dos herramientas de desarrollo con IA ?

saludos

Mexman


r/SpecDrivenDevelopment • • Apr 07 '26

I tested whether specs reduces defects. It doesn't. (119 repos, 100K PRs)

16 Upvotes

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


r/SpecDrivenDevelopment • • May 28 '26

Heard yall like... Specs? :D

0 Upvotes

I made a spec printer! https://manifesto-engine.com/


r/SpecDrivenDevelopment • • Jul 28 '26

Using github spec kit in a mono repo

Thumbnail
reddit.com
0 Upvotes

r/SpecDrivenDevelopment • • 29d ago

Who decided that? (The future of Spec Kitty)

Post image
0 Upvotes

We have published our clearest vision statement to date. It's a manifesto. It shows where we think the important work lies in the world of agents. It's all about decision making. That's what will be left for humans when agents do all of the execution. And Spec Kitty has a huge role to play in identifying, classifying, adjudicating, informing, recording, and applying decisions that get made. https://spec-kitty.ai/blog/who-decided-that


r/SpecDrivenDevelopment • • 22d ago

I'm building an open-source engineering control plane for AI-assisted development — what would you challenge?

Post image
0 Upvotes

r/SpecDrivenDevelopment • • Oct 12 '26

vibe coding

0 Upvotes

1/ Our client app is a brownfield monorepo. I'm testing a "one dev delivers three platforms" setup: one workspace driving iOS / Android / HarmonyOS. Half-working so far — sharing the approach and looking for war stories.

2/ Integration: the three native repos keep their own structure and are mounted into one workspace via symlinks. Zero copy, zero intrusion into the existing repos; each platform still ships independently.

3/ Workflow: a custom skill wraps OpenSpec's explore -> propose -> apply -> archive loop. Requirements start as a spec; the agent produces code against it; review is traceable and revertible.

4/ Parallelism: native git worktree — one branch per feature, no cross-branch interference. AI coding agents work directly inside a worktree and open PRs; the human only reviews.

5/ Still polishing, especially symlink compatibility across Xcode / DevEco / Gradle. Anyone done something like this? Let's compare notes in the replies. #OpenSpec #AICoding #HarmonyOS #iOS #Android


r/SpecDrivenDevelopment • • Jul 12 '26

Any one using Compound Engineering from Every ?

4 Upvotes

I’ve been using it for quite some time and I like the results so far. I discovered the plugin on X, but I rarely see anyone talking about it.

The main appeal is that it compounds knowledge after you finish a feature or spec. The next time you plan something, it checks the documented learnings — from common bugs to architecture patterns to coding conventions.

One thing that feels off is that it burns through a lot of tokens and hits my limits within 4–5 loops (plan → work → review → compound) in OpenCode.

I’m not sure if it’s worth it long-term or if I could get similar results with something more lightweight like OpenSpec or Superpowers.

Has anyone used OpenSpec, CE, or Superpowers on web dev projects (especially Rails or similar MVC frameworks)? Would love to hear real experiences.


r/SpecDrivenDevelopment • • Aug 26 '26

Specs are the contract for what gets built. I built the contract for what review could not close

4 Upvotes

The move that makes spec-driven development work is taking intent out of the chat and into a versioned artifact that tools can enforce. I have been applying the same move to the other end of the pipeline: the review.

My loop for the past few months: one assistant generates the plan or the code, a second assistant from a different model family attacks it under an explicitly adversarial prompt, and the round only ends when every finding is incorporated, refuted with evidence, or escalated to a human. It works, but everything the round produced used to die in the chat window. And the most valuable part of a review is precisely what did NOT close: the unverifiable assumptions, the tradeoffs someone accepted, the escalations waiting for a human decision. That is the residue.

disensor turns that into a contract. Each round closes with a JSON artifact (schema residue/v0.3) that records who generated, who attacked (model family plus the hash of the adversarial prompt), every finding with a terminal state, and the residue items. A validator enforces the schema plus semantic rules: counts have to add up, generator and reviewer must come from different families, verifiable refutations need material evidence, and generic markers like "reviewed, all good" are rejected. A GitHub Action then gates every PR: code changes need a valid declaration covering the exact tree being merged, and evidence is append only, so a PR cannot rewrite review history.

If your spec is the single source of truth for what should be built, the residue declaration is the single source of truth for what verification left open. They bookend the same workflow, and neither runs a model: disensor validates artifacts that already live in your repo, no API keys involved.

Honest limit: the gate detects the empty field and the generic marker, not a well-written lie. Human sampling of merged PRs stays in the loop by design.

I documented the method before publishing the tool: 91 review events across 5 projects over 52 days, DOI 10.5281/zenodo.21633495. The repo gates its own PRs, so .residue/ holds the real declarations of its own development.

Repo: https://github.com/NicolasRocchia/disensor (MIT, pip install disensor)

Site: https://disensor.dev

Curious how people here would wire this into a spec-driven flow: does the residue belong next to the spec, or downstream of it?


r/SpecDrivenDevelopment • • Aug 04 '26

Rethinking Spec Driven Development

4 Upvotes

I've been working on ZeNorm, a tool where an agent interviews you about a feature and turns your answers into a spec your coding agent can implement.

I built it because existing spec-driven dev tools never struck the right balance of overhead and improved results in agentic coding workflows. I wanted to avoid another markdown file generator.

Describe the feature, and ZeNorm connects to your repo and asks questions until there's a spec with tasks and a dependency graph. Then have your agent of choice implement the spec by invoking a skill.

Would love to hear any feedback you have!


r/SpecDrivenDevelopment • • Apr 16 '26

What breaks about SDD past the first few features, and how I ended up designing around it

4 Upvotes

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.


r/SpecDrivenDevelopment • • Oct 01 '26

I built SpecForge: a Rust compiler that turns your specs into a validated graph for AI coding agents

15 Upvotes

AI coding agents burn most of their tokens working out what you meant. They read 20–50 files, guess at requirements, and get it wrong. Then you spend a second pass fixing it. The intent was in the docs, tickets and people's heads the whole time. It just wasn't in a form the agent could rely on.

So I started building **SpecForge**. It compiles human intent into a typed, validated entity graph that agents can query.

**What it looks like**

```spec

behavior authenticate_user "Authenticate a user with credentials" {

status draft

contract "Given valid credentials, returns an auth token"

produces [user_logged_in]

verify "rejects invalid password"

verify "returns token on success"

}

event user_logged_in "User successfully logged in" {

payload user

}

```

```bash

specforge check # validate specs, report diagnostics

specforge export # emit the typed graph for an agent

```

**What it does**

- **The graph is the product.** The compiler parses `.spec` files, resolves references, finds orphans and cycles, and emits a typed graph as an open JSON schema (the "Graph Protocol").

- **It's built for agents.** `specforge mcp` serves the graph over MCP, so you can hook it into Claude Code or any MCP client with one command. There are also multi-depth queries and context/brief exports.

- **Proof, not just claims.** `specforge collect` runs your own tests (only after you approve the command) and records which spec entities they actually prove.

- **It isn't a code generator or a test framework.** It gives the agent context, and the agent writes the code. The compiler never executes anything on its own.

**How I built it**

It's a Cargo workspace of about 25 crates and roughly 160k lines of Rust (tests included), split by pipeline stage:

- **Parsing:** I wrote a tree-sitter grammar for the DSL (`tree-sitter-specforge`). The parser, formatter and LSP all sit on top of it. That gave me error-tolerant parsing and incremental re-parse for editor use without writing a parser from scratch.

- **Pipeline:** parser → resolver → graph → validator → emitter, each its own crate. Strings are interned with `lasso`, and diagnostics are rendered with `ariadne`.

- **Zero-domain-knowledge core:** the compiler knows nothing about "behaviors" or "events". Entity kinds, edge types and validation rules all come from extensions. I made this a hard rule on purpose, so a new domain should never need a compiler change.

- **Extensions are WASM components:** I defined the extension interface in WIT and host them with `wasmtime` and the component model. There's an extension SDK crate with proc macros, so writing an extension in Rust is mostly declaring kinds and rules. The nine builtin extensions are compiled to components and embedded in the binary, so installing needs no extra toolchain.

- **Surfaces:** the CLI, the LSP server, and the MCP server all share one operations layer (`specforge-ops`), so they can't drift apart on behavior.

**How AI was involved**

I built a lot of this with Claude Code, and I'm saying so up front. It wrote a large share of the code, and I drove the design: the architecture, the extension boundary, and the ADRs in `docs/adr`.

It also caused my biggest dead-end. Partway through, I audited the test suite and found features that had passing tests but didn't actually work. The tests were checking the wrong thing, so they passed anyway. I've been fixing those since, and the `specforge collect` idea (record which entities your tests really prove) came out of that experience. A tool that checks specs against tests seemed like the right answer to AI-written tests that only look green.

The hardest design problem is still the extension boundary. The core can't know anything about the domain, yet validation still has to produce good diagnostics and cross-entity checks.

**Try it**

```bash

git clone https://github.com/leaderiop/SpecForge && cd SpecForge

cargo install --path crates/specforge-cli

specforge init --extensions u/specforge/software

```

It's early, and I'd like feedback on a few things:

  1. Does the DSL feel natural, or would you prefer YAML/Markdown front-matter?

  2. Is the WASM-component extension model overkill, or the right call?

  3. Which extensions would you want (OpenAPI? data models? infra?)

Repo: https://github.com/leaderiop/SpecForge