kiro-skill

name	kiro-skill
description	Interactive feature development workflow from idea to implementation. Creates requirements (EARS format), design documents, and implementation task lists. Use when creating feature specs, requirements documents, design documents, or implementation plans. Triggered by "kiro" or references to .kiro/specs/ directory. Use when this capability is needed.
metadata	{"author":"feiskyer"}

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.

---

📋 Phase 1: Requirements Gathering

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

🎨 Phase 2: Design Document Creation

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]

✅ Phase 3: Implementation Task List

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
 

[Additional tasks...]

⚙️ Phase 4: Task Execution

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

---

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.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.