Feature Specs support two workflows: Requirements-First and Design-First.
Choose Requirements-First when:
Choose Design-First when:
No, you must choose a workflow when creating the spec. If you need to change approaches, create a new Feature Spec with the desired workflow. You can copy relevant content from the previous spec if needed.
Yes! You can create multiple specs. For example:
If you have existing architecture diagrams or design documents:
Using Design-First workflow:
Using images: Export diagrams from tools like draw.io, Lucidchart, or take photos of whiteboard sketches and include them in your initial prompt.
Using MCP integration: If your design tool has an MCP server, you can connect directly to import designs.
If your requirements or designs already exist in another system (such as JIRA, Confluence, or Word documents), you have two options:
Using MCP integration: If your requirements tool has an MCP server, you can connect directly to import requirements into your spec session. Kiro supports both local and remote MCP servers.
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.
Kiro's Feature Specs 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.
For Requirements-First specs:
Update Requirements: Either modify the requirements.md file directly or initiate a spec session and instruct Kiro to add new requirements or design elements.
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.
Update tasks: Navigate to the tasks.md file and choose Update tasks. This will create new tasks that map to the new requirements.
For Design-First specs:
Update Design: Modify the design.md file directly or ask Kiro to update it in a spec session.
Update Requirements: After architecture changes, ask Kiro to validate and regenerate requirements to ensure they remain feasible.
Update tasks: Navigate to the tasks.md file and choose Update tasks to reflect the changes.
A clear bug description helps Kiro perform accurate root cause analysis. Include:
Example prompt:
When a user submits a form with special characters in the name field (e.g., O'Brien), the API returns a 500 error. It should accept the input and save it correctly. The validation logic for email and password fields should not be affected.
Bugfix Specs explicitly capture "unchanged behavior" alongside the fix. During the analysis phase, document what must continue working:
Kiro generates property-based tests that validate both the fix and the preservation of existing behavior, giving you confidence that the fix doesn't break anything else.
Use a Bugfix Spec when:
A quick fix in chat is fine for straightforward issues like typos, simple logic errors, or well-understood one-line changes.
Not directly. If root cause analysis reveals that the fix requires significant new functionality, create a separate Feature Spec for the new work and keep the Bugfix Spec focused on the original defect.
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:
Create a central specs repository - Establish a dedicated repository for shared specifications that multiple projects can reference.
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.
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.
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.
Yes, you can execute all the tasks in your tasks.md file by clicking the "Run all tasks" button. Note: this will only run incomplete tasks that are marked as required.
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
tasks.md fileOption 2: Let Kiro scan for you in a spec chat session
This keeps your task spec accurate.
You can reference any spec from your specs list in chat conversations using the #spec context provider. Type #spec and press Enter to see a list of available specs, then select the one you want to include. Kiro automatically includes all spec files (requirements.md, design.md, and tasks.md) in the conversation context to ensure responses align with your documented specifications.
Using #spec is particularly helpful when you need context-aware assistance:
Examples:
#spec:user-authentication implement task 2.3 #spec:user-authentication update the design file to include password reset flow #spec:user-authentication does my current implementation meet the acceptance criteria for task 7.1? #spec:user-authentication why did we choose JWT over session-based authentication?
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:
.kiro/specs/ ├── user-authentication/ # Login, signup, password reset ├── product-catalog/ # Product listing, search, filtering ├── shopping-cart/ # Add to cart, quantity updates, checkout ├── payment-processing/ # Payment gateway integration, order confirmation └── admin-dashboard/ # Product management, user analytics
This approach allows you to:
Best practices