Kiro Spec-Driven Development: From Prompt to Pull Request

Spec-driven development is Kiro’s superpower. On Day 0 we explained why it matters, on Day 1 we installed and configured everything. Today, we run through a complete spec-driven workflow — from a vague prompt to a merged pull request — using a real feature: building a subscription billing integration with Stripe.

By the end, you’ll understand exactly how each stage works, where human judgment is required, and how to get the best results from Kiro’s spec engine.

The Setup#

We’ll use a fictional Node.js SaaS project called SaaSKit with:

Express.js backend
PostgreSQL via Drizzle ORM
Stripe for payments
Vitest for unit tests
Zod for input validation

Our steering file (.kiro/steering.md) already defines the architecture, code standards, and security rules from Day 1. Let’s see how Kiro uses that context.

Stage 1: The Prompt#

We start with a deliberately vague prompt in Spec Mode:

“Add subscription billing so users can pay monthly”

In Vibe Mode, this prompt would produce a login page and a payments widget — completely wrong. In Spec Mode, Kiro does something different.

Stage 2: Spec Generation#

Kiro generates structured requirements. Here’s what it produces:

1
## Feature: Subscription Billing
2

3
### User Stories
4
1. As a user, I want to choose between Monthly ($29) and Annual ($290) plans
5
2. As a user, I want to enter my payment details and subscribe
6
3. As a user, I want to see my subscription status on my dashboard
7
4. As a user, I want to cancel my subscription at any time
8
5. As a user, I want my billing history visible in the app
9

10
### Functional Requirements
11
- [ ] Plan selection screen with Monthly/Annual toggle
12
- [ ] Stripe Checkout integration for payments
13
- [ ] Webhook handler for subscription events (created, updated, canceled)
14
- [ ] Database schema: subscriptions table with status, plan, stripe_customer_id
15
- [ ] Dashboard widget showing subscription status and next billing date
16
- [ ] Cancel subscription flow with confirmation dialog
17

18
### Acceptance Criteria
19
- [ ] Monthly plan charges $29.00 USD every 30 days
20
- [ ] Annual plan charges $290.00 USD every 365 days
21
- [ ] Users can upgrade from Monthly to Annual (prorated)
22
- [ ] Downgrade takes effect at next billing cycle
23
- [ ] Canceled subscriptions remain active until period end
24
- [ ] Webhook signature verification for all Stripe events
25
- [ ] All endpoints return 401 for unauthenticated requests
26
- [ ] Idempotent webhook processing (no duplicate charges)
27

28
### Edge Cases
29
- [ ] Stripe Checkout session expired
30
- [ ] Webhook delivery failure (retry logic)
31
- [ ] Customer cancels during trial period
32
- [ ] Payment method declined (retry with email notification)
33
- [ ] Concurrent subscription changes
34
- [ ] Currency mismatch (enforce USD only)
35
- [ ] Plan price changes mid-cycle (grandfather existing)
36

37
### Non-functional Requirements
38
- [ ] Webhook response within 5 seconds (Stripe timeout)
39
- [ ] Subscription status cached for dashboard (max 5 min stale)
40
- [ ] GDPR: export subscription data on request
41
- [ ] Audit log for all subscription state changes
42

43
### Database Schema (suggested)
44
```sql
45
CREATE TYPE subscription_status AS ENUM (
46
  'trialing', 'active', 'past_due', 'canceled', 'unpaid'
47
);
48

49
CREATE TABLE subscriptions (
50
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
51
  user_id       UUID NOT NULL REFERENCES users(id),
52
  plan          VARCHAR(20) NOT NULL CHECK (plan IN ('monthly', 'annual')),
53
  status        subscription_status NOT NULL DEFAULT 'trialing',
54
  stripe_customer_id VARCHAR(255),
55
  stripe_subscription_id VARCHAR(255),
56
  current_period_start TIMESTAMPTZ,
57
  current_period_end   TIMESTAMPTZ,
58
  canceled_at    TIMESTAMPTZ,
59
  created_at     TIMESTAMPTZ DEFAULT NOW(),
60
  updated_at     TIMESTAMPTZ DEFAULT NOW()
61
);

Spec Review Notes#

Kiro flags dependencies and potential issues automatically:

1
⚠️ This feature requires Stripe API keys in environment variables
2
⚠️ Database migration needed (new subscriptions table + index on user_id)
3
⚠️ Webhook endpoint must be registered in Stripe dashboard
4
💡 Suggested: add /api/billing/webhook endpoint before Checkout routes

Your job at this stage: Review and approve the spec. This is the most important human checkpoint in the flow. Correct edge cases, add missing scenarios, validate the schema. Once approved, Kiro creates the task plan.

Stage 3: Task Plan Generation#

With the spec approved, Kiro generates a dependency-ordered task sequence:

1
## Task Plan: Subscription Billing
2

3
### Task 1: Database Migration
4
- Create subscriptions table with enum support
5
- Add indexes on user_id, stripe_customer_id
6
- Create audit_logs table for billing events
7
- Dependencies: none
8
- Acceptance: rollback must be possible
9

10
### Task 2: Stripe Configuration Module
11
- Create services/stripe.ts with client initialization
12
- Define plan constants (monthly price ID, annual price ID)
13
- Add webhook signature verification utility
14
- Dependencies: Task 1 (schema referenced in code)
15

16
### Task 3: Subscription Model & Repository
17
- Create models/Subscription.ts with Drizzle schema
18
- Create repositories/SubscriptionRepository.ts
19
- CRUD operations + status transition validation
20
- Dependencies: Task 1
21

22
### Task 4: Checkout API Endpoint
23
- POST /api/billing/checkout — creates Stripe Checkout Session
24
- Plan selection, customer creation (or reuse)
25
- POST /api/billing/portal — Stripe Customer Portal
26
- Dependencies: Task 2, Task 3
27

28
### Task 5: Webhook Handler
29
- POST /api/billing/webhook — Stripe webhook receiver
30
- Handle events: checkout.session.completed, invoice.paid, customer.subscription.updated
31
- Event deduplication via Stripe-Signature header
32
- Dependencies: Task 2, Task 3
33

34
### Task 6: Dashboard Subscription Widget
35
- Frontend component showing status, plan, next billing date
36
- Cancel button with confirmation modal
37
- Billing history table
38
- Dependencies: Task 4, Task 5 (data shape known)
39

40
### Task 7: Unit Tests
41
- Test each repository method
42
- Test webhook handler with mock Stripe events
43
- Validate edge cases (expired checkout, declined payment)
44
- Dependencies: Tasks 1-5
45

46
### Task 8: Integration Tests
47
- Test full checkout → webhook → subscription creation flow
48
- Test cancel and re-subscribe cycle
49
- Test prorated upgrade
50
- Dependencies: Tasks 1-6

Review the plan carefully. Dependencies must be correct. If Task 5 needs a database column that Task 1 doesn’t include, flag it now. Kiro will adjust the plan before executing.

Stage 4: Implementation#

Kiro starts executing tasks in dependency order. You can observe the agent working in real time — it opens files, reads context, writes code, and moves to the next task.

How Kiro implements Task 1 (Database)#

It reads the steering file, understands you use Drizzle ORM, generates:

1
import { pgTable, uuid, varchar, timestamp, pgEnum } from 'drizzle-orm/pg-core';
2
import { users } from './users';
3

4
export const subscriptionStatusEnum = pgEnum('subscription_status', [
5
  'trialing', 'active', 'past_due', 'canceled', 'unpaid'
6
]);
7

8
export const subscriptions = pgTable('subscriptions', {
9
  id: uuid('id').defaultRandom().primaryKey(),
10
  userId: uuid('user_id').notNull().references(() => users.id),
11
  plan: varchar('plan', { length: 20 }).notNull(),
12
  status: subscriptionStatusEnum('status').notNull().default('trialing'),
13
  stripeCustomerId: varchar('stripe_customer_id', { length: 255 }),
14
  stripeSubscriptionId: varchar('stripe_subscription_id', { length: 255 }),
15
  currentPeriodStart: timestamp('current_period_start'),
16
  currentPeriodEnd: timestamp('current_period_end'),
17
  canceledAt: timestamp('canceled_at'),
18
  createdAt: timestamp('created_at').defaultNow(),
19
  updatedAt: timestamp('updated_at').defaultNow(),
20
});

It also generates the migration file automatically.

How Kiro handles uncertainty#

During Task 4 (Checkout API), Kiro encounters an ambiguity: should it use Stripe Checkout or Stripe Elements? It pauses and asks:

“Your spec says ‘Stripe Checkout integration’. I can implement using Stripe Checkout (hosted page, redirect) or Elements (embedded form). Checkout is simpler and PCI-compliant out of the box. Shall I proceed with Checkout?”

You respond, it continues. This question-asking behavior is critical — Kiro doesn’t guess when trade-offs exist.

Stage 5: Review & Accept#

After all tasks complete, Kiro presents a summary of everything it changed:

1
## Implementation Summary — Subscription Billing
2

3
### Files Created (14)
4
- db/schema/subscriptions.ts (+63 lines)
5
- db/migrations/0005_subscriptions.sql (+28 lines)
6
- services/stripe.ts (+45 lines)
7
- repositories/SubscriptionRepository.ts (+112 lines)
8
- routes/billing.ts (+89 lines)
9
- webhooks/stripe.ts (+156 lines)
10
- frontend/widgets/SubscriptionStatus.tsx (+78 lines)
11
- frontend/widgets/BillingHistory.tsx (+52 lines)
12
- frontend/components/CancelModal.tsx (+34 lines)
13
- tests/unit/subscription-repo.test.ts (+145 lines)
14
- tests/unit/stripe-webhook.test.ts (+201 lines)
15
- tests/integration/billing-flow.test.ts (+178 lines)
16
- types/billing.ts (+22 lines)
17
- .env.example (updated, +3 lines)
18

19
### Files Modified (3)
20
- db/schema/index.ts (export subscriptions)
21
- routes/index.ts (register billing routes)
22
- frontend/router.tsx (add billing pages)
23

24
### Test Results
25
- Unit tests: 32 passed, 0 failed
26
- Integration tests: 8 passed, 0 failed
27
- Coverage: 87% (target 80% ✓)
28

29
### Open Questions
30
- [ ] Need to set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in production
31
- [ ] Webhook URL must be registered in Stripe dashboard: /api/billing/webhook
32
- [ ] Database migration must be run before deployment

Review this summary against the original spec. Did it implement all acceptance criteria? Are the edge cases addressed? If something is wrong, you can request changes and Kiro will adjust.

Stage 6: The Approval Loop#

Kiro’s approval cycle works in three modes:

Mode	Description	Best For
Auto-approve	Kiro moves through tasks without waiting	Routine changes, well-scoped features
Per-task approve	Review each task before next starts	Complex features, new patterns
Per-file approve	Review every file diff inline	Security-sensitive changes, compliance

For this subscription feature, per-task approve is appropriate. You’d review database schema changes before Kiro writes business logic, and review business logic before tests.

Practical Tips for Great Specs#

Be specific about the “what”, let Kiro figure out the “how”#

1
✅ Good: "Users must confirm their email before accessing the dashboard"
2
❌ Bad:  "Send a confirmation email with a token in the link, verify it in the controller"

Include edge cases upfront#

The spec should mention:

What happens when third-party APIs are down?
What’s the timeout behavior?
How do we handle duplicate requests?
What data should never be logged?

Use examples for ambiguous requirements#

1
✅ Good: "Proration: if user upgrades on day 15 of a 30-day cycle,
2
   charge (plan_price / 30) * 15 remaining days as a one-time adjustment"

Keep steering files in sync#

Every time you add a new dependency or change an architectural pattern, update your .kiro/steering.md. Kiro reads it at the start of every session — stale steering files produce outdated code.

Spec Mode vs Vibe Mode: When to Use Each#

Situation	Mode	Why
New feature with clear requirements	Spec	Structured output, edge case coverage
Bug fix with known root cause	Vibe	Faster turnaround, no spec overhead
Refactoring (rename, extract, move)	Vibe	Simple, well-understood transformations
Cross-repo change	Spec	Need dependency tracking across projects
Prototype / exploration	Vibe → Spec	Start fast, lock down when direction is clear
Security-critical code	Spec + per-file review	Maximum oversight
CI/CD autofix	CLI vibe	Headless, non-interactive

Common Pitfalls#

Over-specifying the implementation#

Specs should describe what the system should do, not how the code should be written. The spec is a contract between you and the agent — let Kiro choose the implementation details within your steering file’s boundaries.

Accepting the first spec without review#

The first generated spec is often 80% correct. The remaining 20% is where bugs hide. Always review edge cases, error handling, and security considerations before approving.

Forgetting to update steering files#

A steering file from a previous project that still says “use MongoDB” will produce wrong results. Keep steering files current — they’re the single source of truth for your agent’s understanding of your project.

Skipping the task plan review#

The task plan reveals dependency issues and missing components. If you skip this step, Kiro might implement tasks in an order that creates unnecessary merge conflicts or rework.

What’s Next#

With the spec-driven workflow under your belt, Day 3 explores Agent Hooks, Powers, and MCP Integrations — how to automate quality gates, extend Kiro’s capabilities, and build your own custom tool integrations.

Series: Practical Kiro — AWS’s Agentic Development Environment. Day 2: Spec-Driven Development Workflow. Day 3: Agent Hooks, Powers & MCP → coming next.