From e7e6879d682bbd640606dac9899310ef42b197eb Mon Sep 17 00:00:00 2001 From: TakumaNakao <34386181+TakumaNakao@users.noreply.github.com> Date: Tue, 28 Oct 2025 12:53:42 +0000 Subject: [PATCH] =?UTF-8?q?cc-sdd=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gemini/commands/kiro/spec-design.toml | 457 +++++++++++++++++++ .gemini/commands/kiro/spec-impl.toml | 83 ++++ .gemini/commands/kiro/spec-init.toml | 85 ++++ .gemini/commands/kiro/spec-requirements.toml | 124 +++++ .gemini/commands/kiro/spec-status.toml | 96 ++++ .gemini/commands/kiro/spec-tasks.toml | 175 +++++++ .gemini/commands/kiro/steering-custom.toml | 152 ++++++ .gemini/commands/kiro/steering.toml | 169 +++++++ .gemini/commands/kiro/validate-design.toml | 178 ++++++++ .gemini/commands/kiro/validate-gap.toml | 154 +++++++ GEMINI.md | 72 +++ 11 files changed, 1745 insertions(+) create mode 100644 .gemini/commands/kiro/spec-design.toml create mode 100644 .gemini/commands/kiro/spec-impl.toml create mode 100644 .gemini/commands/kiro/spec-init.toml create mode 100644 .gemini/commands/kiro/spec-requirements.toml create mode 100644 .gemini/commands/kiro/spec-status.toml create mode 100644 .gemini/commands/kiro/spec-tasks.toml create mode 100644 .gemini/commands/kiro/steering-custom.toml create mode 100644 .gemini/commands/kiro/steering.toml create mode 100644 .gemini/commands/kiro/validate-design.toml create mode 100644 .gemini/commands/kiro/validate-gap.toml create mode 100644 GEMINI.md diff --git a/.gemini/commands/kiro/spec-design.toml b/.gemini/commands/kiro/spec-design.toml new file mode 100644 index 00000000..35f3a746 --- /dev/null +++ b/.gemini/commands/kiro/spec-design.toml @@ -0,0 +1,457 @@ +description = "Create technical design for a specification" + +prompt = """ +# Technical Design + +Create comprehensive technical design for feature: **{{args}}** + +## Task: Create Technical Design Document + +### 1. Prerequisites & File Handling +- **Requirements Approval Check**: + - If invoked with `-y`, set `requirements.approved=true` in `spec.json` + - Otherwise, **stop** with an actionable message if requirements are missing or unapproved +- **Design File Handling**: + - If design.md does not exist: Create new design.md file + - If design.md exists: Interactive prompt with options: + - **[o] Overwrite**: Generate completely new design document + - **[m] Merge**: Generate new design document using existing content as reference context + - **[c] Cancel**: Stop execution for manual review +- **Context Loading**: Read `.kiro/specs/{{args}}/requirements.md`, core steering documents, and existing design.md (if merge mode) + +### 2. Discovery & Analysis Phase + +**CRITICAL**: Before generating the design, conduct thorough research and analysis: + +#### Feature Classification & Process Adaptation +**Classify feature type to adapt process scope**: +- **New Feature** (greenfield): Full process including technology selection and architecture decisions +- **Extension** (existing system): Focus on integration analysis, minimal architectural changes +- **Simple Addition** (CRUD, UI): Streamlined process, follow established patterns +- **Complex Integration** (external systems, new domains): Comprehensive analysis and risk assessment + +**Process Adaptation**: Skip or streamline analysis steps based on classification above + +#### A. Requirements to Technical Components Mapping +- Map requirements (EARS format) to technical components +- Extract non-functional requirements (performance, security, scalability) +- Identify core technical challenges and constraints + +#### B. Existing Implementation Analysis +**MANDATORY when modifying or extending existing features**: +- Analyze codebase structure, dependencies, patterns +- Map reusable modules, services, utilities +- Understand domain boundaries, layers, data flow +- Determine extension vs. refactor vs. wrap approach +- Prioritize minimal changes and file reuse + +**Optional for completely new features**: Review existing patterns for consistency and reuse opportunities + +#### C. Steering Alignment Check +- Verify alignment with core steering documents (`structure.md`, `tech.md`, `product.md`) and any custom steering files + - **Core steering**: @.kiro/steering/structure.md, @.kiro/steering/tech.md, @.kiro/steering/product.md + - **Custom steering**: All additional `.md` files in `.kiro/steering/` directory (e.g., `api.md`, `testing.md`, `security.md`) +- Document deviations with rationale for steering updates + +#### D. Technology & Alternative Analysis +**For New Features or Unknown Technology Areas**: +- Research latest best practices using WebSearch/WebFetch when needed in parallel +- Compare relevant architecture patterns (MVC, Clean, Hexagonal) if pattern selection is required +- Assess technology stack alternatives only when technology choices are being made +- Document key findings that impact design decisions + +**Skip this step if**: Using established team technology stack and patterns for straightforward feature additions + +#### E. Implementation-Specific Investigation +**When new technology or complex integration is involved**: +- Verify specific API capabilities needed for requirements +- Check version compatibility with existing dependencies +- Identify configuration and setup requirements +- Document any migration or integration challenges + +**For ANY external dependencies (libraries, APIs, services)**: +- Use WebSearch to find official documentation and community resources +- Use WebFetch to analyze specific documentation pages +- Document authentication flows, rate limits, and usage constraints +- Note any gaps in understanding for implementation phase + +**Skip only if**: Using well-established internal libraries with no external dependencies + +#### F. Technical Risk Assessment +- Performance/scalability risks: bottlenecks, capacity, growth +- Security vulnerabilities: attack vectors, compliance gaps +- Maintainability risks: complexity, knowledge, support +- Integration complexity: dependencies, coupling, API changes +- Technical debt: new creation vs. existing resolution + +## Design Document Structure & Guidelines + +### Core Principles +- **Review-optimized structure**: Critical technical decisions prominently placed to prevent oversight +- **Contextual relevance**: Include sections only when applicable to project type and scope +- **Visual-first design**: Essential Mermaid diagrams for architecture and data flow +- **Design focus only**: Architecture and interfaces, NO implementation code +- **Type safety**: Never use `any` type - define explicit types and interfaces +- **Formal tone**: Use definitive, declarative statements without hedging language +- **Language**: Use language from `spec.json.language` field, default to English + +### Document Sections + +**CORE SECTIONS** (Include when relevant): +- Overview, Architecture, Components and Interfaces (always) +- Data Models, Error Handling, Testing Strategy (when applicable) +- Security Considerations (when security implications exist) + +**CONDITIONAL SECTIONS** (Include only when specifically relevant): +- Performance & Scalability (for performance-critical features) +- Migration Strategy (for existing system modifications) + + +## 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 + +## Architecture + +### 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 + +### High-Level Architecture +**RECOMMENDED**: Include Mermaid diagram showing system architecture (required for complex features, optional for simple additions) + +**Architecture Integration**: +- Existing patterns preserved: [list key patterns] +- New components rationale: [why each is needed] +- Technology alignment: [how it fits current stack] +- Steering compliance: [principles maintained] + +### Technology Stack and Design Decisions + +**Generation Instructions** (DO NOT include this section in design.md): +Adapt content based on feature classification from Discovery & Analysis Phase: + +**For New Features (greenfield)**: +Generate Technology Stack section with ONLY relevant layers: +- Include only applicable technology layers (e.g., skip Frontend for CLI tools, skip Infrastructure for libraries) +- For each technology choice, provide: selection, rationale, and alternatives considered +- Include Architecture Pattern Selection if making architectural decisions + +**For Extensions/Additions to Existing Systems**: +Generate Technology Alignment section instead: +- Document how feature aligns with existing technology stack +- Note any new dependencies or libraries being introduced +- Justify deviations from established patterns if necessary + +**Key Design Decisions**: +Generate 1-3 critical technical decisions that significantly impact the implementation. +Each decision should follow this format: +- **Decision**: [Specific technical choice made] +- **Context**: [Problem or requirement driving this decision] +- **Alternatives**: [2-3 other approaches considered] +- **Selected Approach**: [What was chosen and how it works] +- **Rationale**: [Why this is optimal for the specific context] +- **Trade-offs**: [What we gain vs. what we sacrifice] + +Skip this entire section for simple CRUD operations or when following established patterns without deviation. + +## System Flows + +**Flow Design Generation Instructions** (DO NOT include this section in design.md): +Generate appropriate flow diagrams ONLY when the feature requires flow visualization. Select from: +- **Sequence Diagrams**: For user interactions across multiple components +- **Process Flow Charts**: For complex algorithms, decision branches, or state machines +- **Data Flow Diagrams**: For data transformations, ETL processes, or data pipelines +- **State Diagrams**: For complex state transitions +- **Event Flow**: For async/event-driven architectures + +Skip this section entirely for simple CRUD operations or features without complex flows. +When included, provide concise Mermaid diagrams specific to the actual feature requirements. + +## Requirements Traceability + +**Traceability Generation Instructions** (DO NOT include this section in design.md): +Generate traceability mapping ONLY for complex features with multiple requirements or when explicitly needed for compliance/validation. + +When included, create a mapping table showing how each EARS requirement is realized: +| Requirement | Requirement Summary | Components | Interfaces | Flows | +|---------------|-------------------|------------|------------|-------| +| 1.1 | Brief description | Component names | API/Methods | Relevant flow diagrams | + +Alternative format for simpler cases: +- **1.1**: Realized by [Component X] through [Interface Y] +- **1.2**: Implemented in [Component Z] with [Flow diagram reference] + +Skip this section for simple features with straightforward 1:1 requirement-to-component mappings. + +## Components and Interfaces + +**Component Design Generation Instructions** (DO NOT include this section in design.md): +Structure components by domain boundaries or architectural layers. Generate only relevant subsections based on component type. +Group related components under domain/layer headings for clarity. + +### [Domain/Layer Name] + +#### [Component Name] + +**Responsibility & Boundaries** +- **Primary Responsibility**: Single, clear statement of what this component does +- **Domain Boundary**: Which domain/subdomain this belongs to +- **Data Ownership**: What data this component owns and manages +- **Transaction Boundary**: Scope of transactional consistency (if applicable) + +**Dependencies** +- **Inbound**: Components/services that depend on this component +- **Outbound**: Components/services this component depends on +- **External**: Third-party services, libraries, or external systems + +**External Dependencies Investigation** (when using external libraries/services): +- Use WebSearch to locate official documentation, GitHub repos, and community resources +- Use WebFetch to retrieve and analyze documentation pages, API references, and usage examples +- Verify API signatures, authentication methods, and rate limits +- Check version compatibility, breaking changes, and migration guides +- Investigate common issues, best practices, and performance considerations +- Document any assumptions, unknowns, or risks for implementation phase +- If critical information is missing, clearly note "Requires investigation during implementation: [specific concern]" + +**Contract Definition** + +Select and generate ONLY the relevant contract types for each component: + +**Service Interface** (for business logic components): +```typescript +interface [ComponentName]Service { + // Method signatures with clear input/output types + // Include error types in return signatures + methodName(input: InputType): Result; +} +``` +- **Preconditions**: What must be true before calling +- **Postconditions**: What is guaranteed after successful execution +- **Invariants**: What remains true throughout + +**API Contract** (for REST/GraphQL endpoints): +| Method | Endpoint | Request | Response | Errors | +|--------|----------|---------|----------|--------| +| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 | + +With detailed schemas only for complex payloads + +**Event Contract** (for event-driven components): +- **Published Events**: Event name, schema, trigger conditions +- **Subscribed Events**: Event name, handling strategy, idempotency +- **Ordering**: Guaranteed order requirements +- **Delivery**: At-least-once, at-most-once, or exactly-once + +**Batch/Job Contract** (for scheduled/triggered processes): +- **Trigger**: Schedule, event, or manual trigger conditions +- **Input**: Data source and validation rules +- **Output**: Results destination and format +- **Idempotency**: How repeat executions are handled +- **Recovery**: Failure handling and retry strategy + +**State Management** (only if component maintains state): +- **State Model**: States and valid transitions +- **Persistence**: Storage strategy and consistency model +- **Concurrency**: Locking, optimistic/pessimistic control + +**Integration Strategy** (when modifying existing systems): +- **Modification Approach**: Extend, wrap, or refactor existing code +- **Backward Compatibility**: What must be maintained +- **Migration Path**: How to transition from current to target state + +## Data Models + +**Data Model Generation Instructions** (DO NOT include this section in design.md): +Generate only relevant data model sections based on the system's data requirements and chosen architecture. +Progress from conceptual to physical as needed for implementation clarity. + +### Domain Model +**When to include**: Complex business domains with rich behavior and rules + +**Core Concepts**: +- **Aggregates**: Define transactional consistency boundaries +- **Entities**: Business objects with unique identity and lifecycle +- **Value Objects**: Immutable descriptive aspects without identity +- **Domain Events**: Significant state changes in the domain + +**Business Rules & Invariants**: +- Constraints that must always be true +- Validation rules and their enforcement points +- Cross-aggregate consistency strategies + +Include conceptual diagram (Mermaid) only when relationships are complex enough to benefit from visualization + +### Logical Data Model +**When to include**: When designing data structures independent of storage technology + +**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 +**When to include**: Systems with service boundaries or external integrations + +**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 any section not directly relevant to the feature being designed. +Focus on aspects that influence implementation decisions. + +## 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 +**Include when**: Features handle authentication, sensitive data, external integrations, or user permissions +- Threat modeling, security controls, compliance requirements +- Authentication and authorization patterns +- Data protection and privacy considerations + +### Performance & Scalability +**Include when**: Features have specific performance requirements, high load expectations, or scaling concerns +- Target metrics and measurement strategies +- Scaling approaches (horizontal/vertical) +- Caching strategies and optimization techniques + +### Migration Strategy +**REQUIRED**: Include Mermaid flowchart showing migration phases + +**Process**: Phase breakdown, rollback triggers, validation checkpoints + + +--- + +## Process Instructions (NOT included in design.md) + +### Visual Design Guidelines +**Include based on complexity**: +- **Simple features**: Basic component diagram or none if trivial +- **Complex features**: Architecture diagram, data flow diagram, ER diagram (if complex) +- **When helpful**: State machines, component interactions, decision trees, process flows, auth flows, approval workflows, data pipelines + +**Mermaid Diagram Rules**: +- Use only basic graph syntax with nodes and relationships +- Exclude all styling elements (no style definitions, classDef, fill colors) +- Avoid visual customization (backgrounds, custom CSS) +- Example: `graph TB` → `A[Login] --> B[Dashboard]` → `B --> C[Settings]` + +### Quality Checklist +- [ ] Requirements covered with traceability +- [ ] Existing implementation respected +- [ ] Steering compliant, deviations documented +- [ ] Architecture visualized with clear diagrams +- [ ] Components have Purpose, Key Features, Interface Design +- [ ] Data models individually documented +- [ ] Integration with existing system explained + +### 3. Design Document Generation & Metadata Update +- Generate complete design document following structure guidelines +- Update `@.kiro/specs/{{args}}/spec.json`: +```json +{ + "phase": "design-generated", + "approvals": { + "requirements": { "generated": true, "approved": true }, + "design": { "generated": true, "approved": false } + }, + "updated_at": "current_timestamp" +} +``` + +### Actionable Messages +If requirements are not approved and no `-y` flag: +- **Error Message**: "Requirements must be approved before generating design. Run `/kiro:spec-requirements {{args}}` to review requirements, then run `/kiro:spec-design {{args}} -y` to proceed." +- **Alternative**: "Or run `/kiro:spec-design {{args}} -y` to auto-approve requirements and generate design." + +### Conversation Guidance +After generation: +- Guide user to review design narrative and visualizations +- Suggest specific diagram additions if needed +- Direct to run `/kiro:spec-tasks {{args}} -y` when approved + +Create design document that tells complete story through clear narrative, structured components, and effective visualizations. think deeply +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/spec-impl.toml b/.gemini/commands/kiro/spec-impl.toml new file mode 100644 index 00000000..bd4eb969 --- /dev/null +++ b/.gemini/commands/kiro/spec-impl.toml @@ -0,0 +1,83 @@ +description = "Execute spec tasks using TDD methodology" + +prompt = """ +# Execute Spec Tasks with TDD + +Execute implementation tasks from spec using Kent Beck's Test-Driven Development methodology. + +## Arguments: {{args}} + +## Current Specs +Available specs: !{bash -c 'ls .kiro/specs/ 2>/dev/null || echo "No specs found"'} + +## Instructions + +### Help Mode (--help) +If arguments contain "--help", show usage: +``` +/kiro:spec-impl [feature-name] + +Examples: + /kiro:spec-impl auth-system 1.1 # Execute task 1.1 + /kiro:spec-impl auth-system 1,2,3 # Execute tasks 1, 2, 3 + /kiro:spec-impl auth-system --all # Execute all pending tasks +``` + +### Pre-Execution Validation +Feature name: **{{args}}** (first argument will be parsed as feature name) + +Validate required files exist: +Validate required files exist for feature **[feature-name]**: +- Requirements: `.kiro/specs/[feature-name]/requirements.md` +- Design: `.kiro/specs/[feature-name]/design.md` +- Tasks: `.kiro/specs/[feature-name]/tasks.md` +- Metadata: `.kiro/specs/[feature-name]/spec.json` + +### Project Context Loading +**Load all required content before execution:** + +**Core Steering:** +- Structure: @.kiro/steering/structure.md +- Tech Stack: @.kiro/steering/tech.md +- Product: @.kiro/steering/product.md + +**Custom Steering:** +- Additional `*.md` files in `.kiro/steering/` (excluding structure.md, tech.md, product.md) + +Core Steering and Custom Steering files will provide overall project context. + +**Spec Documents:** +Feature name directory: **{{args}}** (first argument) +- Metadata: @.kiro/specs/[feature-name]/spec.json +- Requirements: `.kiro/specs/[feature-name]/requirements.md` +- Design: `.kiro/specs/[feature-name]/design.md` +- Tasks: `.kiro/specs/[feature-name]/tasks.md` + + +### Task Execution +1. **Parse feature name and task numbers** from arguments +2. **Load all context** (steering + spec documents) +3. **Execute selected tasks** using TDD methodology + +### TDD Implementation +For each selected task: + +1. **RED**: Write failing tests first +2. **GREEN**: Write minimal code to pass tests +3. **REFACTOR**: Clean up and improve code structure +4. **Verify**: + - All tests pass + - No regressions in existing tests + - Code quality and test coverage maintained +5. **Mark Complete**: Update checkbox from `- [ ]` to `- [x]` in tasks.md + +**Note**: Follow Kent Beck's TDD methodology strictly, implementing only the specific task requirements. + +## Implementation Notes + +- **Feature**: Use `$1` for feature name +- **Tasks**: Use `$2` for specific task numbers (optional) +- **Validation**: Check all required spec files exist +- **TDD Focus**: Always write tests before implementation +- **Task Tracking**: Update checkboxes in tasks.md as completed +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/spec-init.toml b/.gemini/commands/kiro/spec-init.toml new file mode 100644 index 00000000..83343cf4 --- /dev/null +++ b/.gemini/commands/kiro/spec-init.toml @@ -0,0 +1,85 @@ +description = "Initialize a new specification with detailed project description and requirements" + +prompt = """ +# Spec Initialization + +Initialize a new specification based on the provided project description: + +**Project Description**: {{args}} + +## Task: Initialize Specification Structure + +**SCOPE**: This command initializes the directory structure and metadata based on the detailed project description provided. + +### 1. Generate Feature Name +Create a concise, descriptive feature name from the project description ({{args}}). +**Check existing `.kiro/specs/` directory to ensure the generated feature name is unique. If a conflict exists, append a number suffix (e.g., feature-name-2).** + +### 2. Create Spec Directory +Create `.kiro/specs/[generated-feature-name]/` directory with: +- `spec.json` - Metadata and approval tracking +- `requirements.md` - Lightweight template with project description + +**Note**: design.md and tasks.md will be created by their respective commands during the development process. + +### 3. Initialize spec.json Metadata +Create initial metadata with approval tracking: +```json +{ + "feature_name": "{generated-feature-name}", + "created_at": "current_timestamp", + "updated_at": "current_timestamp", + "language": "ja", + "phase": "initialized", + "approvals": { + "requirements": { + "generated": false, + "approved": false + }, + "design": { + "generated": false, + "approved": false + }, + "tasks": { + "generated": false, + "approved": false + } + }, + "ready_for_implementation": false +} +``` + +### 4. Create Requirements Template +Create requirements.md with project description: +```markdown +# Requirements Document + +## Project Description (Input) +{{args}} + +## Requirements + +``` + +### 5. Update GEMINI.md Reference +Add the new spec to the active specifications list with the generated feature name and a brief description. + +## Next Steps After Initialization + +Follow the strict spec-driven development workflow: +1. **`/kiro:spec-requirements [feature-name]`** - Create and generate requirements.md +2. **`/kiro:spec-design [feature-name]`** - Create and generate design.md (requires approved requirements) +3. **`/kiro:spec-tasks [feature-name]`** - Create and generate tasks.md (requires approved design) + +**Important**: Each phase creates its respective file and requires approval before proceeding to the next phase. + +## Output Format + +After initialization, provide: +1. Generated feature name and rationale +2. Brief project summary +3. Created spec.json path +4. **Clear next step**: `/kiro:spec-requirements [feature-name]` +5. Explanation that only spec.json was created, following stage-by-stage development principles + +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/spec-requirements.toml b/.gemini/commands/kiro/spec-requirements.toml new file mode 100644 index 00000000..328ab387 --- /dev/null +++ b/.gemini/commands/kiro/spec-requirements.toml @@ -0,0 +1,124 @@ +description = "Generate comprehensive requirements for a specification" + +prompt = """ +# Requirements Generation + +Generate comprehensive requirements for feature: **{{args}}** + +## Context Validation + +### Steering Context +- Architecture context: @.kiro/steering/structure.md +- Technical constraints: @.kiro/steering/tech.md +- Product context: @.kiro/steering/product.md +- Custom steering: Load all "Always" mode custom steering files from .kiro/steering/ + +### Existing Spec Context +- Current spec directory: !{bash -c 'ls -la .kiro/specs/{{args}}/'} +- Current requirements: @.kiro/specs/{{args}}/requirements.md +- Spec metadata: @.kiro/specs/{{args}}/spec.json + +## Task: Generate Initial Requirements + +Generate an initial set of requirements in EARS format based on the feature idea, then iterate with the user to refine them until they are complete and accurate. + +Don't focus on implementation details in this phase. Instead, just focus on writing requirements which will later be turned into a design. + +### Requirements Generation Guidelines +1. **Focus on Core Functionality**: Start with the essential features from the user's idea +2. **Use EARS Format**: All acceptance criteria must use proper EARS syntax +3. **No Sequential Questions**: Generate initial version first, then iterate based on user feedback +4. **Keep It Manageable**: Create a solid foundation that can be expanded through user review +5. **Choose an appropriate subject**: For software projects, use the concrete system/service name (e.g., "Checkout Service"). For non-software, select a responsible subject (e.g., process/workflow, team/role, artifact/document, campaign, protocol). + +### 1. EARS Format Requirements + +**EARS (Easy Approach to Requirements Syntax)** is the recommended format for acceptance criteria: + +**Primary EARS Patterns:** +- WHEN [event/condition] THEN [system/subject] SHALL [response] +- IF [precondition/state] THEN [system/subject] SHALL [response] +- WHILE [ongoing condition] THE [system/subject] SHALL [continuous behavior] +- WHERE [location/context/trigger] THE [system/subject] SHALL [contextual behavior] + +**Combined Patterns:** +- WHEN [event] AND [additional condition] THEN [system/subject] SHALL [response] +- IF [condition] AND [additional condition] THEN [system/subject] SHALL [response] + +### 2. Requirements Document Structure +Generate requirements.md in the language specified in spec.json (check `@.kiro/specs/{{args}}/spec.json` for "language" field): + +```markdown +# Requirements Document + +## Introduction +[Clear introduction summarizing the feature and its business value] + +## Requirements + +### Requirement 1: [Major Objective Area] +**Objective:** As a [role/stakeholder], I want [feature/capability/outcome], so that [benefit] + +#### Acceptance Criteria +This section should have EARS requirements + +1. WHEN [event] THEN [system/subject] SHALL [response] +2. IF [precondition] THEN [system/subject] SHALL [response] +3. WHILE [ongoing condition] THE [system/subject] SHALL [continuous behavior] +4. WHERE [location/context/trigger] THE [system/subject] SHALL [contextual behavior] + +### Requirement 2: [Next Major Objective Area] +**Objective:** As a [role/stakeholder], I want [feature/capability/outcome], so that [benefit] + +1. WHEN [event] THEN [system/subject] SHALL [response] +2. WHEN [event] AND [condition] THEN [system/subject] SHALL [response] + +### Requirement 3: [Additional Major Areas] +[Continue pattern for all major functional areas] +``` + +### 3. Update Metadata +Update spec.json with: +```json +{ + "phase": "requirements-generated", + "approvals": { + "requirements": { + "generated": true, + "approved": false + } + }, + "updated_at": "current_timestamp" +} +``` + +### 4. Document Generation Only +Generate the requirements document content ONLY. Do not include any review or approval instructions in the actual document file. + +--- + +## Next Phase: Interactive Approval + +After generating requirements.md, review the requirements and choose: + +**If requirements look good:** +Run `/kiro:spec-design {{args}} -y` to proceed to design phase + +**If requirements need modification:** +Request changes, then re-run this command after modifications + +The `-y` flag auto-approves requirements and generates design directly, streamlining the workflow while maintaining review enforcement. + +## Instructions + +1. **Check spec.json for language** - Use the language specified in the metadata +2. **Generate initial requirements** based on the feature idea WITHOUT asking sequential questions first +3. **Apply EARS format** - Use proper EARS syntax patterns for all acceptance criteria +4. **Focus on core functionality** - Start with essential features and user workflows +5. **Structure clearly** - Group related functionality into logical requirement areas +6. **Make requirements testable** - Each acceptance criterion should be verifiable +7. **Update tracking metadata** upon completion + +Generate requirements that provide a solid foundation for the design phase, focusing on the core functionality from the feature idea. +think deeply +""" diff --git a/.gemini/commands/kiro/spec-status.toml b/.gemini/commands/kiro/spec-status.toml new file mode 100644 index 00000000..bc5c7a20 --- /dev/null +++ b/.gemini/commands/kiro/spec-status.toml @@ -0,0 +1,96 @@ +description = "Show specification status and progress" +argument-hint = "[feature-name]" + +prompt = """ +# Specification Status + +Show current status and progress for feature: **{{args}}** + +## Spec Context + +### Spec Files +- Spec directory: !{bash -c 'ls -la .kiro/specs/{{args}}/'} +- Spec metadata: @.kiro/specs/{{args}}/spec.json +- Requirements: @.kiro/specs/{{args}}/requirements.md +- Design: @.kiro/specs/{{args}}/design.md +- Tasks: @.kiro/specs/{{args}}/tasks.md + +### All Specs Overview +- Available specs: !{bash -c 'ls -la .kiro/specs/'} +- Active specs: !{bash -c 'find .kiro/specs/ -name "spec.json" -exec grep -l "implementation_ready.*true" {} +'} + +## Task: Generate Status Report + +Create comprehensive status report for the specification in the language specified in spec.json (check `@.kiro/specs/{{args}}/spec.json` for "language" field): + +### 1. Specification Overview +Display: +- Feature name and description +- Creation date and last update +- Current phase (requirements/design/tasks/implementation) +- Overall completion percentage + +### 2. Phase Status +For each phase, show: +- ✅ **Requirements Phase**: [completion %] + - Requirements count: [number] + - Acceptance criteria defined: [yes/no] + - Requirements coverage: [complete/partial/missing] + +- ✅ **Design Phase**: [completion %] + - Architecture documented: [yes/no] + - Components defined: [yes/no] + - Diagrams created: [yes/no] + - Integration planned: [yes/no] + +- ✅ **Tasks Phase**: [completion %] + - Total tasks: [number] + - Completed tasks: [number] + - Remaining tasks: [number] + - Blocked tasks: [number] + +### 3. Implementation Progress +If in implementation phase: +- Task completion breakdown +- Current blockers or issues +- Estimated time to completion +- Next actions needed + +#### Task Completion Tracking +- Parse tasks.md checkbox status: `- [x]` (completed) vs `- [ ]` (pending) +- Count completed vs total tasks +- Show completion percentage +- Identify next uncompleted task + +### 4. Quality Metrics +Show: +- Requirements coverage: [percentage] +- Design completeness: [percentage] +- Task granularity: [appropriate/too large/too small] +- Dependencies resolved: [yes/no] + +### 5. Recommendations +Based on status, provide: +- Next steps to take +- Potential issues to address +- Suggested improvements +- Missing elements to complete + +### 6. Steering Alignment +Check alignment with steering documents: +- Architecture consistency: [aligned/misaligned] +- Technology stack compliance: [compliant/non-compliant] +- Product requirements alignment: [aligned/misaligned] + +## Instructions + +1. **Check spec.json for language** - Use the language specified in the metadata +2. **Parse all spec files** to understand current state +3. **Calculate completion percentages** for each phase +4. **Identify next actions** based on current progress +5. **Highlight any blockers** or issues +6. **Provide clear recommendations** for moving forward +7. **Check steering alignment** to ensure consistency + +Generate status report that provides clear visibility into spec progress and next steps. +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/spec-tasks.toml b/.gemini/commands/kiro/spec-tasks.toml new file mode 100644 index 00000000..6a0c29d7 --- /dev/null +++ b/.gemini/commands/kiro/spec-tasks.toml @@ -0,0 +1,175 @@ +description = "Generate implementation tasks for a specification" + +prompt = """ +# Implementation Tasks + +Generate detailed implementation tasks for feature: **{{args}}** + +## Task: Generate Implementation Tasks + +### Prerequisites & Context Loading +- If invoked with `-y` flag: Auto-approve requirements and design in `spec.json` +- Otherwise: Stop if requirements/design missing or unapproved with message: + "Run `/kiro:spec-requirements` and `/kiro:spec-design` first, or use `-y` flag to auto-approve" +- If tasks.md exists: Prompt [o]verwrite/[m]erge/[c]ancel + +**Context Loading (Full Paths)**: +1. `.kiro/specs/{{args}}/requirements.md` - Feature requirements (EARS format) +2. `.kiro/specs/{{args}}/design.md` - Technical design document +3. `.kiro/steering/` - Project-wide guidelines and constraints: + - **Core files (always load)**: + - @.kiro/steering/product.md - Business context, product vision, user needs + - @.kiro/steering/tech.md - Technology stack, frameworks, libraries + - @.kiro/steering/structure.md - File organization, naming conventions, code patterns + - **Custom steering files** (load all EXCEPT "Manual" mode in `AGENTS.md`): + - Any additional `*.md` files in `.kiro/steering/` directory + - Examples: `api.md`, `testing.md`, `security.md`, etc. + - (Task planning benefits from comprehensive context) +4. `.kiro/specs/{{args}}/tasks.md` - Existing tasks (only if merge mode) + +### CRITICAL Task Numbering Rules (MUST FOLLOW) + +**⚠️ MANDATORY: Sequential major task numbering & hierarchy limits** +- Major tasks: 1, 2, 3, 4, 5... (MUST increment sequentially) +- Sub-tasks: 1.1, 1.2, 2.1, 2.2... (reset per major task) +- **Maximum 2 levels of hierarchy** (no 1.1.1 or deeper) +- Format exactly as: +```markdown +- [ ] 1. Major task description +- [ ] 1.1 Sub-task description + - Detail item 1 + - Detail item 2 + - _Requirements: X.X, Y.Y_ + +- [ ] 1.2 Sub-task description + - Detail items... + - _Requirements: X.X_ + +- [ ] 2. Next major task (NOT 1 again!) +- [ ] 2.1 Sub-task... +``` + +### Task Generation Rules + +1. **Natural language descriptions**: Focus on capabilities and outcomes, not code structure + - Describe **what functionality to achieve**, not file locations or code organization + - Specify **business logic and behavior**, not method signatures or type definitions + - Reference **features and capabilities**, not class names or API contracts + - Use **domain language**, not programming constructs + - **Avoid**: File paths, function/method names, type signatures, class/interface names, specific data structures + - **Include**: User-facing functionality, business rules, system behaviors, data relationships + - Implementation details (files, methods, types) come from design.md +2. **Task integration & progression**: + - Each task must build on previous outputs (no orphaned code) + - End with integration tasks to wire everything together + - No hanging features - every component must connect to the system + - Incremental complexity - no big jumps between tasks + - Validate core functionality early in the sequence +3. **Flexible task sizing**: + - Major tasks: As many sub-tasks as logically needed + - Sub-tasks: 1-3 hours each, 3-10 details per sub + - Group by cohesion, not arbitrary numbers + - Balance between too granular and too broad +4. **Requirements mapping**: End details with `_Requirements: X.X, Y.Y_` or `_Requirements: [description]_` +5. **Code-only focus**: Include ONLY coding/testing tasks, exclude deployment/docs/user testing + +### Example Structure (FORMAT REFERENCE ONLY) + +```markdown +# Implementation Plan + +- [ ] 1. Set up project foundation and infrastructure + - Initialize project with required technology stack + - Configure server infrastructure and request handling + - Establish data storage and caching layer + - Set up configuration and environment management + - _Requirements: All requirements need foundational setup_ + +- [ ] 2. Build authentication and user management system +- [ ] 2.1 Implement core authentication functionality + - Set up user data storage with validation rules + - Implement secure authentication mechanism + - Build user registration functionality + - Add login and session management features + - _Requirements: 7.1, 7.2_ + +- [ ] 2.2 Enable email service integration + - Implement secure credential storage system + - Build authentication flow for email providers + - Create email connection validation logic + - Develop email account management features + - _Requirements: 5.1, 5.2, 5.4_ +``` + +### Requirements Coverage Check +- **MANDATORY**: Ensure ALL requirements from requirements.md are 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 + +### Document Generation +- Generate `.kiro/specs/{{args}}/tasks.md` using the exact numbering format above +- **Language**: Use language from `spec.json.language` field, default to English +- **Task descriptions**: Use natural language for "what to do" (implementation details in design.md) + - Update `.kiro/specs/{{args}}/spec.json`: + - Set `phase: "tasks-generated"` + - Set approvals map exactly as: + - `approvals.tasks = { "generated": true, "approved": false }` + - Preserve existing metadata (e.g., `language`), do not remove unrelated fields + - If invoked with `-y` flag: ensure the above approval booleans are applied even if previously unset/false + - Set `updated_at` to current ISO8601 timestamp + - Use file tools only (no shell commands) + +--- + +## INTERACTIVE APPROVAL IMPLEMENTED (Not included in document) + +The following is for Claude Code conversation only - NOT for the generated document: + +## Next Phase: Implementation Ready + +After generating tasks.md, review the implementation tasks: + +**If tasks look good:** +Begin implementation following the generated task sequence + +**If tasks need modification:** +Request changes and re-run this command after modifications + +Tasks represent the final planning phase - implementation can begin once tasks are approved. + +**Final approval process for implementation**: +``` +📋 Tasks review completed. Ready for implementation. +📄 Generated: .kiro/specs/{{args}}/tasks.md +✅ All phases approved. Implementation can now begin. +``` + +### Next Steps: Implementation +Once tasks are approved, start implementation: +```bash +/kiro:spec-impl {{args}} # Execute all pending tasks +/kiro:spec-impl {{args}} 1.1 # Execute specific task +/kiro:spec-impl {{args}} 1,2,3 # Execute multiple tasks +``` + +**Implementation Tips**: +- Use `/clear` if conversation becomes too long, then continue with spec commands +- All spec files (.kiro/specs/) are preserved and will be reloaded as needed + +### Review Checklist (for user reference): +- [ ] Tasks are properly sized (1-3 hours each) +- [ ] All requirements are covered by tasks +- [ ] Task dependencies are correct +- [ ] Technology choices match the design +- [ ] Testing tasks are included + +### Implementation Instructions +When tasks are approved, the implementation phase begins: +1. Work through tasks sequentially +2. Mark tasks as completed in tasks.md +3. Each task should produce working, tested code +4. Commit code after each major task completion + +think deeply +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/steering-custom.toml b/.gemini/commands/kiro/steering-custom.toml new file mode 100644 index 00000000..773e9b39 --- /dev/null +++ b/.gemini/commands/kiro/steering-custom.toml @@ -0,0 +1,152 @@ +description = "Create custom Kiro steering documents for specialized project contexts" + +prompt = """ +# Kiro Custom Steering Creation + +Create custom steering documents in `.kiro/steering/` for specialized contexts beyond the three foundational files (product.md, tech.md, structure.md). + +## Current Steering Status + +### Existing Steering Documents +- Core steering files: !{bash -c 'ls -la .kiro/steering/*.md 2>/dev/null || echo "No steering directory found"'} +- Custom steering count: !{bash -c 'find .kiro/steering -maxdepth 1 -name '"'"'*.md'"'"' ! -name '"'"'product.md'"'"' ! -name '"'"'tech.md'"'"' ! -name '"'"'structure.md'"'"' 2>/dev/null | wc -l || echo "0"'} + +### Project Analysis +- Specialized areas: !{bash -c 'find . -name "test*" -o -name "spec*" -o -name "api" -o -name "auth" -o -name "security" 2>/dev/null || echo "No specialized directories found"'} +- Config patterns: !{bash -c 'find . -name "*.config.*" -o -name "*rc.*" -o -name ".*rc" 2>/dev/null || echo "No config files found"'} + +## Task: Create Custom Steering Document + +You will create a new custom steering document based on user requirements. Common use cases include: + +### Common Custom Steering Types + +1. **API Standards** (`api-standards.md`) + - REST/GraphQL conventions + - Error handling patterns + - Authentication/authorization approaches + - Rate limiting and pagination + - API versioning strategy + +2. **Testing Approach** (`testing.md`) + - Test file organization + - Naming conventions for tests + - Mocking strategies + - Coverage requirements + - E2E vs unit vs integration testing + +3. **Code Style Guidelines** (`code-style.md`) + - Language-specific conventions + - Formatting rules beyond linters + - Comment standards + - Function/variable naming patterns + - Code organization principles + +4. **Security Policies** (`security.md`) + - Input validation requirements + - Authentication patterns + - Secrets management + - OWASP compliance guidelines + - Security review checklist + +5. **Database Conventions** (`database.md`) + - Schema design patterns + - Migration strategies + - Query optimization guidelines + - Connection pooling settings + - Backup and recovery procedures + +6. **Performance Standards** (`performance.md`) + - Load time requirements + - Memory usage limits + - Optimization techniques + - Caching strategies + - Monitoring and profiling + +7. **Deployment Workflow** (`deployment.md`) + - CI/CD pipeline stages + - Environment configurations + - Release procedures + - Rollback strategies + - Health check requirements + +## Inclusion Mode Selection + +Choose the inclusion mode based on how frequently and in what context this steering document should be referenced: + +### 1. Always Included (Use sparingly for custom files) +- **When to use**: Universal standards that apply to ALL code (security policies, core conventions) +- **Impact**: Increases context size for every interaction +- **Example**: `security-standards.md` for critical security requirements +- **Recommendation**: Only use for truly universal guidelines + +### 2. Conditional Inclusion (Recommended for most custom files) +- **When to use**: Domain-specific guidelines for particular file types or directories +- **File patterns**: `"*.test.js"`, `"src/api/**/*"`, `"**/auth/*"`, `"*.config.*"` +- **Example**: `testing-approach.md` only loads when editing test files +- **Benefits**: Relevant context without overwhelming general interactions + +### 3. Manual Inclusion (Best for specialized contexts) +- **When to use**: Specialized knowledge needed occasionally +- **Usage**: Reference with `@filename.md` during specific conversations +- **Example**: `deployment-runbook.md` for deployment-specific tasks +- **Benefits**: Available when needed, doesn't clutter routine interactions + +## Document Structure Guidelines + +Create the custom steering document with: + +1. **Clear Title and Purpose** + - What aspect of the project this document covers + - When this guidance should be applied + +2. **Specific Guidelines** + - Concrete rules and patterns to follow + - Rationale for important decisions + +3. **Code Examples** + - Show correct implementation patterns + - Include counter-examples if helpful + +4. **Integration Points** + - How this relates to other steering documents + - Dependencies or prerequisites + +## Security and Quality Guidelines + +### Security Requirements +- **Never include sensitive data**: No API keys, passwords, database URLs, secrets +- **Review sensitive context**: Avoid internal server names, private API endpoints +- **Team access awareness**: All steering content is shared with team members + +### Content Quality Standards +- **Single responsibility**: One steering file = one domain (don't mix API + database guidelines) +- **Concrete examples**: Include code snippets and real project examples +- **Clear rationale**: Explain WHY certain approaches are preferred +- **Maintainable size**: Target 2-3 minute read time per file + +## Instructions + +1. **Ask the user** for: + - Document name (descriptive filename ending in .md) + - Topic/purpose of the custom steering + - Inclusion mode preference + - Specific patterns for conditional inclusion (if applicable) + +2. **Create the document** in `.kiro/steering/` with: + - Clear, focused content (2-3 minute read) + - Practical examples + - Consistent formatting with other steering files + +3. **Document the inclusion mode** by adding a comment at the top: + ```markdown + + ``` + +4. **Validate** that the document: + - Doesn't duplicate existing steering content + - Provides unique value for the specified context + - Follows markdown best practices + +Remember: Custom steering documents should supplement, not replace, the foundational three files. They provide specialized context for specific aspects of your project. +""" diff --git a/.gemini/commands/kiro/steering.toml b/.gemini/commands/kiro/steering.toml new file mode 100644 index 00000000..fa387f8a --- /dev/null +++ b/.gemini/commands/kiro/steering.toml @@ -0,0 +1,169 @@ +description = "Create or update Kiro steering documents intelligently based on project state" + +prompt = """ +# Kiro Steering Management + +Intelligently create or update steering documents in `.kiro/steering/` to maintain accurate project knowledge for spec-driven development. This command detects existing documents and handles them appropriately. + +## Existing Files Check + +### Current steering documents status +- Product overview: !{bash -c '[ -f ".kiro/steering/product.md" ] && echo "✅ EXISTS - Will be updated preserving custom content" || echo "📝 Not found - Will be created"'} +- Technology stack: !{bash -c '[ -f ".kiro/steering/tech.md" ] && echo "✅ EXISTS - Will be updated preserving custom content" || echo "📝 Not found - Will be created"'} +- Project structure: !{bash -c '[ -f ".kiro/steering/structure.md" ] && echo "✅ EXISTS - Will be updated preserving custom content" || echo "📝 Not found - Will be created"'} +- Custom steering files: !{bash -c 'find .kiro/steering -maxdepth 1 -name '"'"'*.md'"'"' ! -name '"'"'product.md'"'"' ! -name '"'"'tech.md'"'"' ! -name '"'"'structure.md'"'"' 2>/dev/null && echo "🔧 Custom files found - Will be preserved" || echo "📋 No custom files"'} + +## Project Analysis + +### Current Project State +- Project files: !{bash -c 'find . -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.java" -o -name "*.go" -o -name "*.rs" 2>/dev/null || echo "No source files found"'} +- Configuration files: !{bash -c 'find . -maxdepth 3 -name "package.json" -o -name "requirements.txt" -o -name "pom.xml" -o -name "Cargo.toml" -o -name "go.mod" -o -name "pyproject.toml" -o -name "tsconfig.json" 2>/dev/null || echo "No config files found"'} +- Documentation: !{bash -c 'find . -maxdepth 3 -name "README*" -o -name "CHANGELOG*" -o -name "LICENSE*" -o -name "*.md" 2>/dev/null || echo "No documentation files found"'} + +### Recent Changes (if updating) +- Last steering update: !{bash -c 'git log -1 --oneline -- .kiro/steering/ 2>/dev/null || echo "No previous steering commits"'} +- Commits since last steering update: !{bash -c 'git log --oneline --max-count=20 2>/dev/null || echo "Not a git repository"'} +- Working tree status: !{bash -c 'git status --porcelain 2>/dev/null || echo "Not a git repository"'} + +### Existing Documentation +- Main README: @README.md +- Package configuration: @package.json +- Python requirements: @requirements.txt +- TypeScript config: @tsconfig.json +- Project documentation: @docs/ + +## Smart Update Strategy + +Based on the existing files check above, this command will: + +### For NEW files (showing "📝 Not found"): +Generate comprehensive initial content covering all aspects of the project. + +### For EXISTING files (showing "✅ EXISTS"): +1. **Preserve user customizations** - Any manual edits or custom sections +2. **Update factual information** - Dependencies, file structures, commands +3. **Add new sections** - Only if significant new capabilities exist +4. **Mark deprecated content** - Rather than deleting +5. **Maintain formatting** - Keep consistent with existing style + +## Inclusion Modes for Core Steering Files + +The three core steering files (product.md, tech.md, structure.md) are designed to be **Always Included** - loaded in every AI interaction to provide consistent project context. + +### Understanding Inclusion Modes +- **Always Included (Default for core files)**: Loaded in every interaction - ensures consistent project knowledge +- **Conditional**: Loaded only when working with matching file patterns (mainly for custom steering) +- **Manual**: Referenced on-demand with @filename syntax (for specialized contexts) + +### Core Files Strategy +- `product.md`: Always - Business context needed for all development decisions +- `tech.md`: Always - Technical constraints affect all code generation +- `structure.md`: Always - Architectural decisions impact all file organization + +## Task: Create or Update Steering Documents + +### 1. Product Overview (`product.md`) + +#### For NEW file: +Generate comprehensive product overview including: +- **Product Overview**: Brief description of what the product is +- **Core Features**: Bulleted list of main capabilities +- **Target Use Case**: Specific scenarios the product addresses +- **Key Value Proposition**: Unique benefits and differentiators + +#### For EXISTING file: +Update only if there are: +- **New features** added to the product +- **Removed features** or deprecated functionality +- **Changed use cases** or target audience +- **Updated value propositions** or benefits + +### 2. Technology Stack (`tech.md`) + +#### For NEW file: +Document the complete technology landscape: +- **Architecture**: High-level system design +- **Frontend**: Frameworks, libraries, build tools (if applicable) +- **Backend**: Language, framework, server technology (if applicable) +- **Development Environment**: Required tools and setup +- **Common Commands**: Frequently used development commands +- **Environment Variables**: Key configuration variables +- **Port Configuration**: Standard ports used by services + +#### For EXISTING file: +Check for changes in: +- **New dependencies** added via package managers +- **Removed libraries** or frameworks +- **Version upgrades** of major dependencies +- **New development tools** or build processes +- **Changed environment variables** or configuration +- **Modified port assignments** or service architecture + +### 3. Project Structure (`structure.md`) + +#### For NEW file: +Outline the codebase organization: +- **Root Directory Organization**: Top-level structure with descriptions +- **Subdirectory Structures**: Detailed breakdown of key directories +- **Code Organization Patterns**: How code is structured +- **File Naming Conventions**: Standards for naming files and directories +- **Import Organization**: How imports/dependencies are organized +- **Key Architectural Principles**: Core design decisions and patterns + +#### For EXISTING file: +Look for changes in: +- **New directories** or major reorganization +- **Changed file organization** patterns +- **New or modified naming conventions** +- **Updated architectural patterns** or principles +- **Refactored code structure** or module boundaries + +### 4. Custom Steering Files +If custom steering files exist: +- **Preserve them** - Do not modify unless specifically outdated +- **Check relevance** - Note if they reference removed features +- **Suggest new custom files** - If new specialized areas emerge + +## Instructions + +1. **Create `.kiro/steering/` directory** if it doesn't exist +2. **Check existing files** to determine create vs update mode +3. **Analyze the codebase** using available tools +4. **For NEW files**: Generate comprehensive initial documentation +5. **For EXISTING files**: + - Read current content first + - Preserve user customizations and comments + - Update only factual/technical information + - Maintain existing structure and style +6. **Use clear markdown formatting** with proper headers and sections +7. **Include concrete examples** where helpful for understanding +8. **Focus on facts over assumptions** - document what exists +9. **Follow spec-driven development principles** + +## Important Principles + +### Security Guidelines +- **Never include sensitive data**: No API keys, passwords, database credentials, or personal information +- **Review before commit**: Always review steering content before version control +- **Team sharing consideration**: Remember steering files are shared with all project collaborators + +### Content Quality Guidelines +- **Single domain focus**: Each steering file should cover one specific area +- **Clear, descriptive content**: Provide concrete examples and rationale for decisions +- **Regular maintenance**: Review and update steering files after major project changes +- **Actionable guidance**: Write specific, implementable guidelines rather than abstract principles + +### Preservation Strategy +- **User sections**: Any section not in the standard template should be preserved +- **Custom examples**: User-added examples should be maintained +- **Comments**: Inline comments or notes should be kept +- **Formatting preferences**: Respect existing markdown style choices + +### Update Philosophy +- **Additive by default**: Add new information rather than replacing +- **Mark deprecation**: Use strikethrough or [DEPRECATED] tags +- **Date significant changes**: Add update timestamps for major changes +- **Explain changes**: Brief notes on why something was updated + +The goal is to maintain living documentation that stays current while respecting user customizations, supporting effective spec-driven development without requiring users to worry about losing their work. +""" diff --git a/.gemini/commands/kiro/validate-design.toml b/.gemini/commands/kiro/validate-design.toml new file mode 100644 index 00000000..54ff3b4f --- /dev/null +++ b/.gemini/commands/kiro/validate-design.toml @@ -0,0 +1,178 @@ +description = "Interactive technical design quality review and validation" + +prompt = """ +# Technical Design Validation + +Interactive design quality review for feature: **{{args}}** + +## Context Loading + +### Prerequisites Validation +- Design document must exist: `.kiro/specs/{{args}}/design.md` +- If not exist, stop with message: "Run `/kiro:spec-design {{args}}` first to generate design document" + +### Review Context +- Spec metadata: @.kiro/specs/{{args}}/spec.json +- Requirements document: @.kiro/specs/{{args}}/requirements.md +- Design document: @.kiro/specs/{{args}}/design.md +- Core steering documents: + - Architecture: @.kiro/steering/structure.md + - Technology: @.kiro/steering/tech.md + - Product context: @.kiro/steering/product.md +- Custom steering: All additional `.md` files in `.kiro/steering/` directory + +## Task: Interactive Design Quality Review + +### Review Methodology + +**Focus**: Critical issues only - limit to 3 most important concerns +**Format**: Interactive dialogue with immediate feedback and improvement suggestions +**Outcome**: GO/NO-GO decision with clear rationale + +### Core Review Criteria + +#### 1. Existing Architecture Alignment (Critical) +**Evaluation Points**: +- Integration with existing system boundaries and layers +- Consistency with established architectural patterns +- Proper dependency direction and coupling management +- Alignment with current module organization and responsibilities + +**Review Questions**: +- Does this design respect existing architectural boundaries? +- Are new components properly integrated with existing systems? +- Does the design follow established patterns and conventions? + +#### 2. Design Consistency & Standards +**Evaluation Points**: +- Adherence to project naming conventions and code standards +- Consistent error handling and logging strategies +- Uniform approach to configuration and dependency management +- Alignment with established data modeling patterns + +**Review Questions**: +- Is the design consistent with existing code standards? +- Are error handling and configuration approaches unified? +- Does naming and structure follow project conventions? + +#### 3. Extensibility & Maintainability +**Evaluation Points**: +- Design flexibility for future requirements changes +- Clear separation of concerns and single responsibility principle +- Testability and debugging considerations +- Documentation and code clarity requirements + +**Review Questions**: +- How well does this design handle future changes? +- Are responsibilities clearly separated and testable? +- Is the design complexity appropriate for the requirements? + +#### 4. Type Safety & Interface Design +**Evaluation Points** (for TypeScript projects): +- Proper type definitions and interface contracts +- Avoidance of `any` types and unsafe patterns +- Clear API boundaries and data structure definitions +- Input validation and error handling coverage + +**Review Questions**: +- Are types properly defined and interfaces clear? +- Is the API design robust and well-defined? +- Are edge cases and error conditions handled appropriately? + +### Interactive Review Process + +#### Step 1: Design Analysis +Thoroughly analyze the design document against all review criteria, identifying the most critical issues that could impact: +- System integration and compatibility +- Long-term maintainability +- Implementation complexity and risks +- Requirements fulfillment accuracy + +#### Step 2: Critical Issues Identification +**Limit to 3 most important concerns maximum**. For each critical issue: + +**Issue Format**: +``` +🔴 **Critical Issue [1-3]**: [Brief title] +**Concern**: [Specific problem description] +**Impact**: [Why this matters for the project] +**Suggestion**: [Concrete improvement recommendation] +``` + +#### Step 3: Design Strengths Recognition +Acknowledge 1-2 strong aspects of the design to maintain balanced feedback. + +#### Step 4: GO/NO-GO Decision + +**GO Criteria**: +- No critical architectural misalignment +- Requirements adequately addressed +- Implementation path is clear and reasonable +- Risks are acceptable and manageable + +**NO-GO Criteria**: +- Fundamental architectural conflicts +- Critical requirements not addressed +- Implementation approach has high failure risk +- Design complexity disproportionate to requirements + +### Output Format + +Generate review in the language specified in spec.json (check `.kiro/specs/{{args}}/spec.json` for "language" field): + +#### Design Review Summary +Brief overview of the design's overall quality and readiness. + +#### Critical Issues (Maximum 3) +For each issue identified: +- **Issue**: Clear problem statement +- **Impact**: Why it matters +- **Recommendation**: Specific improvement suggestion + +#### Design Strengths +1-2 positive aspects worth highlighting. + +#### Final Assessment +**Decision**: GO / NO-GO +**Rationale**: Clear reasoning for the decision +**Next Steps**: What should happen next + +#### Interactive Discussion +Engage in dialogue about: +- Designer's perspective on identified issues +- Alternative approaches or trade-offs +- Clarification of design decisions +- Agreement on necessary changes (if any) + +## 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 + +## Instructions + +1. **Load all context documents** - Understand full project scope +2. **Analyze design thoroughly** - Review against all criteria +3. **Identify critical issues only** - Focus on most important problems +4. **Engage interactively** - Discuss findings with user +5. **Make clear decision** - Provide definitive GO/NO-GO +6. **Guide next steps** - Clear direction for proceeding + +**Remember**: This is quality assurance, not perfection seeking. The goal is ensuring the design is solid enough to proceed to implementation with acceptable risk. + +--- + +## Next Phase: Task Generation + +After design validation: + +**If design passes validation (GO decision):** +Run `/kiro:spec-tasks {{args}}` to generate implementation tasks + +**Auto-approve and proceed:** +Run `/kiro:spec-tasks {{args}} -y` to auto-approve requirements and design, then generate tasks directly +""" \ No newline at end of file diff --git a/.gemini/commands/kiro/validate-gap.toml b/.gemini/commands/kiro/validate-gap.toml new file mode 100644 index 00000000..1ba49c0d --- /dev/null +++ b/.gemini/commands/kiro/validate-gap.toml @@ -0,0 +1,154 @@ +description = "Analyze implementation gap between requirements and existing codebase" + +prompt = """ +# Implementation Gap Validation + +Analyze implementation requirements and existing codebase for feature: **{{args}}** + +## Context Validation + +### Steering Context +- Architecture context: @.kiro/steering/structure.md +- Technical constraints: @.kiro/steering/tech.md +- Product context: @.kiro/steering/product.md +- Custom steering: Load all "Always" mode custom steering files from `.kiro/steering/` + +### Existing Spec Context +- Current spec directory: !{bash -c 'ls -la .kiro/specs/{{args}}/'} +- Requirements document: @.kiro/specs/{{args}}/requirements.md +- Spec metadata: @.kiro/specs/{{args}}/spec.json + +## Task: Implementation Gap Analysis + +### Prerequisites +- Requirements document must exist: `.kiro/specs/{{args}}/requirements.md` +- If not exist, stop with message: "Run `/kiro:spec-requirements {{args}}` first to generate requirements" + +### Analysis Process + +#### 1. Current State Investigation +**Existing Codebase Analysis**: +- Identify files and modules related to the feature domain +- Map current architecture patterns, conventions, and tech stack usage +- Document existing services, utilities, and reusable components +- Understand current data models, APIs, and integration patterns + +**Code Structure Assessment**: +- Document file organization, naming conventions, and architectural layers +- Extract import/export patterns and module dependency structures +- Identify existing testing patterns (file placement, frameworks, mocking approaches) +- Map API client, database, and authentication implementation approaches currently used +- Note established coding standards and development practices + +#### 2. Requirements Feasibility Analysis +**Technical Requirements Extraction**: +- Parse EARS format requirements from requirements.md +- Identify technical components needed for each requirement +- Extract non-functional requirements (security, performance, etc.) +- Map business logic complexity and integration points + +**Gap Identification**: +- Missing technical capabilities vs requirements +- Unknown technologies or external dependencies +- Potential integration challenges with existing systems +- Areas requiring research or proof-of-concept work + +#### 3. Implementation Approach Options +**Multiple Strategy Evaluation**: +- **Option A**: Extend existing components/files + - Which existing files/modules to extend + - Compatibility with current patterns + - Code complexity and maintainability impact + +- **Option B**: Create new components (when justified) + - Clear rationale for new file creation + - Integration points with existing system + - Responsibility boundaries and interfaces + +- **Option C**: Hybrid approach + - Combination of extension and new creation + - Phased implementation strategy + - Risk mitigation approach + +#### 4. Technical Research Requirements +**External Dependencies Analysis** (if any): +- Required libraries, APIs, or services not currently used +- Version compatibility with existing dependencies +- Authentication, configuration, and setup requirements +- Rate limits, usage constraints, and cost implications + +**Knowledge Gap Assessment**: +- Technologies unfamiliar to the team +- Complex integration patterns requiring research +- Performance or security considerations needing investigation +- Best practice research requirements + +#### 5. Implementation Complexity Assessment +**Effort Estimation**: +- **Small (S)**: 1-3 days, mostly using existing patterns +- **Medium (M)**: 3-7 days, some new patterns or integrations +- **Large (L)**: 1-2 weeks, significant new functionality +- **Extra Large (XL)**: 2+ weeks, complex architecture changes + +**Risk Factors**: +- High: Unknown technologies, complex integrations, architectural changes +- Medium: New patterns, external dependencies, performance requirements +- Low: Extending existing patterns, well-understood technologies + +### Output Format + +Generate analysis in the language specified in spec.json (check `.kiro/specs/{{args}}/spec.json` for "language" field): + +#### Analysis Summary +- Feature scope and complexity overview +- Key technical challenges identified +- Overall implementation approach recommendation + +#### Existing Codebase Insights +- Relevant existing components and their current responsibilities +- Established patterns and conventions to follow +- Reusable utilities and services available + +#### Implementation Strategy Options +For each viable approach: +- **Approach**: [Extension/New/Hybrid] +- **Rationale**: Why this approach makes sense +- **Trade-offs**: Pros and cons of this approach +- **Complexity**: [S/M/L/XL] with reasoning + +#### Technical Research Needs +- External dependencies requiring investigation +- Unknown technologies needing research +- Integration patterns requiring proof-of-concept +- Performance or security considerations to investigate + +#### Recommendations for Design Phase +- Preferred implementation approach with rationale +- Key architectural decisions that need to be made +- Areas requiring further investigation during design +- Potential risks to address in design phase + +## Instructions + +1. **Check spec.json for language** - Use the language specified in the metadata +2. **Prerequisites validation** - Ensure requirements are approved +3. **Thorough investigation** - Analyze existing codebase comprehensively +4. **Multiple options** - Present viable implementation approaches +5. **Information focus** - Provide analysis, not final decisions +6. **Research identification** - Flag areas needing investigation +7. **Design preparation** - Set up design phase for success + +**CRITICAL**: This is an analysis phase. Provide information and options, not final implementation decisions. The design phase will make strategic choices based on this analysis. + +--- + +## Next Phase: Design Generation + +After validation, proceed to design phase: + +**Generate design based on analysis:** +Run `/kiro:spec-design {{args}}` to create technical design document + +**Auto-approve and proceed:** +Run `/kiro:spec-design {{args}} -y` to auto-approve requirements and generate design directly +""" \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..57edc579 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,72 @@ +# Gemini CLI Spec-Driven Development + +Kiro-style Spec Driven Development implementation using gemini cli slash commands. + +## Project Context + +### Paths +- Steering: `.kiro/steering/` +- Specs: `.kiro/specs/` +- Commands: `.gemini/commands/` + +### Steering vs Specification + +**Steering** (`.kiro/steering/`) - Guide AI with project-wide rules and context +**Specs** (`.kiro/specs/`) - Formalize development process for individual features + +### Active Specifications +- Check `.kiro/specs/` for active specifications +- Use `/kiro:spec-status [feature-name]` to check progress + +## Development Guidelines +- Think in English, but generate responses in Japanese (思考は英語、回答の生成は日本語で行うように) + +## Workflow + +### Phase 0: Steering (Optional) +`/kiro:steering` - Create/update steering documents +`/kiro:steering-custom` - Create custom steering for specialized contexts + +Note: Optional for new features or small additions. You can proceed directly to spec-init. + +### Phase 1: Specification Creation +1. `/kiro:spec-init [detailed description]` - Initialize spec with detailed project description +2. `/kiro:spec-requirements [feature]` - Generate requirements document +3. `/kiro:spec-design [feature]` - Interactive: "Have you reviewed requirements.md? [y/N]" +4. `/kiro:spec-tasks [feature]` - Interactive: Confirms both requirements and design review + +### Phase 2: Progress Tracking +`/kiro:spec-status [feature]` - Check current progress and phases + +## Development Rules +1. **Consider steering**: Run `/kiro:steering` before major development (optional for new features) +2. **Follow 3-phase approval workflow**: Requirements → Design → Tasks → Implementation +3. **Approval required**: Each phase requires human review (interactive prompt or manual) +4. **No skipping phases**: Design requires approved requirements; Tasks require approved design +5. **Update task status**: Mark tasks as completed when working on them +6. **Keep steering current**: Run `/kiro:steering` after significant changes +7. **Check spec compliance**: Use `/kiro:spec-status` to verify alignment + +## Steering Configuration + +### Current Steering Files +Managed by `/kiro:steering` command. Updates here reflect command changes. + +### Active Steering Files +- `product.md`: Always included - Product context and business objectives +- `tech.md`: Always included - Technology stack and architectural decisions +- `structure.md`: Always included - File organization and code patterns + +### Custom Steering Files + + + +### Inclusion Modes +- **Always**: Loaded in every interaction (default) +- **Conditional**: Loaded for specific file patterns (e.g., "*.test.js") +- **Manual**: Reference with `@filename.md` syntax +