mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-10-16 03:49:26 +00:00
chore: add kiro spec-driven tooling and steering docs
Add the Kiro-style agentic SDLC tooling used to drive this project: the .opencode/skills/kiro-* skill set (discovery, spec init/requirements/design/ tasks, validation, implementation, review, steering), the .kiro/settings templates, and AGENTS.md describing the workflow. Update the spec docs (assessment/design/requirements/tasks) to current state. Scope tests/test_opencode_skills.py to the project's own openultrasast-* skills so the third-party kiro-* tooling (which uses a different frontmatter convention) no longer breaks the frontmatter check. Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Marius Ciepluch
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
8fe8911020
commit
6699f1f8f9
@@ -0,0 +1,331 @@
|
||||
# Design Document Template
|
||||
|
||||
---
|
||||
**Purpose**: Provide sufficient detail to ensure implementation consistency across different implementers, preventing interpretation drift.
|
||||
|
||||
**Approach**:
|
||||
- Include essential sections that directly inform implementation decisions
|
||||
- Omit optional sections unless critical to preventing implementation errors
|
||||
- Match detail level to feature complexity
|
||||
- Use diagrams and tables over lengthy prose
|
||||
|
||||
**Warning**: Approaching 1000 lines indicates excessive feature complexity that may require design simplification or splitting into multiple specs.
|
||||
---
|
||||
|
||||
> Sections may be reordered (e.g., surfacing Requirements Traceability earlier or moving Data Models nearer Architecture) when it improves clarity. Within each section, keep the flow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
|
||||
|
||||
## Overview
|
||||
2-3 paragraphs max
|
||||
**Purpose**: This feature delivers [specific value] to [target users].
|
||||
**Users**: [Target user groups] will utilize this for [specific workflows].
|
||||
**Impact** (if applicable): Changes the current [system state] by [specific modifications].
|
||||
|
||||
|
||||
### Goals
|
||||
- Primary objective 1
|
||||
- Primary objective 2
|
||||
- Success criteria
|
||||
|
||||
### Non-Goals
|
||||
- Explicitly excluded functionality
|
||||
- Future considerations outside current scope
|
||||
- Integration points deferred
|
||||
|
||||
## Boundary Commitments
|
||||
|
||||
State the responsibility boundary of this spec in concrete terms. Treat this as the anchor for architecture, tasks, and later validation.
|
||||
|
||||
### This Spec Owns
|
||||
- Capabilities and behaviors this spec is responsible for
|
||||
- Data it owns or is authoritative for
|
||||
- Interfaces or contracts it defines or stabilizes
|
||||
|
||||
### Out of Boundary
|
||||
- Related concerns this spec explicitly does NOT own
|
||||
- Work deferred to another spec, existing subsystem, or later phase
|
||||
- Changes this spec must not absorb as "just one more thing"
|
||||
|
||||
### Allowed Dependencies
|
||||
- Upstream systems/specs/components this design may depend on
|
||||
- Shared infrastructure this design may use
|
||||
- Dependency constraints that must not be violated
|
||||
|
||||
### Revalidation Triggers
|
||||
List the kinds of changes that should force dependent specs or consumers to re-check integration.
|
||||
|
||||
- Contract shape changes
|
||||
- Data ownership changes
|
||||
- Dependency direction changes
|
||||
- Startup/runtime prerequisite changes
|
||||
|
||||
## Architecture
|
||||
|
||||
> Reference detailed discovery notes in `research.md` only for background; keep design.md self-contained for reviewers by capturing all decisions and contracts here.
|
||||
> Capture key decisions in text and let diagrams carry structural detail—avoid repeating the same information in prose.
|
||||
> Supporting sections below should remain as light as possible unless they materially clarify the responsibility boundary, dependency rules, or integration seams.
|
||||
|
||||
### Existing Architecture Analysis (if applicable)
|
||||
When modifying existing systems:
|
||||
- Current architecture patterns and constraints
|
||||
- Existing domain boundaries to be respected
|
||||
- Integration points that must be maintained
|
||||
- Technical debt addressed or worked around
|
||||
|
||||
### Architecture Pattern & Boundary Map
|
||||
**RECOMMENDED**: Include Mermaid diagram showing the chosen architecture pattern and system boundaries (required for complex features, optional for simple additions)
|
||||
|
||||
**Architecture Integration**:
|
||||
- Selected pattern: [name and brief rationale]
|
||||
- Domain/feature boundaries: [how responsibilities are separated to avoid conflicts]
|
||||
- Existing patterns preserved: [list key patterns]
|
||||
- New components rationale: [why each is needed]
|
||||
- Steering compliance: [principles maintained]
|
||||
|
||||
### Technology Stack
|
||||
|
||||
| Layer | Choice / Version | Role in Feature | Notes |
|
||||
|-------|------------------|-----------------|-------|
|
||||
| Frontend / CLI | | | |
|
||||
| Backend / Services | | | |
|
||||
| Data / Storage | | | |
|
||||
| Messaging / Events | | | |
|
||||
| Infrastructure / Runtime | | | |
|
||||
|
||||
> Keep rationale concise here and, when more depth is required (trade-offs, benchmarks), add a short summary plus pointer to the Supporting References section and `research.md` for raw investigation notes.
|
||||
|
||||
## File Structure Plan
|
||||
|
||||
Map the directory structure and file responsibilities for this feature. This section directly drives task `_Boundary:_` annotations and implementation Task Briefs. Use the appropriate level of detail:
|
||||
|
||||
- **Small features**: List individual files with responsibilities
|
||||
- **Large features**: Describe directory-level structure + per-domain/module pattern, list only non-obvious files individually
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
src/
|
||||
├── domain-a/ # Domain A responsibility
|
||||
│ ├── controller.ts # Endpoint handlers
|
||||
│ ├── service.ts # Business logic
|
||||
│ └── types.ts # Domain types
|
||||
├── domain-b/ # Domain B (same pattern as domain-a)
|
||||
└── shared/
|
||||
└── cross-cutting.ts # Non-obvious: why this exists
|
||||
```
|
||||
|
||||
> For repeated structures, describe the pattern once (e.g., "domain-b follows same pattern as domain-a"). List individual files only when their responsibility isn't obvious from the path.
|
||||
|
||||
### Modified Files
|
||||
- `path/to/existing.ts` — What changes and why
|
||||
|
||||
> Each file should have one clear responsibility. Group files that change together. For repeated structures, describe the pattern once rather than listing every file.
|
||||
> Avoid duplicating what Components and Interfaces already describes — focus on the physical file layout that Components maps to.
|
||||
|
||||
## System Flows
|
||||
|
||||
Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:
|
||||
- Sequence (multi-party interactions)
|
||||
- Process / state (branching logic or lifecycle)
|
||||
- Data / event flow (pipelines, async messaging)
|
||||
|
||||
Skip this section entirely for simple CRUD changes.
|
||||
> Describe flow-level decisions (e.g., gating conditions, retries) briefly after the diagram instead of restating each step.
|
||||
|
||||
## Requirements Traceability
|
||||
|
||||
Use this section for complex or compliance-sensitive features where requirements span multiple domains. Straightforward 1:1 mappings can rely on the Components summary table.
|
||||
|
||||
Map each requirement ID (e.g., `2.1`) to the design elements that realize it.
|
||||
|
||||
| Requirement | Summary | Components | Interfaces | Flows |
|
||||
|-------------|---------|------------|------------|-------|
|
||||
| 1.1 | | | | |
|
||||
| 1.2 | | | | |
|
||||
|
||||
> Omit this section only when a single component satisfies a single requirement without cross-cutting concerns.
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
Provide a quick reference before diving into per-component details.
|
||||
|
||||
- Summaries can be a table or compact list. Example table:
|
||||
| Component | Domain/Layer | Intent | Req Coverage | Key Dependencies (P0/P1) | Contracts |
|
||||
|-----------|--------------|--------|--------------|--------------------------|-----------|
|
||||
| ExampleComponent | UI | Displays XYZ | 1, 2 | GameProvider (P0), MapPanel (P1) | Service, State |
|
||||
- Only components introducing new boundaries (e.g., logic hooks, external integrations, persistence) require full detail blocks. Simple presentation components can rely on the summary row plus a short Implementation Note.
|
||||
|
||||
Group detailed blocks by domain or architectural layer. For each detailed component, list requirement IDs as `2.1, 2.3` (omit “Requirement”). When multiple UI components share the same contract, reference a base interface/props definition instead of duplicating code blocks.
|
||||
|
||||
### [Domain / Layer]
|
||||
|
||||
#### [Component Name]
|
||||
|
||||
| Field | Detail |
|
||||
|-------|--------|
|
||||
| Intent | 1-line description of the responsibility |
|
||||
| Requirements | 2.1, 2.3 |
|
||||
| Owner / Reviewers | (optional) |
|
||||
|
||||
**Responsibilities & Constraints**
|
||||
- Primary responsibility
|
||||
- Domain boundary and transaction scope
|
||||
- Data ownership / invariants
|
||||
|
||||
**Dependencies**
|
||||
- Inbound: Component/service name — purpose (Criticality)
|
||||
- Outbound: Component/service name — purpose (Criticality)
|
||||
- External: Service/library — purpose (Criticality)
|
||||
|
||||
Summarize external dependency findings here; deeper investigation (API signatures, rate limits, migration notes) lives in `research.md`.
|
||||
|
||||
**Contracts**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [ ] ← check only the ones that apply.
|
||||
|
||||
##### Service Interface
|
||||
```typescript
|
||||
interface [ComponentName]Service {
|
||||
methodName(input: InputType): Result<OutputType, ErrorType>;
|
||||
}
|
||||
```
|
||||
- Preconditions:
|
||||
- Postconditions:
|
||||
- Invariants:
|
||||
|
||||
##### API Contract
|
||||
| Method | Endpoint | Request | Response | Errors |
|
||||
|--------|----------|---------|----------|--------|
|
||||
| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 |
|
||||
|
||||
##### Event Contract
|
||||
- Published events:
|
||||
- Subscribed events:
|
||||
- Ordering / delivery guarantees:
|
||||
|
||||
##### Batch / Job Contract
|
||||
- Trigger:
|
||||
- Input / validation:
|
||||
- Output / destination:
|
||||
- Idempotency & recovery:
|
||||
|
||||
##### State Management
|
||||
- State model:
|
||||
- Persistence & consistency:
|
||||
- Concurrency strategy:
|
||||
|
||||
**Implementation Notes**
|
||||
- Integration:
|
||||
- Validation:
|
||||
- Risks:
|
||||
|
||||
## Data Models
|
||||
|
||||
Focus on the portions of the data landscape that change with this feature.
|
||||
|
||||
### Domain Model
|
||||
- Aggregates and transactional boundaries
|
||||
- Entities, value objects, domain events
|
||||
- Business rules & invariants
|
||||
- Optional Mermaid diagram for complex relationships
|
||||
|
||||
### Logical Data Model
|
||||
|
||||
**Structure Definition**:
|
||||
- Entity relationships and cardinality
|
||||
- Attributes and their types
|
||||
- Natural keys and identifiers
|
||||
- Referential integrity rules
|
||||
|
||||
**Consistency & Integrity**:
|
||||
- Transaction boundaries
|
||||
- Cascading rules
|
||||
- Temporal aspects (versioning, audit)
|
||||
|
||||
### Physical Data Model
|
||||
**When to include**: When implementation requires specific storage design decisions
|
||||
|
||||
**For Relational Databases**:
|
||||
- Table definitions with data types
|
||||
- Primary/foreign keys and constraints
|
||||
- Indexes and performance optimizations
|
||||
- Partitioning strategy for scale
|
||||
|
||||
**For Document Stores**:
|
||||
- Collection structures
|
||||
- Embedding vs referencing decisions
|
||||
- Sharding key design
|
||||
- Index definitions
|
||||
|
||||
**For Event Stores**:
|
||||
- Event schema definitions
|
||||
- Stream aggregation strategies
|
||||
- Snapshot policies
|
||||
- Projection definitions
|
||||
|
||||
**For Key-Value/Wide-Column Stores**:
|
||||
- Key design patterns
|
||||
- Column families or value structures
|
||||
- TTL and compaction strategies
|
||||
|
||||
### Data Contracts & Integration
|
||||
|
||||
**API Data Transfer**
|
||||
- Request/response schemas
|
||||
- Validation rules
|
||||
- Serialization format (JSON, Protobuf, etc.)
|
||||
|
||||
**Event Schemas**
|
||||
- Published event structures
|
||||
- Schema versioning strategy
|
||||
- Backward/forward compatibility rules
|
||||
|
||||
**Cross-Service Data Management**
|
||||
- Distributed transaction patterns (Saga, 2PC)
|
||||
- Data synchronization strategies
|
||||
- Eventual consistency handling
|
||||
|
||||
Skip subsections that are not relevant to this feature.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Strategy
|
||||
Concrete error handling patterns and recovery mechanisms for each error type.
|
||||
|
||||
### Error Categories and Responses
|
||||
**User Errors** (4xx): Invalid input → field-level validation; Unauthorized → auth guidance; Not found → navigation help
|
||||
**System Errors** (5xx): Infrastructure failures → graceful degradation; Timeouts → circuit breakers; Exhaustion → rate limiting
|
||||
**Business Logic Errors** (422): Rule violations → condition explanations; State conflicts → transition guidance
|
||||
|
||||
**Process Flow Visualization** (when complex business logic exists):
|
||||
Include Mermaid flowchart only for complex error scenarios with business workflows.
|
||||
|
||||
### Monitoring
|
||||
Error tracking, logging, and health monitoring implementation.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Default sections (adapt names/sections to fit the domain)
|
||||
- Unit Tests: 3–5 items from core functions/modules (e.g., auth methods, subscription logic)
|
||||
- Integration Tests: 3–5 cross-component flows (e.g., webhook handling, notifications)
|
||||
- E2E/UI Tests (if applicable): 3–5 critical user paths (e.g., forms, dashboards)
|
||||
- Performance/Load (if applicable): 3–4 items (e.g., concurrency, high-volume ops)
|
||||
|
||||
## Optional Sections (include when relevant)
|
||||
|
||||
### Security Considerations
|
||||
_Use this section for features handling auth, sensitive data, external integrations, or user permissions. Capture only decisions unique to this feature; defer baseline controls to steering docs._
|
||||
- Threat modeling, security controls, compliance requirements
|
||||
- Authentication and authorization patterns
|
||||
- Data protection and privacy considerations
|
||||
|
||||
### Performance & Scalability
|
||||
_Use this section when performance targets, high load, or scaling concerns exist. Record only feature-specific targets or trade-offs and rely on steering documents for general practices._
|
||||
- Target metrics and measurement strategies
|
||||
- Scaling approaches (horizontal/vertical)
|
||||
- Caching strategies and optimization techniques
|
||||
|
||||
### Migration Strategy
|
||||
Include a Mermaid flowchart showing migration phases when schema/data movement is required.
|
||||
- Phase breakdown, rollback triggers, validation checkpoints
|
||||
|
||||
## Supporting References (Optional)
|
||||
- Create this section only when keeping the information in the main body would hurt readability (e.g., very long TypeScript definitions, vendor option matrices, exhaustive schema tables). Keep decision-making context in the main sections so the design stays self-contained.
|
||||
- Link to the supporting references from the main text instead of inlining large snippets.
|
||||
- Background research notes and comparisons continue to live in `research.md`, but their conclusions must be summarized in the main design.
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# Requirements Document
|
||||
|
||||
## Project Description (Input)
|
||||
{{PROJECT_DESCRIPTION}}
|
||||
|
||||
## Requirements
|
||||
<!-- Will be generated in /kiro-spec-requirements phase -->
|
||||
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
{{INTRODUCTION}}
|
||||
|
||||
<!-- Optional when scope could be misread or the feature touches adjacent systems/specs -->
|
||||
## Boundary Context (Optional)
|
||||
- **In scope**: {{IN_SCOPE_BEHAVIORS}}
|
||||
- **Out of scope**: {{OUT_OF_SCOPE_BEHAVIORS}}
|
||||
- **Adjacent expectations**: {{ADJACENT_SYSTEM_OR_SPEC_EXPECTATIONS}}
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: {{REQUIREMENT_AREA_1}}
|
||||
<!-- Requirement headings MUST include a leading numeric ID only (for example: "Requirement 1: ...", "1. Overview", "2 Feature: ..."). Alphabetic IDs like "Requirement A" are not allowed. -->
|
||||
**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
|
||||
|
||||
#### Acceptance Criteria
|
||||
1. When [event], the [system] shall [response/action]
|
||||
2. If [trigger], then the [system] shall [response/action]
|
||||
3. While [precondition], the [system] shall [response/action]
|
||||
4. Where [feature is included], the [system] shall [response/action]
|
||||
5. The [system] shall [response/action]
|
||||
|
||||
### Requirement 2: {{REQUIREMENT_AREA_2}}
|
||||
**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
|
||||
|
||||
#### Acceptance Criteria
|
||||
1. When [event], the [system] shall [response/action]
|
||||
2. When [event] and [condition], the [system] shall [response/action]
|
||||
|
||||
<!-- Additional requirements follow the same pattern -->
|
||||
@@ -0,0 +1,61 @@
|
||||
# Research & Design Decisions Template
|
||||
|
||||
---
|
||||
**Purpose**: Capture discovery findings, architectural investigations, and rationale that inform the technical design.
|
||||
|
||||
**Usage**:
|
||||
- Log research activities and outcomes during the discovery phase.
|
||||
- Document design decision trade-offs that are too detailed for `design.md`.
|
||||
- Provide references and evidence for future audits or reuse.
|
||||
---
|
||||
|
||||
## Summary
|
||||
- **Feature**: `<feature-name>`
|
||||
- **Discovery Scope**: New Feature / Extension / Simple Addition / Complex Integration
|
||||
- **Key Findings**:
|
||||
- Finding 1
|
||||
- Finding 2
|
||||
- Finding 3
|
||||
|
||||
## Research Log
|
||||
Document notable investigation steps and their outcomes. Group entries by topic for readability.
|
||||
|
||||
### [Topic or Question]
|
||||
- **Context**: What triggered this investigation?
|
||||
- **Sources Consulted**: Links, documentation, API references, benchmarks
|
||||
- **Findings**: Concise bullet points summarizing the insights
|
||||
- **Implications**: How this affects architecture, contracts, or implementation
|
||||
|
||||
_Repeat the subsection for each major topic._
|
||||
|
||||
## Architecture Pattern Evaluation
|
||||
List candidate patterns or approaches that were considered. Use the table format where helpful.
|
||||
|
||||
| Option | Description | Strengths | Risks / Limitations | Notes |
|
||||
|--------|-------------|-----------|---------------------|-------|
|
||||
| Hexagonal | Ports & adapters abstraction around core domain | Clear boundaries, testable core | Requires adapter layer build-out | Aligns with existing steering principle X |
|
||||
|
||||
## Design Decisions
|
||||
Record major decisions that influence `design.md`. Focus on choices with significant trade-offs.
|
||||
|
||||
### Decision: `<Title>`
|
||||
- **Context**: Problem or requirement driving the decision
|
||||
- **Alternatives Considered**:
|
||||
1. Option A — short description
|
||||
2. Option B — short description
|
||||
- **Selected Approach**: What was chosen and how it works
|
||||
- **Rationale**: Why this approach fits the current project context
|
||||
- **Trade-offs**: Benefits vs. compromises
|
||||
- **Follow-up**: Items to verify during implementation or testing
|
||||
|
||||
_Repeat the subsection for each decision._
|
||||
|
||||
## Risks & Mitigations
|
||||
- Risk 1 — Proposed mitigation
|
||||
- Risk 2 — Proposed mitigation
|
||||
- Risk 3 — Proposed mitigation
|
||||
|
||||
## References
|
||||
Provide canonical links and citations (official docs, standards, ADRs, internal guidelines).
|
||||
- [Title](https://example.com) — brief note on relevance
|
||||
- ...
|
||||
@@ -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.
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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._
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
@@ -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_
|
||||
Reference in New Issue
Block a user