Kiro Project Template System

A comprehensive template system for structured project development with Kiro, featuring spec-driven development methodology, guided decision-making, and quality assurance throughout all project phases.

🏷️ Topics

kiro template-system project-management spec-driven-development property-based-testing ai-collaboration development-workflow quality-assurance markdown-templates validation-tools

🎯 Overview

This template system transforms rough project ideas into detailed, executable specifications through a structured workflow that emphasizes:

• Guided Decision-Making: Multiple choice options at every key decision point
• Quality Assurance: Built-in validation and quality gates
• Property-Based Testing: Formal correctness properties and testing strategies
• Spec-Driven Development: Integration with Kiro's requirements → design → tasks workflow
• Decision Tracking: Comprehensive logging of choices and reasoning

📁 Template Structure

project-template.md                    # Master workflow guide
├── templates/workflow/                # Phase-specific templates
│   ├── requirements-template.md       # Requirements gathering
│   ├── design-template.md            # Architecture & design
│   └── tasks-template.md             # Implementation planning
├── templates/standards/               # Development standards
│   ├── tech-stack-standards.md       # Technology requirements
│   ├── interaction-rules.md          # Developer interaction guidelines
│   └── ai-collaboration-guidelines.md # AI assistant collaboration best practices
├── templates/reference/               # Reference materials
│   └── glossary.md                   # Terminology & definitions
├── template-development-decisions.md  # Decision log from template creation
├── README.md                         # This file
└── faq.md                           # Frequently asked questions

🚀 Quick Start

For New Projects

1. Read the Master Guide: Start with project-template.md to understand the complete workflow
2. Choose Your Starting Phase:
   • Phase 0: Project initialization (new projects)
   • Phase 1: Requirements gathering (have rough idea)
   • Phase 2: Design (have requirements)
   • Phase 3: Implementation planning (have design)
3. Use Phase Templates: Follow the appropriate template in templates/workflow/
4. Apply Standards: Reference templates/standards/ for technical requirements
5. Track Decisions: Create a decision log for your project

For Existing Projects

1. Assess Current State: Determine which phase your project is in
2. Fill Documentation Gaps: Use templates to create missing specifications
3. Standardize: Apply standards to improve consistency
4. Enhance Quality: Add property-based testing and validation

📋 Workflow Phases

Phase 0: Project Initialization

• Objective: Establish foundation and technology decisions
• Key Decisions: Project type, complexity level, quality requirements
• Outputs: Project structure, tech stack configuration, initial documentation

Phase 1: Requirements Gathering

• Template: templates/workflow/requirements-template.md
• Objective: Define what the project should accomplish
• Key Decisions: Stakeholder identification, elicitation methods, acceptance criteria style
• Outputs: .kiro/specs/{project-name}/requirements.md, user stories, priority matrix

Phase 2: Design & Architecture

• Template: templates/workflow/design-template.md
• Objective: Define how the project will be built
• Key Decisions: Architecture patterns, data management, API design, testing strategy
• Outputs: .kiro/specs/{project-name}/design.md, architecture diagrams, correctness properties

Phase 3: Implementation Planning

• Template: templates/workflow/tasks-template.md
• Objective: Break down design into actionable tasks
• Key Decisions: Task breakdown strategy, development approach, quality gates
• Outputs: .kiro/specs/{project-name}/tasks.md, dependencies, timeline estimates

Phase 4-6: Execution, Testing, Deployment

• Process: Execute using Kiro's task execution capabilities
• Quality Gates: Validation at each step
• Documentation: Continuous updates and final deliverables

🛠 Technology Standards

Core Requirements

• Python: Version 3.14 (managed by uv)
• Package Manager: uv (with virtual environments)
• Platform: Cross-platform (Windows, Mac, Linux)
• Configuration: uv.toml and pyproject.toml

Approved Tools

• Web Framework: FastAPI (preferred), Flask, Django
• Testing: pytest, hypothesis (property-based testing)
• Code Quality: Black, Ruff, mypy
• Documentation: Sphinx, MkDocs, Markdown Style Guide
• Databases: PostgreSQL (preferred), SQLite, MongoDB

Build and Validation Tools

• Build Tool: Just (modern make alternative)
• Validation: Python scripts with comprehensive checks
• Linting: markdownlint for documentation quality
• CI/CD: GitHub Actions integration
• Development: Automated project creation and testing

See templates/standards/tech-stack-standards.md for complete details.

🛠 Development Commands

Using Just (Modern Build Tool)

Install Just: https://github.com/casey/just

# Quick development workflow

just dev

# Full validation suite

just validate-all

# Create new project from templates

just create-project my-new-project

# See all available commands

just --list

Common Development Tasks

# Validate templates
just validate

# Check markdown formatting
just lint

# Test template system
just test-templates

# Clean temporary files
just clean

🎯 Decision-Making Framework

Multiple Choice Approach

Every key decision point offers:

• 5 Standard Options: Covering most common scenarios
• Custom Option: "Other - please specify" for unique needs
• Clear Trade-offs: Advantages and disadvantages explained
• Decision Logging: Record choices and reasoning

Example Decision Point

Architecture Pattern Selection:
A) Layered architecture (traditional MVC/MVP)
B) Hexagonal architecture (ports & adapters)
C) Microservices architecture
D) Event-driven architecture
E) Custom architecture pattern

Choice: B) Hexagonal architecture
Reasoning: Better testability and separation of concerns for our domain-heavy application

📊 Quality Assurance

Built-in Quality Gates

• Requirements Phase: All requirements testable and measurable
• Design Phase: Architecture addresses all requirements
• Implementation: Code passes all tests and meets acceptance criteria
• Testing: Comprehensive test coverage including property-based tests
• Deployment: Complete documentation and monitoring

Property-Based Testing Integration

• Define correctness properties during design phase
• Implement property-based tests alongside unit tests
• Use Hypothesis framework for test generation
• Validate universal properties across all inputs

📝 Decision Tracking

Project Decision Log

Maintain a decision log for every project:

Decision ID	Date	Phase	Decision	Options	Choice	Reasoning	Impact
PD-001	2026-01-25	Phase 0	Architecture Pattern	Layered, Hexagonal, Microservices	B) Hexagonal	Better testability	Improved code organization

Architecture Decision Records (ADRs)

For significant architectural decisions:

• Status: Proposed/Accepted/Deprecated
• Context: Why this decision was needed
• Decision: What was decided
• Consequences: Positive and negative outcomes

🤖 AI Collaboration

Working with AI Assistants

The template system is specifically designed for effective human-AI collaboration:

• Structured Prompts: Templates provide clear context for AI interactions
• Decision Partnership: Clear guidelines on when to use AI assistance vs. human judgment
• Quality Assurance: Built-in validation processes for AI-generated content
• Prompt Engineering: Phase-specific prompt templates for optimal AI collaboration
• Continuous Learning: Decision logs capture successful collaboration patterns

See templates/standards/ai-collaboration-guidelines.md for comprehensive guidance on:

• Effective prompt engineering for each workflow phase
• Decision delegation strategies
• Code quality validation for AI-generated content
• Common collaboration patterns and troubleshooting

AI Assistant Capabilities

• Code Generation: Implementing well-defined functions and boilerplate
• Testing: Creating unit tests, property-based tests, and test data
• Documentation: Generating docstrings, API docs, and technical content
• Analysis: Evaluating options, identifying patterns, suggesting improvements
• Standards Compliance: Ensuring code follows established guidelines

Human Expertise Areas

• Business Requirements: Understanding stakeholder needs and priorities
• Strategic Decisions: Long-term architecture and technology choices
• User Experience: Interface design and interaction patterns
• Quality Judgment: Final validation of AI suggestions and implementations

� Usage Examplesm

Starting a New Web Application

1. Read project-template.md Phase 0
2. Choose "Web Application (FastAPI + Frontend)"
3. Use templates/workflow/requirements-template.md
4. Apply tech stack from templates/standards/tech-stack-standards.md
5. Create decision log for your project

Adding Testing to Existing Project

1. Review current test coverage
2. Use design template to define correctness properties
3. Implement property-based tests using Hypothesis
4. Add integration tests following template guidance

Learning from Example Project

1. Explore examples/task-manager-cli/ for complete workflow demonstration
2. Review decision log to understand choice reasoning
3. See how templates are applied to real project scenarios
4. Use as reference for your own projects

Improving Project Documentation

1. Assess current documentation gaps
2. Use appropriate workflow templates to fill gaps
3. Apply interaction standards for consistency
4. Update decision log with documentation choices

🤝 Contributing

Template Improvements

• Test templates with real projects
• Gather feedback on usability
• Suggest improvements via issues or pull requests
• Share successful customizations

Decision Pattern Sharing

• Document successful decision patterns
• Share lessons learned from project outcomes
• Contribute to FAQ with common questions
• Help improve template effectiveness

🙏 Acknowledgments

This project was developed with assistance from Kiro AI, combining human creativity and direction with AI capabilities to create a comprehensive template system for structured project development.

📖 Additional Resources

• FAQ: See faq.md for frequently asked questions
• Decision Log: Review template-development-decisions.md for template creation decisions
• Example Project: Explore examples/task-manager-cli/ for complete workflow demonstration
• Integration Guides: Check guides/integrations/ for tool integration examples
• Glossary: Check templates/reference/glossary.md for terminology
• Standards: Reference templates/standards/ for detailed requirements
  • Tech Stack Standards - Technology requirements and approved tools
  • Markdown Style Guide - Consistent formatting rules
  • AI Collaboration Guidelines - Working effectively with AI assistants
  • Interaction Rules - Developer interaction guidelines

🆘 Support

Getting Help

• Check faq.md for common questions
• Review decision log for similar situations
• Use Kiro's built-in help and documentation
• Create issues for template-specific problems

Best Practices

• Always document your decisions
• Use quality gates to maintain standards
• Iterate and improve based on experience
• Share learnings with the community

---

Version: 1.0.0 Last Updated: January 25, 2026 Compatibility: Kiro AI Assistant, Python 3.14, uv package manager