Show HN: Specification First Agentic Development Plugin and Prove | Hacker News Reader

Show HN: Specification First Agentic Development Plugin and Prove

spec-first.dev

34 pointshleichsenring31 comments

Implemented agent smith since start 2026 with over 1000 specifications which lead to about 500k lines of code. The procedure with that spec-first works well. How do you do it?

Open articleView on HN

Always reminds me of this meme.

Some day we won't even need coders any more. We'll be able to just write the specification and the program will write itself.

Oh wow, you're right! We'll be able to write a comprehensive and precise spec and bam, we won't need programmers any more!

Exactly!

And do you know the industry term for a project specification that is comprehensive and precise enough to generate a program?

Code It's called code.

Two things about that. On the one hand, I couldn't believe coding would be replaced when I started Agent Smith in January 2026. On the other hand, I wanted proof.

After 500k lines of code in Agent Smith, none of which I wrote by hand, I have to admit it: coding is more or less solved. That doesn't mean architects, developers, DevOps people and everyone else aren't needed anymore. I think they're needed more than ever.

Just implementing something isn't good enough. The spec has to point to sensible approaches and procedures, and the code has to be well structured (in my view, at least). Then the specs can simply run in parallel all night.

So my actual work on Agent Smith isn't coding at all. It's deciding what the right thing to build is, and how, in terms of design and architecture. I don't even review the code. But I do test it: 10k tests, a harness, a commit hook that blocks a spec while the suite is red, the whole story.

And unfortunately, that works pretty well. I also think last year's programming was more romantic :-D

> And unfortunately, that works pretty well.

Why unfortunately?

Because I loved writing code myself, and that feels kind of outdated now. Who's going to pay me to code "slowly" when AI does it a lot faster?

But people do unpaid painting, horseback riding, calligraphy, etc. which are outdated because they love it. Why is it so unfortunate for you?

Don't take it too seriously. But anyway:

I work as a freelancer and started programming at 12. I've been doing it for 40 years now.

I guess I'm ambivalent. On one hand these are crazy times, really stunning. Everything is changing, and AI takes over a lot of stuff I never wanted to do, but also parts of what I loved doing.

This year the time I spend actually programming dropped to 5–10%. Last year it was still 80%. That's a big change for a professional life. It means developers and architects spend their time on design and on proving the code works, not on writing it.

Agent Smith and all the other stuff is one of my side projects. So I'm just being a little nostalgic here, I guess. Nothing too serious ;-)

In their spare time, with what energy remains after putting most of their energy into work and other obligations.

Of course it is unfortunate to lose the ability to get paid for something they enjoyed.

I agree that “coding” in the sense of hand-writing code is solved.

But code was made to create architecture, to design systems and also to make actual code (machine code) readable for humans.

In my experience with spec-driven development, the lossy layer of specs on top of code is not the right way to drive development of systems and architecture. The English language is not precise enough to describe those systems.

Of course you can use specs or just prompts to drive the creation of code (I do that for 99% of my code) but the “truth” is still the actual code and not the prompts/specs.

Maybe that’s also just a difference between people (like visual learners vs non-visual etc.) and some have an easier time to grasp every detail of the systems they are working on through code and some through descriptions.

Guess it also depends on the complexity of the software you are developing. For private projects I had more success with spec-driven while at work it would be a terrible choice.

Very confidently wrong.

Do you know why it's easier to specify theorems than it is their proofs? Or why ACSL != C?

You can go ahead and make a more specific argument, e.g. that mainstream UX-centric software development may not be amenable to current paradigms of formal verification, but to insinuate that a complete spec reduces to source code itself is naive.

EDIT: Possibly I have responded too acutely to the points you care less about. I agree that "in the future we won't need programmers" is questionable since good spec-writing and spec-vetting requires at least as much expertise, if not more, than ordinary coding work, and that is fair to call comprehensive spec work "code" in that it is technical and formal. But it is decisively not source code.

A couple of decades ago coding was "solved" by just writing UML diagrams. The nonsense never ends.

That's a different thing. UML described structure: classes, relations, maybe some state machines. The generators turned that into skeletons, and people still wrote the actual logic by hand.

Here the agent writes the logic too, and 10k tests plus a commit gate check whether it works. In my case that's about 500k lines nobody typed. You can doubt that the approach generalizes, but it's not the same promise as UML.

I think both can be true: as coding languages go from lower to higher level, they go from being more implementation-like (e.g. assembly, C) to being more spec-like (e.g. Rust, Haskell). It then follows that writing a good spec could be considered coding if your compiler (or agent) can reliably turn that spec into your desired output.

So the main challenge I see with this approach is getting the spec right. Too little detail and the output is uncontrolled, too much detail and you're adding too many constraints (and you may be better off just writing code). From my experience, agents haven't been the best at writing good specs. But maybe this project can help with that?

Yes. That’s the problem I noticed with specs too. Agents aren’t really good at finding the right abstraction layer. They tend to write way too detailed specs (e.g. naming variables in specs) and when controlling for less details the output degrades.

But I worry the most about who will be able to define all of those specs (with all of their necessary detail and edge cases etc.) without understanding the systems that live below the specs. Maybe that won’t be a problem anymore if agents will be able to 100% accurately translate specs into code. But for now I imagine this to be really difficult.

I have not seen spec first development work well in real world environments at all. The problem is that you typically don't know what you don't know upfront for most product based decisions. Going back and forth in the spec to fix problems is a huge mistake, it just leads to contradictory sets of requirements for the agent.

What does work well is using AI to generate a quick and dirty prototype ala vibecoding, and then using that as a basis to regenerate the final code. Some might say it's still spec driven development, but the spec is a working prototype.

they do work well in production. have a look at https://github.com/holgerleichsenring/agent-smith. While writing that the methodology had been created. Obviously, I didnt know upfront what I wanted to generate here. Also features are changed or removed on the way. that's not a problem, when the specifications are part of the git repository as it is done here. Actually it's the other way around: it is an advantage as the agent can have a look at everything that had been done previously and can understand what, why and how it had been implemented. give it a try :-)

Your silly software factory is not proof that SDD works well in production. It is proof that it can produce software, and that’s a very low bar.

We’ve been using SDD at $workplace for more than a year and we’ve started to actively remove all spec documents so agents don’t get stuck reviewing out of date context for 20 minutes, burn through token budgets, and give disproportionate focus to legacy patterns and business directions we’ve pivoted from.

Models are RLHF’d to work on non-historical documentation and iterative design, and that’s what yields the best overall results.

Specs-as-history is rapidly becoming an antipattern as teams actually try to scale SDD. We're already putting guardrails in agents.md (non-normative in all caps), some teams are actually offboarding them - to Rally (which I find the height of hilarity).

Spec docs - at least in all the other things like this thing - aren't a living representation of truth, instead they are a collection of snapshots in time of feature deliverables. Layer 500 of these on top of each other and they quickly become not just useless but actively harmful. Archive them, compile them, whatever your plugin does, it still doesn't help. Nobody is going to pay for tokens just to keep the specs time-coherent, when the agent can just read the code.

Don't get me wrong, a spec is a useful bit of kit for development, just like Jira and Rally, but also like Jira and Rally they aren't the source of truth because there's already a better one which you just paid for.

I think this is where updating and maintaining the specs is just as important, if not more than adding new ones.

Maybe your flows coins take advantage of ensuring that the specs define the intent and active decisions made and not just “what the code does”, which it can actively read from the code itself.

in my opinion, high-level planning is the important thing. not going too deep into planning, but more about having a plan as a red line that helps you not to drift away from the initial goal. in my point of view is that the risk when you start with a vibe-coded prototype, which is a great starting point and something I also like to use. But a few weeks later, you get to the point where the initial goal starts to drift, and you constantly have to steer things back to stay on track. That’s one of the critical pain points in my opinion.

I’ve recently adopted openspec for one of our repos and it’s worked great. Openspec is already decently well established and has a lot of support for all the different harnesses that exist.

I’m really starting to enjoy it for helping flush out the ideas in my head into something real and tangible.

You dont know what you dont know upfront, we are back to the SDLC cycle of waterfall, where we discuss, and document the requirements and if needed prepare test cases as per TDD pattern and then use that to start the development same as in the old days, while it also gets merge with the agile model where the build is done so fast that in one week we may be taking up the next phase which in the old world would have taken 6 months

If your specs are not executable or are editable by the agent, they are as non-deterministic as any code that comes out of them.

the agent creates and maintains the specs, doing this manually doesn't make sense. The specs are written for the agents. after execution of create-spec, review-spec skill will check against the code and add evidence of the spec's aims. Only when the aims fits to the evidence, the specs is going to be validated successful. after that apply and deliver skills can be executed. finally there is commit hooks and tests that shall ensure quality and functionality. have a look at https://github.com/holgerleichsenring/agent-smith for the quality gates.

Seems straight forward and easy to use. How does it compare with GSD? https://github.com/open-gsd/gsd-core

What is the difference between having the agent create a spec and having the agent create a plan?

A plan lives in one session and is gone afterwards. A spec is a file in the repo. It gets reviewed against the actual code before anything is built, its definition of done is checked when the change is committed, and it stays there with the decisions behind it.

The next agent reads what was built before and why. And because it has a fixed format and workflow, everyone on a team works the same way, instead of each developer prompting their own plans.

its crazy how capable the agents are becoming so quickly

How does this differ to Spec Kit / BMAD / etc?

Fair question. Spec Kit and BMAD are both broader than this. Spec Kit has dozens of agent integrations and an extension ecosystem, BMAD has personas for product, architecture, UX, dev and test. This is narrower and stricter about a few things:

Checking the spec before building. Spec Kit's converge compares the code with the spec after implementation. Here a script first resolves every file and line the spec cites against the current code, then a fresh agent answers BUILD, BUILD WITH CUTS or REFUSE.

A spec built on a wrong assumption gets stopped before any code is written. A commit gate that's part of the method. Every spec commit runs the project's verify stages (build, full test suite) and is blocked if anything is red. In Spec Kit you can add gates through extensions; here the definition of done is enforced by default. Decisions per spec. Every non-obvious choice is logged as chose / over / why, and later agents read it before changing something.

Memory as hints. Facts that don't fit in code or git live in the repo as hints, separate from decisions. In Agent Smith, the server product, a memory's standing comes from the runs that relied on it, so a wrong one can't turn into a rule.

Parallel by design. Each spec runs in its own worktree, and spec ids are minted from the date plus random hex instead of counting existing specs, so agents working in parallel never collide on a number.

YAML instead of Markdown. My first 100 specs in Markdown were 250k tokens; in YAML they're 15k.

A spec should use orthodox tools and formats for higher level system descriptions. Like a BPMN file, a TLA+ state machine model, a P/ModP or Event B system.

Llms compile that into a binary and you deploy it and present it and users use it and they're happy or not.

There's just so many different projections of how to describe a system. What's the moat bang for the buck.

formal methods like TLA+/BPMN describe system behavior, while the specs document individual changes. these complement each other rather than competing from my point of view.

but yes, it would be great to able to have such kind of formal description. code is not standardized enough for that (by now)

Reply on news.ycombinator.com