---
name: kiro
description: "This skill should be used when managing structured spec-driven development workflows. Triggered by phrases like [kiro], [check kiro status], [load kiro], [update kiro], [kiro workflow], or when the user mentions kiro spec, create new kiro spec. Use this for managing requirements, design docs, and implementation tasks in kiro"
---

# Kiro - Structured Spec-Driven Development Workflow

## Overview

Kiro is a workflow management system for structured spec-driven development that uses spec files to track progress through requirements gathering, design, and implementation phases. This skill enables Claude to manage the complete lifecycle of a kiro spec, from initial requirements to final implementation.

The kiro spec dir default to <project-root>/llm/kiro/<spec-name>/ but can be customized per spec.

## Core Workflow Structure

Every kiro spec contains four key spec files, which need to be updated and tracked throughout the workflow:

1. **`claude.md`** - Control board with session notes, decisions, and spec status tracking
2. **`requirements.md`** - User stories and acceptance criteria
3. **`design.md`** - Architecture, data models, and implementation details
4. **`tasks.md`** - Implementation tasks with status tracking

## Workflow Decision Tree

When user mentions kiro, follow this decision tree:

1. **Does the user want to create a new kiro spec?**
   - Keywords: "new kiro", "create kiro spec", "start new kiro"
   - Action: Run `agpod kiro pr-new --desc "<description>" --template default`

2. **Does the user want to select/load an existing spec?**
   - Keywords: "load kiro", "check kiro", "select kiro", "which kiro"
   - Action: List specs and help user select one

3. **Is the user already working on a spec?**
   - Action: Continue with the current workflow phase

## Phase 1: Loading a Kiro Spec

### Step 1: List Available Specs

Run the following command to get all kiro specs:

```bash
agpod kiro --json pr-list
```

**Expected JSON output format:**
```json
[
  {
    "name": "spec-name",
    "path": "<spec-path>",
    "created": "2024-01-15T10:30:00Z"
  }
]
```

Note, the `path` should be relatieve to the project root or is absolute path if it starts with `/`.

### Step 2: Parse User Selection

If user mentions:
- **Spec number/index**: Select the corresponding spec from the list
- **Spec name/keyword**: Match against spec names using fuzzy matching
- **No specific spec**: Ask user to choose from the list

### Step 3: Read the Control Board

Once spec is selected, read `<spec-path>/claude.md` to understand:
- Current spec file statuses (empty, draft, ready)
- Previous decisions made
- Outstanding questions and risks
- Recent findings

**Example:**
```bash
Read <spec-path>/claude.md
```

## Phase 2: Requirements Gathering

**When to enter this phase:**
- `claude.md` shows `requirements.md: empty` or `requirements.md: draft`

### Workflow

1. **Read current requirements**
   ```bash
   Read <spec-path>/requirements.md
   ```

2. **Gather requirements from user**
   - Ask clarifying questions about user stories
   - Define acceptance criteria with WHEN/THEN format
   - Document each requirement using semantic IDs (e.g., REQ-AUTH-LOGIN, REQ-DATA-EXPORT)
   - Use pattern: REQ-{DOMAIN}-{ACTION} for stable, descriptive identifiers
   - Add all requirement IDs to the "Requirements Order" section at the top of requirements.md

3. **Update requirements.md**
   - Add user stories in format: "As a [role], I want to [action], so that [benefit]"
   - Define acceptance criteria for each requirement
   - Follow the existing structure already present in the generated `requirements.md` file

4. **Update claude.md status**
   - Change `requirements.md: draft` when in progress
   - Change to `requirements.md: ready` when complete and approved
   - Document key decisions in Session Notebook → Decisions

**Critical Rule:** Never proceed to design phase without user approval of requirements.

## Phase 3: Design Documentation

**When to enter this phase:**
- `claude.md` shows `requirements.md: ready` AND `design.md: empty` or `design.md: draft`

### Workflow

1. **Read current design and requirements**
   ```bash
   Read <spec-path>/design.md
   Read <spec-path>/requirements.md
   ```

2. **Create design for each requirement**

   For each requirement ID (e.g., REQ-AUTH-LOGIN), create a corresponding design section with:

   - **Overview**: Purpose, key objectives, non-goals
   - **Architecture**: System design diagrams, data flow
   - **Components and Interfaces**: Component responsibilities
   - **Data Models**: Configuration, data structures, API contracts
   - **Implementation Details**: Algorithms, PoC findings (if needed)
   - **Performance & Security Considerations**
   - **Error Handling**: Error scenarios and strategies
   - **Testing Strategy**: Unit and integration tests
   - **Migration and Rollout**: Deployment strategy (if needed)

3. **Present design options**
   - Offer multiple approaches when applicable
   - Explain trade-offs clearly
   - Let user choose the preferred approach
   - Ask oracle subagent with `Task` tool to review the design

4. **Update design.md**
   - Follow the existing structure already present in the generated `design.md` file
   - Include ASCII diagrams for system architecture
   - Keep it focused and scannable

5. **Update claude.md**
   - Change `design.md: draft` when in progress
   - Change to `design.md: ready` when complete and approved
   - Document design decisions in Session Notebook → Decisions
   - Note any identified risks in Session Notebook → Risks

**Critical Rule:** Never proceed to implementation without user approval of design.

## Phase 4: Task Planning

**When to enter this phase:**
- `claude.md` shows `design.md: ready` AND `tasks.md: empty` or `tasks.md: draft`

### Workflow

1. **Read design and create tasks**
   ```bash
   Read <spec-path>/design.md
   Read <spec-path>/tasks.md
   ```

2. **Break down each requirement into tasks**

   For each requirement ID (e.g., REQ-AUTH-LOGIN), create corresponding TASK-REQ-{ID} section (e.g., TASK-REQ-AUTH-LOGIN) with:

   - **Phases**: Group related tasks (e.g., Phase 1: Core Implementation, Phase 2: Integration)
   - **Task details** for each item:
     - Checkbox for completion tracking
     - **Status**: ⬜ Not Started / 🟡 In Progress / ✅ Completed / ⚠️ Blocked
     - **Prompt**: Detailed implementation instructions
     - **Requirements**: Reference to requirement ID (e.g., REQ-AUTH-LOGIN)
     - **Design ref**: Section reference in design.md
     - **Files**: List of files to modify

3. **Update tasks.md**
   - Follow the existing structure already present in the generated `tasks.md` file
   - Keep tasks atomic and independently executable
   - Order tasks by dependencies

4. **Update claude.md**
   - Change `tasks.md: draft` when in progress
   - Change to `tasks.md: ready` when complete and approved

**Critical Rule:** Never start implementation without user approval of tasks.

## Phase 5: Implementation

**When to enter this phase:**
- `claude.md` shows `tasks.md: ready`
- User explicitly requests code changes

### Workflow

1. **Read tasks and select next task**
   ```bash
   Read <spec-path>/tasks.md
   ```

2. **Confirm task with user**
   - Show which task will be implemented
   - Verify user approval before coding

3. **Implement the task**
   - Follow the prompt in the task definition
   - Reference the design document
   - Verify requirements are met

4. **Update task status**
   - Mark task as 🟡 In Progress when starting
   - Update checkbox `[x]` when complete
   - Change status to ✅ Completed
   - Document any findings in `claude.md` → Session Notebook → Findings

5. **Update claude.md after each task**
   - Add any new decisions to Session Notebook → Decisions
   - Note any risks encountered
   - Keep spec file status current

## Critical Rules (Always Enforce)

1. **Status Tracking**: Keep the "Spec files status" section in `claude.md` current at all times
2. **Never Skip Approval**: Never proceed to next phase without explicit user approval
3. **Always Ask Questions**: When requirements are unclear, ask rather than assume
4. **Present Options**: Offer choices for user to decide rather than making assumptions
5. **Only Edit Code When Requested**: Research and planning phases should not modify code
6. **Document Decisions**: Update Session Notebook → Decisions whenever user makes a choice
7. **Task Checkboxes**: All tasks must have checkboxes for completion tracking
8. **Sync Updates**: Update `claude.md` immediately after changes to other spec files

## Status Values

Spec files can have three statuses:
- **empty**: File is template/placeholder, not yet filled
- **draft**: Work in progress, not approved
- **ready**: Complete and approved by user

## Useful Commands

### List all kiro specs
```bash
agpod kiro --json pr-list
```

### Create new kiro spec
```bash
agpod kiro pr-new --desc "<description>" --template default
```

Additional options:
- `--git-branch`: Create and checkout git branch
- `--open`: Open in editor after creation
- `--force`: Force creation even if directory exists

To list templates, run `agpod kiro --json list-templates`

## Session Management Best Practices

1. **Start every kiro session** by reading `claude.md` to understand context
2. **Review previous decisions** before proposing new solutions
3. **Update session notebook** in real-time as conversations progress
4. **Ask questions early** rather than making incorrect assumptions
5. **Keep user informed** of which phase and file you're currently working on
6. **Validate completion** of each phase before moving to next