Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
- skills/spec-driven-development/SKILL.md
- skills/create-steering-documents/SKILL.md
- spec-process-guide/resources/standards.md
- spec-process-guide/process/design-phase.md
- spec-process-guide/templates/tasks-template.md
- spec-process-guide/methodology/overview.md
- skills/requirements-engineering/SKILL.md
- spec-process-guide/templates/design-template.md
- commands/create-steering-documents-standalone.md
This document outlines the contribution guidelines for the project, focusing on the Spec-Driven Development methodology and the creation of Steering Documents. The primary goal is to ensure that all contributions are well-planned, documented, and align with the project's standards for quality and maintainability. Following these guidelines facilitates effective collaboration, especially when working with AI assistants.
The core of the contribution process is a systematic, three-phase approach that transforms a feature idea into an implementable solution. This ensures clarity, reduces ambiguity, and preserves knowledge for future maintainers.
Sources: spec-process-guide/methodology/overview.md:14-17, 39-42, skills/spec-driven-development/SKILL.md:11-15
Spec-Driven Development Methodology
Spec-Driven Development is a structured workflow for developing features. It is divided into three distinct phases: Requirements, Design, and Task Planning. Each phase must be completed and approved before the next one begins, ensuring a solid foundation for implementation. This approach is ideal for complex features and high-stakes projects where quality and shared understanding are paramount.
Sources: skills/spec-driven-development/SKILL.md:17-19, spec-process-guide/methodology/overview.md:19-21
The following diagram illustrates the three-phase workflow.
This diagram shows the sequential flow from Requirements to Design to Tasks, with iteration possible within each phase before proceeding.
Sources: spec-process-guide/process/README.md:27-36, skills/spec-driven-development/SKILL.md:21-22
Phase 1: Requirements Engineering
The first phase transforms a vague feature idea into clear, testable requirements. The primary outputs are user stories and acceptance criteria written in the EARS (Easy Approach to Requirements Syntax) format. This ensures that requirements are specific, unambiguous, and verifiable.
Sources: skills/spec-driven-development/SKILL.md:24-26, skills/requirements-engineering/SKILL.md:11-13
User Stories and Acceptance Criteria
- User Story: Captures the user's goal and the value it provides. It follows the format:
As a [role], I want [feature], so that [benefit]. - Acceptance Criteria: Defines the specific, testable conditions that must be met for the user story to be considered complete. These are written using EARS.
Sources: skills/requirements-engineering/SKILL.md:36-44, 48-50
EARS (Easy Approach to Requirements Syntax)
EARS uses specific keywords to structure requirements, making them clear and testable.
| Keyword | Format | Purpose |
|---|---|---|
| WHEN | WHEN [event/trigger] THEN [system] SHALL [response] | For requirements triggered by specific events. |
| IF | IF [condition] THEN [system] SHALL [response] | For requirements that depend on a specific system state. |
| WHILE | WHILE [condition] [system] SHALL [continuous behavior] | For requirements that must be maintained during an operation. |
| WHERE | WHERE [location/context] [system] SHALL [behavior] | For requirements that apply only in specific contexts. |
Sources: spec-process-guide/resources/standards.md:16-51
Phase 2: Design Documentation
Once requirements are approved, the design phase begins. This phase translates the "what" from the requirements into the "how" by creating a comprehensive technical blueprint for implementation. It involves research, architectural decisions, and detailed planning.
Sources: spec-process-guide/process/design-phase.md:20-26, skills/spec-driven-development/SKILL.md:52-54
A design document should cover the following key areas:
- Architecture: High-level system context and component relationships.
- Components and Interfaces: Detailed descriptions of each component's purpose, responsibilities, and APIs.
- Data Models: Definitions of data structures, validation rules, and entity relationships.
- API Design: Detailed specifications for any new or modified API endpoints.
- Security Considerations: Authentication, authorization, and data protection strategies.
- Error Handling: A plan for various error categories and system responses.
- Testing Strategy: An approach for unit, integration, and end-to-end testing.
Sources: spec-process-guide/templates/design-template.md:29-129, spec-process-guide/process/design-phase.md:100-129
The following diagram shows a typical data flow that might be included in a design document.
This sequence illustrates the interaction between the user, frontend, API, and database for a single action.
Sources: spec-process-guide/templates/design-template.md:92-103
Phase 3: Task Planning
The final phase of the spec process is to break down the approved design into a sequence of actionable implementation steps. Each task should be small, well-defined, and directly traceable back to the design and requirements.
Sources: skills/spec-driven-development/SKILL.md:79-82, spec-process-guide/templates/tasks-template.md:20-23
An implementation plan is structured into phases, such as:
- Foundation and Setup
- Core Business Logic
- API Layer
- User Interface
- Integration and Testing
- Deployment and Documentation
Each task within these phases should be a checklist item with a clear description, implementation details, and a reference to the requirements it fulfills.
Sources: spec-process-guide/templates/tasks-template.md:32-113
Task Structure Example
- [ ] 4.1 Create [Component Name] service
- Implement core business rules and validation
- Add error handling and logging
- Write comprehensive unit tests
- _Requirements: [Reference specific requirements]_
Sources: spec-process-guide/templates/tasks-template.md:50-55
Creating Steering Documents
A key contribution method is the creation of "Steering Documents." These are contextual guidelines containing project-specific standards, conventions, and best practices that influence how AI assistants approach development tasks. They are stored in the .kiro/steering/ directory.
Sources: skills/create-steering-documents/SKILL.md:21-24, 150-156
Steering Document Inclusion Logic
Steering documents use front-matter to control when they are included in an AI's context.
This diagram shows the three mechanisms for including steering documents.
Sources: skills/create-steering-documents/SKILL.md:27-33, 158-163
The front-matter options are defined as follows:
---
inclusion: always|fileMatch|manual
fileMatchPattern: 'glob-pattern' # for fileMatch only
---
Sources: skills/create-steering-documents/SKILL.md:165-169
Core and Conditional Documents
The creation process involves analyzing the project type to determine which documents are needed.
| Document Type | Project Type | Purpose |
|---|---|---|
| Core (Always Create) | All | project-standards.md, git-workflow.md |
| Conditional | Frontend | frontend-standards.md |
| Conditional | Backend/API | api-design.md |
| Conditional | All | development-environment.md |
Sources: commands/create-steering-documents-standalone.md:20-35, 78-80
Git Workflow and Standards
All contributions must adhere to the project's Git workflow and branching strategy. These standards are typically defined in git-workflow.md.
Sources: skills/create-steering-documents/SKILL.md:92-93
Branch Naming Convention
- Features:
feature/description-of-feature - Bug Fixes:
fix/description-of-bug - Hotfixes:
hotfix/critical-issue-description - Releases:
release/version-number
Sources: skills/create-steering-documents/SKILL.md:96-100
Commit Message Format
The project follows the Conventional Commits format.
type(scope): description
[optional body]
[optional footer]
The type must be one of the following:
| Type | Description |
|---|---|
feat | A new feature |
fix | A bug fix |
docs | Documentation only changes |
style | Changes that do not affect the meaning of the code |
refactor | A code change that neither fixes a bug nor adds a feature |
test | Adding missing tests or correcting existing tests |
chore | Changes to the build process or auxiliary tools |
Sources: skills/create-steering-documents/SKILL.md:103-112
Pull Request (PR) Guidelines
- PRs should be created from a feature branch to
mainordevelop. - Include a clear description of changes and link any related issues.
- Ensure all tests pass before requesting a review.
- At least one approval is required before merging.
- Squash commits when merging to maintain a clean history.
Sources: skills/create-steering-documents/SKILL.md:114-129
Conclusion
Contributing to this project requires adherence to a structured, spec-driven process. By following the three-phase methodology for feature development and creating clear steering documents, contributors can ensure their work is high-quality, well-documented, and aligned with project goals. The standardized Git workflow further enhances collaboration and code history clarity. This systematic approach is fundamental to the project's success and maintainability.