by Dominik Schmidle on
Table of contents
In September the whole Giant Swarm team was at our annual offsite in Greece, and one of the things we decided there is to open source the way we plan our work. So here it is: spec-driven-development, free to fork.
And here is why we built it.
Code got cheap. Review didn't.
You have heard it everywhere by now. AI made code cheap, fast and abundant. We see it too. Across Giant Swarm, the number of pull requests written by people and their agents has roughly tripled in a year, from around 700 a month in summer 2025 to more than 2,100 a month in summer 2026 (bots like Renovate not counted).
That speed is real, but it comes with two problems, and both come down to the same rule: going faster must not make the product worse.
The first problem is intent. If you tell a model "build me an app that does X" and walk away, you get an average product at best. A model doesn't have the context, the customer conversations or the judgment of a good product engineer. The decisions that make a product good (what to build, what to leave out, which trade-off to accept) can't be outsourced. We call them intent, and intent has to stay with people.
The second problem is volume. Three times the pull requests means three times the diffs to read. Nobody has the time or the energy for that. Reviewers either become the bottleneck or start approving what they haven't read, and neither protects quality.
So how do you keep building the right product, the right way, with the important decisions visible and argued over, when you can't read every diff?
We moved the review to the plan
Our answer is spec-driven development (SDD). We moved human review from the code diff to the plan for what we're about to build. People argue about the plan, decide, and merge it. Then agents implement against that agreed spec.
The term isn't ours. GitHub's Spec Kit is a toolkit built around it, and AWS's Kiro describes itself as spec-driven too. What's different in how we do it: the spec is the pull request people argue about, every claim in it is checked against the real code before anyone agrees to it, a dedicated step tries to kill the plan and can send it back, and the whole workflow lives as skills inside the repo, with no install step.
This isn't something we reserve for side projects. Large parts of our new product, the Giant Swarm Agent Platform, were built this way. Some large-scope epics went from plan to working feature in about a week. Model serving on GPU node pools is one example, counted from the first question in the plan to a working feature. Not every epic is that fast.
How a plan gets made
A plan is one directory in a git repository: the spec, a rendered page for reviewers, and every artifact produced along the way, all dated and versioned. That directory goes into a pull request, and that pull request is what humans review.
One command, /plan, runs the whole thing. A typical plan is a few hours of work, with the review spread over a day or two. The examples below come from the worked example plan that ships with the repo, a fictional feature-flag service whose install silently depends on cert-manager.
Grilling: /grill-me
It starts with an interview. /grill-me, adapted from Matt Pocock's skills, walks the plan as a decision tree and asks every question it can, each with its own recommended answer. It looks up facts itself. The decisions it leaves to you, and every question and answer is logged as it happens.
The recommendations are the interesting part, because a good grilling overrules some of them. In the example, the agent recommends shipping cert-manager as an optional chart dependency, on by default. The human says no:
Overruled. cert-manager is a cluster-wide singleton. Bundling it means a second copy on every cluster that already has one when somebody forgets the value, CRD ownership fights between the two releases, and uninstalling our product taking down the certificate machinery that other workloads rely on.
That's intent. The model had a reasonable default; the person had the context.
We recommend doing this as pair or mob planning. When two or three people grill a plan together, decisions have to be argued, not just taken, and more than one opinion goes into them. It's also where juniors learn the most: they sit in the room where context and trade-offs are discussed, and later they can read back exactly why a decision was made. Review used to be where people learned a codebase. Now it's the plan.
The spec: /to-spec
/to-spec turns the conversation into SPEC.md, with no second interview. The spec is the single source the implementing agent works from, and its diff is how reviewers see what changed between plan revisions.
Fact-checking: /ground-truth
This is the step that catches hallucinations. /ground-truth pulls out every claim the spec makes about something that already exists (an API, a config value, a flag, a deadline) and verifies each one in parallel, against a clone of the real code or a primary source. In the example, seven of eight claims hold. The eighth doesn't:
MISMATCH: The chart has awebhook.certificate.certManager.enabledvalue. No such key exists anywhere in the chart. The real value iswebhook.certificate.source, an enum of cert-manager or secret.
A made-up config value, caught before a single line of implementation. Found, fixed, cited.
Trying to kill the plan: /contrarian
Where ground-truth asks whether the plan is true, /contrarian asks whether it's necessary. It hunts for what already covers the problem, builds the simplest path using only existing things, and demands a written justification for everything new. The verdict is BUILD, SIMPLIFY or KILL, and anything other than BUILD sends the plan back to grilling.
In the example, the first draft wanted an umbrella chart, a CRD upgrade hook and a CLI wrapper. The contrarian's answer:
Two of five problems are real. The plan should build for those two and nothing else.
After the rework, the plan shrank to one existing chart plus one small new component, and the verdict became BUILD. That's typical: most plans we run through it come back SIMPLIFY.
We didn't start with this step. Early on, a plan carried a false premise through grilling, spec and fact-check, and only a human reviewer caught it. The answer was already sitting in the code the plan had cloned. So we added a step whose job is to catch exactly that, before a person has to.
The page: /to-website
/to-website renders the spec into a single HTML page. Reviewers need visuals, not just markdown: diagrams, a summary they can skim, and one click to the research, the fact-check or the contrarian verdict behind any line.
When not to plan
Not everything needs a plan. Dependency bumps, bug fixes with an obvious cause and small changes inside an already agreed plan don't. Our rule of thumb: if a change contains a decision someone could disagree with, it gets a plan.
A plan is a baseline, not a contract
The objection we hear most is "isn't this just waterfall with better tooling?" It isn't, because a plan is where the discussion starts, not where it ends.
Plans change after they're agreed, all the time. One of our Slack integration plans was rewritten the day after it was merged, because live testing broke two of its assumptions (the Slack client swallows DMs that start with a slash, for one). Other plans get replaced by newer plans, reworked from scratch, or abandoned, which is a good outcome when the alternative was building the wrong thing.
Sometimes the first plan exists only to learn. Our agent identity work is a good example: the current plan's job is to prove, with a prototype, that the approach works the way we think it does. The plan for the production feature comes after that, informed by what the prototype taught us.
Plans are cheap on purpose. That's what makes it safe to change them.
So who checks the code?
Moving review to the plan only works if the implementation lands reliably. That took more work than the planning skills did.
Judgment moved into the plan: people decide the intent and the test gate there. The spec's testing decisions say exactly what "done" means, for example:
The three acceptance scenarios are the test gate: an implementation that passes them and nothing else is complete; one that fails any of them is not, whatever else it ships.
Agents do the line-level work inside their own loop. They implement, test and review their changes before a pull request is even opened. To make that possible, we raised our test coverage, made our apps build and run locally, and built a local installer (agentlab) that gives an agent a realistic-enough environment to try what it just built and get direct feedback. We also put work into delivery, so that feedback arrives early and specifically, not as a red pipeline an hour later.
Most changes then merge without a human reading the diff. The author owns the change and stays accountable after it merges; the agent or the team merges it, depending on what the plan says. We built an Agent Platform integration that posts code pull requests to the team's Slack as short, approvable summaries, so anyone on the team can approve with one click. When the plan already shows a change touches a public API or something security relevant, people look at the pull request as well. Today that's team practice rather than code, and we keep improving our review skills and profiles, with dedicated security reviews next.
Whether it's the right approach was settled in the plan. For line-level checks against an agreed spec and test gate, we trust an agent's review over a tired person's on their eighth hour of reading diffs.
The process keeps changing
None of this is finished, and that's by design. The contrarian step exists because we learned something. Steps get added, steps get removed.
One gap we see today: most of our plans carry too few visuals, so we often don't know what a UI will look like until it's built. Two steps we're trying next:
- A mockup step, so frontend plans carry agreed mockups based on our design principles before anyone writes a component.
- A persona step, where an agent plays one of our customer personas and reviews the plan for desirability and usability while it's still cheap to change.
Some of these will stick, some won't. The rule we keep: whatever helps us discuss and take decisions stays. Everything else is ceremony.
Try it
spec-driven-development is fully open sourced and ready to fork. To get a feel for it:
- Fork it and read the worked example plan.
- Pick one upcoming change that contains a real decision, and run it through
/plan, ideally as a pair. - Before you hand the spec to agents, make sure they have tests they can run and a local environment they can try things in.
- Watch where your team starts arguing. If it's the plan's pull request and not the code's, it's working.
Not ready for the whole pipeline? Lift just /ground-truth and /contrarian into your own setup.
I've actually started using an adapted version of this process to plan non-code things (like the overall concept of this article :)).
A big thank you to Giant Swarm's Agent Platform Team, who built this and argue about plans every day, and to Matt Pocock, whose skills gave us the starting point.
If your agents got fast too, we'd like to know where you moved your review to. Open an issue on the repo and tell us.
This post first appeared on LinkedIn on 29 September 2026.
