diff --git a/.kiro/settings/mcp.json b/.kiro/settings/mcp.json new file mode 100644 index 00000000..53f188a2 --- /dev/null +++ b/.kiro/settings/mcp.json @@ -0,0 +1,4 @@ +{ + "mcpServers": { + } +} diff --git a/.kiro/settings/rules/design-discovery-full.md b/.kiro/settings/rules/design-discovery-full.md new file mode 100644 index 00000000..b80c2f26 --- /dev/null +++ b/.kiro/settings/rules/design-discovery-full.md @@ -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 \ No newline at end of file diff --git a/.kiro/settings/rules/design-discovery-light.md b/.kiro/settings/rules/design-discovery-light.md new file mode 100644 index 00000000..7a00ae29 --- /dev/null +++ b/.kiro/settings/rules/design-discovery-light.md @@ -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 \ No newline at end of file diff --git a/.kiro/settings/rules/design-principles.md b/.kiro/settings/rules/design-principles.md new file mode 100644 index 00000000..cb12e95f --- /dev/null +++ b/.kiro/settings/rules/design-principles.md @@ -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 diff --git a/.kiro/settings/rules/design-review-gate.md b/.kiro/settings/rules/design-review-gate.md new file mode 100644 index 00000000..06bc5feb --- /dev/null +++ b/.kiro/settings/rules/design-review-gate.md @@ -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. diff --git a/.kiro/settings/rules/design-review.md b/.kiro/settings/rules/design-review.md new file mode 100644 index 00000000..3209d8df --- /dev/null +++ b/.kiro/settings/rules/design-review.md @@ -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 diff --git a/.kiro/settings/rules/design-synthesis.md b/.kiro/settings/rules/design-synthesis.md new file mode 100644 index 00000000..935e4d6f --- /dev/null +++ b/.kiro/settings/rules/design-synthesis.md @@ -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 diff --git a/.kiro/settings/rules/ears-format.md b/.kiro/settings/rules/ears-format.md new file mode 100644 index 00000000..cef8e7df --- /dev/null +++ b/.kiro/settings/rules/ears-format.md @@ -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]. diff --git a/.kiro/settings/rules/gap-analysis.md b/.kiro/settings/rules/gap-analysis.md new file mode 100644 index 00000000..c4e4bca8 --- /dev/null +++ b/.kiro/settings/rules/gap-analysis.md @@ -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 diff --git a/.kiro/settings/rules/requirements-review-gate.md b/.kiro/settings/rules/requirements-review-gate.md new file mode 100644 index 00000000..b5c61dcc --- /dev/null +++ b/.kiro/settings/rules/requirements-review-gate.md @@ -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. diff --git a/.kiro/settings/rules/steering-principles.md b/.kiro/settings/rules/steering-principles.md new file mode 100644 index 00000000..b3ac5f5e --- /dev/null +++ b/.kiro/settings/rules/steering-principles.md @@ -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.) diff --git a/.kiro/settings/rules/tasks-generation.md b/.kiro/settings/rules/tasks-generation.md new file mode 100644 index 00000000..58060974 --- /dev/null +++ b/.kiro/settings/rules/tasks-generation.md @@ -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. diff --git a/.kiro/settings/rules/tasks-parallel-analysis.md b/.kiro/settings/rules/tasks-parallel-analysis.md new file mode 100644 index 00000000..fb31a4a0 --- /dev/null +++ b/.kiro/settings/rules/tasks-parallel-analysis.md @@ -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. diff --git a/.kiro/settings/templates/specs/design.md b/.kiro/settings/templates/specs/design.md new file mode 100644 index 00000000..1d31e71a --- /dev/null +++ b/.kiro/settings/templates/specs/design.md @@ -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; +} +``` +- 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. diff --git a/.kiro/settings/templates/specs/init.json b/.kiro/settings/templates/specs/init.json new file mode 100644 index 00000000..410b1cd5 --- /dev/null +++ b/.kiro/settings/templates/specs/init.json @@ -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 +} + + diff --git a/.kiro/settings/templates/specs/requirements-init.md b/.kiro/settings/templates/specs/requirements-init.md new file mode 100644 index 00000000..edde05de --- /dev/null +++ b/.kiro/settings/templates/specs/requirements-init.md @@ -0,0 +1,9 @@ +# Requirements Document + +## Project Description (Input) +{{PROJECT_DESCRIPTION}} + +## Requirements + + + diff --git a/.kiro/settings/templates/specs/requirements.md b/.kiro/settings/templates/specs/requirements.md new file mode 100644 index 00000000..42424014 --- /dev/null +++ b/.kiro/settings/templates/specs/requirements.md @@ -0,0 +1,32 @@ +# Requirements Document + +## Introduction +{{INTRODUCTION}} + + +## 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}} + +**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] + + diff --git a/.kiro/settings/templates/specs/research.md b/.kiro/settings/templates/specs/research.md new file mode 100644 index 00000000..b7c32906 --- /dev/null +++ b/.kiro/settings/templates/specs/research.md @@ -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**: `` +- **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: `` +- **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 +- ... diff --git a/.kiro/settings/templates/specs/tasks.md b/.kiro/settings/templates/specs/tasks.md new file mode 100644 index 00000000..98298741 --- /dev/null +++ b/.kiro/settings/templates/specs/tasks.md @@ -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. diff --git a/.kiro/settings/templates/steering-custom/api-standards.md b/.kiro/settings/templates/steering-custom/api-standards.md new file mode 100644 index 00000000..acf6d4e3 --- /dev/null +++ b/.kiro/settings/templates/steering-custom/api-standards.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/authentication.md b/.kiro/settings/templates/steering-custom/authentication.md new file mode 100644 index 00000000..e6afadfc --- /dev/null +++ b/.kiro/settings/templates/steering-custom/authentication.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/database.md b/.kiro/settings/templates/steering-custom/database.md new file mode 100644 index 00000000..bfd7c592 --- /dev/null +++ b/.kiro/settings/templates/steering-custom/database.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/deployment.md b/.kiro/settings/templates/steering-custom/deployment.md new file mode 100644 index 00000000..0d97a0bd --- /dev/null +++ b/.kiro/settings/templates/steering-custom/deployment.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/error-handling.md b/.kiro/settings/templates/steering-custom/error-handling.md new file mode 100644 index 00000000..2d534398 --- /dev/null +++ b/.kiro/settings/templates/steering-custom/error-handling.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/security.md b/.kiro/settings/templates/steering-custom/security.md new file mode 100644 index 00000000..aca172a3 --- /dev/null +++ b/.kiro/settings/templates/steering-custom/security.md @@ -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._ diff --git a/.kiro/settings/templates/steering-custom/testing.md b/.kiro/settings/templates/steering-custom/testing.md new file mode 100644 index 00000000..f4e22fe9 --- /dev/null +++ b/.kiro/settings/templates/steering-custom/testing.md @@ -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._ diff --git a/.kiro/settings/templates/steering/product.md b/.kiro/settings/templates/steering/product.md new file mode 100644 index 00000000..a0f43fa7 --- /dev/null +++ b/.kiro/settings/templates/steering/product.md @@ -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_ diff --git a/.kiro/settings/templates/steering/structure.md b/.kiro/settings/templates/steering/structure.md new file mode 100644 index 00000000..01162476 --- /dev/null +++ b/.kiro/settings/templates/steering/structure.md @@ -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_ diff --git a/.kiro/settings/templates/steering/tech.md b/.kiro/settings/templates/steering/tech.md new file mode 100644 index 00000000..c7b25b40 --- /dev/null +++ b/.kiro/settings/templates/steering/tech.md @@ -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_