How to Use Kiro Specs for a Production Feature: Requirements, Design, Tasks, and Tests

A feature request can sound perfectly clear until an AI coding agent starts filling in everything you did not say.

Take this:

Add password reset by email.

Simple enough.

But what should the agent do about token expiry? Can a token be used twice? Should the API reveal whether an email address exists? How many reset requests should one account be allowed to make?

If those details are missing, the agent still has to build something.

That is where assumptions enter the code.

Kiro Specs gives us a way to move those assumptions into something we can read before implementation starts.

In this walkthrough, we will take one password-reset feature through:

1. requirements
2. requirements analysis
3. technical design
4. implementation tasks
5. agent execution
6. normal project tests

By the end, you should have a workflow you can reuse for authentication, billing, permissions, background jobs, or any feature where a small misunderstanding can spread through several files.

What Kiro creates

A Kiro Feature Spec can produce three files:

.kiro/specs/password-reset/
├── requirements.md
├── design.md
└── tasks.md

They each answer a different question.

The coding comes after those layers have something useful to say.

That is the part we are going to test.

1. Start with a real feature request

Open the project in Kiro CLI.

cd my-saas-app
kiro-cli

Start a new spec:

/spec new password-reset

Choose a Feature Spec and use the Requirements-First workflow for this example.

Now describe the feature.

Do not describe how to code it yet.

Give Kiro the behaviour you want:

Add password reset for existing users.

A user should be able to request a password reset by email
and set a new password using a one-time reset token.

Requirements:

- Reset tokens expire after 15 minutes.
- A token cannot be used more than once.
- The reset request endpoint must not reveal whether an email
  address belongs to an account.
- Repeated reset requests must be rate limited.
- Successful and rejected reset attempts must be auditable.
- Plaintext passwords and reset tokens must never be written
  to logs.

That is already much stronger than:

Add password reset.

The second prompt forces the agent to guess far less.

2. Review requirements.md before the agent designs anything

Kiro uses EARS-style requirements.

A requirement follows a structure similar to:

WHEN [condition]
THE SYSTEM SHALL [expected behaviour]

For our feature, requirements.md may contain ideas like these:

# Password Reset Requirements

## Reset request

WHEN a user submits an email address to the password-reset endpoint
THE SYSTEM SHALL return the same public response whether or not an account exists

WHEN an existing account requests a password reset
THE SYSTEM SHALL create a one-time reset token

WHEN a reset token is created
THE SYSTEM SHALL make the token expire after 15 minutes

## Password update

WHEN a user submits a valid and unexpired reset token
THE SYSTEM SHALL allow the user to set a valid new password

WHEN a reset token has already been used
THE SYSTEM SHALL reject another password reset using that token

WHEN a reset token has expired
THE SYSTEM SHALL reject the password reset

## Abuse protection

WHEN password-reset requests exceed the configured rate limit
THE SYSTEM SHALL reject further requests for the rate-limit window

## Auditability

WHEN a password-reset attempt succeeds or fails
THE SYSTEM SHALL create an audit event without storing the plaintext password or reset token

This is where I would stop and read.

Not because writing requirements is exciting.

Because this is the cheapest place to discover that the agent understood something differently from you.

3. Look for what is still missing

A neat requirements file can still be incomplete.

For password reset, I would look for questions such as:

• Does requesting a second token invalidate the first one?
• What password rules apply?
• Should existing sessions remain active after the password changes?
• What happens if the email provider fails?
• Should rate limiting apply by account, email, IP address, or more than one of them?
• What exactly gets written into the audit event?
• What response does an expired token return?
• Can two reset confirmations race against each other?

These are small questions while we are reading Markdown.

They become more expensive when they appear after several services, database models, tests, and API handlers already exist.

4. Let Kiro analyse the requirements

Kiro CLI supports a requirements-analysis command:

/spec analyze_requirements password-reset

The analysis looks across the requirement set for things such as:

• ambiguity
• conflicting constraints
• unstated assumptions
• logical inconsistencies
• missing edge cases

For example, suppose one requirement says:

A reset token is valid for 15 minutes.

but nothing says whether creating another token invalidates the first one.

That is a real product behaviour hiding inside an apparently complete requirement.

The analysis can surface questions like that before design starts.

For a very small feature, this extra pass may be unnecessary.

For authentication, payments, permissions, customer credits, or workflows with several failure states, it can be worth the few extra minutes.

5. Review the technical design

Once the behaviour is clear, move into design.

A useful design.md for this feature should settle questions such as:

Endpoints

POST /auth/password-reset/request
POST /auth/password-reset/confirm

It should also describe how the reset token behaves:

Reset token

- generated using a cryptographically secure random value
- plaintext token sent to the user
- only a hash stored in the database
- expires after 15 minutes
- single use

And the surrounding components:

PasswordResetService
EmailService
RateLimiter
AuditService
UserRepository
ResetTokenRepository

The exact architecture will depend on your application.

The useful question while reviewing the design is:

Is Kiro reusing the patterns that already exist in this repository?

If your app already has an email service, audit system, rate limiter, or token utility, the design should not quietly create a second version just for this feature.

6. Make the implementation tasks small enough to review

Kiro then generates tasks.md.

For this feature, a useful task list might look something like this:

# Implementation Tasks

- [ ] 1. Add password-reset token persistence
  - store a token hash
  - store expiration time
  - store consumed state

- [ ] 2. Add password-reset request service
  - generate a secure token
  - apply rate limiting
  - send reset email
  - return the same public response for existing and unknown emails

- [ ] 3. Add password-reset confirmation service
  - verify token hash
  - verify expiration
  - verify token has not already been consumed
  - validate new password
  - update password
  - consume token

- [ ] 4. Add audit events
  - reset requested
  - reset completed
  - reset rejected

- [ ] 5. Add API endpoints

- [ ] 6. Add tests
  - successful reset
  - expired token
  - reused token
  - unknown email
  - repeated requests
  - invalid password

Compare that with this:

Implement password reset.

The first version gives us checkpoints.

The second gives the agent one large area in which to make assumptions.

7. Run the spec

Once the requirements, design, and task list look right:

/spec run password-reset

Kiro validates that tasks.md exists, then works through the tasks sequentially.

You can interrupt execution if the implementation starts moving in the wrong direction.

That gives code review a much clearer reference too.

Instead of asking:

Does this implementation look reasonable?

you can ask:

Does this implementation satisfy the requirement that a reset token can only be used once?

That is a much easier question to test.

8. Keep your normal tests

The agent's workflow should sit beside your existing engineering checks.

It should not replace them.

For a Node.js project, that might still mean:

npm test
npm run lint
npm run typecheck

Then add tests that map back to the behaviours in the spec.

Using Vitest or Jest, the shape could look like this:

describe("password reset", () => {
  it("rejects an expired reset token", async () => {
    const token = await createResetToken({
      expiresAt: new Date(Date.now() - 1000),
    });

    const result = await resetPassword({
      token,
      password: "A-Valid-New-Password-123",
    });

    expect(result.ok).toBe(false);
    expect(result.code).toBe("RESET_TOKEN_EXPIRED");
  });

  it("allows a valid token only once", async () => {
    const token = await createValidResetToken();

    const first = await resetPassword({
      token,
      password: "A-Valid-New-Password-123",
    });

    const second = await resetPassword({
      token,
      password: "Another-Valid-Password-123",
    });

    expect(first.ok).toBe(true);
    expect(second.ok).toBe(false);
  });
});

The function names here are examples. Your repository will have its own services and test helpers.

What matters is that the tests now have an agreed behaviour to verify.

9. Quick Spec is useful when the feature is already clear

A full Requirements-First workflow is not necessary for every change.

Kiro also offers Quick Spec.

It asks clarifying questions up front, then generates:

requirements.md
design.md
tasks.md

in one pass without approval gates between each phase.

That can work well for something like:

• adding CSV export to an existing table
• extending an established CRUD flow
• adding another API endpoint using a pattern already in the repository
• adding a field to a familiar admin workflow

For authentication, billing, permissions, or a feature with several failure states, I would usually want more room to review what the agent thinks the feature means.

Different tasks deserve different amounts of structure.

10. Kiro also supports Design-First specs

Requirements-First is not the only Feature Spec workflow.

If the technical constraints are already fixed, Kiro can start from design instead.

That can make more sense when you already know things such as:

• the required database
• the API shape
• the cloud architecture
• latency or throughput requirements
• compliance constraints
• an existing low-level design

The flow then becomes:

Design
↓
Requirements
↓
Tasks
↓
Implementation

So Specs do not have to mean "product requirements always come first."

The starting point can match the kind of problem you actually have.

11. One current limitation worth knowing

Kiro also documents property-based testing for checking whether an implementation matches behaviours described in a Spec.

At the moment, Kiro's documentation marks that capability as available in the IDE, not the CLI.

So if you are following this exact CLI walkthrough, keep your normal automated tests in place.

If you use the Kiro IDE, property-based correctness checks are another layer you can explore.

Where the economics show up

OpenAI published an update on August 24 about GPT-5.6 in Kiro.

In testing with AWS on Terminal-Bench 2.1, OpenAI reported that GPT-5.6 Terra completed successful tasks in Kiro at roughly 82% lower cost in that benchmark setup.

That is interesting.

I would not turn 82% into an estimate for a real client codebase.

Your repository, task size, test quality, model choice, context, and requirements can all change the result.

For real development work, I would rather track:

• How many times did the agent need a correction?
• How many files were rewritten because the requirement changed?
• Did the first implementation pass the expected tests?
• How much review time did the task need?
• How much AI usage was required before the code was actually mergeable?

Those numbers describe your development process.

A benchmark describes somebody else's test environment.

The pattern worth keeping

The most useful part of Specs is not that they create three Markdown files.

It is the chance to expose a misunderstanding while that misunderstanding is still easy to change.

Feature request
      ↓
Requirements
      ↓
Design
      ↓
Tasks
      ↓
Implementation
      ↓
Verification

At Ascent Innovate Software, this is the kind of structure that makes the most sense around features where hidden behaviour matters: authentication, usage rules, billing states, permissions, background processing, and similar workflows.

For a tiny change, keep the process light.

For a feature where one missing condition could spread through several parts of the product, making the intent visible first can save a lot of unnecessary correction later.

Sources

• OpenAI: Advancing price-performance for developers with GPT-5.6 in Kiro
• Kiro: Specs in CLI
• Kiro: Feature Specs
• Kiro: Requirements-First workflow
• Kiro: Quick Spec
• Kiro: Analyze Requirements
• Kiro: Correctness with Property-based Tests

Editorial note

The technical claims, Kiro commands, workflow details, code examples, and final article were reviewed against the current OpenAI and Kiro documentation before publication.