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:
- Requirements → Define what needs to be built (EARS format with user stories)
- Design → Determine how to build it (architecture, components, data models)
- Tasks → Create actionable implementation steps (test-driven, incremental)
- 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
- 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
- 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-drivenIF [condition] THEN [system] SHALL [response]- ConditionalWHILE [state] [system] SHALL [response]- State-drivenWHERE [feature] [system] SHALL [response]- Ubiquitous[system] SHALL [response]- Unconditional
Review & Iteration
- 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
- Identify Research Needs
- What technologies/patterns need investigation? - What existing solutions can inform the design?
- 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
1. **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 - 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
1. **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
## 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
---
## 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.