# Spec-Driven Development Guide

[![Run in Smithery](https://smithery.ai/badge/skills/jasonkneen)](https://smithery.ai/skills?ns=jasonkneen&utm_source=github&utm_medium=badge)


A comprehensive guide to systematic feature development using the three-phase spec process: Requirements → Design → Tasks.

<!-- Navigation Metadata -->
<!-- Keywords: spec-driven development, requirements engineering, system design, implementation planning, AI collaboration -->
<!-- Topics: methodology, process, templates, examples, best practices -->
<!-- Audience: developers, project managers, technical leads -->

## Used by

- [@kazini](https://github.com/kazini) in their spec kit https://github.com/kazini/yask-spec-kit
- Amazon in internal presentations: _"It’s the best stuff I have found on [spec driven development]. I will be sharing links back to your repo with full attribution."_

## 🧭 Navigation Guide

**New to spec-driven development?** → Start with [Methodology Overview](spec-process-guide/methodology/README.md)  
**Ready to create your first spec?** → Jump to [Process Guide](spec-process-guide/process/README.md)  
**Looking for examples?** → Browse [Examples & Case Studies](spec-process-guide/examples/README.md)  
**Need templates?** → Get [Ready-to-Use Templates](spec-process-guide/templates/README.md)  
**Working with AI?** → Learn [Prompting Strategies](spec-process-guide/prompting/README.md)

**📍 Need detailed navigation?** → See [Complete Navigation Index](spec-process-guide/NAVIGATION.md) - Find content by role, problem, or learning style

---

## 📚 Complete Table of Contents

### 🎯 [Methodology](spec-process-guide/methodology/README.md)
Learn the foundational concepts and philosophy behind spec-driven development
- [Overview](spec-process-guide/methodology/overview.md) - Core concepts and benefits
- [Philosophy](spec-process-guide/methodology/philosophy.md) - Why spec-driven development works
- [When to Use](spec-process-guide/methodology/when-to-use.md) - Decision framework and scenarios

### 📋 [Process Guide](spec-process-guide/process/README.md)
Step-by-step walkthrough of the three-phase workflow
- [Requirements Phase](spec-process-guide/process/requirements-phase.md) - Gathering and structuring requirements using EARS
- [Design Phase](spec-process-guide/process/design-phase.md) - Creating comprehensive design documents
- [Tasks Phase](spec-process-guide/process/tasks-phase.md) - Breaking down design into actionable coding tasks
- [Workflow Diagrams](spec-process-guide/process/workflow-diagrams.md) - Visual process flows and decision points

### 🧠 [AI Reasoning](spec-process-guide/ai-reasoning/README.md)
Insights into decision-making frameworks and thought processes
- [Decision Frameworks](spec-process-guide/ai-reasoning/decision-frameworks.md) - How choices are evaluated
- [Thought Processes](spec-process-guide/ai-reasoning/thought-processes.md) - Analysis and prioritization methods
- [Examples](spec-process-guide/ai-reasoning/examples.md) - Real reasoning chains and decision points

### 💬 [Prompting Strategies](spec-process-guide/prompting/README.md)
Effective communication techniques for AI collaboration
- [Strategies](spec-process-guide/prompting/strategies.md) - Core prompting approaches
- [Templates](spec-process-guide/prompting/templates.md) - Ready-to-use prompt patterns
- [Best Practices](spec-process-guide/prompting/best-practices.md) - Tips for clear, effective communication

### ⚡ [Execution Guide](spec-process-guide/execution/README.md)
Practical guidance for implementing features from specs
- [Implementation Guide](spec-process-guide/execution/implementation-guide.md) - Step-by-step execution strategies
- [Quality Assurance](spec-process-guide/execution/quality-assurance.md) - Testing and validation techniques
- [Troubleshooting](spec-process-guide/execution/troubleshooting.md) - Common issues and solutions

### 📚 [Resources](spec-process-guide/resources/README.md)
Curated references and learning materials
- [Standards](spec-process-guide/resources/standards.md) - EARS and industry standards
- [Tools](spec-process-guide/resources/tools.md) - Recommended tools and integrations
- [Further Reading](spec-process-guide/resources/further-reading.md) - Additional learning resources

### 📖 [Examples](spec-process-guide/examples/README.md)
Real-world case studies and complete spec examples
- [Simple Feature Specs](spec-process-guide/examples/simple-feature-spec.md) - Basic feature examples
- [Complex System Specs](spec-process-guide/examples/complex-system-spec.md) - Large system examples
- [Case Studies](spec-process-guide/examples/case-studies.md) - Success stories and lessons learned
- [Troubleshooting & Pitfalls](spec-process-guide/examples/troubleshooting-pitfalls.md) - Common mistakes and recovery strategies

### 📝 [Templates](spec-process-guide/templates/README.md)
Ready-to-use templates and checklists
- [Requirements Template](spec-process-guide/templates/requirements-template.md) - EARS-formatted requirements
- [Design Template](spec-process-guide/templates/design-template.md) - Comprehensive design structure
- [Tasks Template](spec-process-guide/templates/tasks-template.md) - Implementation planning format

---

## Quick Start

New to spec-driven development? Start here:

1. **Understand the Methodology** - Read the [Overview](spec-process-guide/methodology/overview.md) to grasp core concepts
2. **See It in Action** - Review a [Simple Feature Spec](spec-process-guide/examples/simple-feature-spec.md) example
3. **Try It Yourself** - Use the [Requirements Template](spec-process-guide/templates/requirements-template.md) for your first spec
4. **Get Better Results** - Apply [Prompting Strategies](spec-process-guide/prompting/strategies.md) for AI collaboration

## Navigation Tips

- 📋 **Process sections** provide step-by-step instructions
- 🧠 **AI Reasoning sections** explain the "why" behind decisions  
- 💬 **Prompting sections** help you communicate effectively with AI
- 📖 **Examples** show complete, real-world applications
- 📝 **Templates** give you ready-to-use starting points

---

## 🔗 Cross-References & Related Content

### By Workflow Phase
- **Planning Phase**: [Methodology](spec-process-guide/methodology/README.md) → [Requirements](spec-process-guide/process/requirements-phase.md) → [Design](spec-process-guide/process/design-phase.md) → [Tasks](spec-process-guide/process/tasks-phase.md)
- **Execution Phase**: [Implementation Guide](spec-process-guide/execution/implementation-guide.md) → [Quality Assurance](spec-process-guide/execution/quality-assurance.md)
- **AI Collaboration**: [Prompting Strategies](spec-process-guide/prompting/README.md) → [AI Reasoning](spec-process-guide/ai-reasoning/README.md) → [Best Practices](spec-process-guide/prompting/best-practices.md)

### By Experience Level
- **Beginner**: [Methodology](spec-process-guide/methodology/README.md) → [Simple Examples](spec-process-guide/examples/simple-feature-spec.md) → [Templates](spec-process-guide/templates/README.md)
- **Intermediate**: [Process Guide](spec-process-guide/process/README.md) → [Prompting Strategies](spec-process-guide/prompting/README.md) → [Case Studies](spec-process-guide/examples/case-studies.md)
- **Advanced**: [AI Reasoning](spec-process-guide/ai-reasoning/README.md) → [Complex Examples](spec-process-guide/examples/complex-system-spec.md) → [Decision Frameworks](spec-process-guide/ai-reasoning/decision-frameworks.md)

### Quick Problem Solving
- **Unclear Requirements** → [Requirements Phase](spec-process-guide/process/requirements-phase.md) + [EARS Standards](spec-process-guide/resources/standards.md)
- **Design Challenges** → [Design Phase](spec-process-guide/process/design-phase.md) + [AI Decision Frameworks](spec-process-guide/ai-reasoning/decision-frameworks.md)
- **Implementation Issues** → [Implementation Guide](spec-process-guide/execution/implementation-guide.md) + [Troubleshooting](spec-process-guide/examples/troubleshooting-pitfalls.md)
- **AI Communication Problems** → [Prompting Best Practices](spec-process-guide/prompting/best-practices.md) + [Troubleshooting](spec-process-guide/examples/troubleshooting-pitfalls.md)

---

## 🔌 Kiro MCP Server

The Kiro MCP Server exposes Kiro's system prompts and instructions through the Model Context Protocol (MCP), allowing other AI assistants and tools to access Kiro's best practices.

### Features

- **Resources**: Access all Kiro system documentation files via MCP resources
- **Tools**: Query and retrieve specific system instructions programmatically
- **Prompts**: Pre-configured prompts for common Kiro workflows

### Quick Start

Install and configure the MCP server:

```bash
# Using uvx (recommended)
uvx kiro-mcp-server

# Or install with pip
pip install kiro-mcp-server
```

Add to your MCP client configuration (e.g., `~/.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "kiro-prompts": {
      "command": "uvx",
      "args": ["kiro-mcp-server"],
      "disabled": false
    }
  }
}
```

For more details, see the [MCP Server Documentation](mcp-server/README.md).

---

## 🎯 Claude Code Plugin

Kiro is available as an installable Claude Code plugin with 7 skills following the [agentskills.io](https://agentskills.io) specification.

### Quick Install

```bash
# In Claude Code
/plugin marketplace add https://github.com/jasonkneen/kiro
/plugin install kiro-spec-driven@kiro-marketplace
```

### Available Skills

Once installed, Claude automatically uses these skills when relevant:

| Skill | Description | Use When |
|-------|-------------|----------|
| [spec-driven-development](skills/spec-driven-development/) | Master methodology | "create a spec for..." |
| [requirements-engineering](skills/requirements-engineering/) | EARS format | "write requirements for..." |
| [design-documentation](skills/design-documentation/) | Technical architecture | "design the architecture..." |
| [task-breakdown](skills/task-breakdown/) | Implementation planning | "break down into tasks..." |
| [ai-prompting](skills/ai-prompting/) | AI communication | "how to prompt better..." |
| [quality-assurance](skills/quality-assurance/) | Testing strategies | "testing strategy for..." |
| [troubleshooting](skills/troubleshooting/) | Problem resolution | "debug this issue..." |
| [create-steering-documents](skills/create-steering-documents/) | Project guidelines | "create steering documents..." |

### Installation Options

```bash
# User scope (available everywhere)
/plugin install kiro-spec-driven@kiro-marketplace

# Project scope (shared via git)
/plugin install kiro-spec-driven@kiro-marketplace --scope project
```

### Validate Skills

```bash
./scripts/validate-skills.sh
```

For more details, see the [Plugin Documentation](PLUGIN.md) and [Skills Documentation](skills/README.md).

---

*This guide is designed to be both a learning resource and a reference manual. Jump to any section based on your current needs, or read through sequentially for comprehensive understanding.*

**📍 For detailed navigation by role, problem, or learning style, see the [Complete Navigation Index](spec-process-guide/NAVIGATION.md)**