Agentic Software Factories

The Thesis

What Is an Agentic Software Factory?

You installed a coding agent, watched it do an afternoon's work in twenty minutes, and then a quieter feeling showed up: you're shipping faster than you can vouch for. That unease is a production problem, and it has a fifty-year-old answer called a factory.

“Ford never sold you a wrench, some parts, and wished you good luck. Ford sold you a car, and if the car failed, Ford recalled it, because it was their factory that produced it.”

If you're reading this, you have probably already crossed the threshold. You installed Claude Code or Codex, pointed it at a repository, and watched it do in twenty minutes what used to take you an afternoon. The first week felt like cheating. Somewhere around the third week, a quieter feeling showed up underneath the speed, and it's worth naming precisely, because this entire book is an answer to it.

The feeling is: I am shipping faster than I can vouch for.

The code works, mostly. The tests are green, when there are tests. But the pull requests are larger than the ones you used to write, they arrive faster than you can fully read them, and the mental model of what the system does now lives partly in your head and partly in a conversation transcript you'll never open again. You're the only person who watched it get built. If a teammate asked you why the retry logic backs off the way it does, you'd have to go read it to find out, which means, functionally, nobody knows. You've traded a bottleneck you understood (writing code) for one you don't (trusting code you didn't write, at a volume you can't review).

This is not a prompting problem. You will not fix it with a better system prompt or a cleverer agent. It is a production problem, and production problems have production answers. The answer has a name, it is roughly fifty years old, and most of the industry currently reaching for it is reaching for the word without the thing. The word is factory.

Start with the extreme version of the problem, because it makes the shape of the solution obvious.

Earlier in 2026, a team at the startup 8090 was handed the billing engine behind US Medicare claims, run by the Centers for Medicare & Medicaid Services (CMS): roughly 18 million lines of COBOL and Assembly that had accumulated since before some of their engineers were born. Nobody at the agency fully understood it anymore. It ran, it billed, and every year the maintenance contract climbed another five to eight percent, because the understanding of the system had long since leaked out of the organization and into the heads of a shrinking number of specialists, some of whom had retired. Using an agentic pipeline they call a Software Factory, the team reverse-engineered that codebase into more than 100,000 plain-English business rules in 40 days.

The interesting part is that when a rule in that extracted set is wrong, someone at 8090 answers for it. The output came off a line that was designed, from the first stage, so that every rule could be traced back to the code that implied it, checked against the behavior of the original system, and owned by a specific person. They didn't just generate 100,000 rules. They generated 100,000 rules plus the machinery to stand behind them, and the second half is the factory. The first half, on its own, is just a very fast intern who doesn't return your calls after they leave.

Now shrink that story down to your world. You are not reverse-engineering COBOL. You are building a SaaS backend, or a data pipeline, or an internal tool, with an agent that writes most of the code. The 18-million-line black box is not your starting condition, it's your destination if you keep generating code faster than you govern it. The person who cannot answer “why does it do that?” a year from now is you. The factory is how you avoid becoming the agency in the story.

The phrase “software factory” is having a moment, and the moment is borrowing credibility it mostly hasn't earned yet. So it's worth establishing where the credibility originally came from, because the history isn't decoration, it tells you exactly which properties are load-bearing.

In 1969, Hitachi opened a facility it called Software Works (in Totsuka, Yokohama), and it meant the word works literally: a building where software was produced under statistical quality control. Defect rates were measured per thousand lines of code. Processes were standardized so that output didn't depend on which engineer happened to be assigned. A management team was accountable for the quality of what shipped. Over the following decade, Toshiba, NEC, and Fujitsu built their own software factories, and through the 1970s and 1980s these Japanese operations shipped some of the most reliable code of the era, the software that ran banking, rail, and power infrastructure for decades. (The definitive account is Michael Cusumano's Japan's Software Factories, Oxford University Press, 1991. Decades later, Hitachi's Omika Works, a control-systems plant founded the same year, was named a World Economic Forum “Lighthouse” manufacturing site, the factory metaphor was never a metaphor there.)

In 2004, two Microsoft architects, Jack Greenfield and Keith Short, published Software Factories: Assembling Applications with Patterns, Models, Frameworks, and Tools (Wiley). Their argument was that software should be built the way cars are built: assembled from proven components, on repeatable production lines, with variation controlled by upfront design rather than fixed by heroics downstream. They were writing against a world of bespoke, artisanal, snowflake systems, a world where every application was hand-carved and therefore every application was a maintenance liability the moment its author moved on.

And today, the United States Air Force runs software factories, plural. Kessel Run is generally described as the Department of Defense's first software factory; Platform One, a roughly two-hundred-person organization, operates Kessel Run alongside others like Kobayashi Maru and Space CAMP. In December 2023, the DoD's Deputy CIO for the Information Enterprise, Lily Zeleke, put the department-wide count at up to fifty software factories. When mission software built in one of those factories breaks, the factory owns it. “The model wrote it” is not a sentence anyone says to an auditor.

Across sixty years and three continents, one thing stayed constant right up until this AI wave: a factory was never a tool. No matter how good the tool. A factory was a system of production that took inputs, produced finished goods, and stood behind the quality of those goods. That's the standard the word carries, and any modern software factory, agentic or otherwise, has to conform to it or pick a different word.

Here is the definition made operational. A software factory passes five tests. Miss any one and you have something else, usually a developer tool, which is genuinely useful but carries a completely different obligation. Throughout this book, every chapter maps to one of these tests, and we build the machinery for each in turn.

Test 1, It starts from business intent. A factory's input is what the business needs, expressed in the language of the business: requirements, rules, constraints, desired outcomes. If the input is a Jira ticket written by one engineer for another engineer, you have a power tool bolted onto an existing process, not a factory. The whole point is that the customer describes the product and the factory figures out the production.

Test 2, It maintains coherence under continuous change. This is the hardest test and the one almost nobody selling AI tooling talks about, because their products make it worse. Writing new code was never the bottleneck in real systems. The bottleneck is that a live system gets changed every week by many hands, and every change is a chance for the pieces to pull apart: requirements drift from documentation, documentation drifts from code, code drifts from tests. Give that drift twenty years and you get the 18-million-line black box. Code generation accelerates drift, if your agents produce ten times more code against specifications nobody keeps in sync, you are inducing drift at unprecedented speed. A factory keeps intent, spec, code, tests, and production behavior synchronized as a single governed object.

Test 3, It operates independent of any specific person. Hand the same coding agent to two engineers and you'll get radically different output, because a tool is only as good as the person holding it. That variance is fine in a tool and disqualifying in a production system. Hitachi's statistical controls existed precisely to make quality a property of the line, not the operator. The mechanism is that knowledge compounds in the system rather than in individuals: when someone joins, the factory hands them everything it has already learned; when someone leaves, nothing walks out the door. This does not mean people don't matter, a factory always has someone specific who answers for the output. It means the factory never depends on any one person being irreplaceable. A system that needs a hero has a hero, not a factory, and heroes eventually find new adventures.

Test 4, Every unit of output is traceable. In a real factory, every part has a lot number, and when something fails you trace it back through the line to the batch, the machine, and the shift. Regulated industries demand exactly this from software, which is why they've been slowest to adopt AI coding tools: “the model wrote it” is not an answer an auditor accepts. A factory produces the audit trail as a byproduct of production itself, this rule exists because of this requirement, approved by this person, implemented in this change, verified by this test, deployed at this time. Documentation written after the fact doesn't count; provenance has to be built into the line.

Test 5, Someone is accountable for the finished product. This is the test that separates a factory from a tool, and it's the one most vendors won't meet. A factory ships a product it stands behind: when the billing engine miscalculates, when the trading system prints a wrong number, someone specific answers for it, fixes it, and eats the cost. Read the AI-tooling contracts and you'll find the intellectual-property section runs for pages while the accountability section is one sentence, and the sentence says the output is provided as-is and verification is your problem. For a factory, that is disqualifying.

You could have written that history in 2015 and it would have been true and inert. What makes it urgent in 2026 is a single economic fact and its consequence.

The cost of producing software is collapsing. A frontier model can now resolve a large share of real, human-validated GitHub issues on its own, the SWE-bench Verified benchmark (500 human-checked tasks) has gone from a hard problem to a nearly-saturated one, with top reported scores above 80 percent (93.9 percent for Anthropic's restricted Claude Mythos Preview in April 2026), to the point that OpenAI argued in February 2026 that the benchmark no longer measures frontier capability. Meanwhile the price of the machining keeps falling: Anthropic's Claude Opus 4.5, released in November 2025, matched Sonnet 4.5's best SWE-bench Verified score using roughly 76% fewer output tokens, cut the Opus per-token price by two-thirds, and added an effort control to trade thoroughness against cost directly. Machining is getting cheaper and better on a quarterly cadence.

Here is the consequence, and it's the thesis of the whole book: when production costs collapse, value migrates to whoever can guarantee the output. This has happened in every industrialization before this one. Once anyone can stamp out a part, the part is worth almost nothing and the guarantee, this part meets spec, and we'll recall it if it doesn't, becomes the entire business. Cheap generation makes the generated thing a commodity and makes the governance around it precious.

The market has already felt the first half of this and not yet the second. In Stack Overflow's 2025 developer survey (over 49,000 respondents), 84% said they use or plan to use AI tools, up from 76% the year before. Adoption is essentially settled. But in the same survey, only about a third trusted the accuracy of what those tools produced, nearly half actively distrusted it, and a rounding-error 3% “highly trusted” it. Trust in AI-generated output actually fell year over year. Read those two numbers together and the situation is unambiguous: the industry has already bought the tools and has not bought the trust. The scarce, valuable, buildable thing is the trust, the guarantee, and that is precisely what a factory manufactures and a tool does not.

If you want empirical humility to go with the hype, the sharpest data point runs the other way from the marketing. In a 2025 randomized controlled trial, the research group METR had 16 experienced open-source developers complete 246 real tasks on large codebases they knew intimately (arXiv 2507.09089). With AI assistance, they were 19% slower, while believing they had been about 20% faster. Outside experts had predicted a ~38% speedup. METR's February 2026 follow-up (later tools, 57 developers, more than 800 tasks) estimated a speedup instead, 4% for new recruits and 18% for returning developers, with confidence intervals that still include a slowdown, and METR itself called that data unreliable because more developers declined to take part rather than work without AI. The gap between felt productivity and measured productivity is, in part, the coherence tax from Test 2: on a mature system with high standards, ungoverned generation doesn't just fail to help, it actively costs you, and it hides the cost behind the pleasant sensation of moving fast. The factory is how you convert the felt speedup into a real one.

Apply the five tests and a lot of things currently wearing the word fall out. This taxonomy matters because you will be sold these as factories, and buying the wrong layer for the job you actually have is the most expensive mistake in this book.

Coding agents are tools. Claude Code and Codex, however good, take engineering tasks as input, produce code as output, and transfer all verification and accountability to you. That is the correct and honest design of a tool. Calling a fleet of them a factory doesn't change the direction accountability flows. A tool is where the factory starts, not what the factory is.

Orchestration dashboards are supervision surfaces. A pane of glass that shows you twelve agents working in parallel makes it easier to watch production. It does not make production coherent, traceable, or accountable. Supervision is a real need, you'll build some in Chapter 4, but a window onto the line is not the line.

Benchmarks are measurement harnesses. A high SWE-bench score tells you a tool is good at benchmarked tasks. It cannot tell you whether your system stays coherent after two years of continuous change by a mixed team of humans and agents, because that is not what it measures. Benchmarks measure the machining. Factories are judged on the finished goods and the guarantee.

To make the distinction concrete rather than philosophical: here is a coding agent used as a tool. It's a single, unaccountable act of machining, useful, fast, and the moment it finishes, everything it produced becomes your problem to verify.

# The tool. One shot of machining. Accountability flows to you.
claude -p "explain the auth flow in src/auth.py"

That command is not wrong, you'll run its cousins constantly. But notice what it isn't: it doesn't start from a spec, it leaves no trace linking its output to a requirement, it produces a different answer depending on who asked and how, and if its explanation is subtly wrong, nothing catches it. Every chapter after this one is, in effect, the story of wrapping commands like that one in the five properties that turn machining into manufacturing.

One more idea before we start building, because it reframes everything downstream. When you move from tool to factory, the thing you hand the system changes, and this is the single most consequential shift in the whole book.

Here is the unit of production for a tool. It's a Jira ticket, written by an engineer, for an engineer who is assumed to already understand the codebase:

# TICKET-4213
Add rate limiting to the login endpoint.
- Use Redis
- 5 attempts per 15 min per IP
- Return 429

It's fine. It's also a set of implementation decisions disguised as a requirement, addressed to someone who already has the context in their head. Redis is a choice. Per-IP is a choice with real consequences (it punishes users behind shared NATs and does nothing against a distributed attacker). “Return 429” is a mechanism. Nowhere does the ticket say what the business actually needs, which means nobody, human or agent, can check whether the implementation serves the intent, because the intent was never written down.

Here is the unit of production for a factory. Same feature, expressed as intent, portable to anyone (or any agent) with no prior context:

# Intent: Protect authentication from credential-stuffing abuse

## Why
Automated login attempts are degrading service and risking account takeover.

## Behavior (business language)
- A legitimate user is never blocked during normal use, including typos.
- An abusive source is throttled quickly enough to make bulk guessing impractical.
- When throttled, the caller is told clearly and can recover without contacting support.

## Constraints
- Must not lock out users behind shared corporate IPs.
- Throttling state survives a single server restart.

## Acceptance
- WHEN a source exceeds the abuse threshold, THE SYSTEM SHALL reject
  further attempts with a clear, recoverable response.
- GIVEN a legitimate user who mistypes a password twice,
  WHEN they enter the correct password, THEN they are allowed in.

The second version says nothing about Redis, nothing about 429, nothing about per-IP, because those are production decisions, and the whole premise of a factory is that the customer describes the product and the factory figures out the production. It's also checkable: every line of the acceptance section can become an executable test (Chapter 5), the constraints can become guardrails, and a year from now a new teammate, or a fresh agent with an empty context window, can read this file and know not just what the code does but why it exists. That's Test 1, and it's where Chapter 2 begins.

This is not a book of principles. By the last chapter you will have turned an ordinary repository into a working factory, one property at a time, in current Claude Code and Codex syntax. A single companion project, a small TypeScript/Node service, with a Python component where it earns its place, carries through every chapter, so each idea lands as a real commit rather than an abstraction. Here's the build order and where each of the five tests gets manufactured:

A note on how to read the technical claims in this book, offered up front so you can trust the rest: features move fast. Claude Code shipped native git worktrees and Agent Teams within a few months of this writing, model prices change quarterly, and at least one billing change was announced and then paused during the period these chapters were drafted. Every chapter is stamped with a verified-as-of date and pins the versions it relies on. Where a claim is vendor-reported (like the 8090 figures) or forward-looking (like anything in Chapter 10 about where models are headed), it is labeled as such, because the audience this book is written for is exactly the half of the Stack Overflow survey that distrusts unverified claims about AI, and earning that reader's trust is the entire point.

So: ignore the demos, ignore the benchmark leaderboards, and ask every self-described software factory the one question that actually sorts them.

When the system breaks in production, who takes the call?

For a factory, the answer has to be we do. The rest of this book is how you build one small enough to fit on your laptop and honest enough to mean it.

Verified as of September 2026. Vendor-reported figures (8090) and benchmark/pricing numbers are perishable and labeled inline; re-verify before relying on them.

Test 1 · Intent

The Unit of Production: From Tickets to Intent

This chapter builds the first and most important part of the factory: the thing you feed it. Get the unit of production wrong and nothing downstream can be right, because every later stage is either derived from it or checked against it.

“A specification is version control for your thinking.”, adapted from the GitHub Spec Kit docs

From here to the end of the book we build one real thing. Meet Trimly, the reference project: a small URL-shortener API with user accounts, written in TypeScript on Node. It is deliberately boring and deliberately realistic, it has a login surface (so the credential-stuffing feature from Chapter 1 has a home), short-link creation and redirects, per-account rate limits, click analytics, and enough business rules that a specification is worth writing but not so many that the examples drown. Every configuration file, hook, subagent, spec, and workflow in the coming chapters is a real artifact you could commit to Trimly's repository today. Where a Python component earns its place, the analytics roll-up in Chapter 5, we'll add one.

This chapter builds the first and most important part of the factory: the thing you feed it. Get the unit of production wrong and nothing downstream can be right, because every later stage is either derived from it or checked against it.

Chapter 1 ended on a contrast worth restating, because it is the hinge the whole book turns on. A Jira ticket, “Add rate limiting to the login endpoint. Use Redis. 5 attempts per 15 min per IP. Return 429.”, is a set of implementation decisions addressed to a reader who already holds the context in their head. A statement of intent, “a legitimate user is never blocked during normal use; an abusive source is throttled fast enough to make bulk guessing impractical”, describes the product and leaves the production to the factory.

The reason this matters more with agents than it ever did with humans is a difference in what the reader can supply. A senior engineer handed a thin ticket fills the gaps from years of shared context: they know why the team avoids Redis for this, they remember the incident that made per-IP limiting a bad idea, they infer the unstated acceptance criteria. An agent fills the gaps too, but it fills them from a statistical prior, not from your team's history. It will confidently choose per-IP because per-IP is the most common pattern in its training data, and it will be wrong for exactly the reasons the ticket never mentioned. The thinner the input, the more the agent invents, and the invention is plausible enough to survive review. Intent is how you stop paying that tax: you write down the why and the what-counts-as-correct once, and every agent that ever touches the feature reads the same ground truth.

This is also the precise failure of “vibe coding”, the practice of steering an agent conversationally, turn by turn, toward something that looks right. Vibe coding fails the coherence test from Chapter 1 not because the code is bad but because there is no source of truth. The intent lived in a chat window, the chat window is gone, and what remains is code whose reasons no longer exist anywhere. Six months later, when a change breaks the abuse protection, there is nothing to check the change against. The spec is what you check against. That is its entire job.

A spec that can govern a factory has five parts. Fewer, and it can't be checked; more, and you've built the ceremony trap we'll dismantle in 2.6. Here is the shape, using Trimly's abuse-protection feature:

Intent, one sentence naming the outcome the business wants. “Protect Trimly accounts from credential-stuffing abuse.” If you can't say it in a sentence, the feature is really several features and should be split.

Why, the forcing function. “Automated login attempts are degrading service and risking account takeover.” The why is not decoration; it's what lets an agent (or a teammate) resolve an ambiguity the spec didn't anticipate. When a question comes up that the acceptance criteria don't cover, the answer is whatever best serves the why.

Behavior, in business language, what the system does, described so a non-engineer could verify it. No mechanisms. “A legitimate user is never blocked during normal use, including typos. An abusive source is throttled quickly enough to make bulk guessing impractical. When throttled, the caller is told clearly and can recover without contacting support.”

Constraints, the non-negotiable boundaries, including the ones that rule out the obvious-but-wrong implementation. “Must not lock out users behind shared corporate IPs. Throttling state survives a single server restart.” Notice the first constraint quietly kills per-IP limiting, which is the whole point of writing it down.

Acceptance, the behavior restated as conditions a test can check. This is the part that becomes Chapter 5's test suite, so it must be mechanical. We write it in EARS (next section).

The discipline is that these five parts are sufficient, an agent handed this spec and nothing else should be able to produce a correct implementation, and a reviewer handed this spec and the diff should be able to tell whether it did. If the spec leaves the agent guessing, add to it. If the spec dictates mechanisms, cut it back.

“A legitimate user is never blocked” is good behavior language and a terrible test, “never” and “legitimate” aren't checkable. The bridge from prose to test is a small, boring notation called EARS (Easy Approach to Requirements Syntax), which constrains each requirement to one of a few sentence templates. AWS's Kiro adopted EARS as its native format precisely because the templates force the ambiguity out.

The core EARS patterns, each with a Trimly example:

• Ubiquitous, THE SYSTEM SHALL [behavior]. “THE SYSTEM SHALL record the timestamp of every login attempt.”
• Event-driven, WHEN [trigger] THE SYSTEM SHALL [behavior]. “WHEN a source exceeds the abuse threshold, THE SYSTEM SHALL reject further attempts with a recoverable response.”
• State-driven, WHILE [state] THE SYSTEM SHALL [behavior]. “WHILE an account is in a throttled state, THE SYSTEM SHALL return the same response to valid and invalid passwords.” (This one closes a real vulnerability, a login endpoint that behaves differently under throttling leaks which passwords are correct.)
• Unwanted behavior, IF [condition] THEN THE SYSTEM SHALL [behavior]. “IF throttling state is lost to a restart, THEN THE SYSTEM SHALL fail toward allowing legitimate traffic rather than blocking it.”
• Optional-feature, WHERE [feature is present] THE SYSTEM SHALL [behavior].

Each EARS line maps almost mechanically to a test, and where an example needs concrete data, we drop to Gherkin's GIVEN/WHEN/THEN:

GIVEN a legitimate user who mistypes their password twice
WHEN they enter the correct password on the third attempt
THEN they are allowed in

The value isn't the syntax for its own sake, it's that “WHEN a source exceeds the abuse threshold” forces you to define “abuse threshold” and “source,” the two things the original Jira ticket smuggled in as 5 per 15 min per IP without anyone deciding they were right. The spec surfaces the decision; EARS makes you write it down where a test can hold you to it.

Spec-driven development (SDD) is a genuine movement now, with three tools worth knowing and one useful mental model for telling them apart. The model comes from Birgitta Böckeler's evaluation on martinfowler.com, which sorts SDD approaches into three levels of how much authority the spec holds:

• Spec-first, you write a spec to kick off the work, then the code becomes the source of truth and the spec is discarded. Lightweight; the spec is scaffolding.
• Spec-anchored, the spec lives alongside the code and is kept roughly in sync; useful reference, but code still wins ties.
• Spec-as-source, the spec is authoritative. Code serves the spec, not the reverse. This is the purest and most demanding form, and it's the one a factory wants, because it's the only level at which the spec can govern.

The three tools, and where they sit:

GitHub Spec Kit is the spec-as-source standard-bearer (about 139k GitHub stars as of September 2026) and the one this book uses. It's a CLI, specify, that scaffolds an in-repo workflow of Markdown artifacts and agent commands (installed as skills for Claude Code and Codex). As of v1.0 (August 2026) the commands are namespaced: /speckit.constitution → /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement → /speckit.converge, where converge checks the code against the artifacts and appends any missing tasks, with optional quality gates /speckit.clarify, /speckit.checklist, and /speckit.analyze. Bug fixing and idea assessment now ship as opt-in extensions with their own steps. Crucially, everything lives as Markdown and scripts in your repo, the workflow is repo-native, not trapped in a tool's UI, which is exactly the property a governed object needs.

AWS Kiro is an agentic IDE built around SDD, launched in 2025. It structures work as three files, requirements.md (in EARS), design.md, and tasks.md, and generates them for you. It's more opinionated and more visual than Spec Kit, and it popularized EARS in this space.

OpenSpec is the lightest of the three: a small state machine of proposal → apply → archive that treats each change as a proposal you accept and then archive. Good when Spec Kit feels heavy and you still want a spec artifact per change.

Here is the Trimly workflow end to end. First, bootstrap Spec Kit into the repo. Note that Claude Code and Codex use a skills-based install mode rather than raw slash commands: the workflow ships as Skills the agent invokes, so inside Claude Code each step is spelled with a hyphen (/speckit-specify) and in Codex with a dollar sign ($speckit-specify). Spec Kit's reference docs, and this chapter's prose, use the dotted /speckit.specify form:

# Install the CLI (uv is the recommended installer)
uv tool install specify-cli

# Scaffold into the existing Trimly repo, selecting the Claude Code integration
specify init --here --integration claude
# (older tutorials show --ai claude; the --ai flag family was removed in v0.10)

That writes a .specify/ directory (templates, scripts, and memory/constitution.md) and installs the workflow as speckit-* skills under .claude/skills/. Now the loop, run inside a claude session:

# 1. Establish the non-negotiables once, for the whole project
/speckit-constitution

# 2. Describe WHAT and WHY for this feature — no tech stack
/speckit-specify Protect Trimly accounts from credential-stuffing abuse.
A legitimate user is never blocked during normal use, including typos.
An abusive source is throttled fast enough to make bulk guessing impractical.
Throttled callers are told clearly and can recover without support.

# 3. (Recommended) let the agent interrogate the spec for gaps
/speckit-clarify

# 4. NOW introduce the HOW — stack, patterns, constraints
/speckit-plan Use our existing Node/TypeScript stack and Postgres.
Throttling state must survive a single restart. Consult the constitution.

# 5. Turn the plan into a dependency-ordered task list
/speckit-tasks

# 6. Check spec/plan/tasks for contradictions before writing code
/speckit-analyze

# 7. Implement against the approved artifacts
/speckit-implement

# 8. Check the code against spec, plan, and tasks; repeat 7 and 8
#    until it reports Converged
/speckit-converge

The output is a specs/NNN-abuse-protection/ directory containing spec.md, plan.md, and tasks.md, plus the code. The critical property, the one that makes this a factory input rather than a fancy prompt, is that those Markdown files are committed to the repo and versioned. When the abuse-protection requirement changes next quarter, you edit spec.md, re-run /speckit.plan and downstream, and the change ripples through as a diff you can review. The spec is not a disposable planning step (that's Claude Code's built-in plan mode, which is great for exploration and by default files its plan under ~/.claude/plans, outside the repo and outside review). The spec is a durable governed object. That distinction is Chapter 6's entire subject, and it starts here.

Here is where honesty about SDD matters, because the failure mode is real and the critics are right. Böckeler's own evaluation found Kiro turning a small bug fix into “4 user stories and 16 acceptance criteria”, she called it “using a sledgehammer to crack a nut.” An independent Scott Logic write-up rebuilt one feature with Spec Kit and watched the plan step emit a 444-line “module contract” for a module that was 100 lines once implemented, roughly four times as much specification as code, most of it, in the author's words, “obvious and valueless transformations of the spec.” GitHub itself hosts a discussion thread of users complaining that the spec phase generates “work about work.”

The lesson is not “don't spec.” It's that spec weight must scale to problem size and problem risk, and the tools will happily over-produce if you let them. Practical rules for Trimly-sized work:

• A typo fix or a copy change needs no spec. Just fix it. The spec's job is to remove ambiguity and enable checking; a one-line change has neither ambiguity nor much to check.
• A bounded feature needs a lean spec, the five parts from 2.2, a handful of EARS lines, and a short plan. Use Spec Kit's lean path (/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement → /speckit.converge) and skip the optional gates.
• A risky or ambiguous feature earns the full ceremony, the abuse-protection feature qualifies, because getting it wrong means either locking out real users or leaving the door open. Here you want /speckit.clarify, /speckit.checklist, and /speckit.analyze.
• When the plan is longer than the code will be, stop and trim it. That ratio is the clearest signal the tool has run away from you. Delete the valueless transformations; keep the decisions.

The skill you're building is judgment about how much structure a given change deserves, the same judgment a good tech lead applies to how much design review a change needs. SDD gives you the dial; you still have to turn it.

Step back and notice what the spec has become. It is simultaneously three things: a brief an agent can execute without your context, a test oracle the acceptance criteria compile into (Chapter 5), and a contract a reviewer can hold the diff against. One artifact, three jobs, and it is the only thing in the pipeline that a human wrote deliberately and can read a year later.

That last property is why the spec, not the code, and not the chat transcript, is the true unit of production in a factory. The code is now cheap and regenerable; a good spec can be re-implemented by a fresh agent in an afternoon. The chat transcript is worthless the moment the session closes. The spec is the durable, human-authored, version-controlled statement of what the system is for and what counts as correct. Everything else in this book, the factory floor, the assembly line, the QC station, the coherence machinery, the audit trail, exists to turn that contract into software you can stand behind, and to keep the two in sync as both change.

Chapter 3 builds the floor those specs get processed on.