Kiro: Spec-Driven Development Workflow

An interactive workflow that transforms ideas into comprehensive feature specifications, design documents, and actionable implementation plans.

Quick Start

When you mention creating a feature spec, design document, or implementation plan, this skill helps guide you through:

1. Requirements → Define what needs to be built (EARS format with user stories)
2. Design → Determine how to build it (architecture, components, data models)
3. Tasks → Create actionable implementation steps (test-driven, incremental)
4. Execute → Implement tasks one at a time

Storage: Creates files in .kiro/specs/{feature-name}/ directory (kebab-case naming)

When to Use

• Creating a new feature specification
• Defining requirements with acceptance criteria
• Designing system architecture
• Planning feature implementation
• Executing tasks from a spec

Kiro Identity & Philosophy

Read helpers/kiro-identity.md before responding. It defines tone, language preference, and minimal-code philosophy.

If you need visual phase gates or flow references, see helpers/workflow-diagrams.md.

Requirements Phase

Transform a rough idea into structured requirements with user stories and EARS acceptance criteria.

Process

1. Generate Initial Requirements

   • Create .kiro/specs/{feature-name}/requirements.md
   • Use kebab-case for feature name (e.g., "user-authentication")
   • Write initial requirements based on user's idea
   • Don't ask sequential questions first - generate then iterate

2. Requirements Structure

# Requirements Document

## Introduction

[Feature summary - what problem does this solve?]

## Requirements

### Requirement 1

**User Story:** As a [role], I want [feature], so that [benefit]

#### Acceptance Criteria

1. WHEN [event] THEN [system] SHALL [response]
2. IF [precondition] THEN [system] SHALL [response]
3. WHEN [event] AND [condition] THEN [system] SHALL [response]

### Requirement 2

**User Story:** As a [role], I want [feature], so that [benefit]

#### Acceptance Criteria

1. WHEN [event] THEN [system] SHALL [response]

EARS Format

Easy Approach to Requirements Syntax - structured acceptance criteria:

• WHEN [event] THEN [system] SHALL [response] - Event-driven
• IF [condition] THEN [system] SHALL [response] - Conditional
• WHILE [state] [system] SHALL [response] - State-driven
• WHERE [feature] [system] SHALL [response] - Ubiquitous
• [system] SHALL [response] - Unconditional

Review & Iteration

3. Ask for Approval
   • After creating/updating requirements
   • Ask: "Do the requirements look good? If so, we can move on to the design."
   • Make modifications if user requests changes
   • Continue feedback-revision cycle until explicit approval
   • DO NOT proceed to design without clear approval

Best Practices

• Consider edge cases and technical constraints
• Focus on user experience and success criteria
• Suggest areas needing clarification
• May ask targeted questions about specific aspects
• Break down complex requirements into smaller pieces

Troubleshooting

If clarification stalls:

• Suggest moving to different aspect
• Provide examples or options
• Summarize what's established and identify gaps
• Continue with available information rather than blocking

Design Phase

Create comprehensive design document based on approved requirements, conducting research during the design process.

Prerequisites

• Ensure requirements.md exists at .kiro/specs/{feature-name}/requirements.md
• Requirements must be approved before design phase

Research Phase

1. Identify Research Needs

   • What technologies/patterns need investigation?
   • What existing solutions can inform the design?

2. Conduct Research

   • Use available resources (web search, documentation)
   • Build up context in conversation thread
   • Don't create separate research files
   • Summarize key findings
   • Cite sources with relevant links

Design Document Structure

Create .kiro/specs/{feature-name}/design.md with:

Overview

• High-level description of design approach
• Key architectural decisions and rationales

Architecture

• System architecture overview
• Component relationships
• Data flow diagrams (use Mermaid when appropriate)

Components and Interfaces

• Detailed component descriptions
• API specifications
• Interface contracts

Data Models

• Database schemas
• Data structures
• State management approach

Error Handling

• Error scenarios and recovery strategies
• Validation approaches
• Logging and monitoring considerations

Testing Strategy

• Unit testing approach
• Integration testing plan
• Performance testing considerations

Design Example

# Feature Design

## Overview

[High-level approach and key decisions]

## Architecture

```mermaid
graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

Components and Interfaces

Component A

• Purpose: [What it does]
• Interfaces: [APIs it exposes]
• Dependencies: [What it needs]

Data Models

interface UserModel {
  id: string;
  email: string;
  role: UserRole;
}

[Continue with other sections...]

Review & Iteration

3. Ask for Approval
   • After creating/updating design
   • Ask: "Does the design look good? If so, we can move on to the implementation plan."
   • Make modifications if user requests changes
   • Continue feedback-revision cycle until explicit approval
   • DO NOT proceed to tasks without clear approval

Key Principles

• Research-driven: Inform decisions with research
• Comprehensive: Address all requirements
• Visual when helpful: Include diagrams
• Decision documentation: Explain rationales
• Iterative refinement: Incorporate feedback

Troubleshooting

If design becomes too complex:

• Break down into smaller components
• Focus on core functionality first
• Suggest phased approach
• Return to requirements to prioritize if needed

Tasks Phase

Convert approved design into actionable, test-driven implementation tasks.

Prerequisites

• Ensure design.md exists and is approved
• Requirements and design provide context for tasks

Task Generation Instructions

Core Principle: Convert design into prompts for code-generation LLM to implement each step in test-driven manner.

Focus:

• Incremental progress with early testing
• Build on previous tasks - no orphaned code
• ONLY tasks involving writing, modifying, or testing code
• No big jumps in complexity

Exclude:

• User acceptance testing or feedback gathering
• Deployment to production/staging
• Performance metrics gathering
• Running application for manual testing (but OK to write automated end-to-end tests)
• User training or documentation creation
• Business process changes
• Marketing or communication activities

Task Format

Create .kiro/specs/{feature-name}/tasks.md with:

# Implementation Plan

- [ ] 1. Set up project structure and core interfaces
  - Create directory structure for models, services, repositories
  - Define interfaces that establish system boundaries
  - _Requirements: 1.1_

- [ ] 2. Implement data models and validation
  - [ ] 2.1 Create core data model interfaces and types
    - Write TypeScript interfaces for all data models
    - Implement validation functions for data integrity
    - _Requirements: 2.1, 3.3, 1.2_

  - [ ] 2.2 Implement User model with validation
    - Write User class with validation methods
    - Create unit tests for User model validation
    - _Requirements: 1.2_

- [ ] 3. Create storage mechanism
  - [ ] 3.1 Implement database connection utilities
    - Wri