The spec is in the wrong place

My day job is at a large tech company. Hundreds of engineering teams, and every one of them is somewhere different on AI adoption. Some are still treating coding agents as a curiosity. Some have quietly rebuilt their whole workflow around them. Most are in the messy middle, and watching that middle is where the idea for Penling came from.

Spec-driven development has arrived, and I think it's the right idea. Tools like SpecKit and Kiro put the specification front and center to the coding workflow, and the results are noticeably better — an agent working from a written spec produces dramatically better output than an agent working from a vibe and a prompt.

But look at where the spec gets written. In the engineer's IDE. In the terminal. At the moment the task gets picked up.

That's a long way from where the product decisions were actually made.

Think about the journey a piece of intent takes before it reaches that terminal. A team decides something — in a planning session, in a strategy doc, in a passing conversation that should have been a meeting. That decision gets compressed into a ticket. Maybe that ticket sits in a backlog for a few weeks. Eventually an engineer picks it up, reads whatever context has been given, and writes a spec for the agent.

That spec is probably not the team's full intent, at least not in my experience of how tickets get written. It's the engineer's reconstruction of what they think the team meant, written under deadline, weeks after the actual decision. A translation of a translation. And then we hand it to an agent and let it build, fast and confidently, exactly what the spec says.

The agents are doing their job. The spec is just in the wrong place.

I've believed this for a long time, well before AI coding tools existed: the quality of work is mostly determined before the work begins. Teams consistently start executing before they've aligned on purpose and scope, and almost every painful thing that happens later — rework, drift, the feature nobody asked for — traces back to that.

Coding agents didn't create this problem. They made it urgent. Execution used to be expensive enough that misalignment surfaced slowly; you'd catch the misunderstanding somewhere in week two of building. Now execution is nearly free and nearly instant. The agent will build the wrong thing completely, beautifully, before anyone notices the brief was ambiguous.

So the gap between "we can build it" and "we agreed what it should be" is now most of the risk in a software project. Possibly all of it.

Which means the spec — the written, agreed statement of what we're building and what success looks like — shouldn't be a just-in-time artefact produced at the keyboard. It should be where the project starts. The whole team involved in creating it: product, engineering, whoever owns the outcome. Arguing about it while arguing is still cheap. Agreeing on what done means before anything gets built.

Do that, and two things happen at once. You decide the project's success where it's actually decided anyway — at the start. And you constrain the agent to the bounds the team set, not the bounds one engineer inferred from what they were given at some point down the track.

The obvious objection: don't we already have tools for this? We have project trackers. We have wikis. We have spec-driven dev tools. Between Jira, Confluence and SpecKit, surely this is covered.

I don't think it is, and the reason is that each one holds the right thing in the wrong place.

Confluence holds the team's intent, far from the code. Nothing connects the document to what gets built. It doesn't version with the code, agents don't read it, and it starts rotting the day after it's written. Everyone has opened a design doc and wondered whether it describes the system or a system that almost got built.

Jira holds the breakdown, but a ticket is intent with the reasoning stripped out. It tells you what to do this sprint and nothing about why, or what success was supposed to look like.

SpecKit holds the right artefact — a real spec, next to the code, readable by the agent. But it lives with the engineer at implementation time, which is exactly the problem. It's spec-driven development scoped to a terminal session, when the decisions it should encode were made weeks earlier, by more people than one.

The intent exists in all three places, partially, and lives durably in none of them. And there's a quieter problem underneath all of it: where the spec currently lives — in the repo — most of the team can't even reach it. If your company is anything like mine, the product managers don't have GitHub licences. So even when a real spec exists, the people who should have a say in it never see it.

If you take the placement argument seriously, the product design mostly falls out of it.

The spec has to be durable, so it lives as a markdown file committed to your repo, versioned alongside the code it describes. But it has to be authored where the whole team can reach it — in a shared environment, in a format everyone can read, not behind a licence half the team doesn't have.

And it has to come first, so the workflow starts at the brief, not the backlog. A rough idea gets shaped into a spec by the team, the spec gets broken down into buildable work, and the agent builds against it. Planning, breakdown and build all hang off the one artefact — because in this workflow they were never really separate things to begin with.

That's the whole of it. The rest is detail.

Vibe-coding a prototype is genuinely great. No spec needed, and anyone telling you otherwise is selling process. But the moment that prototype has users, a team, a roadmap — the moment it has to keep doing the right thing after the person who built it has moved on — somebody has to write down what it's meant to do. Somewhere durable. Somewhere the next person, and the next agent, will actually look.

If your team is building with agents today, it's worth knowing where your spec gets written — and who writes it. Or whether it gets written at all.

Paul is a software engineer in Sydney and the founder of Penling, a spec-driven delivery platform for teams building with LLMs.