kiro-skill

# 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

2. **Requirements Structure**

```markdown
# 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

</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?

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

```markdown
# 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

```typescript
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 refin