From User Stories to Specs: What Changes When Agents Do the Building

A user story is a conversation starter. That's what it was designed to be. "As a user, I want X so that Y" works because a developer reads it, walks over to the product manager, asks six questions, and fills in the rest from what they know about the codebase and the team.

An agent can't walk over to anyone. It reads the story, fills the gaps with its best guess, and builds exactly what it guessed. When your AI pilot produces code that technically meets the ticket and still has to be rewritten, the ticket is usually where things went wrong.

That's why the artifact that drives development is one of the first things to change as teams mature from AI-assisted development toward agentic delivery. Most teams move through four stages here: story-driven, workflow-driven, specification-driven, and eventually intent-driven. The easiest way to see the difference is to write the same feature both ways.

The feature: lock an account after failed logins

This is a good test case because it sounds simple and isn't. Here's how it typically shows up in a backlog.

Before: the user story

As a user, I want my account to be locked after several failed login attempts so that my account stays secure.

Acceptance criteria:

• Account locks after too many failed attempts
• User sees a message explaining what happened
• User can unlock their account

A senior developer on your team would read this and know what to ask. How many attempts? Over what time window? Is the lock temporary or permanent? Does it apply to people who sign in through SSO? And the question that matters most: if anyone can lock any account just by typing the wrong password five times, haven't we built a way for an attacker to lock out every customer we have?

An agent given this story will answer all of those questions for you, silently. It might pick three attempts or ten. It might lock accounts permanently until an email reset. It might display "No account found with that email," which tells an attacker which email addresses are valid. Each choice is defensible in isolation, and none of them were decisions your team actually made.

The code will pass review if the reviewer is skimming. The acceptance criteria are vague enough that almost any implementation meets them.

The same feature, written as a spec

After: the specification

Outcome: Reduce credential-stuffing and brute-force success against customer accounts without letting attackers lock legitimate users out.

Rules

• Count failed attempts per account. After 5 failures within 15 minutes, apply a temporary 15-minute lock.
• Each subsequent lock in a 24-hour period doubles in length, capped at 4 hours.
• Never lock permanently. Unlock happens automatically when the lock expires, or immediately through a verified password reset.
• Separately, rate-limit failed attempts per source IP to 20 per 10 minutes. This limit returns a generic error and does not touch account state.
• Error messages must be identical whether or not the account exists: "Email or password is incorrect."
• SSO users are out of scope. Their lockout policy belongs to the identity provider.

Constraints

• Use the existing notification service to email the account owner on first lock only.
• Write lock, unlock, and rate-limit events to the audit log with account ID, timestamp, source IP, and reason.
• No changes to session handling or token lifetimes.

Acceptance tests

• Given 4 failed attempts in 15 minutes, the 5th correct attempt succeeds.
• Given 5 failed attempts in 15 minutes, the account is locked and a correct password is rejected until the lock expires.
• Given a nonexistent email, the response body and timing match those of a real account with a wrong password.
• Given 21 failures from one IP across different accounts, the IP is throttled and none of those accounts are locked.

Out of scope: Admin unlock tooling, CAPTCHA, MFA changes.

Approval tier: Authentication change. Requires security review before merge.

Hand that to an agent and the range of reasonable implementations shrinks from dozens to a handful. More to the point, every decision that matters was made by a person before the build started.

What changed between the two

The spec is longer. That's the part people notice first, and it's the least interesting difference.

The rules are specific enough to be wrong. "Too many attempts" can't be argued with. "5 failures in 15 minutes" can, which means someone on your team had to decide whether that's the right number. That argument used to happen at a developer's desk halfway through the sprint. Now it happens before anyone, human or agent, writes code.

The acceptance criteria became tests. Each one has a given, a condition, and an observable result, so an agent can generate the test suite from the spec and check its own work against it. The fourth test is the one the original story would never have produced, and it's the one that stops the lockout feature from becoming an attack.

The spec says what it isn't. The out-of-scope list keeps an agent from helpfully building an admin unlock screen nobody asked for. Agents are eager. Boundaries help.

And the approval tier tells your pipeline who has to sign off. That's where the spec starts connecting to the rest of your operating model: higher-risk changes route to a human reviewer automatically, and routine ones don't clog anyone's queue.

Where workflow-driven fits

Most teams don't jump straight from stories to specs. The step in between is workflow-driven delivery, where agents run bounded, repeatable pieces of the lifecycle (generating tests, diagnosing CI failures, scaffolding services) inside guardrails your platform team already built. The stories stay, but agents handle defined tasks around them.

It's a useful stage. It's also where a lot of teams plateau, because the tasks agents can do well are exactly the tasks with clear inputs. Once you want agents implementing features, the input has to get clearer, and that means specs.

What intent-driven looks like

Look back at the spec. Several of those rules aren't really about this feature. Keeping error messages from revealing whether an account exists applies to login, password reset, signup, and any other endpoint that takes an email address. Logging security events with a standard set of fields applies everywhere.In an intent-driven model, those rules come out of individual specs and live as policy the whole system can read:

policy: auth-enumeration-01
applies_to: [endpoints.accepts_identifier]
rule: responses must not differ by account existence
verify: response_body_parity, response_timing_parity
owner: security-engineering

Now any agent working on any change that touches those endpoints checks against the policy automatically. The spec for the next feature gets shorter, because it inherits the rules instead of restating them. Humans spend their time deciding what the policies should be rather than re-explaining them in every ticket.

Very few teams are here yet. It depends on a platform that can enforce policy at execution time and on business rules that someone has actually written down, which is the harder of the two for most organizations.

Where the switch to specs gets stuck

Three problems come up almost every time.

Nobody owns the spec. Product managers were trained to write stories, not rules and edge cases, and engineers don't want to write requirements. The teams that make this work usually pair them: product owns the outcome and business rules, engineering owns constraints and acceptance tests, and the spec is done when both sign off.

Specs get treated as documentation. If the spec lives in a wiki and the code lives somewhere else, they'll drift within a month. Keep the spec in the repo next to the code it describes, version it, and make changes to behavior start with a change to the spec.

Teams try to spec everything at once. Pick one workflow with clear rules and low blast radius, write specs for a handful of changes, and measure the rework rate against your story-driven baseline. That number will tell you whether to expand faster than any debate will.

If you work in financial services, there's a bonus here. The rules, constraints, and approval tier in a good spec are most of what an auditor wants to see when they ask how a change was authorized and tested. Teams that write specs for agents end up producing audit evidence as a side effect.

Find out where your SDLC stands

The artifact that drives your development is one pillar of three. Your platform and the way your business defines intent have to mature alongside it, and whichever one is furthest behind sets your pace. Tensure's agentic engineering maturity self-assessment takes 20 questions and shows you where each pillar sits and which one to work on first.

‍