Kiro Spec Guide

What are specs?

Specs or specifications are structured artifacts that formalize the development process for complex features in your application. They provide a systematic approach to transform high-level ideas into detailed implementation plans with clear tracking and accountability.

With Kiro's specs, you can:

• Break down requirements into user stories with acceptance criteria
• Build design docs with sequence diagrams and architecture plans
• Track implementation progress across discrete tasks
• Collaborate effectively between product and engineering teams

Quickstart

Ready to create your first specification? Here's how to get started:

1. From the Kiro pane, click the + button under Specs. Alternatively, choose Spec from the chat pane.
2. Describe your project idea.
3. Follow the three phase workflow through Requirements → Design → Implementation.

Concepts

Specs bridge the gap between conceptual product requirements and technical implementation details, ensuring alignment and reducing development iterations. Kiro generates three key files that form the foundation of each specification:

• requirements.md - Captures user stories and acceptance criteria in structured EARS notation
• design.md - Documents technical architecture, sequence diagrams, and implementation considerations
• tasks.md - Provides a detailed implementation plan with discrete, trackable tasks

graph TD
    A[Product Idea] --> B[Requirements Phase]
    B --> C[Design Phase]
    C --> D[Implementation Planning]
    D --> E[Execution Phase]
    
    B --> F[requirements.md<br/>User Stories & Acceptance Criteria]
    C --> G[design.md<br/>Architecture & Sequence Diagrams]
    D --> H[tasks.md<br/>Discrete Implementation Tasks]
    
    F --> I[EARS Notation<br/>Structured Requirements]
    G --> J[Technical Architecture<br/>Component Interactions]
    H --> K[Trackable Tasks<br/>Clear Outcomes]
    
    style A fill:#e1f5fe
    style F fill:#f3e5f5
    style G fill:#e8f5e8
    style H fill:#fff3e0

Workflow

The workflow follows a logical progression with decision points between phases, ensuring each step is properly completed before moving to the next.

• Requirements Phase (leftmost section): Define user stories and acceptance criteria in structured EARS notation
• Design Phase (second section): Document the technical architecture, sequence diagrams, and implementation considerations
• Implementation Planning (third section): Break down the work into discrete, trackable tasks with clear descriptions and outcomes
• Execution Phase (rightmost section): Track progress as tasks are completed, with the ability to update and refine the spec as needed

flowchart LR
    subgraph "Requirements Phase"
        A[Define User Stories] --> B[Write Acceptance Criteria]
        B --> C[Structure in EARS Notation]
    end
    
    subgraph "Design Phase"
        D[Document Architecture] --> E[Create Sequence Diagrams]
        E --> F[Implementation Considerations]
    end
    
    subgraph "Implementation Planning"
        G[Break Down Tasks] --> H[Define Clear Outcomes]
        H --> I[Set Dependencies]
    end
    
    subgraph "Execution Phase"
        J[Track Progress] --> K[Update Status]
        K --> L[Refine as Needed]
    end
    
    C --> D
    F --> G
    I --> J
    
    style A fill:#ffebee
    style D fill:#e8f5e8
    style G fill:#fff3e0
    style J fill:#e3f2fd

Requirements

The requirements.md file is written in the form of user stories with acceptance criteria in EARS notation. The way you wish your PM would give you requirements!

EARS (Easy Approach to Requirements Syntax) notation provides a structured format for writing clear, testable requirements. In a spec's requirements.md file, each requirement follows this pattern:

For example:

This structured approach offers several benefits:

• Clarity: Requirements are unambiguous and easy to understand
• Testability: Each requirement can be directly translated into test cases
• Traceability: Individual requirements can be tracked through implementation
• Completeness: The format encourages thinking through all conditions and behaviors

Kiro helps you transform vague feature requests into these well-structured requirements, making the development process more efficient and reducing misunderstandings between product and engineering teams.

Design

The design.md file is where you document technical architecture, sequence diagrams, and implementation considerations. It's a great place to capture the big picture of how the system will work, including the components and their interactions.

Kiro's specs offer a structured approach to design documentation, making it easier to understand and collaborate on complex systems. The design.md file is a great place to capture the big picture of how the system will work, including the components and their interactions.

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database
    participant External Service
    
    User->>Frontend: Initiate Action
    Frontend->>API: Send Request
    API->>Database: Query Data
    Database-->>API: Return Data
    API->>External Service: Process Request
    External Service-->>API: Return Response
    API-->>Frontend: Send Response
    Frontend-->>User: Display Result
    
    Note over User,External Service: Example sequence flow for a typical application

Implementation Plan

The tasks.md file is where you provide a detailed implementation plan with discrete, trackable tasks and sub-tasks. Each task is clearly defined, with a clear description, expected outcome, and any necessary resources or dependencies. Kiro's specs offer a structured approach to implementation plans, making it easier to understand and collaborate on complex systems.

Kiro provides a task execution interface for tasks.md files that displays real-time status updates. Tasks are updated as in-progress or completed, allowing you to efficiently track implementation progress and maintain an up-to-date view of your development status.

Best Practices

How do I import existing requirements?

If your requirements or designs already exist in another system (such as JIRA, Confluence, or Word documents), you have two options:

1. Using MCP integration: If your requirements tool has an MCP server that supports STDIO, you can connect directly to import requirements into your spec session.

2. Manual import: Simply copy your existing requirements (e.g. foo-prfaq.md) into a new file in your repo and open a spec chat session and say #foo-prfaq.md Generate a spec from it. Kiro will read your requirements, and generate requirement and design specs.

How do I iterate on my specs?

Kiro's specifications are designed for continuous refinement, allowing you to update and enhance them as your project evolves. This iterative approach ensures that specifications remain synchronized with changing requirements and technical designs, providing a reliable foundation for development.

1. Update Requirements: Either modify the requirements.md file directly or initiate a spec session and instruct Kiro to add new requirements or design elements.

2. Update Design: Navigate to the design.md file for your spec and select Refine. This action will update both the design documentation and the associated task list to reflect your modified requirements.

3. Update tasks: Navigate to the tasks.md file and choose Update tasks. This will create new tasks that map to the new requirements.

Specs are designed to be version-controlled, making them easily shareable across your team. Store specs directly in your project repository alongside the code they describe. This keeps all project artifacts together and maintains the connection between requirements and implementation.

Yes, you can share specs across multiple teams by leveraging Git submodules or package references. Here are some best practices for managing shared specs across teams:

1. Create a central specs repository - Establish a dedicated repository for shared specifications that multiple projects can reference.

2. Use Git submodules or package references - Link your central specs to individual projects using Git submodules, package references, or symbolic links depending on your development environment.

3. Implement cross-repository workflows - Develop processes for proposing, reviewing, and updating shared specs that affect multiple projects.

If you have specific needs for cross-project spec management, please share your requirements on our GitHub issue tracker so we can prioritize features that support your workflow.

Can I start a spec session from a vibe session?

Yes. You can have a vibe conversation and then say Generate spec. Kiro will then ask you if you want to start a spec session. If you say yes, it will proceed with generating requirements based on the context of your vibe session.

Can I execute all the tasks in my spec in a single shot?

Yes, you can execute all the tasks in your tasks.md file by asking the Kiro agent to Execute all tasks in the spec. Kiro will start executing all your tasks. Note: we do not recommend doing this as we recommend a task-wise execution to get better results.

What if some tasks are already implemented?

When working on an existing codebase, you might find that some tasks in your spec are already complete because a coworker or you ended up doing it in another session. Here are two ways to handle this:

Option 1: Click on Update tasks in your tasks.md

• Open your tasks.md file
• Click Update tasks
• Kiro will automatically mark completed tasks.

Option 2: Let Kiro scan for you in a spec chat session

• In a spec session, ask Kiro: "Check which tasks are already complete"
• Kiro will analyze your codebase and identify implemented functionality
• Kiro will automatically mark completed tasks

This keeps your task spec accurate.

How many specs can I have in a single repo?

You can have as many specs as you want in a single repo. We recommend creating multiple specs for different features for your project rather than attempting to just have a single one for your entire codebase.

For example, in an e-commerce application, you might organize your specs like this:

This approach allows you to:

• Work on features independently without conflicts
• Maintain focused, manageable spec documents
• Iterate on specific functionality without affecting other areas
• Collaborate with team members on different features simultaneously