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.

<details> <summary>📋 Phase 1: Requirements Gathering</summary>

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

1. 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

1. 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

</details>

<details> <summary>🎨 Phase 2: Design Document Creation</summary>

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?

1. 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

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

</details>

<details>
<summary>✅ Phase 3: Implementation Task List</summary>

## 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
• Write connection management code
• Create error handling utilities
• _Requirements: 2.1, 3.3_

[Additional tasks...]

### Task Requirements

**Structure**:
- Maximum two-level hierarchy (tasks and sub-tasks)
- Use decimal notation for sub-tasks (1.1, 1.2, 2.1)
- Each item must be a checkbox
- Simple structure preferred

**Each Task Must Include**:
- Clear objective involving code (writing, modifying, testing)
- Additional info as sub-bullets
- Specific requirement references (granular sub-requirements, not just user stories)

**Quality Standards**:
- Discrete, manageable coding steps
- Incremental builds on previous steps
- Test-driven development prioritized
- Covers all design aspects implementable through code
- Validates core functionality early

### Review & Iteration

3. **Ask for Approval**
   - After creating/updating tasks
   - Ask: "Do the tasks look good?"
     - Make modifications if user requests changes
   - Continue feedback-revision cycle until explicit approval
   - **Stop once approved - do not proceed to implementation**

### Completion

**Important**: This workflow is ONLY for creating planning artifacts.

- DO NOT implement the feature as part of this workflow
- Inform user they can execute tasks by:
  - Opening tasks.md
  - Clicking "Start task" next to items
  - Or asking you to execute specific tasks

</details>

<details>
<summary>⚙️ Phase 4: Task Execution</summary>

## Execute Phase

Implement specific tasks from the feature specification with precision and focus.

### Prerequisites

**ALWAYS read spec files first**:
- `.kiro/specs/{feature-name}/requirements.md`
- `.kiro/specs/{feature-name}/design.md`
- `.kiro/specs/{feature-name}/tasks.md`

Never execute tasks without understanding full context.

### Execution Process

1. **Task Selection**
   - If task number/description provided: Focus on that specific task
   - If no task specified: Review task list and recommend next logical task
   - If task has sub-tasks: Always complete sub-tasks first

2. **Implementation**
   - **ONE task at a time** - Never implement multiple without approval
   - **Minimal code** - Write only what's necessary for current task
   - **Follow the design** - Adhere to architecture decisions
   - **Verify requirements** - Ensure implementation meets specifications

3. **Completion Protocol**
   - Once task complete, STOP and inform user
   - DO NOT proceed to next task automatically
   - Wait for user review and approval
   - Only run tests if explicitly requested

### Efficiency Principles

- **Parallel operations**: Execute independent operations simultaneously
- **Batch edits**: Use MultiEdit for multiple changes to same file
- **Minimize steps**: Complete tasks in fewest operations
- **Check your work**: Verify implementation meets requirements

### Response Patterns

**For implementation requests**:
1. Read relevant spec files
2. Identify the specific task
3. Implement with minimal code
4. Stop and await review

**For information requests**:
- Answer directly without starting implementation
- Examples: "What's the next task?", "What tasks are remaining?"

### Key Behaviors

- Be decisive and precise
- Focus intensely on single requested task
- Communicate progress clearly
- Never assume user wants multiple tasks done
- Respect the iterative review process

</details>

---

## Workflow Rules

- **Never skip phases** - Always progress sequentially
- **Explicit approval required** - Get user approval after each document
- **No combined steps** - Don't merge multiple phases
- **Iterative refinement** - Continue feedback-revision until approved
- **One task at a time** - During execution, focus on single task

## Workflow Diagram

stateDiagram-v2 [*] --> Requirements

Requirements --> ReviewReq : Complete ReviewReq --> Requirements : Changes ReviewReq --> Design : Approved

Design --> ReviewDesign : Complete ReviewDesign --> Design : Changes ReviewDesign --> Tasks : Approved

Tasks --> ReviewTasks : Complete ReviewTasks --> Tasks : Changes ReviewTasks --> [*] : Approved

Execute : Execute Single Task [] --> Execute : Task Request Execute --> [] : Complete

## Detection Logic

Determine current state by checking:

Check for .kiro directory

if [ -d ".kiro/specs" ]; then

List features

ls .kiro/specs/

For specific feature, check phase

FEATURE="$1" if [ -f ".kiro/specs/$FEATURE/requirements.md" ]; then echo "Requirements exists" fi if [ -f ".kiro/specs/$FEATURE/design.md" ]; then echo "Design exists" fi if [ -f ".kiro/specs/$FEATURE/tasks.md" ]; then echo "Tasks exists - ready for execution" fi fi

## Summary

Kiro provides a structured, iterative approach to feature development:
- Start with **requirements** (what to build)
- Progress to **design** (how to build it)
- Create **tasks** (implementation steps)
- **Execute** tasks one at a time

Each phase requires explicit user approval before proceeding, ensuring alignment and quality throughout the development process.