RomanNum3ral
/
MicroFish
mirror of https://github.com/666ghj/MiroFish.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat(claude): add CC-SDD planning workflow and /plan command (Step 4) 

Adopt CC-SDD (Kiro) as the project's spec-driven planning tool, with
plans persisted in .kiro/specs/ and a checkpoint after every task
(strictest cadence — no code without an approved plan).

CC-SDD install (via npx cc-sdd@latest --claude --lang en):
- .kiro/settings/rules/: EARS format, gap-analysis, design and
  requirements review gates, design discovery, tasks generation,
  steering principles, parallel-task analysis.
- .kiro/settings/templates/: specs (init, requirements, design, tasks,
  research) and steering (product/tech/structure plus optional
  api-standards/auth/db/deployment/error-handling/security/testing).
- .claude/commands/kiro/: 11 Kiro slash commands — spec-init,
  spec-requirements, spec-design, spec-tasks, spec-impl, spec-status,
  steering, steering-custom, validate-gap, validate-design,
  validate-impl.

Local additions:
- .claude/commands/plan.md: /plan [task] wrapper that picks up the task
  from $ARGUMENTS or a single .ticket/<n>.md snapshot, walks the Kiro
  flow (steering -> spec-init -> spec-requirements -> validate-gap ->
  spec-design -> validate-design -> spec-tasks) and stops for human
  approval after each artefact. Refuses "just code it" requests.
- .claude/hooks/session_start.sh: extend to print active tickets
  (.ticket/*.md) and open specs (.kiro/specs/*/) with phase from
  spec.json, alongside the existing branch/state line.

Documentation: .claude/onboarding/step4_workflow/01_tool_decision.md
This commit is contained in:
Dominik Seemann 2026-05-06 18:01:41 +02:00
parent 52f78d9fe3
commit 8144290fc6
42 changed files with 3570 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
.claude/commands/kiro/spec-design.md Normal file
View File

@ -0,0 +1,177 @@
---
description: Create comprehensive technical design for a specification
allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
argument-hint: <feature-name> [-y]
---
# Technical Design Generator
<background_information>
- **Mission**: Generate comprehensive technical design document that translates requirements (WHAT) into architectural design (HOW)
- **Success Criteria**:
- All requirements mapped to technical components with clear interfaces
- Appropriate architecture discovery and research completed
- Design aligns with steering context and existing patterns
- Visual diagrams included for complex architectures
</background_information>
<instructions>
## Core Task
Generate technical design document for feature **$1** based on approved requirements.
## Execution Steps
### Step 1: Load Context
**Read all necessary context**:
- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md` (if exists)
- **Entire `.kiro/steering/` directory** for complete project memory
- `.kiro/settings/templates/specs/design.md` for document structure
- `.kiro/settings/rules/design-principles.md` for design principles
- `.kiro/settings/templates/specs/research.md` for discovery log structure
**Validate requirements approval**:
- If `-y` flag provided ($2 == "-y"): Auto-approve requirements in spec.json
- Otherwise: Verify approval status (stop if unapproved, see Safety & Fallback)
### Step 2: Discovery & Analysis
**Critical: This phase ensures design is based on complete, accurate information.**
1. **Classify Feature Type**:
- **New Feature** (greenfield) → Full discovery required
- **Extension** (existing system) → Integration-focused discovery
- **Simple Addition** (CRUD/UI) → Minimal or no discovery
- **Complex Integration** → Comprehensive analysis required
2. **Execute Appropriate Discovery Process**:
**For Complex/New Features**:
- Read and execute `.kiro/settings/rules/design-discovery-full.md`
- Conduct thorough research using WebSearch/WebFetch:
- Latest architectural patterns and best practices
- External dependency verification (APIs, libraries, versions, compatibility)
- Official documentation, migration guides, known issues
- Performance benchmarks and security considerations
**For Extensions**:
- Read and execute `.kiro/settings/rules/design-discovery-light.md`
- Focus on integration points, existing patterns, compatibility
- Use Grep to analyze existing codebase patterns
**For Simple Additions**:
- Skip formal discovery, quick pattern check only
3. **Retain Discovery Findings for Step 3**:
- External API contracts and constraints
- Technology decisions with rationale
- Existing patterns to follow or extend
- Integration points and dependencies
- Identified risks and mitigation strategies
- Potential architecture patterns and boundary options (note details in `research.md`)
- Parallelization considerations for future tasks (capture dependencies in `research.md`)
4. **Persist Findings to Research Log**:
- Create or update `.kiro/specs/$1/research.md` using the shared template
- Summarize discovery scope and key findings (Summary section)
- Record investigations in Research Log topics with sources and implications
- Document architecture pattern evaluation, design decisions, and risks using the template sections
- Use the language specified in spec.json when writing or updating `research.md`
### Step 3: Generate Design Document
1. **Load Design Template and Rules**:
- Read `.kiro/settings/templates/specs/design.md` for structure
- Read `.kiro/settings/rules/design-principles.md` for principles
2. **Generate Design Document**:
- **Follow specs/design.md template structure and generation instructions strictly**
- **Integrate all discovery findings**: Use researched information (APIs, patterns, technologies) throughout component definitions, architecture decisions, and integration points
- If existing design.md found in Step 1, use it as reference context (merge mode)
- Apply design rules: Type Safety, Visual Communication, Formal Tone
- Use language specified in spec.json
- Ensure sections reflect updated headings ("Architecture Pattern & Boundary Map", "Technology Stack & Alignment", "Components & Interface Contracts") and reference supporting details from `research.md`
3. **Update Metadata** in spec.json:
- Set `phase: "design-generated"`
- Set `approvals.design.generated: true, approved: false`
- Set `approvals.requirements.approved: true`
- Update `updated_at` timestamp
## Critical Constraints
- **Type Safety**:
- Enforce strong typing aligned with the project's technology stack.
- For statically typed languages, define explicit types/interfaces and avoid unsafe casts.
- For TypeScript, never use `any`; prefer precise types and generics.
- For dynamically typed languages, provide type hints/annotations where available (e.g., Python type hints) and validate inputs at boundaries.
- Document public interfaces and contracts clearly to ensure cross-component type safety.
- **Latest Information**: Use WebSearch/WebFetch for external dependencies and best practices
- **Steering Alignment**: Respect existing architecture patterns from steering context
- **Template Adherence**: Follow specs/design.md template structure and generation instructions strictly
- **Design Focus**: Architecture and interfaces ONLY, no implementation code
- **Requirements Traceability IDs**: Use numeric requirement IDs only (e.g. "1.1", "1.2", "3.1", "3.3") exactly as defined in requirements.md. Do not invent new IDs or use alphabetic labels.
</instructions>
## Tool Guidance
- **Read first**: Load all context before taking action (specs, steering, templates, rules)
- **Research when uncertain**: Use WebSearch/WebFetch for external dependencies, APIs, and latest best practices
- **Analyze existing code**: Use Grep to find patterns and integration points in codebase
- **Write last**: Generate design.md only after all research and analysis complete
## Output Description
**Command execution output** (separate from design.md content):
Provide brief summary in the language specified in spec.json:
1. **Status**: Confirm design document generated at `.kiro/specs/$1/design.md`
2. **Discovery Type**: Which discovery process was executed (full/light/minimal)
3. **Key Findings**: 2-3 critical insights from `research.md` that shaped the design
4. **Next Action**: Approval workflow guidance (see Safety & Fallback)
5. **Research Log**: Confirm `research.md` updated with latest decisions
**Format**: Concise Markdown (under 200 words) - this is the command output, NOT the design document itself
**Note**: The actual design document follows `.kiro/settings/templates/specs/design.md` structure.
## Safety & Fallback
### Error Scenarios
**Requirements Not Approved**:
- **Stop Execution**: Cannot proceed without approved requirements
- **User Message**: "Requirements not yet approved. Approval required before design generation."
- **Suggested Action**: "Run `/kiro:spec-design $1 -y` to auto-approve requirements and proceed"
**Missing Requirements**:
- **Stop Execution**: Requirements document must exist
- **User Message**: "No requirements.md found at `.kiro/specs/$1/requirements.md`"
- **Suggested Action**: "Run `/kiro:spec-requirements $1` to generate requirements first"
**Template Missing**:
- **User Message**: "Template file missing at `.kiro/settings/templates/specs/design.md`"
- **Suggested Action**: "Check repository setup or restore template file"
- **Fallback**: Use inline basic structure with warning
**Steering Context Missing**:
- **Warning**: "Steering directory empty or missing - design may not align with project standards"
- **Proceed**: Continue with generation but note limitation in output
**Discovery Complexity Unclear**:
- **Default**: Use full discovery process (`.kiro/settings/rules/design-discovery-full.md`)
- **Rationale**: Better to over-research than miss critical context
- **Invalid Requirement IDs**:
- **Stop Execution**: If requirements.md is missing numeric IDs or uses non-numeric headings (for example, "Requirement A"), stop and instruct the user to fix requirements.md before continuing.
### Next Phase: Task Generation
**If Design Approved**:
- Review generated design at `.kiro/specs/$1/design.md`
- **Optional**: Run `/kiro:validate-design $1` for interactive quality review
- Then `/kiro:spec-tasks $1 -y` to generate implementation tasks
**If Modifications Needed**:
- Provide feedback and re-run `/kiro:spec-design $1`
- Existing design used as reference (merge mode)
**Note**: Design approval is mandatory before proceeding to task generation.

108
.claude/commands/kiro/spec-impl.md Normal file
View File

@ -0,0 +1,108 @@
---
description: Execute spec tasks using TDD methodology
allowed-tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS, WebFetch, WebSearch
argument-hint: <feature-name> [task-numbers]
---
# Implementation Task Executor
<background_information>
- **Mission**: Execute implementation tasks using Test-Driven Development methodology based on approved specifications
- **Success Criteria**:
- All tests written before implementation code
- Code passes all tests with no regressions
- Tasks marked as completed in tasks.md
- Implementation aligns with design and requirements
</background_information>
<instructions>
## Core Task
Execute implementation tasks for feature **$1** using Test-Driven Development.
## Execution Steps
### Step 1: Load Context
**Read all necessary context**:
- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md`, `tasks.md`
- **Entire `.kiro/steering/` directory** for complete project memory
**Validate approvals**:
- Verify tasks are approved in spec.json (stop if not, see Safety & Fallback)
### Step 2: Select Tasks
**Determine which tasks to execute**:
- If `$2` provided: Execute specified task numbers (e.g., "1.1" or "1,2,3")
- Otherwise: Execute all pending tasks (unchecked `- [ ]` in tasks.md)
### Step 3: Execute with TDD
For each selected task, follow Kent Beck's TDD cycle:
1. **RED - Write Failing Test**:
- Write test for the next small piece of functionality
- Test should fail (code doesn't exist yet)
- Use descriptive test names
2. **GREEN - Write Minimal Code**:
- Implement simplest solution to make test pass
- Focus only on making THIS test pass
- Avoid over-engineering
3. **REFACTOR - Clean Up**:
- Improve code structure and readability
- Remove duplication
- Apply design patterns where appropriate
- Ensure all tests still pass after refactoring
4. **VERIFY - Validate Quality**:
- All tests pass (new and existing)
- No regressions in existing functionality
- Code coverage maintained or improved
5. **MARK COMPLETE**:
- Update checkbox from `- [ ]` to `- [x]` in tasks.md
## Critical Constraints
- **TDD Mandatory**: Tests MUST be written before implementation code
- **Task Scope**: Implement only what the specific task requires
- **Test Coverage**: All new code must have tests
- **No Regressions**: Existing tests must continue to pass
- **Design Alignment**: Implementation must follow design.md specifications
</instructions>
## Tool Guidance
- **Read first**: Load all context before implementation
- **Test first**: Write tests before code
- Use **WebSearch/WebFetch** for library documentation when needed
## Output Description
Provide brief summary in the language specified in spec.json:
1. **Tasks Executed**: Task numbers and test results
2. **Status**: Completed tasks marked in tasks.md, remaining tasks count
**Format**: Concise (under 150 words)
## Safety & Fallback
### Error Scenarios
**Tasks Not Approved or Missing Spec Files**:
- **Stop Execution**: All spec files must exist and tasks must be approved
- **Suggested Action**: "Complete previous phases: `/kiro:spec-requirements`, `/kiro:spec-design`, `/kiro:spec-tasks`"
**Test Failures**:
- **Stop Implementation**: Fix failing tests before continuing
- **Action**: Debug and fix, then re-run
### Task Execution
**Execute specific task(s)**:
- `/kiro:spec-impl $1 1.1` - Single task
- `/kiro:spec-impl $1 1,2,3` - Multiple tasks
**Execute all pending**:
- `/kiro:spec-impl $1` - All unchecked tasks

65
.claude/commands/kiro/spec-init.md Normal file
View File

@ -0,0 +1,65 @@
---
description: Initialize a new specification with detailed project description
allowed-tools: Bash, Read, Write, Glob
argument-hint: <project-description>
---
# Spec Initialization
<background_information>
- **Mission**: Initialize the first phase of spec-driven development by creating directory structure and metadata for a new specification
- **Success Criteria**:
- Generate appropriate feature name from project description
- Create unique spec structure without conflicts
- Provide clear path to next phase (requirements generation)
</background_information>
<instructions>
## Core Task
Generate a unique feature name from the project description ($ARGUMENTS) and initialize the specification structure.
## Execution Steps
1. **Check Uniqueness**: Verify `.kiro/specs/` for naming conflicts (append number suffix if needed)
2. **Create Directory**: `.kiro/specs/[feature-name]/`
3. **Initialize Files Using Templates**:
- Read `.kiro/settings/templates/specs/init.json`
- Read `.kiro/settings/templates/specs/requirements-init.md`
- Replace placeholders:
- `{{FEATURE_NAME}}` → generated feature name
- `{{TIMESTAMP}}` → current ISO 8601 timestamp
- `{{PROJECT_DESCRIPTION}}` → $ARGUMENTS
- Write `spec.json` and `requirements.md` to spec directory
## Important Constraints
- DO NOT generate requirements/design/tasks at this stage
- Follow stage-by-stage development principles
- Maintain strict phase separation
- Only initialization is performed in this phase
</instructions>
## Tool Guidance
- Use **Glob** to check existing spec directories for name uniqueness
- Use **Read** to fetch templates: `init.json` and `requirements-init.md`
- Use **Write** to create spec.json and requirements.md after placeholder replacement
- Perform validation before any file write operation
## Output Description
Provide output in the language specified in `spec.json` with the following structure:
1. **Generated Feature Name**: `feature-name` format with 1-2 sentence rationale
2. **Project Summary**: Brief summary (1 sentence)
3. **Created Files**: Bullet list with full paths
4. **Next Step**: Command block showing `/kiro:spec-requirements <feature-name>`
5. **Notes**: Explain why only initialization was performed (2-3 sentences on phase separation)
**Format Requirements**:
- Use Markdown headings (##, ###)
- Wrap commands in code blocks
- Keep total output concise (under 250 words)
- Use clear, professional language per `spec.json.language`
## Safety & Fallback
- **Ambiguous Feature Name**: If feature name generation is unclear, propose 2-3 options and ask user to select
- **Template Missing**: If template files don't exist in `.kiro/settings/templates/specs/`, report error with specific missing file path and suggest checking repository setup
- **Directory Conflict**: If feature name already exists, append numeric suffix (e.g., `feature-name-2`) and notify user of automatic conflict resolution
- **Write Failure**: Report error with specific path and suggest checking permissions or disk space

96
.claude/commands/kiro/spec-requirements.md Normal file
View File

@ -0,0 +1,96 @@
---
description: Generate comprehensive requirements for a specification
allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
argument-hint: <feature-name>
---
# Requirements Generation
<background_information>
- **Mission**: Generate comprehensive, testable requirements in EARS format based on the project description from spec initialization
- **Success Criteria**:
- Create complete requirements document aligned with steering context
- Follow the project's EARS patterns and constraints for all acceptance criteria
- Focus on core functionality without implementation details
- Update metadata to track generation status
</background_information>
<instructions>
## Core Task
Generate complete requirements for feature **$1** based on the project description in requirements.md.
## Execution Steps
1. **Load Context**:
- Read `.kiro/specs/$1/spec.json` for language and metadata
- Read `.kiro/specs/$1/requirements.md` for project description
- **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
- Default files: `structure.md`, `tech.md`, `product.md`
- All custom steering files (regardless of mode settings)
- This provides complete project memory and context
2. **Read Guidelines**:
- Read `.kiro/settings/rules/ears-format.md` for EARS syntax rules
- Read `.kiro/settings/templates/specs/requirements.md` for document structure
3. **Generate Requirements**:
- Create initial requirements based on project description
- Group related functionality into logical requirement areas
- Apply EARS format to all acceptance criteria
- Use language specified in spec.json
4. **Update Metadata**:
- Set `phase: "requirements-generated"`
- Set `approvals.requirements.generated: true`
- Update `updated_at` timestamp
## Important Constraints
- Focus on WHAT, not HOW (no implementation details)
- Requirements must be testable and verifiable
- Choose appropriate subject for EARS statements (system/service name for software)
- Generate initial version first, then iterate with user feedback (no sequential questions upfront)
- Requirement headings in requirements.md MUST include a leading numeric ID only (for example: "Requirement 1", "1.", "2 Feature ..."); do not use alphabetic IDs like "Requirement A".
</instructions>
## Tool Guidance
- **Read first**: Load all context (spec, steering, rules, templates) before generation
- **Write last**: Update requirements.md only after complete generation
- Use **WebSearch/WebFetch** only if external domain knowledge needed
## Output Description
Provide output in the language specified in spec.json with:
1. **Generated Requirements Summary**: Brief overview of major requirement areas (3-5 bullets)
2. **Document Status**: Confirm requirements.md updated and spec.json metadata updated
3. **Next Steps**: Guide user on how to proceed (approve and continue, or modify)
**Format Requirements**:
- Use Markdown headings for clarity
- Include file paths in code blocks
- Keep summary concise (under 300 words)
## Safety & Fallback
### Error Scenarios
- **Missing Project Description**: If requirements.md lacks project description, ask user for feature details
- **Ambiguous Requirements**: Propose initial version and iterate with user rather than asking many upfront questions
- **Template Missing**: If template files don't exist, use inline fallback structure with warning
- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
- **Incomplete Requirements**: After generation, explicitly ask user if requirements cover all expected functionality
- **Steering Directory Empty**: Warn user that project context is missing and may affect requirement quality
- **Non-numeric Requirement Headings**: If existing headings do not include a leading numeric ID (for example, they use "Requirement A"), normalize them to numeric IDs and keep that mapping consistent (never mix numeric and alphabetic labels).
### Next Phase: Design Generation
**If Requirements Approved**:
- Review generated requirements at `.kiro/specs/$1/requirements.md`
- **Optional Gap Analysis** (for existing codebases):
- Run `/kiro:validate-gap $1` to analyze implementation gap with current code
- Identifies existing components, integration points, and implementation strategy
- Recommended for brownfield projects; skip for greenfield
- Then `/kiro:spec-design $1 -y` to proceed to design phase
**If Modifications Needed**:
- Provide feedback and re-run `/kiro:spec-requirements $1`
**Note**: Approval is mandatory before proceeding to design phase.

85
.claude/commands/kiro/spec-status.md Normal file
View File

@ -0,0 +1,85 @@
---
description: Show specification status and progress
allowed-tools: Bash, Read, Glob, Write, Edit, MultiEdit, Update
argument-hint: <feature-name>
---
# Specification Status
<background_information>
- **Mission**: Display comprehensive status and progress for a specification
- **Success Criteria**:
- Show current phase and completion status
- Identify next actions and blockers
- Provide clear visibility into progress
</background_information>
<instructions>
## Core Task
Generate status report for feature **$1** showing progress across all phases.
## Execution Steps
### Step 1: Load Spec Context
- Read `.kiro/specs/$1/spec.json` for metadata and phase status
- Read existing files: `requirements.md`, `design.md`, `tasks.md` (if they exist)
- Check `.kiro/specs/$1/` directory for available files
### Step 2: Analyze Status
**Parse each phase**:
- **Requirements**: Count requirements and acceptance criteria
- **Design**: Check for architecture, components, diagrams
- **Tasks**: Count completed vs total tasks (parse `- [x]` vs `- [ ]`)
- **Approvals**: Check approval status in spec.json
### Step 3: Generate Report
Create report in the language specified in spec.json covering:
1. **Current Phase & Progress**: Where the spec is in the workflow
2. **Completion Status**: Percentage complete for each phase
3. **Task Breakdown**: If tasks exist, show completed/remaining counts
4. **Next Actions**: What needs to be done next
5. **Blockers**: Any issues preventing progress
## Critical Constraints
- Use language from spec.json
- Calculate accurate completion percentages
- Identify specific next action commands
</instructions>
## Tool Guidance
- **Read**: Load spec.json first, then other spec files as needed
- **Parse carefully**: Extract completion data from tasks.md checkboxes
- Use **Glob** to check which spec files exist
## Output Description
Provide status report in the language specified in spec.json:
**Report Structure**:
1. **Feature Overview**: Name, phase, last updated
2. **Phase Status**: Requirements, Design, Tasks with completion %
3. **Task Progress**: If tasks exist, show X/Y completed
4. **Next Action**: Specific command to run next
5. **Issues**: Any blockers or missing elements
**Format**: Clear, scannable format with emojis (✅/⏳/❌) for status
## Safety & Fallback
### Error Scenarios
**Spec Not Found**:
- **Message**: "No spec found for `$1`. Check available specs in `.kiro/specs/`"
- **Action**: List available spec directories
**Incomplete Spec**:
- **Warning**: Identify which files are missing
- **Suggested Action**: Point to next phase command
### List All Specs
To see all available specs:
- Run with no argument or use wildcard
- Shows all specs in `.kiro/specs/` with their status

136
.claude/commands/kiro/spec-tasks.md Normal file
View File

@ -0,0 +1,136 @@
---
description: Generate implementation tasks for a specification
allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep
argument-hint: <feature-name> [-y] [--sequential]
---
# Implementation Tasks Generator
<background_information>
- **Mission**: Generate detailed, actionable implementation tasks that translate technical design into executable work items
- **Success Criteria**:
- All requirements mapped to specific tasks
- Tasks properly sized (1-3 hours each)
- Clear task progression with proper hierarchy
- Natural language descriptions focused on capabilities
</background_information>
<instructions>
## Core Task
Generate implementation tasks for feature **$1** based on approved requirements and design.
## Execution Steps
### Step 1: Load Context
**Read all necessary context**:
- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md`
- `.kiro/specs/$1/tasks.md` (if exists, for merge mode)
- **Entire `.kiro/steering/` directory** for complete project memory
**Validate approvals**:
- If `-y` flag provided ($2 == "-y"): Auto-approve requirements and design in spec.json
- Otherwise: Verify both approved (stop if not, see Safety & Fallback)
- Determine sequential mode based on presence of `--sequential`
### Step 2: Generate Implementation Tasks
**Load generation rules and template**:
- Read `.kiro/settings/rules/tasks-generation.md` for principles
- If `sequential` is **false**: Read `.kiro/settings/rules/tasks-parallel-analysis.md` for parallel judgement criteria
- Read `.kiro/settings/templates/specs/tasks.md` for format (supports `(P)` markers)
**Generate task list following all rules**:
- Use language specified in spec.json
- Map all requirements to tasks
- When documenting requirement coverage, list numeric requirement IDs only (comma-separated) without descriptive suffixes, parentheses, translations, or free-form labels
- Ensure all design components included
- Verify task progression is logical and incremental
- Collapse single-subtask structures by promoting them to major tasks and avoid duplicating details on container-only major tasks (use template patterns accordingly)
- Apply `(P)` markers to tasks that satisfy parallel criteria (omit markers in sequential mode)
- Mark optional test coverage subtasks with `- [ ]*` only when they strictly cover acceptance criteria already satisfied by core implementation and can be deferred post-MVP
- If existing tasks.md found, merge with new content
### Step 3: Finalize
**Write and update**:
- Create/update `.kiro/specs/$1/tasks.md`
- Update spec.json metadata:
- Set `phase: "tasks-generated"`
- Set `approvals.tasks.generated: true, approved: false`
- Set `approvals.requirements.approved: true`
- Set `approvals.design.approved: true`
- Update `updated_at` timestamp
## Critical Constraints
- **Follow rules strictly**: All principles in tasks-generation.md are mandatory
- **Natural Language**: Describe what to do, not code structure details
- **Complete Coverage**: ALL requirements must map to tasks
- **Maximum 2 Levels**: Major tasks and sub-tasks only (no deeper nesting)
- **Sequential Numbering**: Major tasks increment (1, 2, 3...), never repeat
- **Task Integration**: Every task must connect to the system (no orphaned work)
</instructions>
## Tool Guidance
- **Read first**: Load all context, rules, and templates before generation
- **Write last**: Generate tasks.md only after complete analysis and verification
## Output Description
Provide brief summary in the language specified in spec.json:
1. **Status**: Confirm tasks generated at `.kiro/specs/$1/tasks.md`
2. **Task Summary**:
- Total: X major tasks, Y sub-tasks
- All Z requirements covered
- Average task size: 1-3 hours per sub-task
3. **Quality Validation**:
- ✅ All requirements mapped to tasks
- ✅ Task dependencies verified
- ✅ Testing tasks included
4. **Next Action**: Review tasks and proceed when ready
**Format**: Concise (under 200 words)
## Safety & Fallback
### Error Scenarios
**Requirements or Design Not Approved**:
- **Stop Execution**: Cannot proceed without approved requirements and design
- **User Message**: "Requirements and design must be approved before task generation"
- **Suggested Action**: "Run `/kiro:spec-tasks $1 -y` to auto-approve both and proceed"
**Missing Requirements or Design**:
- **Stop Execution**: Both documents must exist
- **User Message**: "Missing requirements.md or design.md at `.kiro/specs/$1/`"
- **Suggested Action**: "Complete requirements and design phases first"
**Incomplete Requirements Coverage**:
- **Warning**: "Not all requirements mapped to tasks. Review coverage."
- **User Action Required**: Confirm intentional gaps or regenerate tasks
**Template/Rules Missing**:
- **User Message**: "Template or rules files missing in `.kiro/settings/`"
- **Fallback**: Use inline basic structure with warning
- **Suggested Action**: "Check repository setup or restore template files"
- **Missing Numeric Requirement IDs**:
- **Stop Execution**: All requirements in requirements.md MUST have numeric IDs. If any requirement lacks a numeric ID, stop and request that requirements.md be fixed before generating tasks.
### Next Phase: Implementation
**Before Starting Implementation**:
- **IMPORTANT**: Clear conversation history and free up context before running `/kiro:spec-impl`
- This applies when starting first task OR switching between tasks
- Fresh context ensures clean state and proper task focus
**If Tasks Approved**:
- Execute specific task: `/kiro:spec-impl $1 1.1` (recommended: clear context between each task)
- Execute multiple tasks: `/kiro:spec-impl $1 1.1,1.2` (use cautiously, clear context between tasks)
- Without arguments: `/kiro:spec-impl $1` (executes all pending tasks - NOT recommended due to context bloat)
**If Modifications Needed**:
- Provide feedback and re-run `/kiro:spec-tasks $1`
- Existing tasks used as reference (merge mode)
**Note**: The implementation phase will guide you through executing tasks with appropriate context and validation.

127
.claude/commands/kiro/steering-custom.md Normal file
View File

@ -0,0 +1,127 @@
---
description: Create custom steering documents for specialized project contexts
allowed-tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
---
# Kiro Custom Steering Creation
<background_information>
**Role**: Create specialized steering documents beyond core files (product, tech, structure).
**Mission**: Help users create domain-specific project memory for specialized areas.
**Success Criteria**:
- Custom steering captures specialized patterns
- Follows same granularity principles as core steering
- Provides clear value for specific domain
</background_information>
<instructions>
## Workflow
1. **Ask user** for custom steering needs:
- Domain/topic (e.g., "API standards", "testing approach")
- Specific requirements or patterns to document
2. **Check if template exists**:
- Load from `.kiro/settings/templates/steering-custom/{name}.md` if available
- Use as starting point, customize based on project
3. **Analyze codebase** (JIT) for relevant patterns:
- **Glob** for related files
- **Read** for existing implementations
- **Grep** for specific patterns
4. **Generate custom steering**:
- Follow template structure if available
- Apply principles from `.kiro/settings/rules/steering-principles.md`
- Focus on patterns, not exhaustive lists
- Keep to 100-200 lines (2-3 minute read)
5. **Create file** in `.kiro/steering/{name}.md`
## Available Templates
Templates available in `.kiro/settings/templates/steering-custom/`:
1. **api-standards.md** - REST/GraphQL conventions, error handling
2. **testing.md** - Test organization, mocking, coverage
3. **security.md** - Auth patterns, input validation, secrets
4. **database.md** - Schema design, migrations, query patterns
5. **error-handling.md** - Error types, logging, retry strategies
6. **authentication.md** - Auth flows, permissions, session management
7. **deployment.md** - CI/CD, environments, rollback procedures
Load template when needed, customize for project.
## Steering Principles
From `.kiro/settings/rules/steering-principles.md`:
- **Patterns over lists**: Document patterns, not every file/component
- **Single domain**: One topic per file
- **Concrete examples**: Show patterns with code
- **Maintainable size**: 100-200 lines typical
- **Security first**: Never include secrets or sensitive data
</instructions>
## Tool guidance
- **Read**: Load template, analyze existing code
- **Glob**: Find related files for pattern analysis
- **Grep**: Search for specific patterns
- **LS**: Understand relevant structure
**JIT Strategy**: Load template only when creating that type of steering.
## Output description
Chat summary with file location (file created directly).
```
✅ Custom Steering Created
## Created:
- .kiro/steering/api-standards.md
## Based On:
- Template: api-standards.md
- Analyzed: src/api/ directory patterns
- Extracted: REST conventions, error format
## Content:
- Endpoint naming patterns
- Request/response format
- Error handling conventions
- Authentication approach
Review and customize as needed.
```
## Examples
### Success: API Standards
**Input**: "Create API standards steering"
**Action**: Load template, analyze src/api/, extract patterns
**Output**: api-standards.md with project-specific REST conventions
### Success: Testing Strategy
**Input**: "Document our testing approach"
**Action**: Load template, analyze test files, extract patterns
**Output**: testing.md with test organization and mocking strategies
## Safety & Fallback
- **No template**: Generate from scratch based on domain knowledge
- **Security**: Never include secrets (load principles)
- **Validation**: Ensure doesn't duplicate core steering content
## Notes
- Templates are starting points, customize for project
- Follow same granularity principles as core steering
- All steering files loaded as project memory
- Custom files equally important as core files
- Avoid documenting agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories

143
.claude/commands/kiro/steering.md Normal file
View File

@ -0,0 +1,143 @@
---
description: Manage .kiro/steering/ as persistent project knowledge
allowed-tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
---
# Kiro Steering Management
<background_information>
**Role**: Maintain `.kiro/steering/` as persistent project memory.
**Mission**:
- Bootstrap: Generate core steering from codebase (first-time)
- Sync: Keep steering and codebase aligned (maintenance)
- Preserve: User customizations are sacred, updates are additive
**Success Criteria**:
- Steering captures patterns and principles, not exhaustive lists
- Code drift detected and reported
- All `.kiro/steering/*.md` treated equally (core + custom)
</background_information>
<instructions>
## Scenario Detection
Check `.kiro/steering/` status:
**Bootstrap Mode**: Empty OR missing core files (product.md, tech.md, structure.md)
**Sync Mode**: All core files exist
---
## Bootstrap Flow
1. Load templates from `.kiro/settings/templates/steering/`
2. Analyze codebase (JIT):
- `glob_file_search` for source files
- `read_file` for README, package.json, etc.
- `grep` for patterns
3. Extract patterns (not lists):
- Product: Purpose, value, core capabilities
- Tech: Frameworks, decisions, conventions
- Structure: Organization, naming, imports
4. Generate steering files (follow templates)
5. Load principles from `.kiro/settings/rules/steering-principles.md`
6. Present summary for review
**Focus**: Patterns that guide decisions, not catalogs of files/dependencies.
---
## Sync Flow
1. Load all existing steering (`.kiro/steering/*.md`)
2. Analyze codebase for changes (JIT)
3. Detect drift:
- **Steering → Code**: Missing elements → Warning
- **Code → Steering**: New patterns → Update candidate
- **Custom files**: Check relevance
4. Propose updates (additive, preserve user content)
5. Report: Updates, warnings, recommendations
**Update Philosophy**: Add, don't replace. Preserve user sections.
---
## Granularity Principle
From `.kiro/settings/rules/steering-principles.md`:
> "If new code follows existing patterns, steering shouldn't need updating."
Document patterns and principles, not exhaustive lists.
**Bad**: List every file in directory tree
**Good**: Describe organization pattern with examples
</instructions>
## Tool guidance
- `glob_file_search`: Find source/config files
- `read_file`: Read steering, docs, configs
- `grep`: Search patterns
- `list_dir`: Analyze structure
**JIT Strategy**: Fetch when needed, not upfront.
## Output description
Chat summary only (files updated directly).
### Bootstrap:
```
✅ Steering Created
## Generated:
- product.md: [Brief description]
- tech.md: [Key stack]
- structure.md: [Organization]
Review and approve as Source of Truth.
```
### Sync:
```
✅ Steering Updated
## Changes:
- tech.md: React 18 → 19
- structure.md: Added API pattern
## Code Drift:
- Components not following import conventions
## Recommendations:
- Consider api-standards.md
```
## Examples
### Bootstrap
**Input**: Empty steering, React TypeScript project
**Output**: 3 files with patterns - "Feature-first", "TypeScript strict", "React 19"
### Sync
**Input**: Existing steering, new `/api` directory
**Output**: Updated structure.md, flagged non-compliant files, suggested api-standards.md
## Safety & Fallback
- **Security**: Never include keys, passwords, secrets (see principles)
- **Uncertainty**: Report both states, ask user
- **Preservation**: Add rather than replace when in doubt
## Notes
- All `.kiro/steering/*.md` loaded as project memory
- Templates and principles are external for customization
- Focus on patterns, not catalogs
- "Golden Rule": New code following patterns shouldn't require steering updates
- Avoid documenting agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
- `.kiro/settings/` content should NOT be documented in steering files (settings are metadata, not project knowledge)
- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories

92
.claude/commands/kiro/validate-design.md Normal file
View File

@ -0,0 +1,92 @@
---
description: Interactive technical design quality review and validation
allowed-tools: Read, Glob, Grep
argument-hint: <feature-name>
---
# Technical Design Validation
<background_information>
- **Mission**: Conduct interactive quality review of technical design to ensure readiness for implementation
- **Success Criteria**:
- Critical issues identified (maximum 3 most important concerns)
- Balanced assessment with strengths recognized
- Clear GO/NO-GO decision with rationale
- Actionable feedback for improvements if needed
</background_information>
<instructions>
## Core Task
Interactive design quality review for feature **$1** based on approved requirements and design document.
## Execution Steps
1. **Load Context**:
- Read `.kiro/specs/$1/spec.json` for language and metadata
- Read `.kiro/specs/$1/requirements.md` for requirements
- Read `.kiro/specs/$1/design.md` for design document
- **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
- Default files: `structure.md`, `tech.md`, `product.md`
- All custom steering files (regardless of mode settings)
- This provides complete project memory and context
2. **Read Review Guidelines**:
- Read `.kiro/settings/rules/design-review.md` for review criteria and process
3. **Execute Design Review**:
- Follow design-review.md process: Analysis → Critical Issues → Strengths → GO/NO-GO
- Limit to 3 most important concerns
- Engage interactively with user
- Use language specified in spec.json for output
4. **Provide Decision and Next Steps**:
- Clear GO/NO-GO decision with rationale
- Guide user on proceeding based on decision
## Important Constraints
- **Quality assurance, not perfection seeking**: Accept acceptable risk
- **Critical focus only**: Maximum 3 issues, only those significantly impacting success
- **Interactive approach**: Engage in dialogue, not one-way evaluation
- **Balanced assessment**: Recognize both strengths and weaknesses
- **Actionable feedback**: All suggestions must be implementable
</instructions>
## Tool Guidance
- **Read first**: Load all context (spec, steering, rules) before review
- **Grep if needed**: Search codebase for pattern validation or integration checks
- **Interactive**: Engage with user throughout the review process
## Output Description
Provide output in the language specified in spec.json with:
1. **Review Summary**: Brief overview (2-3 sentences) of design quality and readiness
2. **Critical Issues**: Maximum 3, following design-review.md format
3. **Design Strengths**: 1-2 positive aspects
4. **Final Assessment**: GO/NO-GO decision with rationale and next steps
**Format Requirements**:
- Use Markdown headings for clarity
- Follow design-review.md output format
- Keep summary concise
## Safety & Fallback
### Error Scenarios
- **Missing Design**: If design.md doesn't exist, stop with message: "Run `/kiro:spec-design $1` first to generate design document"
- **Design Not Generated**: If design phase not marked as generated in spec.json, warn but proceed with review
- **Empty Steering Directory**: Warn user that project context is missing and may affect review quality
- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
### Next Phase: Task Generation
**If Design Passes Validation (GO Decision)**:
- Review feedback and apply changes if needed
- Run `/kiro:spec-tasks $1` to generate implementation tasks
- Or `/kiro:spec-tasks $1 -y` to auto-approve and proceed directly
**If Design Needs Revision (NO-GO Decision)**:
- Address critical issues identified
- Re-run `/kiro:spec-design $1` with improvements
- Re-validate with `/kiro:validate-design $1`
**Note**: Design validation is recommended but optional. Quality review helps catch issues early.

88
.claude/commands/kiro/validate-gap.md Normal file
View File

@ -0,0 +1,88 @@
---
description: Analyze implementation gap between requirements and existing codebase
allowed-tools: Bash, Glob, Grep, Read, Write, Edit, MultiEdit, WebSearch, WebFetch
argument-hint: <feature-name>
---
# Implementation Gap Validation
<background_information>
- **Mission**: Analyze the gap between requirements and existing codebase to inform implementation strategy
- **Success Criteria**:
- Comprehensive understanding of existing codebase patterns and components
- Clear identification of missing capabilities and integration challenges
- Multiple viable implementation approaches evaluated
- Technical research needs identified for design phase
</background_information>
<instructions>
## Core Task
Analyze implementation gap for feature **$1** based on approved requirements and existing codebase.
## Execution Steps
1. **Load Context**:
- Read `.kiro/specs/$1/spec.json` for language and metadata
- Read `.kiro/specs/$1/requirements.md` for requirements
- **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
- Default files: `structure.md`, `tech.md`, `product.md`
- All custom steering files (regardless of mode settings)
- This provides complete project memory and context
2. **Read Analysis Guidelines**:
- Read `.kiro/settings/rules/gap-analysis.md` for comprehensive analysis framework
3. **Execute Gap Analysis**:
- Follow gap-analysis.md framework for thorough investigation
- Analyze existing codebase using Grep and Read tools
- Use WebSearch/WebFetch for external dependency research if needed
- Evaluate multiple implementation approaches (extend/new/hybrid)
- Use language specified in spec.json for output
4. **Generate Analysis Document**:
- Create comprehensive gap analysis following the output guidelines in gap-analysis.md
- Present multiple viable options with trade-offs
- Flag areas requiring further research
## Important Constraints
- **Information over Decisions**: Provide analysis and options, not final implementation choices
- **Multiple Options**: Present viable alternatives when applicable
- **Thorough Investigation**: Use tools to deeply understand existing codebase
- **Explicit Gaps**: Clearly flag areas needing research or investigation
</instructions>
## Tool Guidance
- **Read first**: Load all context (spec, steering, rules) before analysis
- **Grep extensively**: Search codebase for patterns, conventions, and integration points
- **WebSearch/WebFetch**: Research external dependencies and best practices when needed
- **Write last**: Generate analysis only after complete investigation
## Output Description
Provide output in the language specified in spec.json with:
1. **Analysis Summary**: Brief overview (3-5 bullets) of scope, challenges, and recommendations
2. **Document Status**: Confirm analysis approach used
3. **Next Steps**: Guide user on proceeding to design phase
**Format Requirements**:
- Use Markdown headings for clarity
- Keep summary concise (under 300 words)
- Detailed analysis follows gap-analysis.md output guidelines
## Safety & Fallback
### Error Scenarios
- **Missing Requirements**: If requirements.md doesn't exist, stop with message: "Run `/kiro:spec-requirements $1` first to generate requirements"
- **Requirements Not Approved**: If requirements not approved, warn user but proceed (gap analysis can inform requirement revisions)
- **Empty Steering Directory**: Warn user that project context is missing and may affect analysis quality
- **Complex Integration Unclear**: Flag for comprehensive research in design phase rather than blocking
- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
### Next Phase: Design Generation
**If Gap Analysis Complete**:
- Review gap analysis insights
- Run `/kiro:spec-design $1` to create technical design document
- Or `/kiro:spec-design $1 -y` to auto-approve requirements and proceed directly
**Note**: Gap analysis is optional but recommended for brownfield projects to inform design decisions.

138
.claude/commands/kiro/validate-impl.md Normal file
View File

@ -0,0 +1,138 @@
---
description: Validate implementation against requirements, design, and tasks
allowed-tools: Bash, Glob, Grep, Read, LS
argument-hint: [feature-name] [task-numbers]
---
# Implementation Validation
<background_information>
- **Mission**: Verify that implementation aligns with approved requirements, design, and tasks
- **Success Criteria**:
- All specified tasks marked as completed
- Tests exist and pass for implemented functionality
- Requirements traceability confirmed (EARS requirements covered)
- Design structure reflected in implementation
- No regressions in existing functionality
</background_information>
<instructions>
## Core Task
Validate implementation for feature(s) and task(s) based on approved specifications.
## Execution Steps
### 1. Detect Validation Target
**If no arguments provided** (`$1` empty):
- Parse conversation history for `/kiro:spec-impl <feature> [tasks]` commands
- Extract feature names and task numbers from each execution
- Aggregate all implemented tasks by feature
- Report detected implementations (e.g., "user-auth: 1.1, 1.2, 1.3")
- If no history found, scan `.kiro/specs/` for features with completed tasks `[x]`
**If feature provided** (`$1` present, `$2` empty):
- Use specified feature
- Detect all completed tasks `[x]` in `.kiro/specs/$1/tasks.md`
**If both feature and tasks provided** (`$1` and `$2` present):
- Validate specified feature and tasks only (e.g., `user-auth 1.1,1.2`)
### 2. Load Context
For each detected feature:
- Read `.kiro/specs/<feature>/spec.json` for metadata
- Read `.kiro/specs/<feature>/requirements.md` for requirements
- Read `.kiro/specs/<feature>/design.md` for design structure
- Read `.kiro/specs/<feature>/tasks.md` for task list
- **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
- Default files: `structure.md`, `tech.md`, `product.md`
- All custom steering files (regardless of mode settings)
### 3. Execute Validation
For each task, verify:
#### Task Completion Check
- Checkbox is `[x]` in tasks.md
- If not completed, flag as "Task not marked complete"
#### Test Coverage Check
- Tests exist for task-related functionality
- Tests pass (no failures or errors)
- Use Bash to run test commands (e.g., `npm test`, `pytest`)
- If tests fail or don't exist, flag as "Test coverage issue"
#### Requirements Traceability
- Identify EARS requirements related to the task
- Use Grep to search implementation for evidence of requirement coverage
- If requirement not traceable to code, flag as "Requirement not implemented"
#### Design Alignment
- Check if design.md structure is reflected in implementation
- Verify key interfaces, components, and modules exist
- Use Grep/LS to confirm file structure matches design
- If misalignment found, flag as "Design deviation"
#### Regression Check
- Run full test suite (if available)
- Verify no existing tests are broken
- If regressions detected, flag as "Regression detected"
### 4. Generate Report
Provide summary in the language specified in spec.json:
- Validation summary by feature
- Coverage report (tasks, requirements, design)
- Issues and deviations with severity (Critical/Warning)
- GO/NO-GO decision
## Important Constraints
- **Conversation-aware**: Prioritize conversation history for auto-detection
- **Non-blocking warnings**: Design deviations are warnings unless critical
- **Test-first focus**: Test coverage is mandatory for GO decision
- **Traceability required**: All requirements must be traceable to implementation
</instructions>
## Tool Guidance
- **Conversation parsing**: Extract `/kiro:spec-impl` patterns from history
- **Read context**: Load all specs and steering before validation
- **Bash for tests**: Execute test commands to verify pass status
- **Grep for traceability**: Search codebase for requirement evidence
- **LS/Glob for structure**: Verify file structure matches design
## Output Description
Provide output in the language specified in spec.json with:
1. **Detected Target**: Features and tasks being validated (if auto-detected)
2. **Validation Summary**: Brief overview per feature (pass/fail counts)
3. **Issues**: List of validation failures with severity and location
4. **Coverage Report**: Requirements/design/task coverage percentages
5. **Decision**: GO (ready for next phase) / NO-GO (needs fixes)
**Format Requirements**:
- Use Markdown headings and tables for clarity
- Flag critical issues with ⚠️ or 🔴
- Keep summary concise (under 400 words)
## Safety & Fallback
### Error Scenarios
- **No Implementation Found**: If no `/kiro:spec-impl` in history and no `[x]` tasks, report "No implementations detected"
- **Test Command Unknown**: If test framework unclear, warn and skip test validation (manual verification required)
- **Missing Spec Files**: If spec.json/requirements.md/design.md missing, stop with error
- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
### Next Steps Guidance
**If GO Decision**:
- Implementation validated and ready
- Proceed to deployment or next feature
**If NO-GO Decision**:
- Address critical issues listed
- Re-run `/kiro:spec-impl <feature> [tasks]` for fixes
- Re-validate with `/kiro:validate-impl [feature] [tasks]`
**Note**: Validation is recommended after implementation to ensure spec alignment and quality.

64
.claude/commands/plan.md Normal file
View File

@ -0,0 +1,64 @@
---
description: Plan a feature or fix using Spec-Driven Development (CC-SDD / Kiro). Mandatory before code.
argument-hint: [task-description] (optional — falls back to the active ticket)
---
# /plan — Plan before you code (MANDATORY)
You are running the `/plan` slash command. The user typed:
```
/plan $ARGUMENTS
```
**Rule:** No feature without a plan. No code without an approved plan. This command sets up a spec via CC-SDD (Kiro) and walks the user through Requirements → Design → Tasks before any implementation.
## Step 0 — Determine the source description
1. If `$ARGUMENTS` is non-empty → use it verbatim as the task description.
2. Otherwise, look for ticket snapshots in `.ticket/`:
- List files matching `.ticket/*.md` excluding `repo.md` and `.gitkeep`.
- If exactly one snapshot exists → use the body of that ticket as the description (and report which ticket).
- If multiple exist → ask the user which one (`#42`, `#17`, …).
- If none exist → ask the user "What should I plan?" and stop until they answer.
Treat the resulting text as **the task brief** for the rest of this command.
## Step 1 — Activate Plan Mode
Stay in research/read-only mode for the rest of this command. **Do not edit production code, do not run migrations, do not write code files outside `.kiro/specs/`.** Reading code, running `gh`, and creating files under `.kiro/specs/` are permitted.
## Step 2 — Run the Kiro spec flow
Invoke the Kiro slash commands installed by `cc-sdd` (in `.claude/commands/kiro/`). The expected sequence is:
1. **`/kiro:steering`** — only if `.kiro/steering/` is empty. Establishes product/tech/structure steering docs from the codebase. Skip if steering already exists.
2. **`/kiro:spec-init <task brief>`** — creates `.kiro/specs/<feature>/` with `spec.json` and `requirements.md` skeleton.
3. **`/kiro:spec-requirements`** — fills in requirements (EARS format).
4. **`/kiro:validate-gap`** — gap-analysis review of requirements before design (recommended in the project workflow).
5. **`/kiro:spec-design`** — produce the design document.
6. **`/kiro:validate-design`** — design-review gate.
7. **`/kiro:spec-tasks`** — break the design into tasks with parallel-work analysis.
After each Kiro command, **show the resulting artefact and stop for human approval** before moving to the next phase. The plan is not approved until the user explicitly says so.
## Step 3 — Persistence
CC-SDD stores everything under `.kiro/specs/<feature>/`. Do not duplicate plans elsewhere — that directory is the source of truth.
If a `.ticket/<n>.md` snapshot is associated with this work, link it from `spec.json` (or note the ticket number in `requirements.md`) so the trace from issue → spec is preserved.
## Step 4 — Implementation handoff
Implementation is **a separate, explicit step**:
- Use **`/kiro:spec-impl`** to execute tasks against the approved plan.
- Check progress against the plan **after every task** (the project's chosen checkpoint cadence).
- Use **`/kiro:validate-impl`** at the end to verify the implementation matches the spec.
- Use **`/kiro:spec-status`** at any time to see where the spec stands.
If the user asks to "just code it" without going through the spec, push back and remind them of the rule. Approval first, then code.
## Output expectation
Be terse. State which step you ran, what artefact it produced, and what the user needs to review. One short paragraph per phase, not a wall of text.

94
.claude/hooks/session_start.sh
View File

@ -1,33 +1,79 @@
#!/usr/bin/env bash
# SessionStart hook — print branch + working-tree status to give Claude
# (and the developer) immediate context at the start of a session.
# SessionStart hook — print branch + working-tree status + open Kiro
# specs / cached tickets so context is visible immediately at the start
# of a session.
set -euo pipefail
# Run only inside a git repo
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
exit 0
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
# --- Git branch + state -----------------------------------------------------
if git -C "$PROJECT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
branch="$(git -C "$PROJECT_DIR" symbolic-ref --short HEAD 2>/dev/null || echo 'detached')"
upstream="$(git -C "$PROJECT_DIR" rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || echo '')"
ahead_behind=""
if [ -n "$upstream" ]; then
counts="$(git -C "$PROJECT_DIR" rev-list --left-right --count "${upstream}...HEAD" 2>/dev/null || echo '0 0')"
behind="$(echo "$counts" | awk '{print $1}')"
ahead="$(echo "$counts" | awk '{print $2}')"
if [ "$ahead" != "0" ] || [ "$behind" != "0" ]; then
ahead_behind=" (ahead $ahead, behind $behind vs $upstream)"
fi
fi
dirty_count="$(git -C "$PROJECT_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
if [ "$dirty_count" = "0" ]; then
state="clean"
else
state="$dirty_count uncommitted change(s)"
fi
echo "📍 Branch: ${branch}${ahead_behind} — ${state}"
fi
branch="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'detached')"
upstream="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || echo '')"
# --- Active tickets ---------------------------------------------------------
shopt -s nullglob 2>/dev/null || true
tickets=("$PROJECT_DIR"/.ticket/*.md)
ticket_list=()
for f in "${tickets[@]}"; do
base="$(basename "$f")"
case "$base" in
repo.md|.gitkeep) continue ;;
*) ticket_list+=("${base%.md}") ;;
esac
done
if [ "${#ticket_list[@]}" -gt 0 ]; then
echo "🎫 Active tickets: ${ticket_list[*]} (use /ticket <n> to add more)"
fi
# Ahead / behind vs upstream
ahead_behind=""
if [ -n "$upstream" ]; then
counts="$(git rev-list --left-right --count "${upstream}...HEAD" 2>/dev/null || echo '0 0')"
behind="$(echo "$counts" | awk '{print $1}')"
ahead="$(echo "$counts" | awk '{print $2}')"
if [ "$ahead" != "0" ] || [ "$behind" != "0" ]; then
ahead_behind=" (ahead $ahead, behind $behind vs $upstream)"
# --- Active Kiro specs ------------------------------------------------------
if [ -d "$PROJECT_DIR/.kiro/specs" ]; then
spec_dirs=("$PROJECT_DIR"/.kiro/specs/*/)
spec_list=()
for d in "${spec_dirs[@]}"; do
[ -d "$d" ] || continue
name="$(basename "$d")"
# Try to read phase from spec.json if jq/python is available
phase=""
if [ -f "$d/spec.json" ] && command -v python3 >/dev/null 2>&1; then
phase="$(python3 -c "
import json, sys
try:
with open(sys.argv[1]) as f: d = json.load(f)
print(d.get('phase') or d.get('status') or '', end='')
except Exception:
pass
" "$d/spec.json" 2>/dev/null || true)"
fi
if [ -n "$phase" ]; then
spec_list+=("$name [$phase]")
else
spec_list+=("$name")
fi
done
if [ "${#spec_list[@]}" -gt 0 ]; then
echo "📘 Open specs: $(printf '%s, ' "${spec_list[@]}" | sed 's/, $//') (use /plan or /kiro:spec-status)"
fi
fi
# Working-tree status
dirty_count="$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
if [ "$dirty_count" = "0" ]; then
state="clean"
else
state="$dirty_count uncommitted change(s)"
fi
echo "📍 Branch: ${branch}${ahead_behind} — ${state}"
exit 0

73
.claude/onboarding/step4_workflow/01_tool_decision.md Normal file
View File

@ -0,0 +1,73 @@
# Step 4 — Planning Tool Decision
## Date: 2026-05-06
## Decisions
| Question | Choice |
|----------|--------|
| Q1 — Planning tool | **CC-SDD** (Claude Code Spec Driven Development, Kiro flow). Recommended in the Salestech onboarding doc and matches the project's expected `spec-init → spec-design → spec-tasks → spec-impl → spec-validate` workflow. |
| Q2 — Plan persistence | **In-tool** — `.kiro/specs/<feature>/`. CC-SDD owns this directory; no parallel `.claude/plans/` needed. |
| Q3 — Checkpoint cadence | **After every task** — strictest setting; matches the project rule "no code without an approved plan". |
## What CC-SDD installed
The user ran `npx cc-sdd@latest --claude --lang en` in the terminal.
The installer added:
- **`.kiro/settings/`** — rules and templates that drive the Kiro flow:
- `rules/` — design-discovery, EARS format, requirements/design review gates, gap analysis, steering principles, tasks generation, parallel-analysis.
- `templates/specs/` — `requirements.md`, `design.md`, `tasks.md`, `research.md`, `init.json`, `requirements-init.md`.
- `templates/steering/` — `product.md`, `tech.md`, `structure.md`.
- `templates/steering-custom/` — optional steering docs (api-standards, auth, db, deployment, error-handling, security, testing).
- **`.claude/commands/kiro/`** — slash commands invoked by the Kiro flow:
- `/kiro:steering`, `/kiro:steering-custom`
- `/kiro:spec-init`, `/kiro:spec-requirements`, `/kiro:spec-design`, `/kiro:spec-tasks`, `/kiro:spec-impl`, `/kiro:spec-status`
- `/kiro:validate-gap`, `/kiro:validate-design`, `/kiro:validate-impl`
Notes:
- The installer **did not append to `CLAUDE.md`** in this run, so no
refactor was needed afterwards. (Some CC-SDD versions append; this
one didn't.)
- `.kiro/` is **not** gitignored — specs and steering docs are project
artefacts that need to be shared with the team.
## Slash command added: `/plan`
Created `.claude/commands/plan.md`. Behaviour:
1. **Source description**: uses `$ARGUMENTS`, or falls back to a single
`.ticket/<n>.md` snapshot, or asks the user.
2. **Plan mode**: read-only research; no production-code edits.
3. **Kiro flow**:
`/kiro:steering` (only if `.kiro/steering/` is empty) →
`/kiro:spec-init` → `/kiro:spec-requirements` →
`/kiro:validate-gap` → `/kiro:spec-design` →
`/kiro:validate-design` → `/kiro:spec-tasks`.
**Stops for human approval after each artefact.**
4. **Persistence**: in `.kiro/specs/<feature>/`. Ticket linkage noted
in `spec.json` / `requirements.md`.
5. **Implementation handoff**: separate, explicit step using
`/kiro:spec-impl`, with `/kiro:validate-impl` at the end and
`/kiro:spec-status` for progress checks.
The command rejects "just code it" requests — approval-first is
enforced.
## SessionStart hook extended
`.claude/hooks/session_start.sh` now also prints:
- **Active tickets** — issue numbers cached under `.ticket/` (excludes
`repo.md`/`.gitkeep`).
- **Open specs** — directory names under `.kiro/specs/`, with phase /
status pulled from each `spec.json` if available.
The branch + working-tree-state line is preserved.
## Open follow-ups
- **Run `/kiro:steering`** in a new Claude session to seed `.kiro/steering/` with product/tech/structure context (recommended in brownfield setups). Out of scope for this onboarding pass — flagged for the developer.
- The Stop hook (quality gate around plans / tests / lint) is built in **Step 6**.
## Next
- Step 5: Agents & Skills (subagents, skills, rules from tech-stack).

93
.kiro/settings/rules/design-discovery-full.md Normal file
View File

@ -0,0 +1,93 @@
# Full Discovery Process for Technical Design
## Objective
Conduct comprehensive research and analysis to ensure the technical design is based on complete, accurate, and up-to-date information.
## Discovery Steps
### 1. Requirements Analysis
**Map Requirements to Technical Needs**
- Extract all functional requirements from EARS format
- Identify non-functional requirements (performance, security, scalability)
- Determine technical constraints and dependencies
- List core technical challenges
### 2. Existing Implementation Analysis
**Understand Current System** (if modifying/extending):
- Analyze codebase structure and architecture patterns
- Map reusable components, services, utilities
- Identify domain boundaries and data flows
- Document integration points and dependencies
- Determine approach: extend vs refactor vs wrap
### 3. Technology Research
**Investigate Best Practices and Solutions**:
- **Use WebSearch** to find:
- Latest architectural patterns for similar problems
- Industry best practices for the technology stack
- Recent updates or changes in relevant technologies
- Common pitfalls and solutions
- **Use WebFetch** to analyze:
- Official documentation for frameworks/libraries
- API references and usage examples
- Migration guides and breaking changes
- Performance benchmarks and comparisons
### 4. External Dependencies Investigation
**For Each External Service/Library**:
- Search for official documentation and GitHub repositories
- Verify API signatures and authentication methods
- Check version compatibility with existing stack
- Investigate rate limits and usage constraints
- Find community resources and known issues
- Document security considerations
- Note any gaps requiring implementation investigation
### 5. Architecture Pattern & Boundary Analysis
**Evaluate Architectural Options**:
- Compare relevant patterns (MVC, Clean, Hexagonal, Event-driven)
- Assess fit with existing architecture and steering principles
- Identify domain boundaries and ownership seams required to avoid team conflicts
- Consider scalability implications and operational concerns
- Evaluate maintainability and team expertise
- Document preferred pattern and rejected alternatives in `research.md`
### 6. Risk Assessment
**Identify Technical Risks**:
- Performance bottlenecks and scaling limits
- Security vulnerabilities and attack vectors
- Integration complexity and coupling
- Technical debt creation vs resolution
- Knowledge gaps and training needs
## Research Guidelines
### When to Search
**Always search for**:
- External API documentation and updates
- Security best practices for authentication/authorization
- Performance optimization techniques for identified bottlenecks
- Latest versions and migration paths for dependencies
**Search if uncertain about**:
- Architectural patterns for specific use cases
- Industry standards for data formats/protocols
- Compliance requirements (GDPR, HIPAA, etc.)
- Scalability approaches for expected load
### Search Strategy
1. Start with official sources (documentation, GitHub)
2. Check recent blog posts and articles (last 6 months)
3. Review Stack Overflow for common issues
4. Investigate similar open-source implementations
## Output Requirements
Capture all findings that impact design decisions in `research.md` using the shared template:
- Key insights affecting architecture, technology alignment, and contracts
- Constraints discovered during research
- Recommended approaches and selected architecture pattern with rationale
- Rejected alternatives and trade-offs (documented in the Design Decisions section)
- Updated domain boundaries that inform Components & Interface Contracts
- Risks and mitigation strategies
- Gaps requiring further investigation during implementation

49
.kiro/settings/rules/design-discovery-light.md Normal file
View File

@ -0,0 +1,49 @@
# Light Discovery Process for Extensions
## Objective
Quickly analyze existing system and integration requirements for feature extensions.
## Focused Discovery Steps
### 1. Extension Point Analysis
**Identify Integration Approach**:
- Locate existing extension points or interfaces
- Determine modification scope (files, components)
- Check for existing patterns to follow
- Identify backward compatibility requirements
### 2. Dependency Check
**Verify Compatibility**:
- Check version compatibility of new dependencies
- Validate API contracts haven't changed
- Ensure no breaking changes in pipeline
### 3. Quick Technology Verification
**For New Libraries Only**:
- Use WebSearch for official documentation
- Verify basic usage patterns
- Check for known compatibility issues
- Confirm licensing compatibility
- Record key findings in `research.md` (technology alignment section)
### 4. Integration Risk Assessment
**Quick Risk Check**:
- Impact on existing functionality
- Performance implications
- Security considerations
- Testing requirements
## When to Escalate to Full Discovery
Switch to full discovery if you find:
- Significant architectural changes needed
- Complex external service integrations
- Security-sensitive implementations
- Performance-critical components
- Unknown or poorly documented dependencies
## Output Requirements
- Clear integration approach (note boundary impacts in `research.md`)
- List of files/components to modify
- New dependencies with versions
- Integration risks and mitigations
- Testing focus areas

198
.kiro/settings/rules/design-principles.md Normal file
View File

@ -0,0 +1,198 @@
# Technical Design Rules and Principles
## Core Design Principles
### 0. Boundary First
- **Boundary is mandatory; owner is optional**
- A design is not ready when it explains components but leaves responsibility seams ambiguous
- Define what the spec owns before elaborating how it works
- Explicitly record what is out of boundary
- Do not leak downstream-specific behavior or assumptions into upstream boundaries
### 1. Type Safety is Mandatory
- **NEVER** use `any` type in TypeScript interfaces
- Define explicit types for all parameters and returns
- Use discriminated unions for error handling
- Specify generic constraints clearly
### 2. Design vs Implementation
- **Focus on WHAT, not HOW**
- Define interfaces and contracts, not code
- Specify behavior through pre/post conditions
- Document architectural decisions, not algorithms
### 3. Visual Communication
- **Simple features**: Basic component diagram or none
- **Medium complexity**: Architecture + data flow
- **High complexity**: Multiple diagrams (architecture, sequence, state)
- **Always pure Mermaid**: No styling, just structure
### 4. Component Design Rules
- **Single Responsibility**: One clear purpose per component
- **Clear Boundaries**: Explicit domain ownership
- **Boundary Commitments First**: Before detailing components, state the responsibility boundary this design commits to
- **Dependency Direction**: Follow architectural layers
- **Interface Segregation**: Minimal, focused interfaces
- **Team-safe Interfaces**: Design boundaries that allow parallel implementation without merge conflicts
- **No Hidden Shared Ownership**: If two areas appear to co-own the same behavior or data, the design is incomplete
- **Research Traceability**: Record boundary decisions and rationale in `research.md`
### 5. Data Modeling Standards
- **Domain First**: Start with business concepts
- **Consistency Boundaries**: Clear aggregate roots
- **Normalization**: Balance between performance and integrity
- **Evolution**: Plan for schema changes
### 6. Error Handling Philosophy
- **Fail Fast**: Validate early and clearly
- **Graceful Degradation**: Partial functionality over complete failure
- **User Context**: Actionable error messages
- **Observability**: Comprehensive logging and monitoring
### 7. Integration Patterns
- **Loose Coupling**: Minimize dependencies
- **Contract First**: Define interfaces before implementation
- **Versioning**: Plan for API evolution
- **Idempotency**: Design for retry safety
- **Contract Visibility**: Surface API and event contracts in design.md while linking extended details from `research.md`
### 8. Dependency Direction
- **Define and enforce the dependency direction** in the architecture section of design.md (e.g., Types → Config → Repository → Service → Runtime → UI)
- Each layer imports only from layers to its left — never upward
- This constraint is not a suggestion; implementation and review should treat violations as errors
- When the File Structure Plan maps files to components, the dependency direction determines which imports are allowed
## Documentation Standards
### Language and Tone
- **Declarative**: "The system authenticates users" not "The system should authenticate"
- **Precise**: Specific technical terms over vague descriptions
- **Concise**: Essential information only
- **Formal**: Professional technical writing
### Structure Requirements
- **Hierarchical**: Clear section organization
- **Traceable**: Requirements to components mapping
- **Complete**: All aspects covered for implementation
- **Consistent**: Uniform terminology throughout
- **Focused**: Keep design.md centered on architecture and contracts; move investigation logs and lengthy comparisons to `research.md`
## Section Authoring Guidance
### Global Ordering
- Default flow: Overview → Goals/Non-Goals → Boundary Commitments → Architecture → File Structure Plan → Components & Interfaces → Optional sections.
- Teams may swap Traceability earlier or place Data Models nearer Architecture when it improves clarity, but keep section headings intact.
- Within each section, follow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
### Requirement IDs
- Reference requirements as `2.1, 2.3` without prefixes (no “Requirement 2.1”).
- All requirements MUST have numeric IDs. If a requirement lacks a numeric ID, stop and fix `requirements.md` before continuing.
- Use `N.M`-style numeric IDs where `N` is the top-level requirement number from requirements.md (for example, Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2).
- Every component, task, and traceability row must reference the same canonical numeric ID.
### Technology Stack
- Include ONLY layers impacted by this feature (frontend, backend, data, messaging, infra).
- For each layer specify tool/library + version + the role it plays; push extended rationale, comparisons, or benchmarks to `research.md`.
- When extending an existing system, highlight deviations from the current stack and list new dependencies.
### System Flows
- Add diagrams only when they clarify behavior:
- **Sequence** for multi-step interactions
- **Process/State** for branching rules or lifecycle
- **Data/Event** for pipelines or async patterns
- Always use pure Mermaid. If no complex flow exists, omit the entire section.
### Requirements Traceability
- Use the standard table (`Requirement | Summary | Components | Interfaces | Flows`) to prove coverage.
- Collapse to bullet form only when a single requirement maps 1:1 to a component.
- Prefer the component summary table for simple mappings; reserve the full traceability table for complex or compliance-sensitive requirements.
- Re-run this mapping whenever requirements or components change to avoid drift.
### Components & Interfaces Authoring
- Boundary Commitments should already make the ownership seam explicit before this section begins.
- Group components by domain/layer and provide one block per component.
- Begin with a summary table listing Component, Domain, Intent, Requirement coverage, key dependencies, and selected contracts.
- Table fields: Intent (one line), Requirements (`2.1, 2.3`), Owner/Reviewers (optional).
- Dependencies table must mark each entry as Inbound/Outbound/External and assign Criticality (`P0` blocking, `P1` high-risk, `P2` informational).
- Summaries of external dependency research stay here; detailed investigation (API signatures, rate limits, migration notes) belongs in `research.md`.
- design.md must remain a self-contained reviewer artifact. Reference `research.md` only for background, and restate any conclusions or decisions here.
- Contracts: tick only the relevant types (Service/API/Event/Batch/State). Unchecked types should not appear later in the component section.
- Service interfaces must declare method signatures, inputs/outputs, and error envelopes. API/Event/Batch contracts require schema tables or bullet lists covering trigger, payload, delivery, idempotency.
- Use **Integration & Migration Notes**, **Validation Hooks**, and **Open Questions / Risks** to document rollout strategy, observability, and unresolved decisions.
- Detail density rules:
- **Full block**: components introducing new boundaries (logic hooks, shared services, external integrations, data layers).
- **Summary-only**: presentational/UI components with no new boundaries (plus a short Implementation Note if needed).
- Implementation Notes must combine Integration / Validation / Risks into a single bulleted subsection to reduce repetition.
- Prefer lists or inline descriptors for short data (dependencies, contract selections). Use tables only when comparing multiple items.
### Shared Interfaces & Props
- Define a base interface (e.g., `BaseUIPanelProps`) for recurring UI components and extend it per component to capture only the deltas.
- Hooks, utilities, and integration adapters that introduce new contracts should still include full TypeScript signatures.
- When reusing a base contract, reference it explicitly (e.g., “Extends `BaseUIPanelProps` with `onSubmitAnswer` callback”) instead of duplicating the code block.
### Data Models
- Domain Model covers aggregates, entities, value objects, domain events, and invariants. Add Mermaid diagrams only when relationships are non-trivial.
- Logical Data Model should articulate structure, indexing, sharding, and storage-specific considerations (event store, KV/wide-column) relevant to the change.
- Data Contracts & Integration section documents API payloads, event schemas, and cross-service synchronization patterns when the feature crosses boundaries.
- Lengthy type definitions or vendor-specific option objects should be placed in the Supporting References section within design.md, linked from the relevant section. Investigation notes stay in `research.md`.
- Supporting References usage is optional; only create it when keeping the content in the main body would reduce readability. All decisions must still appear in the main sections so design.md stands alone.
### Error/Testing/Security/Performance Sections
- Record only feature-specific decisions or deviations. Link or reference organization-wide standards (steering) for baseline practices instead of restating them.
### Diagram & Text Deduplication
- Do not restate diagram content verbatim in prose. Use the text to highlight key decisions, trade-offs, or impacts that are not obvious from the visual.
- When a decision is fully captured in the diagram annotations, a short “Key Decisions” bullet is sufficient.
### General Deduplication
- Avoid repeating the same information across Overview, Architecture, and Components. Reference earlier sections when context is identical.
- If a requirement/component relationship is captured in the summary table, do not rewrite it elsewhere unless extra nuance is added.
## Diagram Guidelines
### When to include a diagram
- **Architecture**: Use a structural diagram when 3+ components or external systems interact.
- **Sequence**: Draw a sequence diagram when calls/handshakes span multiple steps.
- **State / Flow**: Capture complex state machines or business flows in a dedicated diagram.
- **ER**: Provide an entity-relationship diagram for non-trivial data models.
- **Skip**: Minor one-component changes generally do not need diagrams.
### Mermaid requirements
```mermaid
graph TB
Client --> ApiGateway
ApiGateway --> ServiceA
ApiGateway --> ServiceB
ServiceA --> Database
```
- **Plain Mermaid only** – avoid custom styling or unsupported syntax.
- **Node IDs** – alphanumeric plus underscores only (e.g., `Client`, `ServiceA`). Do not use `@`, `/`, or leading `-`.
- **Labels** – simple words. Do not embed parentheses `()`, square brackets `[]`, quotes `"`, or slashes `/`.
- ❌ `DnD[@dnd-kit/core]` → invalid ID (`@`).
- ❌ `UI[KanbanBoard(React)]` → invalid label (`()`).
- ✅ `DndKit[dnd-kit core]` → use plain text in labels, keep technology details in the accompanying description.
- ℹ️ Mermaid strict-mode will otherwise fail with errors like `Expecting 'SQE' ... got 'PS'`; remove punctuation from labels before rendering.
- **Edges** – show data or control flow direction.
- **Groups** – using Mermaid subgraphs to cluster related components is allowed; use it sparingly for clarity.
## Quality Metrics
### Design Completeness Checklist
- All requirements addressed
- No implementation details leaked
- Clear component boundaries
- Explicit error handling
- Comprehensive test strategy
- Security considered
- Performance targets defined
- Migration path clear (if applicable)
### Common Anti-patterns to Avoid
❌ Mixing design with implementation
❌ Vague interface definitions
❌ Missing error scenarios
❌ Ignored non-functional requirements
❌ Overcomplicated architectures
❌ Tight coupling between components
❌ Missing data consistency strategy
❌ Incomplete dependency analysis

50
.kiro/settings/rules/design-review-gate.md Normal file
View File

@ -0,0 +1,50 @@
# Design Review Gate
Before writing `design.md`, review the draft design and repair local issues until the design passes or a true spec gap is discovered.
## Requirements Coverage Review
- Every numeric requirement ID from `requirements.md` must appear in the design traceability mapping and be backed by one or more concrete components, contracts, flows, data models, or operational decisions.
- Every requirement that introduces an external dependency, integration point, runtime prerequisite, migration concern, observability need, security constraint, or performance target must be reflected explicitly in `design.md`.
- If coverage is missing because the design draft is incomplete, repair the draft and review again.
- If coverage cannot be completed cleanly because requirements are ambiguous, contradictory, or underspecified, stop and return to the requirements phase instead of inventing design detail.
## Architecture Readiness Review
- Component boundaries must be explicit enough that implementation tasks can be assigned without guessing ownership.
- Interfaces, contracts, state transitions, and integration boundaries must be concrete enough for implementation and validation.
- Build-vs-adopt decisions that materially affect architecture must be captured in `design.md`, with deeper investigation left in `research.md` when present.
- Runtime prerequisites, migrations, rollout constraints, validation hooks, and failure modes must be surfaced when they materially affect implementation order or risk.
## Boundary Readiness Review
- The design must explicitly state what this spec owns.
- The design must explicitly state what is out of boundary.
- Allowed dependencies must be concrete enough that reviewers can detect boundary violations later.
- If data, behavior, or integration responsibility appears shared across multiple areas without a clear seam, stop and repair the design.
- If downstream assumptions are embedded in upstream components "for convenience," stop and repair the design.
- If the boundary cannot be explained in a few direct bullets, it is probably still too vague for task generation.
- If the design reveals multiple independent responsibility seams that could move separately, stop and split the spec or return to roadmap discovery instead of forcing them into one spec.
## Executability Review
- The design must be implementable as a sequence of bounded tasks without hidden prerequisites.
- Parallel-safe boundaries should be visible where the architecture intends concurrent implementation.
- Avoid speculative abstraction: remove components, adapters, or interfaces that exist only for hypothetical future scope.
- If a section is too vague for tasks to reference directly, rewrite it before finalizing the design.
## Mechanical Checks
Before applying judgment, verify these mechanically:
- **Requirements traceability**: Extract all numeric requirement IDs from `requirements.md`. Scan the design draft for each ID. Report any IDs not found in the design.
- **Boundary section populated**: `Boundary Commitments`, `Out of Boundary`, `Allowed Dependencies`, and `Revalidation Triggers` must not be empty or placeholder-only.
- **File Structure Plan populated**: The File Structure Plan section must contain concrete file paths (not just "TBD" or empty). Scan for placeholder text in that section.
- **Boundary ↔ file structure alignment**: The File Structure Plan must reflect the stated responsibility boundary. If files imply broader ownership than the boundary section claims, report a mismatch.
- **No orphan components**: Every component mentioned in the design must appear in the File Structure Plan with a file path. Scan for component names that have no corresponding file entry.
## Review Loop
- Run mechanical checks first, then judgment-based review.
- If issues are local to the draft, repair the draft and re-run the review gate.
- Keep the loop bounded: no more than 2 review-and-repair passes before escalating a real spec gap.
- Write `design.md` only after the review gate passes.

110
.kiro/settings/rules/design-review.md Normal file
View File

@ -0,0 +1,110 @@
# Design Review Process
## Objective
Conduct interactive quality review of technical design documents to ensure they are solid enough to proceed to implementation with acceptable risk.
## Review Philosophy
- **Quality assurance, not perfection seeking**
- **Critical focus**: Limit to 3 most important concerns
- **Interactive dialogue**: Engage with designer, not one-way evaluation
- **Balanced assessment**: Recognize strengths and weaknesses
- **Clear decision**: Definitive GO/NO-GO with rationale
## Scope & Non-Goals
- Scope: Evaluate the quality of the design document against project context and standards to decide GO/NO-GO.
- Non-Goals: Do not perform implementation-level design, deep technology research, or finalize technology choices. Defer such items to the design phase iteration.
## Core Review Criteria
### 1. Existing Architecture Alignment (Critical)
- Integration with existing system boundaries and layers
- Consistency with established architectural patterns
- Proper dependency direction and coupling management
- Alignment with current module organization
### 2. Design Consistency & Standards
- Adherence to project naming conventions and code standards
- Consistent error handling and logging strategies
- Uniform configuration and dependency management
- Alignment with established data modeling patterns
### 3. Extensibility & Maintainability
- Design flexibility for future requirements
- Clear separation of concerns and single responsibility
- Testability and debugging considerations
- Appropriate complexity for requirements
### 4. Type Safety & Interface Design
- Proper type definitions and interface contracts
- Avoidance of unsafe patterns (e.g., `any` in TypeScript)
- Clear API boundaries and data structures
- Input validation and error handling coverage
## Review Process
### Step 1: Analyze
Analyze design against all review criteria, focusing on critical issues impacting integration, maintainability, complexity, and requirements fulfillment.
### Step 2: Identify Critical Issues (≤3)
For each issue:
```
🔴 **Critical Issue [1-3]**: [Brief title]
**Concern**: [Specific problem]
**Impact**: [Why it matters]
**Suggestion**: [Concrete improvement]
**Traceability**: [Requirement ID/section from requirements.md]
**Evidence**: [Design doc section/heading]
```
### Step 3: Recognize Strengths
Acknowledge 1-2 strong aspects to maintain balanced feedback.
### Step 4: Decide GO/NO-GO
- **GO**: No critical architectural misalignment, requirements addressed, clear implementation path, acceptable risks
- **NO-GO**: Fundamental conflicts, critical gaps, high failure risk, disproportionate complexity
## Traceability & Evidence
- Link each critical issue to the relevant requirement(s) from `requirements.md` (ID or section).
- Cite evidence locations in the design document (section/heading, diagram, or artifact) to support the assessment.
- When applicable, reference constraints from steering context to justify the issue.
## Output Format
### Design Review Summary
2-3 sentences on overall quality and readiness.
### Critical Issues (≤3)
For each: Issue, Impact, Recommendation, Traceability (e.g., 1.1, 1.2), Evidence (design.md section).
### Design Strengths
1-2 positive aspects.
### Final Assessment
Decision (GO/NO-GO), Rationale (1-2 sentences), Next Steps.
### Interactive Discussion
Engage on designer's perspective, alternatives, clarifications, and necessary changes.
## Length & Focus
- Summary: 2–3 sentences
- Each critical issue: 5–7 lines total (including Issue/Impact/Recommendation/Traceability/Evidence)
- Overall review: keep concise (~400 words guideline)
## Review Guidelines
1. **Critical Focus**: Only flag issues that significantly impact success
2. **Constructive Tone**: Provide solutions, not just criticism
3. **Interactive Approach**: Engage in dialogue rather than one-way evaluation
4. **Balanced Assessment**: Recognize both strengths and weaknesses
5. **Clear Decision**: Make definitive GO/NO-GO recommendation
6. **Actionable Feedback**: Ensure all suggestions are implementable
## Final Checklist
- **Critical Issues ≤ 3** and each includes Impact and Recommendation
- **Traceability**: Each issue references requirement ID/section
- **Evidence**: Each issue cites design doc location
- **Decision**: GO/NO-GO with clear rationale and next steps

29
.kiro/settings/rules/design-synthesis.md Normal file
View File

@ -0,0 +1,29 @@
# Design Synthesis
After discovery and before writing the design document, apply these three lenses to the collected findings. This step requires the full picture — do not parallelize.
## 1. Generalization
Look across all requirements as a group. Identify cases where multiple requirements are variations of the same underlying problem.
- If feature A is a special case of a more general capability X, design X with an interface that naturally supports A (and potentially B, C later)
- Keep the implementation scope to what the current requirements demand — generalize the interface, not the implementation
- Record identified generalizations in `research.md` under Design Decisions
## 2. Build vs. Adopt
For each major component in the emerging design, ask: is this problem already solved?
- Search for established standards (RFCs, protocols), battle-tested libraries, or platform-native capabilities that address the requirement
- Prefer adopting existing solutions over building custom ones when they fit the requirements without significant adaptation
- If adopting: verify the solution is actively maintained, compatible with the project's stack (check steering), and meets non-functional requirements
- If building: document why existing solutions were rejected (capture in `research.md`)
## 3. Simplification
For each component and abstraction layer in the emerging design, ask: is this necessary?
- Remove components that exist "just in case" or for hypothetical future requirements not in the current spec
- Flatten unnecessary abstraction layers — if an interface has only one implementation with no foreseeable second, it may not need the indirection
- Prefer fewer, cohesive components over many fine-grained ones
- The right design is the smallest one that satisfies all requirements and remains extensible at the interface level

49
.kiro/settings/rules/ears-format.md Normal file
View File

@ -0,0 +1,49 @@
# EARS Format Guidelines
## Overview
EARS (Easy Approach to Requirements Syntax) is the standard format for acceptance criteria in spec-driven development.
EARS patterns describe the logical structure of a requirement (condition + subject + response) and are not tied to any particular natural language.
All acceptance criteria should be written in the target language configured for the specification (for example, `spec.json.language` / `en`).
Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`) and localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`) into the target language. Do not interleave target-language text inside the trigger or fixed English phrases themselves.
## Primary EARS Patterns
### 1. Event-Driven Requirements
- **Pattern**: When [event], the [system] shall [response/action]
- **Use Case**: Responses to specific events or triggers
- **Example**: When user clicks checkout button, the Checkout Service shall validate cart contents
### 2. State-Driven Requirements
- **Pattern**: While [precondition], the [system] shall [response/action]
- **Use Case**: Behavior dependent on system state or preconditions
- **Example**: While payment is processing, the Checkout Service shall display loading indicator
### 3. Unwanted Behavior Requirements
- **Pattern**: If [trigger], the [system] shall [response/action]
- **Use Case**: System response to errors, failures, or undesired situations
- **Example**: If invalid credit card number is entered, then the website shall display error message
### 4. Optional Feature Requirements
- **Pattern**: Where [feature is included], the [system] shall [response/action]
- **Use Case**: Requirements for optional or conditional features
- **Example**: Where the car has a sunroof, the car shall have a sunroof control panel
### 5. Ubiquitous Requirements
- **Pattern**: The [system] shall [response/action]
- **Use Case**: Always-active requirements and fundamental system properties
- **Example**: The mobile phone shall have a mass of less than 100 grams
## Combined Patterns
- While [precondition], when [event], the [system] shall [response/action]
- When [event] and [additional condition], the [system] shall [response/action]
## Subject Selection Guidelines
- **Software Projects**: Use concrete system/service name (e.g., "Checkout Service", "User Auth Module")
- **Process/Workflow**: Use responsible team/role (e.g., "Support Team", "Review Process")
- **Non-Software**: Use appropriate subject (e.g., "Marketing Campaign", "Documentation")
## Quality Criteria
- Requirements must be testable, verifiable, and describe a single behavior.
- Use objective language: "shall" for mandatory behavior, "should" for recommendations; avoid ambiguous terms.
- Follow EARS syntax: [condition], the [system] shall [response/action].

144
.kiro/settings/rules/gap-analysis.md Normal file
View File

@ -0,0 +1,144 @@
# Gap Analysis Process
## Objective
Analyze the gap between requirements and existing codebase to inform implementation strategy decisions.
## Analysis Framework
### 1. Current State Investigation
- Scan for domain-related assets:
- Key files/modules and directory layout
- Reusable components/services/utilities
- Dominant architecture patterns and constraints
- Extract conventions:
- Naming, layering, dependency direction
- Import/export patterns and dependency hotspots
- Testing placement and approach
- Note integration surfaces:
- Data models/schemas, API clients, auth mechanisms
### 2. Requirements Feasibility Analysis
- From EARS requirements, list technical needs:
- Data models, APIs/services, UI/components
- Business rules/validation
- Non-functionals: security, performance, scalability, reliability
- Identify gaps and constraints:
- Missing capabilities in current codebase
- Unknowns to be researched later (mark as "Research Needed")
- Constraints from existing architecture and patterns
- Note complexity signals:
- Simple CRUD / algorithmic logic / workflows / external integrations
### 3. Implementation Approach Options
#### Option A: Extend Existing Components
**When to consider**: Feature fits naturally into existing structure
- **Which files/modules to extend**:
- Identify specific files requiring changes
- Assess impact on existing functionality
- Evaluate backward compatibility concerns
- **Compatibility assessment**:
- Check if extension respects existing interfaces
- Verify no breaking changes to consumers
- Assess test coverage impact
- **Complexity and maintainability**:
- Evaluate cognitive load of additional functionality
- Check if single responsibility principle is maintained
- Assess if file size remains manageable
**Trade-offs**:
- ✅ Minimal new files, faster initial development
- ✅ Leverages existing patterns and infrastructure
- ❌ Risk of bloating existing components
- ❌ May complicate existing logic
#### Option B: Create New Components
**When to consider**: Feature has distinct responsibility or existing components are already complex
- **Rationale for new creation**:
- Clear separation of concerns justifies new file
- Existing components are already complex
- Feature has distinct lifecycle or dependencies
- **Integration points**:
- How new components connect to existing system
- APIs or interfaces exposed
- Dependencies on existing components
- **Responsibility boundaries**:
- Clear definition of what new component owns
- Interfaces with existing components
- Data flow and control flow
**Trade-offs**:
- ✅ Clean separation of concerns
- ✅ Easier to test in isolation
- ✅ Reduces complexity in existing components
- ❌ More files to navigate
- ❌ Requires careful interface design
#### Option C: Hybrid Approach
**When to consider**: Complex features requiring both extension and new creation
- **Combination strategy**:
- Which parts extend existing components
- Which parts warrant new components
- How they interact
- **Phased implementation**:
- Initial phase: minimal viable changes
- Subsequent phases: refactoring or new components
- Migration strategy if needed
- **Risk mitigation**:
- Incremental rollout approach
- Feature flags or configuration
- Rollback strategy
**Trade-offs**:
- ✅ Balanced approach for complex features
- ✅ Allows iterative refinement
- ❌ More complex planning required
- ❌ Potential for inconsistency if not well-coordinated
### 4. Out-of-Scope for Gap Analysis
- Defer deep research activities to the design phase.
- Record unknowns as concise "Research Needed" items only.
### 5. Implementation Complexity & Risk
- Effort:
- S (1–3 days): existing patterns, minimal deps, straightforward integration
- M (3–7 days): some new patterns/integrations, moderate complexity
- L (1–2 weeks): significant functionality, multiple integrations or workflows
- XL (2+ weeks): architectural changes, unfamiliar tech, broad impact
- Risk:
- High: unknown tech, complex integrations, architectural shifts, unclear perf/security path
- Medium: new patterns with guidance, manageable integrations, known perf solutions
- Low: extend established patterns, familiar tech, clear scope, minimal integration
### Output Checklist
- Requirement-to-Asset Map with gaps tagged (Missing / Unknown / Constraint)
- Options A/B/C with short rationale and trade-offs
- Effort (S/M/L/XL) and Risk (High/Medium/Low) with one-line justification each
- Recommendations for design phase:
- Preferred approach and key decisions
- Research items to carry forward
## Principles
- **Information over decisions**: Provide analysis and options, not final choices
- **Multiple viable options**: Offer credible alternatives when applicable
- **Explicit gaps and assumptions**: Flag unknowns and constraints clearly
- **Context-aware**: Align with existing patterns and architecture limits
- **Transparent effort and risk**: Justify labels succinctly

51
.kiro/settings/rules/requirements-review-gate.md Normal file
View File

@ -0,0 +1,51 @@
# Requirements Review Gate
Before writing `requirements.md`, review the draft requirements and repair local issues until the draft passes or a true scope ambiguity is discovered.
## Boundary Continuity
Use boundary terminology consistently across phases without turning requirements into design:
- **Discovery** identifies `Boundary Candidates`
- **Requirements** make inclusion, exclusion, and adjacent expectations explicit when scope could be misread
- **Design** turns those into `Boundary Commitments`
- **Tasks** use `_Boundary:_` to constrain executable work
Requirements should clarify the feature boundary in user- or operator-observable terms, not in architecture ownership or implementation detail.
## Scope and Coverage Review
- The draft must cover the feature's core user journeys, major scope boundaries, primary error cases, and meaningful edge conditions that are visible to the user or operator.
- If the feature touches adjacent systems, specs, or workflows, the draft must make clear what this feature expects from them and what it does not own when that distinction affects user-visible behavior or operator expectations.
- Business/domain rules, compliance constraints, security/privacy expectations, and operational constraints that materially shape user-visible behavior must be reflected explicitly when they are in scope.
- If coverage is missing because the draft is incomplete, repair the draft and review again.
- If coverage cannot be completed cleanly because the project description or steering context is ambiguous, contradictory, or underspecified, stop and ask the user to clarify instead of guessing.
## EARS and Testability Review
- Every acceptance criterion must follow the EARS rules defined in `ears-format.md`.
- Every requirement must be testable, observable, and specific enough that later design and validation can verify it.
- Remove implementation details that belong in `design.md` rather than `requirements.md`.
- Requirement headings must use numeric IDs only; do not mix numeric and alphabetic labels.
## Structure and Quality Review
- Group related behaviors into coherent requirement areas without duplicating the same obligation across multiple sections.
- Make inclusion/exclusion boundaries explicit when the feature scope could otherwise be misread.
- Keep boundary statements lightweight and observable: describe feature responsibility and adjacent expectations without prescribing components, layers, or internal ownership.
- Ensure non-functional expectations remain user-observable or operator-observable; move technology choices and internal architecture detail out of requirements.
- Normalize vague language such as "fast", "robust", or "secure" into concrete user-visible expectations whenever the source material supports it.
## Mechanical Checks
Before applying judgment, verify these mechanically:
- **Numeric IDs present**: Every requirement heading has a numeric ID (1, 1.1, 2, etc.). Scan the draft for headings without IDs.
- **Acceptance criteria exist**: Every requirement has at least one EARS-format acceptance criterion. Scan for requirements with no "When/If/While/Where" acceptance statements.
- **No implementation language**: Scan for technology-specific terms (database names, framework names, API patterns) that belong in design, not requirements. Flag any found.
## Review Loop
- Run mechanical checks first, then judgment-based review.
- If issues are local to the draft, repair the draft and re-run the review gate.
- Keep the loop bounded: no more than 2 review-and-repair passes before escalating a real ambiguity back to the user.
- Write `requirements.md` only after the review gate passes.

90
.kiro/settings/rules/steering-principles.md Normal file
View File

@ -0,0 +1,90 @@
# Steering Principles
Steering files are **project memory**, not exhaustive specifications.
---
## Content Granularity
### Golden Rule
> "If new code follows existing patterns, steering shouldn't need updating."
### ✅ Document
- Organizational patterns (feature-first, layered)
- Naming conventions (PascalCase rules)
- Import strategies (absolute vs relative)
- Architectural decisions (state management)
- Technology standards (key frameworks)
### ❌ Avoid
- Complete file listings
- Every component description
- All dependencies
- Implementation details
- Agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
- Detailed documentation of `.kiro/` metadata directories (settings, automation)
### Example Comparison
**Bad** (Specification-like):
```markdown
- /components/Button.tsx - Primary button with variants
- /components/Input.tsx - Text input with validation
- /components/Modal.tsx - Modal dialog
... (50+ files)
```
**Good** (Project Memory):
```markdown
## UI Components (`/components/ui/`)
Reusable, design-system aligned primitives
- Named by function (Button, Input, Modal)
- Export component + TypeScript interface
- No business logic
```
---
## Security
Never include:
- API keys, passwords, credentials
- Database URLs, internal IPs
- Secrets or sensitive data
---
## Quality Standards
- **Single domain**: One topic per file
- **Concrete examples**: Show patterns with code
- **Explain rationale**: Why decisions were made
- **Maintainable size**: 100-200 lines typical
---
## Preservation (when updating)
- Preserve user sections and custom examples
- Additive by default (add, don't replace)
- Add `updated_at` timestamp
- Note why changes were made
---
## Notes
- Templates are starting points, customize as needed
- Follow same granularity principles as core steering
- All steering files loaded as project memory
- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories
- Custom files equally important as core files
---
## File-Specific Focus
- **product.md**: Purpose, value, business context (not exhaustive features)
- **tech.md**: Key frameworks, standards, conventions (not all dependencies)
- **structure.md**: Organization patterns, naming rules (not directory trees)
- **Custom files**: Specialized patterns (API, testing, security, etc.)

222
.kiro/settings/rules/tasks-generation.md Normal file
View File

@ -0,0 +1,222 @@
# Task Generation Rules
## Core Principles
### 1. Natural Language Descriptions
Focus on capabilities and outcomes, not code structure.
**Describe**:
- What functionality to achieve
- Business logic and behavior
- Features and capabilities
- Domain language and concepts
- Data relationships and workflows
**Avoid**:
- File paths and directory structure
- Function/method names and signatures
- Type definitions and interfaces
- Class names and API contracts
- Specific data structures
**Rationale**: Implementation details (files, methods, types) are defined in design.md. Tasks describe the functional work to be done.
### 2. Task Ordering Principle
**Order implies dependency**: Task N implicitly depends on all tasks before it. This is the primary dependency mechanism.
**Tasks must follow this phase order**:
1. **Foundation**: Environment setup, test infrastructure, shared utilities, database schema, configuration
2. **Core**: Primary feature implementation (parallel-capable tasks grouped here)
3. **Integration**: Wiring components together, cross-boundary connections
4. **Validation**: E2E tests, edge cases, regression checks
**Rationale**: Foundation work unblocks everything else. Placing setup tasks early prevents downstream blocking. Core tasks can often run in parallel because foundation is already complete.
### 3. Task Integration & Progression
**Every task must**:
- Build on previous outputs (no orphaned code)
- Connect to the overall system (no hanging features)
- Progress incrementally (no big jumps in complexity)
- Respect architecture boundaries defined in design.md (Architecture Pattern & Boundary Map)
- Honor interface contracts documented in design.md
- Use major task summaries sparingly—omit detail bullets if the work is fully captured by child tasks.
**End with integration tasks** to wire everything together.
### 4. Dependency Declaration
**Default**: Sequential ordering handles most dependencies (task N depends on tasks before it).
**Explicit declaration required when**:
- A task depends on a specific task in a different major-task group (cross-boundary)
- The dependency is non-obvious from ordering alone
- A task can skip ahead of its position (declared via `(P)`) but still needs specific prior work
**Format**: `_Depends: 1.2, 2.3_` — placed alongside `_Requirements:_` in task detail sections.
**Do not over-annotate**: If a task simply depends on the task directly before it, ordering alone is sufficient.
### 5. Boundary Scope
**Each task should declare its component boundary** using design.md component/module names:
- `_Boundary: AuthService_` or `_Boundary: API Layer, UserRepository_`
- Helps validate parallel safety: tasks with non-overlapping boundaries are parallel candidates
- Helps agents understand scope: what to touch and what not to touch
**When to use**: Required for tasks marked `(P)` to validate parallel safety. Omit for sequential tasks where scope is obvious from the description.
**Boundary rule**:
- Each executable task should stay within a single responsibility boundary
- If work must cross boundaries, make it an explicit integration task rather than a normal implementation task
- Do not hide cross-boundary coordination inside a task that appears local
### 6. Flexible Task Sizing
**Guidelines**:
- **Major tasks**: As many sub-tasks as logically needed (group by cohesion)
- **Sub-tasks**: 1-3 hours each, 3-10 details per sub-task
- Balance between too granular and too broad
**Don't force arbitrary numbers** - let logical grouping determine structure.
### 7. Requirements Mapping
**End each task detail section with**:
- `_Requirements: X.X, Y.Y_` listing **only numeric requirement IDs** (comma-separated). Never append descriptive text, parentheses, translations, or free-form labels.
- For cross-cutting requirements, list every relevant requirement ID. All requirements MUST have numeric IDs in requirements.md. If an ID is missing, stop and correct requirements.md before generating tasks.
- Reference components/interfaces from design.md when helpful (e.g., `_Contracts: AuthService API`)
### 7.5 Observable Completion
**Each executable task must include at least one detail bullet that describes the observable completed state**:
- Phrase it as a deliverable, runtime behavior, persisted state, UI state, endpoint behavior, test result, or integration outcome
- Avoid vague bullets like "implement support", "wire things up", or "handle logic" unless paired with a concrete observable result
- Prefer making one detail bullet clearly answer: "What will be true when this task is done?"
- Keep this within the existing task body; do not add extra bookkeeping fields
### 8. Code-Only Focus
**Include ONLY**:
- Coding tasks (implementation)
- Testing tasks (unit, integration, E2E)
- Technical setup tasks (infrastructure, configuration)
**Exclude**:
- Deployment tasks
- Documentation tasks
- User testing
- Marketing/business activities
## Task Plan Review Gate
Before writing `tasks.md`, review the draft task plan and repair local issues until the plan passes or a true spec gap is discovered.
### Coverage Review
- Every requirement ID from `requirements.md` must appear in at least one task.
- Every design component, interface/contract, integration point, runtime prerequisite, and validation concern from `design.md` must be represented by at least one task.
- If coverage is missing because the task plan is incomplete, repair the draft tasks and review again.
- If coverage cannot be added cleanly because requirements or design are ambiguous, contradictory, or underspecified, stop and return to the requirements/design phase instead of papering over the gap in `tasks.md`.
### Executability Review
- Every sub-task must be executable as written, usually within 1-3 hours.
- Every sub-task must produce a verifiable deliverable (behavior, artifact, endpoint, UI state, config, migration, test, or integration result).
- Every executable sub-task must include at least one detail bullet that states the observable completion condition.
- Split tasks that combine multiple independently verifiable outcomes.
- Split tasks that combine multiple responsibility boundaries unless they are explicit integration tasks.
- If many tasks require broad `_Boundary:_` scopes or repeated cross-boundary coordination, stop and return to design or roadmap decomposition instead of forcing the spec through task generation.
- Merge or collapse tasks that are too small, bookkeeping-only, or not meaningful execution units.
- Make implicit prerequisites explicit as preceding tasks.
- Re-check `_Depends:_`, `_Boundary:_`, and `(P)` markers after edits so concurrency claims still match the design boundaries and dependency graph.
### Review Loop
- Run the review gate on the draft task plan before writing `tasks.md`.
- If issues are task-plan-local, repair the draft and re-run the review gate.
- Keep the loop bounded: no more than 2 review-and-repair passes before escalating a real spec gap.
- Write `tasks.md` only after the review gate passes.
### Optional Test Coverage Tasks
- When the design already guarantees functional coverage and rapid MVP delivery is prioritized, mark purely test-oriented follow-up work (e.g., baseline rendering/unit tests) as **optional** using the `- [ ]*` checkbox form.
- Only apply the optional marker when the sub-task directly references acceptance criteria from requirements.md in its detail bullets.
- Never mark implementation work or integration-critical verification as optional—reserve `*` for auxiliary/deferrable test coverage that can be revisited post-MVP.
## Task Hierarchy Rules
### Maximum 2 Levels
- **Level 1**: Major tasks (1, 2, 3, 4...)
- **Level 2**: Sub-tasks (1.1, 1.2, 2.1, 2.2...)
- **No deeper nesting** (no 1.1.1)
- If a major task would contain only a single actionable item, collapse the structure and promote the sub-task to the major level (e.g., replace `1.1` with `1.`).
- When a major task exists purely as a container, keep the checkbox description concise and avoid duplicating detailed bullets—reserve specifics for its sub-tasks.
### Sequential Numbering
- Major tasks MUST increment: 1, 2, 3, 4, 5...
- Sub-tasks reset per major task: 1.1, 1.2, then 2.1, 2.2...
- Never repeat major task numbers
### Parallel Analysis (default)
- Assume parallel analysis is enabled unless explicitly disabled (e.g. `--sequential` flag).
- `(P)` means: this task has no dependency on its immediately preceding peers and can run concurrently with them.
- Identify tasks that can run concurrently when **all** conditions hold:
- No data dependency on other pending tasks
- No shared file or resource contention
- No prerequisite review/approval from another task
- `_Boundary:_` annotations confirm non-overlapping component scopes
- Foundation-phase tasks (see Task Ordering Principle) are rarely `(P)` — they establish shared prerequisites.
- Core-phase tasks are the primary candidates for `(P)` since foundation is already complete.
- Validate that identified parallel tasks operate within separate boundaries defined in the Architecture Pattern & Boundary Map.
- Confirm API/event contracts from design.md do not overlap in ways that cause conflicts.
- `(P)` tasks with cross-boundary dependencies must declare `_Depends: X.X_` explicitly.
- Append `(P)` immediately after the task number for each parallel-capable task:
- Example: `- [ ] 2.1 (P) Build background worker`
- Apply to both major tasks and sub-tasks when appropriate.
- If sequential mode is requested, omit `(P)` markers entirely.
- Group parallel tasks logically (same parent when possible) and highlight any ordering caveats in detail bullets.
- Explicitly call out dependencies that prevent `(P)` even when tasks look similar.
### Checkbox Format
```markdown
- [ ] 1. Foundation: environment and test infrastructure setup
- [ ] 1.1 Sub-task description
- Detail item 1
- Detail item 2
- Observable completion condition
- _Requirements: X.X_
- [ ] 2. Core feature A
- [ ] 2.1 (P) Sub-task description
- Detail items...
- Observable completion condition
- _Requirements: Y.Y_
- _Boundary: AuthService_
- [ ] 2.2 (P) Sub-task description
- Detail items...
- Observable completion condition
- _Requirements: Z.Z_
- _Boundary: UserRepository_
- [ ] 3. Integration and wiring
- [ ] 3.1 Sub-task description
- Detail items...
- Observable completion condition
- _Depends: 2.1, 2.2_
- _Requirements: W.W_
```
## Requirements Coverage
**Mandatory Check**:
- ALL requirements from requirements.md MUST be covered
- Cross-reference every requirement ID with task mappings
- If gaps found: Return to requirements or design phase
- No requirement should be left without corresponding tasks
Use `N.M`-style numeric requirement IDs where `N` is the top-level requirement number from requirements.md (for example, Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2), and `M` is a local index within that requirement group.
Document any intentionally deferred requirements with rationale.

41
.kiro/settings/rules/tasks-parallel-analysis.md Normal file
View File

@ -0,0 +1,41 @@
# Parallel Task Analysis Rules
## Purpose
Provide a consistent way to identify implementation tasks that can be safely executed in parallel while generating `tasks.md`.
## Relationship to Task Ordering
`(P)` means: this task has no dependency on its immediately preceding peers and can run concurrently with them. The Task Ordering Principle (see tasks-generation.md) ensures Foundation-phase tasks run first, making Core-phase tasks the primary `(P)` candidates.
## When to Consider Tasks Parallel
Only mark a task as parallel-capable when **all** of the following are true:
1. **No data dependency** on pending tasks.
2. **No conflicting files or shared mutable resources** are touched.
3. **No prerequisite review/approval** from another task is required beforehand.
4. **Foundation work complete**: Environment/setup work needed by this task is already satisfied by earlier Foundation-phase tasks.
5. **Non-overlapping boundaries**: `_Boundary:_` annotations confirm tasks operate on separate components.
## Marking Convention
- Append `(P)` immediately after the numeric identifier for each qualifying task.
- Example: `- [ ] 2.1 (P) Build background worker for emails`
- Apply `(P)` to both major tasks and sub-tasks when appropriate.
- If sequential execution is requested (e.g. via `--sequential` flag), omit `(P)` markers entirely.
- Keep `(P)` **outside** of checkbox brackets to avoid confusion with completion state.
## Grouping & Ordering Guidelines
- Group parallel tasks under the same parent whenever the work belongs to the same theme.
- List obvious prerequisites or caveats in the detail bullets (e.g., "Requires schema migration from 1.2").
- When two tasks look similar but are not parallel-safe, call out the blocking dependency explicitly.
- Skip marking container-only major tasks (those without their own actionable detail bullets) with `(P)`—evaluate parallel execution at the sub-task level instead.
## Quality Checklist
Before marking a task with `(P)`, ensure you have:
- Verified that running this task concurrently will not create merge or deployment conflicts.
- Confirmed `_Boundary:_` annotations show non-overlapping component scopes.
- Captured any shared state expectations in the detail bullets.
- Confirmed that the implementation can be tested independently.
- Added `_Depends: X.X_` if this `(P)` task still requires specific prior work from a different major-task group.
If any check fails, **do not** mark the task with `(P)` and explain the dependency in the task details.

331
.kiro/settings/templates/specs/design.md Normal file
View File

@ -0,0 +1,331 @@
# Design Document Template
---
**Purpose**: Provide sufficient detail to ensure implementation consistency across different implementers, preventing interpretation drift.
**Approach**:
- Include essential sections that directly inform implementation decisions
- Omit optional sections unless critical to preventing implementation errors
- Match detail level to feature complexity
- Use diagrams and tables over lengthy prose
**Warning**: Approaching 1000 lines indicates excessive feature complexity that may require design simplification or splitting into multiple specs.
---
> Sections may be reordered (e.g., surfacing Requirements Traceability earlier or moving Data Models nearer Architecture) when it improves clarity. Within each section, keep the flow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
## Overview
2-3 paragraphs max
**Purpose**: This feature delivers [specific value] to [target users].
**Users**: [Target user groups] will utilize this for [specific workflows].
**Impact** (if applicable): Changes the current [system state] by [specific modifications].
### Goals
- Primary objective 1
- Primary objective 2
- Success criteria
### Non-Goals
- Explicitly excluded functionality
- Future considerations outside current scope
- Integration points deferred
## Boundary Commitments
State the responsibility boundary of this spec in concrete terms. Treat this as the anchor for architecture, tasks, and later validation.
### This Spec Owns
- Capabilities and behaviors this spec is responsible for
- Data it owns or is authoritative for
- Interfaces or contracts it defines or stabilizes
### Out of Boundary
- Related concerns this spec explicitly does NOT own
- Work deferred to another spec, existing subsystem, or later phase
- Changes this spec must not absorb as "just one more thing"
### Allowed Dependencies
- Upstream systems/specs/components this design may depend on
- Shared infrastructure this design may use
- Dependency constraints that must not be violated
### Revalidation Triggers
List the kinds of changes that should force dependent specs or consumers to re-check integration.
- Contract shape changes
- Data ownership changes
- Dependency direction changes
- Startup/runtime prerequisite changes
## Architecture
> Reference detailed discovery notes in `research.md` only for background; keep design.md self-contained for reviewers by capturing all decisions and contracts here.
> Capture key decisions in text and let diagrams carry structural detail—avoid repeating the same information in prose.
> Supporting sections below should remain as light as possible unless they materially clarify the responsibility boundary, dependency rules, or integration seams.
### Existing Architecture Analysis (if applicable)
When modifying existing systems:
- Current architecture patterns and constraints
- Existing domain boundaries to be respected
- Integration points that must be maintained
- Technical debt addressed or worked around
### Architecture Pattern & Boundary Map
**RECOMMENDED**: Include Mermaid diagram showing the chosen architecture pattern and system boundaries (required for complex features, optional for simple additions)
**Architecture Integration**:
- Selected pattern: [name and brief rationale]
- Domain/feature boundaries: [how responsibilities are separated to avoid conflicts]
- Existing patterns preserved: [list key patterns]
- New components rationale: [why each is needed]
- Steering compliance: [principles maintained]
### Technology Stack
| Layer | Choice / Version | Role in Feature | Notes |
|-------|------------------|-----------------|-------|
| Frontend / CLI | | | |
| Backend / Services | | | |
| Data / Storage | | | |
| Messaging / Events | | | |
| Infrastructure / Runtime | | | |
> Keep rationale concise here and, when more depth is required (trade-offs, benchmarks), add a short summary plus pointer to the Supporting References section and `research.md` for raw investigation notes.
## File Structure Plan
Map the directory structure and file responsibilities for this feature. This section directly drives task `_Boundary:_` annotations and implementation Task Briefs. Use the appropriate level of detail:
- **Small features**: List individual files with responsibilities
- **Large features**: Describe directory-level structure + per-domain/module pattern, list only non-obvious files individually
### Directory Structure
```
src/
├── domain-a/ # Domain A responsibility
│ ├── controller.ts # Endpoint handlers
│ ├── service.ts # Business logic
│ └── types.ts # Domain types
├── domain-b/ # Domain B (same pattern as domain-a)
└── shared/
└── cross-cutting.ts # Non-obvious: why this exists
```
> For repeated structures, describe the pattern once (e.g., "domain-b follows same pattern as domain-a"). List individual files only when their responsibility isn't obvious from the path.
### Modified Files
- `path/to/existing.ts` — What changes and why
> Each file should have one clear responsibility. Group files that change together. For repeated structures, describe the pattern once rather than listing every file.
> Avoid duplicating what Components and Interfaces already describes — focus on the physical file layout that Components maps to.
## System Flows
Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:
- Sequence (multi-party interactions)
- Process / state (branching logic or lifecycle)
- Data / event flow (pipelines, async messaging)
Skip this section entirely for simple CRUD changes.
> Describe flow-level decisions (e.g., gating conditions, retries) briefly after the diagram instead of restating each step.
## Requirements Traceability
Use this section for complex or compliance-sensitive features where requirements span multiple domains. Straightforward 1:1 mappings can rely on the Components summary table.
Map each requirement ID (e.g., `2.1`) to the design elements that realize it.
| Requirement | Summary | Components | Interfaces | Flows |
|-------------|---------|------------|------------|-------|
| 1.1 | | | | |
| 1.2 | | | | |
> Omit this section only when a single component satisfies a single requirement without cross-cutting concerns.
## Components and Interfaces
Provide a quick reference before diving into per-component details.
- Summaries can be a table or compact list. Example table:
| Component | Domain/Layer | Intent | Req Coverage | Key Dependencies (P0/P1) | Contracts |
|-----------|--------------|--------|--------------|--------------------------|-----------|
| ExampleComponent | UI | Displays XYZ | 1, 2 | GameProvider (P0), MapPanel (P1) | Service, State |
- Only components introducing new boundaries (e.g., logic hooks, external integrations, persistence) require full detail blocks. Simple presentation components can rely on the summary row plus a short Implementation Note.
Group detailed blocks by domain or architectural layer. For each detailed component, list requirement IDs as `2.1, 2.3` (omit “Requirement”). When multiple UI components share the same contract, reference a base interface/props definition instead of duplicating code blocks.
### [Domain / Layer]
#### [Component Name]
| Field | Detail |
|-------|--------|
| Intent | 1-line description of the responsibility |
| Requirements | 2.1, 2.3 |
| Owner / Reviewers | (optional) |
**Responsibilities & Constraints**
- Primary responsibility
- Domain boundary and transaction scope
- Data ownership / invariants
**Dependencies**
- Inbound: Component/service name — purpose (Criticality)
- Outbound: Component/service name — purpose (Criticality)
- External: Service/library — purpose (Criticality)
Summarize external dependency findings here; deeper investigation (API signatures, rate limits, migration notes) lives in `research.md`.
**Contracts**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [ ] ← check only the ones that apply.
##### Service Interface
```typescript
interface [ComponentName]Service {
methodName(input: InputType): Result<OutputType, ErrorType>;
}
```
- Preconditions:
- Postconditions:
- Invariants:
##### API Contract
| Method | Endpoint | Request | Response | Errors |
|--------|----------|---------|----------|--------|
| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 |
##### Event Contract
- Published events:
- Subscribed events:
- Ordering / delivery guarantees:
##### Batch / Job Contract
- Trigger:
- Input / validation:
- Output / destination:
- Idempotency & recovery:
##### State Management
- State model:
- Persistence & consistency:
- Concurrency strategy:
**Implementation Notes**
- Integration:
- Validation:
- Risks:
## Data Models
Focus on the portions of the data landscape that change with this feature.
### Domain Model
- Aggregates and transactional boundaries
- Entities, value objects, domain events
- Business rules & invariants
- Optional Mermaid diagram for complex relationships
### Logical Data Model
**Structure Definition**:
- Entity relationships and cardinality
- Attributes and their types
- Natural keys and identifiers
- Referential integrity rules
**Consistency & Integrity**:
- Transaction boundaries
- Cascading rules
- Temporal aspects (versioning, audit)
### Physical Data Model
**When to include**: When implementation requires specific storage design decisions
**For Relational Databases**:
- Table definitions with data types
- Primary/foreign keys and constraints
- Indexes and performance optimizations
- Partitioning strategy for scale
**For Document Stores**:
- Collection structures
- Embedding vs referencing decisions
- Sharding key design
- Index definitions
**For Event Stores**:
- Event schema definitions
- Stream aggregation strategies
- Snapshot policies
- Projection definitions
**For Key-Value/Wide-Column Stores**:
- Key design patterns
- Column families or value structures
- TTL and compaction strategies
### Data Contracts & Integration
**API Data Transfer**
- Request/response schemas
- Validation rules
- Serialization format (JSON, Protobuf, etc.)
**Event Schemas**
- Published event structures
- Schema versioning strategy
- Backward/forward compatibility rules
**Cross-Service Data Management**
- Distributed transaction patterns (Saga, 2PC)
- Data synchronization strategies
- Eventual consistency handling
Skip subsections that are not relevant to this feature.
## Error Handling
### Error Strategy
Concrete error handling patterns and recovery mechanisms for each error type.
### Error Categories and Responses
**User Errors** (4xx): Invalid input → field-level validation; Unauthorized → auth guidance; Not found → navigation help
**System Errors** (5xx): Infrastructure failures → graceful degradation; Timeouts → circuit breakers; Exhaustion → rate limiting
**Business Logic Errors** (422): Rule violations → condition explanations; State conflicts → transition guidance
**Process Flow Visualization** (when complex business logic exists):
Include Mermaid flowchart only for complex error scenarios with business workflows.
### Monitoring
Error tracking, logging, and health monitoring implementation.
## Testing Strategy
### Default sections (adapt names/sections to fit the domain)
- Unit Tests: 3–5 items from core functions/modules (e.g., auth methods, subscription logic)
- Integration Tests: 3–5 cross-component flows (e.g., webhook handling, notifications)
- E2E/UI Tests (if applicable): 3–5 critical user paths (e.g., forms, dashboards)
- Performance/Load (if applicable): 3–4 items (e.g., concurrency, high-volume ops)
## Optional Sections (include when relevant)
### Security Considerations
_Use this section for features handling auth, sensitive data, external integrations, or user permissions. Capture only decisions unique to this feature; defer baseline controls to steering docs._
- Threat modeling, security controls, compliance requirements
- Authentication and authorization patterns
- Data protection and privacy considerations
### Performance & Scalability
_Use this section when performance targets, high load, or scaling concerns exist. Record only feature-specific targets or trade-offs and rely on steering documents for general practices._
- Target metrics and measurement strategies
- Scaling approaches (horizontal/vertical)
- Caching strategies and optimization techniques
### Migration Strategy
Include a Mermaid flowchart showing migration phases when schema/data movement is required.
- Phase breakdown, rollback triggers, validation checkpoints
## Supporting References (Optional)
- Create this section only when keeping the information in the main body would hurt readability (e.g., very long TypeScript definitions, vendor option matrices, exhaustive schema tables). Keep decision-making context in the main sections so the design stays self-contained.
- Link to the supporting references from the main text instead of inlining large snippets.
- Background research notes and comparisons continue to live in `research.md`, but their conclusions must be summarized in the main design.

24
.kiro/settings/templates/specs/init.json Normal file
View File

@ -0,0 +1,24 @@
{
"feature_name": "{{FEATURE_NAME}}",
"created_at": "{{TIMESTAMP}}",
"updated_at": "{{TIMESTAMP}}",
"language": "en",
"phase": "initialized",
"approvals": {
"requirements": {
"generated": false,
"approved": false
},
"design": {
"generated": false,
"approved": false
},
"tasks": {
"generated": false,
"approved": false
}
},
"ready_for_implementation": false
}

9
.kiro/settings/templates/specs/requirements-init.md Normal file
View File

@ -0,0 +1,9 @@
# Requirements Document
## Project Description (Input)
{{PROJECT_DESCRIPTION}}
## Requirements
<!-- Will be generated in /kiro-spec-requirements phase -->

32
.kiro/settings/templates/specs/requirements.md Normal file
View File

@ -0,0 +1,32 @@
# Requirements Document
## Introduction
{{INTRODUCTION}}
<!-- Optional when scope could be misread or the feature touches adjacent systems/specs -->
## Boundary Context (Optional)
- **In scope**: {{IN_SCOPE_BEHAVIORS}}
- **Out of scope**: {{OUT_OF_SCOPE_BEHAVIORS}}
- **Adjacent expectations**: {{ADJACENT_SYSTEM_OR_SPEC_EXPECTATIONS}}
## Requirements
### Requirement 1: {{REQUIREMENT_AREA_1}}
<!-- Requirement headings MUST include a leading numeric ID only (for example: "Requirement 1: ...", "1. Overview", "2 Feature: ..."). Alphabetic IDs like "Requirement A" are not allowed. -->
**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
#### Acceptance Criteria
1. When [event], the [system] shall [response/action]
2. If [trigger], then the [system] shall [response/action]
3. While [precondition], the [system] shall [response/action]
4. Where [feature is included], the [system] shall [response/action]
5. The [system] shall [response/action]
### Requirement 2: {{REQUIREMENT_AREA_2}}
**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
#### Acceptance Criteria
1. When [event], the [system] shall [response/action]
2. When [event] and [condition], the [system] shall [response/action]
<!-- Additional requirements follow the same pattern -->

61
.kiro/settings/templates/specs/research.md Normal file
View File

@ -0,0 +1,61 @@
# Research & Design Decisions Template
---
**Purpose**: Capture discovery findings, architectural investigations, and rationale that inform the technical design.
**Usage**:
- Log research activities and outcomes during the discovery phase.
- Document design decision trade-offs that are too detailed for `design.md`.
- Provide references and evidence for future audits or reuse.
---
## Summary
- **Feature**: `<feature-name>`
- **Discovery Scope**: New Feature / Extension / Simple Addition / Complex Integration
- **Key Findings**:
- Finding 1
- Finding 2
- Finding 3
## Research Log
Document notable investigation steps and their outcomes. Group entries by topic for readability.
### [Topic or Question]
- **Context**: What triggered this investigation?
- **Sources Consulted**: Links, documentation, API references, benchmarks
- **Findings**: Concise bullet points summarizing the insights
- **Implications**: How this affects architecture, contracts, or implementation
_Repeat the subsection for each major topic._
## Architecture Pattern Evaluation
List candidate patterns or approaches that were considered. Use the table format where helpful.
| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| Hexagonal | Ports & adapters abstraction around core domain | Clear boundaries, testable core | Requires adapter layer build-out | Aligns with existing steering principle X |
## Design Decisions
Record major decisions that influence `design.md`. Focus on choices with significant trade-offs.
### Decision: `<Title>`
- **Context**: Problem or requirement driving the decision
- **Alternatives Considered**:
1. Option A — short description
2. Option B — short description
- **Selected Approach**: What was chosen and how it works
- **Rationale**: Why this approach fits the current project context
- **Trade-offs**: Benefits vs. compromises
- **Follow-up**: Items to verify during implementation or testing
_Repeat the subsection for each decision._
## Risks & Mitigations
- Risk 1 — Proposed mitigation
- Risk 2 — Proposed mitigation
- Risk 3 — Proposed mitigation
## References
Provide canonical links and citations (official docs, standards, ADRs, internal guidelines).
- [Title](https://example.com) — brief note on relevance
- ...

24
.kiro/settings/templates/specs/tasks.md Normal file
View File

@ -0,0 +1,24 @@
# Implementation Plan
## Task Format Template
Use whichever pattern fits the work breakdown:
### Major task only
- [ ] {{NUMBER}}. {{TASK_DESCRIPTION}}{{PARALLEL_MARK}}
- {{DETAIL_ITEM_1}} *(Include details only when needed. If the task stands alone, omit bullet items.)*
- _Requirements: {{REQUIREMENT_IDS}}_
### Major + Sub-task structure
- [ ] {{MAJOR_NUMBER}}. {{MAJOR_TASK_SUMMARY}}
- [ ] {{MAJOR_NUMBER}}.{{SUB_NUMBER}} {{SUB_TASK_DESCRIPTION}}{{SUB_PARALLEL_MARK}}
- {{DETAIL_ITEM_1}}
- {{DETAIL_ITEM_2}}
- {{OBSERVABLE_COMPLETION_ITEM}} *(At least one detail item should state the observable completion condition for this task.)*
- _Requirements: {{REQUIREMENT_IDS}}_ *(IDs only; do not add descriptions or parentheses.)*
- _Boundary: {{COMPONENT_NAMES}}_ *(Only for (P) tasks. Omit when scope is obvious.)*
- _Depends: {{TASK_IDS}}_ *(Only for non-obvious cross-boundary dependencies. Most tasks omit this.)*
> **Parallel marker**: Append ` (P)` only to tasks that can be executed in parallel. Omit the marker when running in `--sequential` mode.
>
> **Optional test coverage**: When a sub-task is deferrable test work tied to acceptance criteria, mark the checkbox as `- [ ]*` and explain the referenced requirements in the detail bullets.

69
.kiro/settings/templates/steering-custom/api-standards.md Normal file
View File

@ -0,0 +1,69 @@
# API Standards
[Purpose: consistent API patterns for naming, structure, auth, versioning, and errors]
## Philosophy
- Prefer predictable, resource-oriented design
- Be explicit in contracts; minimize breaking changes
- Secure by default (auth first, least privilege)
## Endpoint Pattern
```
/{version}/{resource}[/{id}][/{sub-resource}]
```
Examples:
- `/api/v1/users`
- `/api/v1/users/:id`
- `/api/v1/users/:id/posts`
HTTP verbs:
- GET (read, safe, idempotent)
- POST (create)
- PUT/PATCH (update)
- DELETE (remove, idempotent)
## Request/Response
Request (typical):
```json
{ "data": { ... }, "metadata": { "requestId": "..." } }
```
Success:
```json
{ "data": { ... }, "meta": { "timestamp": "...", "version": "..." } }
```
Error:
```json
{ "error": { "code": "ERROR_CODE", "message": "...", "field": "optional" } }
```
(See error-handling for rules.)
## Status Codes (pattern)
- 2xx: Success (200 read, 201 create, 204 delete)
- 4xx: Client issues (400 validation, 401/403 auth, 404 missing)
- 5xx: Server issues (500 generic, 503 unavailable)
Choose the status that best reflects the outcome.
## Authentication
- Credentials in standard location
```
Authorization: Bearer {token}
```
- Reject unauthenticated before business logic
## Versioning
- Version via URL/header/media-type
- Breaking change → new version
- Non-breaking → same version
- Provide deprecation window and comms
## Pagination/Filtering (if applicable)
- Pagination: `page`, `pageSize` or cursor-based
- Filtering: explicit query params
- Sorting: `sort=field:asc|desc`
Return pagination metadata in `meta`.
---
_Focus on patterns and decisions, not endpoint catalogs._

67
.kiro/settings/templates/steering-custom/authentication.md Normal file
View File

@ -0,0 +1,67 @@
# Authentication & Authorization Standards
[Purpose: unify auth model, token/session lifecycle, permission checks, and security]
## Philosophy
- Clear separation: authentication (who) vs authorization (what)
- Secure by default: least privilege, fail closed, short-lived tokens
- UX-aware: friction where risk is high, smooth otherwise
## Authentication
### Method (choose + rationale)
- Options: JWT, Session, OAuth2, hybrid
- Choice: [our method] because [reason]
### Flow (high-level)
```
1) User proves identity (credentials or provider)
2) Server verifies and issues token/session
3) Client sends token per request
4) Server verifies token and proceeds
```
### Token/Session Lifecycle
- Storage: httpOnly cookie or Authorization header
- Expiration: short-lived access, longer refresh (if used)
- Refresh: rotate tokens; respect revocation
- Revocation: blacklist/rotate on logout/compromise
### Security Pattern
- Enforce TLS; never expose tokens to JS when avoidable
- Bind token to audience/issuer; include minimal claims
- Consider device binding and IP/risk checks for sensitive actions
## Authorization
### Permission Model
- Choose one: RBAC / ABAC / ownership-based / hybrid
- Define roles/attributes centrally; avoid hardcoding across codebase
### Checks (where to enforce)
- Route/middleware: coarse-grained gate
- Domain/service: fine-grained decisions
- UI: conditional rendering (no security reliance)
Example pattern:
```typescript
requirePermission('resource:action'); // route
if (!user.can('resource:action')) throw ForbiddenError(); // domain
```
### Ownership
- Pattern: owner OR privileged role can act
- Verify on entity boundary before mutation
## Passwords & MFA
- Passwords: strong policy, hashed (bcrypt/argon2), never plaintext
- Reset: time-limited token, single-use, notify user
- MFA: step-up for risky operations (policy-driven)
## API-to-API Auth
- Use API keys or OAuth client credentials
- Scope keys minimally; rotate and audit usage
- Rate limit by identity (user/key)
---
_Focus on patterns and decisions. No library-specific code._

46
.kiro/settings/templates/steering-custom/database.md Normal file
View File

@ -0,0 +1,46 @@
# Database Standards
[Purpose: guide schema design, queries, migrations, and integrity]
## Philosophy
- Model the domain first; optimize after correctness
- Prefer explicit constraints; let database enforce invariants
- Query only what you need; measure before optimizing
## Naming & Types
- Tables: `snake_case`, plural (`users`, `order_items`)
- Columns: `snake_case` (`created_at`, `user_id`)
- FKs: `{table}_id` referencing `{table}.id`
- Types: timezone-aware timestamps; strong IDs; precise money types
## Relationships
- 1:N: FK in child
- N:N: join table with compound key
- 1:1: FK + UNIQUE
## Migrations
- Immutable migrations; always add rollback
- Small, focused steps; test on non-prod first
- Naming: `{seq}_{action}_{object}` (e.g., `002_add_email_index`)
## Query Patterns
- ORM for simple CRUD and safety; raw SQL for complex/perf-critical
- Avoid N+1 (eager load/batching); paginate large sets
- Index FKs and frequently filtered/sorted columns
## Connection & Transactions
- Use pooling (size/timeouts based on workload)
- One connection per unit of work; close/return promptly
- Wrap multi-step changes in transactions
## Data Integrity
- Use NOT NULL/UNIQUE/CHECK/FK constraints
- Validate at DB when appropriate (defense in depth)
- Prefer generated columns for consistent derivations
## Backup & Recovery
- Regular backups with retention; test restores
- Document RPO/RTO targets; monitor backup jobs
---
_Focus on patterns and decisions. No environment-specific settings._

54
.kiro/settings/templates/steering-custom/deployment.md Normal file
View File

@ -0,0 +1,54 @@
# Deployment Standards
[Purpose: safe, repeatable releases with clear environment and pipeline patterns]
## Philosophy
- Automate; test before deploy; verify after deploy
- Prefer incremental rollout with fast rollback
- Production changes must be observable and reversible
## Environments
- Dev: fast iteration; debugging enabled
- Staging: mirrors prod; release validation
- Prod: hardened; monitored; least privilege
## CI/CD Flow
```
Code → Test → Build → Scan → Deploy (staged) → Verify
```
Principles:
- Fail fast on tests/scans; block deploy
- Artifact builds are reproducible (lockfiles, pinned versions)
- Manual approval for prod; auditable trail
## Deployment Strategies
- Rolling: gradual instance replacement
- Blue-Green: switch traffic between two pools
- Canary: small % users first, expand on health
Choose per risk profile; document default.
## Zero-Downtime & Migrations
- Health checks gate traffic; graceful shutdown
- Backwards-compatible DB changes during rollout
- Separate migration step; test rollback paths
## Rollback
- Keep previous version ready; automate revert
- Rollback faster than fix-forward; document triggers
## Configuration & Secrets
- 12-factor config via env; never commit secrets
- Secret manager; rotate; least privilege; audit access
- Validate required env vars at startup
## Health & Monitoring
- Endpoints: `/health`, `/health/live`, `/health/ready`
- Monitor latency, error rate, throughput, saturation
- Alerts on SLO breaches/spikes; tune to avoid fatigue
## Incident Response & DR
- Standard playbook: detect → assess → mitigate → communicate → resolve → post-mortem
- Backups with retention; test restore; defined RPO/RTO
---
_Focus on rollout patterns and safeguards. No provider-specific steps._

59
.kiro/settings/templates/steering-custom/error-handling.md Normal file
View File

@ -0,0 +1,59 @@
# Error Handling Standards
[Purpose: unify how errors are classified, shaped, propagated, logged, and monitored]
## Philosophy
- Fail fast where possible; degrade gracefully at system boundaries
- Consistent error shape across the stack (human + machine readable)
- Handle known errors close to source; surface unknowns to a global handler
## Classification (decide handling by source)
- Client: Input/validation/user action issues → 4xx
- Server: System failures/unexpected exceptions → 5xx
- Business: Rule/state violations → 4xx (e.g., 409)
- External: 3rd-party/network failures → map to 5xx or 4xx with context
## Error Shape (single canonical format)
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message",
"requestId": "trace-id",
"timestamp": "ISO-8601"
}
}
```
Principles: stable code enums, no secrets, include trace info.
## Propagation (where to convert)
- API layer: Convert domain errors → HTTP status + canonical body
- Service layer: Throw typed business errors, avoid stringly-typed errors
- Data/external layer: Wrap provider errors with safe, actionable codes
- Unknown errors: Bubble to global handler → 500 + generic message
Example pattern:
```typescript
try { return await useCase(); }
catch (e) {
if (e instanceof BusinessError) return respondMapped(e);
logError(e); return respondInternal();
}
```
## Logging (context over noise)
Log: operation, userId (if available), code, message, stack, requestId, minimal context.
Do not log: passwords, tokens, secrets, full PII, full bodies with sensitive data.
Levels: ERROR (failures), WARN (recoverable/edge), INFO (key events), DEBUG (diagnostics).
## Retry (only when safe)
Retry when: network/timeouts/transient 5xx AND operation is idempotent.
Do not retry: 4xx, business errors, non-idempotent flows.
Strategy: exponential backoff + jitter, capped attempts; require idempotency keys.
## Monitoring & Health
Track: error rates by code/category, latency, saturation; alert on spikes/SLI breaches.
Expose health: `/health` (live), `/health/ready` (ready). Link errors to traces.
---
_Focus on patterns and decisions. No implementation details or exhaustive lists._

55
.kiro/settings/templates/steering-custom/security.md Normal file
View File

@ -0,0 +1,55 @@
# Security Standards
[Purpose: define security posture with patterns for validation, authz, secrets, and data]
## Philosophy
- Defense in depth; least privilege; secure by default; fail closed
- Validate at boundaries; sanitize for context; never trust input
- Separate authentication (who) and authorization (what)
## Input & Output
- Validate at API boundaries and UI forms; enforce types and constraints
- Sanitize/escape based on destination (HTML, SQL, shell, logs)
- Prefer allow-lists over block-lists; reject early with minimal detail
## Authentication & Authorization
- Authentication: verify identity; issue short-lived tokens/sessions
- Authorization: check permissions before actions; deny by default
- Centralize policies; avoid duplicating checks across code
Pattern:
```typescript
if (!user.hasPermission('resource:action')) throw ForbiddenError();
```
## Secrets & Configuration
- Never commit secrets; store in secret manager or env
- Rotate regularly; audit access; scope minimal
- Validate required env vars at startup; fail fast on missing
## Sensitive Data
- Minimize collection; mask/redact in logs; encrypt at rest and in transit
- Restrict access by role/need-to-know; track access to sensitive records
## Session/Token Security
- httpOnly + secure cookies where possible; TLS everywhere
- Short expiration; rotate on refresh; revoke on logout/compromise
- Bind tokens to audience/issuer; include minimal claims
## Logging (security-aware)
- Log auth attempts, permission denials, and sensitive operations
- Never log passwords, tokens, secrets, full PII; avoid full bodies
- Include requestId and context to correlate events
## Headers & Transport
- Enforce TLS; HSTS
- Set security headers (CSP, X-Frame-Options, X-Content-Type-Options)
- Prefer modern crypto; disable weak protocols/ciphers
## Vulnerability Posture
- Prefer secure libraries; keep dependencies updated
- Static/dynamic scans in CI; track and remediate
- Educate team on common classes; encode as patterns above
---
_Focus on patterns and principles. Link concrete configs to ops docs._

47
.kiro/settings/templates/steering-custom/testing.md Normal file
View File

@ -0,0 +1,47 @@
# Testing Standards
[Purpose: guide what to test, where tests live, and how to structure them]
## Philosophy
- Test behavior, not implementation
- Prefer fast, reliable tests; minimize brittle mocks
- Cover critical paths deeply; breadth over 100% pursuit
## Organization
Options:
- Co-located: `component.tsx` + `component.test.tsx`
- Separate: `/src/...` and `/tests/...`
Pick one as default; allow exceptions with rationale.
Naming:
- Files: `*.test.*` or `*.spec.*`
- Suites: what is under test; Cases: expected behavior
## Test Types
- Unit: single unit, mocked dependencies, very fast
- Integration: multiple units together, mock externals only
- E2E: full flows, minimal mocks, only for critical journeys
## Structure (AAA)
```typescript
it('does X when Y', () => {
// Arrange
const input = setup();
// Act
const result = act(input);
// Assert
expect(result).toEqual(expected);
});
```
## Mocking & Data
- Mock externals (API/DB); never mock the system under test
- Use factories/fixtures; reset state between tests
- Keep test data minimal and intention-revealing
## Coverage
- Target: [% overall]; higher for critical domains
- Enforce thresholds in CI; exceptions require review rationale
---
_Focus on patterns and decisions. Tool-specific config lives elsewhere._

18
.kiro/settings/templates/steering/product.md Normal file
View File

@ -0,0 +1,18 @@
# Product Overview
[Brief description of what this product does and who it serves]
## Core Capabilities
[3-5 key capabilities, not exhaustive features]
## Target Use Cases
[Primary scenarios this product addresses]
## Value Proposition
[What makes this product unique or valuable]
---
_Focus on patterns and purpose, not exhaustive feature lists_

41
.kiro/settings/templates/steering/structure.md Normal file
View File

@ -0,0 +1,41 @@
# Project Structure
## Organization Philosophy
[Describe approach: feature-first, layered, domain-driven, etc.]
## Directory Patterns
### [Pattern Name]
**Location**: `/path/`
**Purpose**: [What belongs here]
**Example**: [Brief example]
### [Pattern Name]
**Location**: `/path/`
**Purpose**: [What belongs here]
**Example**: [Brief example]
## Naming Conventions
- **Files**: [Pattern, e.g., PascalCase, kebab-case]
- **Components**: [Pattern]
- **Functions**: [Pattern]
## Import Organization
```typescript
// Example import patterns
import { Something } from '@/path' // Absolute
import { Local } from './local' // Relative
```
**Path Aliases**:
- `@/`: [Maps to]
## Code Organization Principles
[Key architectural patterns and dependency rules]
---
_Document patterns, not file trees. New files following patterns shouldn't require updates_

45
.kiro/settings/templates/steering/tech.md Normal file
View File

@ -0,0 +1,45 @@
# Technology Stack
## Architecture
[High-level system design approach]
## Core Technologies
- **Language**: [e.g., TypeScript, Python]
- **Framework**: [e.g., React, Next.js, Django]
- **Runtime**: [e.g., Node.js 20+]
## Key Libraries
[Only major libraries that influence development patterns]
## Development Standards
### Type Safety
[e.g., TypeScript strict mode, no `any`]
### Code Quality
[e.g., ESLint, Prettier rules]
### Testing
[e.g., Jest, coverage requirements]
## Development Environment
### Required Tools
[Key tools and version requirements]
### Common Commands
```bash
# Dev: [command]
# Build: [command]
# Test: [command]
```
## Key Technical Decisions
[Important architectural choices and rationale]
---
_Document standards and patterns, not every dependency_