kiro-skill

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)

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

---

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.

---

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

```markdown

# Requirements Document

[Feature summary - what problem does this solve?]

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

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

```markdown

# Feature Design

[High-level approach and key decisions]

```mermaid

graph TD

A[Component A] --> B[Component B]

B --> C[Component C]

```

Component A

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

```typescript

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

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:

```markdown

# 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

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

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

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

---

• 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

```mermaid

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

```

Determine current state by checking:

```bash

# 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

```

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.