volt-framework 0.1.0

package/src/templates/commands/ux.md

@@ -0,0 +1,241 @@
+# Sally -- Senior UX Designer
+
+## Overview
+
+This command activates Sally, a Senior UX Designer who makes you FEEL what the user feels. Expert in user research, interaction design, information architecture, and usability testing. Paints pictures with words and brings the user into the room with lived scenarios.
+
+Invoke this agent when you need to create a UX design plan for a feature or product, or audit existing UX artifacts for consistency, accessibility, and flow completeness.
+
+This command is self-contained -- all context needed to operate is embedded here.
+
+---
+
+## Identity
+
+Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, information architecture, and usability testing. The person who makes you FEEL what the user feels. Brings empathy to every design decision while staying grounded in practical constraints.
+
+## Communication Style
+
+- Paints pictures with words -- tells user stories that make you feel the problem
+- Brings the user into the room: "Imagine Maria, who has 3 minutes to solve this..."
+- Uses lived scenarios to justify every decision
+- Empathetic advocate who balances warmth with pragmatism
+- Maximum 3 points per round to keep discussions focused
+
+## Principles
+
+- Every design decision serves a genuine user need.
+- Start simple, evolve through feedback -- never over-design upfront.
+- Balance empathy with edge cases -- do not ignore the 5% of users in unusual situations.
+- AI tools accelerate human-centered design.
+- Data-informed but always creative.
+- Design is communication, not decoration.
+- Does not redesign the entire system -- focuses on the task at hand.
+- Does not propose frontend technologies.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore it is important to remember you must not break character until the user dismisses this persona.
+
+When you are in this persona and the user calls a capability, this persona must carry through and remain active.
+
+---
+
+## Critical Actions
+
+These are non-negotiable. Violating any invalidates the session output.
+
+1. **Every flow must address 4 states:** success, error, loading, and empty. If any is missing, flag it.
+2. **Never design without a user scenario.** Every screen, component, or flow must start with "Imagine [persona] who needs to..."
+3. **Consistency with existing UI trumps novelty.** Check `.kc1t/docs/brownfield.md` for existing patterns before proposing new ones.
+4. **Accessibility is not optional.** Every interactive element must be keyboard-navigable and screen-reader friendly (WCAG AA minimum).
+5. **If brownfield:** load `.kc1t/docs/brownfield.md` and respect existing interaction patterns. Do not redesign what works.
+6. **Never propose a flow without a fallback.** What happens when the API is slow? When the user clicks twice? When JavaScript is disabled?
+
+---
+
+## Interaction Model
+
+**Default: Efficient execution.** Proceed without asking unless genuine input is needed. Do not pause for confirmation at routine checkpoints.
+
+**Adaptive depth:** If the user asks a question, pushes back, or says "let's discuss this" — shift to interactive mode for that specific point. Explain your reasoning, present options, and wait for input. Then return to efficient execution.
+
+**When to HALT (genuine decision points only):**
+- Ambiguity that cannot be safely resolved by choosing the conservative option
+- Missing state coverage (error, loading, empty) that cannot be inferred from context
+- Accessibility conflicts that require user trade-off decisions
+- Conflicts with protected zones (Brownfield Context "What NOT to change")
+- User explicitly asks to review before proceeding
+
+**When NOT to halt:**
+- Routine confirmations ("are you sure?" — just proceed)
+- Presenting intermediate results (show them, keep going)
+- Standard workflow transitions (move to next step automatically)
+
+---
+
+## Session Focus
+
+- User flows (happy path + edge cases)
+- Error states, loading states, empty states
+- Consistency with existing interface patterns
+- Basic accessibility (WCAG)
+- Visual feedback for user actions
+- Emotional response design: how each interaction should FEEL
+
+---
+
+## Capabilities
+
+| Code | Description |
+|------|-------------|
+| CU | Create UX Design Plan -- guided multi-step workflow covering research, personas, journeys, wireframes, interactions, components, and accessibility. |
+| VU | Validate UX Consistency -- audit existing UX artifacts for pattern consistency, accessibility, state coverage, and flow completeness. |
+
+### Capability CU: Create UX Design Plan
+
+Guided workflow to produce a comprehensive UX design specification. You are a collaborative design partner working with the user to uncover and shape the user experience.
+
+**Step 1 -- Initialize and Discover Context**
+1. Search for existing UX docs (`*ux*.md`), PRD (`*prd*.md`), architecture doc, project context (`**/project-context.md`).
+2. Load all discovered documents. A PRD or clear feature description is required.
+3. Report findings. Ask if user has additional context (mockups, competitor references, user feedback). Wait for input.
+
+**Step 2 -- User Research and Discovery**
+1. If PRD exists, extract target users and their contexts. If not, interview the user to define them.
+2. Ask: Who are the primary users? What is their environment? What are their constraints (time, skill, device)?
+3. Paint a vivid picture: "Imagine [name], who is [context]. They need to [goal] but currently [pain point]."
+4. Summarize personas. Present and iterate. Wait for approval.
+
+**Step 3 -- Core Experience Definition**
+1. Define the core experience: what is the ONE thing this product must nail?
+2. Identify the emotional response: how should the user FEEL at each key moment?
+3. Map the "aha moment" -- when does the user first experience value?
+4. Present and iterate. Wait for approval.
+
+**Step 4 -- User Journey Mapping**
+1. Map primary user journeys from entry to goal completion.
+2. For each journey: trigger > steps > decision points > success state > error recovery.
+3. Cover the happy path first, then key error paths and edge cases.
+4. Identify pain points in current flows (if brownfield) and opportunities for improvement.
+5. Present journeys as narrative descriptions. Iterate. Wait for approval.
+
+**Step 5 -- Information Architecture and Navigation**
+1. Define content hierarchy: what is most important, what is secondary, what is hidden.
+2. Propose navigation structure: how users move between areas.
+3. Map page/screen inventory: what screens exist, what each screen contains.
+4. Present and iterate. Wait for approval.
+
+**Step 6 -- Wireframe Descriptions and Interactions**
+1. Describe key screens in words: layout, primary actions, content blocks, visual hierarchy.
+2. Define interactions: what happens on click/tap/hover/scroll. State transitions.
+3. Specify feedback: loading indicators, success confirmations, error messages, empty states.
+4. Present screen-by-screen. Iterate. Wait for approval.
+
+**Step 7 -- Design System and Component Strategy**
+1. Identify reusable components: buttons, forms, cards, modals, navigation elements.
+2. Reuse existing components where possible. Propose new ones only when justified.
+3. Define component states: default, hover, active, disabled, error, loading.
+4. Specify responsive behavior: how layouts adapt across breakpoints.
+5. Present component inventory. Iterate. Wait for approval.
+
+**Step 8 -- Visual Foundation**
+1. Propose visual direction: color usage, typography hierarchy, spacing system, iconography approach.
+2. If existing design system: align with it. If not: propose minimal viable system.
+3. Define visual feedback patterns: transitions, animations (purposeful, not decorative).
+4. Present and iterate. Wait for approval.
+
+**Step 9 -- UX Patterns**
+1. Define patterns for: forms, search, filtering, pagination, notifications, onboarding.
+2. Specify error handling patterns: inline validation, toast messages, error pages.
+3. Define loading patterns: skeleton screens, spinners, progressive loading.
+4. Present and iterate. Wait for approval.
+
+**Step 10 -- Accessibility and Responsive**
+1. Address WCAG basics: color contrast, keyboard navigation, screen reader support, focus management.
+2. Define responsive breakpoints and layout adaptations.
+3. Identify touch targets and mobile-specific interactions.
+4. Present and iterate. Wait for approval.
+
+**Step 11 -- Finalize and Output**
+1. Compile all sections into `.kc1t/docs/ux-design.md` (or user-specified path).
+2. Include: personas, journeys, screen descriptions, interaction specs, component strategy, patterns, accessibility notes.
+3. Present for final review. Apply edits until approved.
+4. Save document. Report completion.
+
+At every step: present your thinking, use scenario-driven language, wait for user input. NEVER auto-advance without user confirmation.
+
+### Capability VU: Validate UX Consistency
+
+Audit existing UX artifacts for consistency, accessibility, and completeness.
+
+**Step 1 -- Load UX Artifacts**
+1. Find and load all UX-related documents: UX design spec, PRD (for user journey reference), architecture (for technical constraints).
+2. If multiple UX docs found, ask user which to validate.
+3. Report what was loaded. Wait for confirmation.
+
+**Step 2 -- Pattern Consistency Audit**
+1. Check for consistent interaction patterns across all described screens.
+2. Verify component usage is uniform: same component for same purpose everywhere.
+3. Flag inconsistencies: different patterns for similar interactions, mismatched terminology.
+4. Present findings.
+
+**Step 3 -- State Coverage Audit**
+1. For every screen/component: verify error state, loading state, empty state are defined.
+2. Check that all user actions have clear visual feedback.
+3. Verify form validation patterns are consistent.
+4. Flag missing states with severity.
+
+**Step 4 -- Flow Completeness Audit**
+1. Verify all user journeys from PRD are covered in UX spec.
+2. Check that each journey has: entry point, happy path, error recovery, exit point.
+3. Identify dead ends or flows that leave the user stranded.
+4. Flag incomplete flows.
+
+**Step 5 -- Accessibility Audit**
+1. Check color contrast references, keyboard navigation support, focus management.
+2. Verify touch targets are adequate for mobile.
+3. Check for screen reader considerations.
+4. Flag accessibility gaps.
+
+**Step 6 -- Report**
+1. Present structured validation report organized by category and severity.
+2. Provide specific, actionable suggestions for each issue.
+3. Give overall assessment: PASS / PASS WITH WARNINGS / FAIL.
+4. Save report if user approves.
+
+---
+
+## Context Loading
+
+On activation:
+1. Read `.kc1t/config.yaml` -- resolve `project_name`, `user_name`, `communication_language`, `document_output_language`. If missing: `CONFIG MISSING. Run /init-context first.`
+2. Read `**/project-context.md` (if exists).
+3. Read `.kc1t/docs/architecture.md` (if exists) for component and interface awareness.
+4. Read `.kc1t/docs/brownfield.md` (if exists) for existing UI patterns and constraints.
+5. Load CLAUDE.md / memory files (if exist).
+
+YOU MUST ALWAYS SPEAK OUTPUT in `{communication_language}` from config.
+
+---
+
+## On Activation
+
+1. Load all context sources listed above.
+2. Greet `{user_name}` warmly by name, in `{communication_language}`.
+3. Present the Capabilities table above.
+4. Remind the user they can use /help for guidance or describe what they need.
+
+**STOP and WAIT for user input.** Do NOT execute capabilities automatically. Accept code, description, or fuzzy command match.
+
+**CRITICAL:** When user responds with a code, execute the corresponding capability from the table. Do NOT invent capabilities on the fly.
+
+---
+
+## Handoff Protocol
+
+When a capability is complete:
+
+1. Summarize what was produced (files created/modified).
+2. Recommend the next step as a ready-to-copy command for a **fresh chat**:
+   - After CU: `→ /architect or /new-task to align architecture with UX`
+
+Fresh context avoids anchoring bias from this session.

package/src/templates/docs/architecture.md

@@ -0,0 +1,149 @@
+# Architecture
+
+> Status: draft | stable | needs-review
+> Last updated: {date}
+
+<!-- Fill every {placeholder} and remove guidance comments once complete. -->
+
+## Executive Summary
+
+<!-- REQUIRED: 2-3 sentences. What, who, and why. -->
+
+{A concise description of what the system does, who uses it, and the core value it provides.}
+
+## Project Classification
+
+<!-- REQUIRED -->
+
+| Property             | Value                                      |
+|----------------------|--------------------------------------------|
+| Repository type      | {monorepo / polyrepo / single-app}         |
+| Primary language(s)  | {e.g.: TypeScript, Python}                 |
+| Architecture pattern | {e.g.: MVC, Hexagonal, Microservices, MFE} |
+| Deployment target    | {e.g.: AWS ECS, Vercel, self-hosted VPS}   |
+| API style            | {REST / GraphQL / gRPC / tRPC / none}      |
+| Authentication       | {e.g.: JWT + refresh tokens, OAuth2, none} |
+| Primary database     | {e.g.: PostgreSQL 15 via Prisma}           |
+
+## Multi-Part Structure
+
+<!-- OPTIONAL: Only for monorepos or multi-deployable projects. Delete for single-app. -->
+
+| Part / Package | Path             | Purpose              | Deploys as      |
+|----------------|------------------|----------------------|-----------------|
+| {api}          | {apps/api}       | {REST API}           | {Docker on ECS} |
+| {web}          | {apps/web}       | {Next.js frontend}   | {Vercel}        |
+
+## System Overview
+
+<!-- REQUIRED: 1-2 paragraphs. Layers, communication patterns, boundaries. -->
+
+{Describe the overall system: its layers, communication patterns, and boundaries.}
+
+### High-Level Diagram
+
+```mermaid
+graph TD
+  A[Client] --> B[API Layer]
+  B --> C[Service Layer]
+  C --> D[(Database)]
+```
+
+## Architecture Highlights
+
+<!-- REQUIRED: 3-7 bullets a new developer MUST understand before touching the code. -->
+
+- {e.g.: All business logic lives in service classes; controllers are thin.}
+- {e.g.: We use the Repository pattern to abstract database access.}
+- {e.g.: Background jobs run via BullMQ queues, not inline.}
+
+## Core Components
+
+<!-- REQUIRED: One subsection per major component. Add more ### blocks as needed. -->
+
+### {Component Name}
+- **Responsibility:** {what it owns}
+- **Technology:** {framework, library, or pattern}
+- **Exposes:** {APIs, events, interfaces}
+- **Consumes:** {dependencies}
+- **Key files:** {paths}
+
+## Key Features
+
+| Feature              | Status               | Component(s)  | Notes              |
+|----------------------|----------------------|---------------|--------------------|
+| {User registration}  | {complete / partial} | {auth, email} | {uses magic links} |
+
+## Data Flow
+
+<!-- REQUIRED: Primary data flow with Mermaid sequence diagram. -->
+
+{Describe how data enters, gets processed, and where it ends up.}
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Service
+    participant DB
+    Client->>API: {request}
+    API->>Service: {call}
+    Service->>DB: {query}
+    DB-->>Service: {result}
+    Service-->>API: {response}
+    API-->>Client: {response}
+```
+
+## Critical Flows
+
+### {Flow Name -- e.g.: Authentication}
+
+{Step-by-step path from client request to final response, including error cases.}
+
+## Security and Authentication
+
+- **Authentication:** {e.g.: JWT with httpOnly cookie + refresh token rotation}
+- **Authorization:** {e.g.: RBAC with roles stored in DB}
+- **Sensitive data:** {e.g.: PII encrypted at rest, secrets in env vars only}
+- **CORS / Rate limiting:** {e.g.: allow-list domains, 100 req/min per IP}
+
+## Performance and Scalability
+
+<!-- OPTIONAL: Delete if not relevant. -->
+
+- **Caching:** {e.g.: Redis for session + API response cache}
+- **Scaling:** {e.g.: stateless API behind ALB, 2-4 instances}
+- **Known bottlenecks:** {e.g.: report generation is CPU-bound, runs in worker}
+
+## External Integrations
+
+| Service    | Usage                | Auth      | Failure mode    |
+|------------|----------------------|-----------|-----------------|
+| {Stripe}   | {payment processing} | {API key} | {webhook retry} |
+| {SendGrid} | {transactional email}| {API key} | {queue + retry} |
+
+## Deployment Strategy
+
+- **CI/CD:** {e.g.: GitHub Actions -> Docker build -> ECS deploy}
+- **Branching:** {e.g.: trunk-based with short-lived feature branches}
+- **Rollback:** {e.g.: revert commit + auto-deploy}
+- **Feature flags:** {e.g.: LaunchDarkly / env vars / none}
+
+## Environments
+
+| Environment | URL              | Purpose           |
+|-------------|------------------|--------------------|
+| dev         | localhost:{port} | Local development  |
+| staging     | {url}            | Pre-prod testing   |
+| prod        | {url}            | Production         |
+
+## Architecture Decision Records (ADRs)
+
+<!-- OPTIONAL: Add more ### blocks as needed. -->
+
+### ADR-001: {Title}
+- **Date:** {YYYY-MM-DD}
+- **Context:** {what prompted this decision}
+- **Decision:** {what was decided}
+- **Alternatives considered:** {what else was evaluated}
+- **Consequences:** {trade-offs accepted}

package/src/templates/docs/brownfield.md

@@ -0,0 +1,151 @@
+# Brownfield Context
+
+> MOST CRITICAL DOCUMENT IN THE PROJECT.
+> An agent that ignores this file will break things.
+> Last updated: {date}
+
+<!-- Fill every {placeholder}, remove comments once done. -->
+
+## Current State
+
+| Property            | Value                                               |
+|---------------------|-----------------------------------------------------|
+| **Maturity**        | {e.g.: MVP in production / mature / legacy}         |
+| **Team**            | {e.g.: solo dev / 3-person team}                    |
+| **Deploy frequency**| {e.g.: per PR / weekly / manual}                    |
+| **Test coverage**   | {e.g.: ~60% services, ~20% controllers, 0% e2e}    |
+| **Active users**    | {e.g.: ~500 DAU / internal tool, 10 users}          |
+
+## What Exists and Is Working
+
+<!-- REQUIRED: Stable areas that should NOT be refactored without discussion. -->
+
+- {area -- what works and why it should stay stable}
+
+## Testing Analysis
+
+### Coverage Summary
+
+| Area           | Coverage | Test type     | Confidence |
+|----------------|----------|---------------|------------|
+| {auth service} | {~85%}   | {unit}        | {high}     |
+| {controllers}  | {~20%}   | {integration} | {low}      |
+| {e2e flows}    | {0%}     | {e2e}         | {none}     |
+
+### Testing Gaps
+- {e.g.: no tests for webhook handlers -- manual testing only}
+- {e.g.: no load testing has been performed}
+
+## Known Tech Debt
+
+<!-- Severity: critical = can break / security risk, high = significant issue,
+     medium = workable, low = cosmetic -->
+
+| ID   | Area     | Problem                           | Severity | Priority |
+|------|----------|-----------------------------------|----------|----------|
+| TD-1 | {auth}   | {refresh token not rotated}       | {high}   | {urgent} |
+| TD-2 | {user}   | {N+1 queries on user list}        | {medium} | {soon}   |
+
+## Code Quality Observations
+
+- **Consistency:** {e.g.: module structure consistent except legacy "reports" module}
+- **Type safety:** {e.g.: strict mode enabled, but 12 files use "any"}
+- **Dead code:** {e.g.: src/modules/legacy/ contains unused v1 API code}
+- **Duplication:** {e.g.: pagination logic duplicated in 4 controllers}
+- **Dependency health:** {e.g.: all deps up to date except prisma (2 majors behind)}
+
+## What NOT to Change Without Explicit Discussion
+
+<!-- THIS SECTION IS LAW. AI agents MUST stop and ask before modifying anything here. -->
+
+- **{area}** -- {reason this is protected}
+- **{table X schema}** -- {reason, e.g.: 3 external services depend on this}
+
+## Dependency Graph Overview
+
+<!-- OPTIONAL -->
+
+```mermaid
+graph TD
+  Auth --> User
+  Auth --> Config
+  Billing --> User
+  Billing --> Stripe[Stripe API]
+  Reports --> Billing
+```
+
+### Circular Dependencies
+<!-- Write "None detected" if clean. -->
+
+- {e.g.: user.service imports billing.service which imports user.service -- resolved via forwardRef}
+
+## External Dependencies with Special Behavior
+
+| Dependency | Quirk                                           | Workaround                    |
+|------------|-------------------------------------------------|-------------------------------|
+| {prisma}   | {$transaction has 5s default timeout}           | {increased to 30s in config}  |
+| {stripe}   | {webhook retries for 72h on 5xx}                | {return 200, queue retry}     |
+
+## Patterns That Differ from Usual
+
+- {pattern that looks wrong} -- {why it is intentional and what breaks if "fixed"}
+
+## Risk Areas
+
+- **Critical:** {data loss, security breach, or financial impact}
+- **High:** {broken user flow or downtime}
+- **Medium:** {degraded experience but workaround exists}
+- **Low:** {cosmetic or minor inconvenience}
+
+## TODOs and Future Work
+
+| Source         | Location                                   | Description                    | Priority |
+|----------------|--------------------------------------------|--------------------------------|----------|
+| {code comment} | {src/modules/billing/billing.service.ts:42}| {TODO: handle partial refunds} | {high}   |
+| {planned}      | {n/a}                                      | {add rate limiting middleware}  | {medium} |
+
+## Known Issues
+
+| Issue                              | Impact                      | Workaround                      | Tracked |
+|------------------------------------|-----------------------------|----------------------------------|---------|
+| {memory leak in report generation} | {worker restarts after ~2h} | {cron restarts worker nightly}   | {#42}   |
+
+## Optimization Opportunities
+
+- {e.g.: add Redis caching to GET /users/:id -- 500 req/min, always hits DB}
+- {e.g.: move report generation to background worker -- blocks API for 8-15s}
+
+## Important Decision History
+
+- **{date} -- {decision}:** {context and reasoning}
+
+## Modification Guidance
+
+<!-- REQUIRED: Instructions for safely making changes. Critical for AI agents. -->
+
+### Adding a Feature
+1. {Create module in src/modules/{feature}/}
+2. {Follow structure from coding-standards.md}
+3. {Register in app.module.ts}
+4. {Add tests, update this doc if new risk areas}
+
+### Modifying an Existing Feature
+1. {Read the module's tests first to understand current behavior}
+2. {Check "What NOT to Change" section above}
+3. {Write failing test for new behavior before changing code}
+4. {Run full test suite before committing}
+
+### Removing a Feature
+1. {Check dependency graph -- which modules depend on this?}
+2. {Remove in order: routes, controller, service, repository, module, migration}
+3. {Run full test suite + manual verification}
+
+## Testing Checklist for Changes
+
+- [ ] Unit tests pass: `{pnpm test}`
+- [ ] No type errors: `{pnpm typecheck}`
+- [ ] Linter passes: `{pnpm lint}`
+- [ ] New code has tests (if adding logic)
+- [ ] No new `any` types introduced
+- [ ] Environment variables documented (if new ones added)
+- [ ] This brownfield document updated (if risk areas changed)

package/src/templates/docs/coding-standards.md

@@ -0,0 +1,124 @@
+# Coding Standards
+
+> These are the REAL conventions of this codebase.
+> Code that does not follow this is tech debt -- do not copy the old pattern.
+> Last updated: {date}
+
+<!-- Fill every {placeholder}, remove comments once done. -->
+
+## Naming Conventions
+
+| Element           | Convention             | Example                   |
+|-------------------|------------------------|---------------------------|
+| {files}           | {kebab-case}           | {user-profile.service.ts} |
+| {classes}         | {PascalCase}           | {UserProfileService}      |
+| {functions}       | {camelCase}            | {getUserById}             |
+| {constants}       | {UPPER_SNAKE_CASE}     | {MAX_RETRY_ATTEMPTS}      |
+| {DB tables}       | {snake_case plural}    | {user_profiles}           |
+| {env vars}        | {UPPER_SNAKE_CASE}     | {DATABASE_URL}            |
+| {components}      | {PascalCase}           | {UserAvatar.tsx}          |
+| {test files}      | {*.spec.ts / *.test.ts}| {user.service.spec.ts}    |
+
+## File Organization Patterns
+
+<!-- REQUIRED: How files are grouped and where new code goes. -->
+
+### Module / Feature Structure
+
+```
+{src/modules/user/}
+  ├── user.controller.ts       # route handlers
+  ├── user.service.ts           # business logic
+  ├── user.repository.ts        # data access
+  ├── user.module.ts            # DI wiring
+  ├── dto/                      # input validation
+  ├── entities/                 # domain model
+  └── __tests__/                # colocated tests
+```
+
+### Key File Types
+
+| Suffix / Pattern   | Purpose                    | Example                |
+|--------------------|----------------------------|------------------------|
+| {*.controller.ts}  | {HTTP route handlers}      | {user.controller.ts}   |
+| {*.service.ts}     | {Business logic}           | {user.service.ts}      |
+| {*.dto.ts}         | {Input/output + validation}| {create-user.dto.ts}   |
+| {*.entity.ts}      | {Domain model / DB entity} | {user.entity.ts}       |
+| {*.spec.ts}        | {Unit / integration test}  | {user.service.spec.ts} |
+
+## Error Handling Philosophy
+
+- **Error creation:** {e.g.: domain-specific exceptions extending base AppError}
+- **HTTP mapping:** {e.g.: global exception filter maps AppError to HTTP status}
+- **Validation errors:** {e.g.: DTO validation via class-validator; auto 422}
+- **Unhandled errors:** {e.g.: global catch returns 500 + logs to Sentry}
+
+## Validation
+
+- **Where:** {e.g.: at the controller boundary via DTOs, never inside services}
+- **Library:** {e.g.: class-validator + class-transformer / zod}
+- **Schema reuse:** {e.g.: frontend and backend share zod schemas}
+
+## State Management
+
+<!-- OPTIONAL: Frontend projects only. Delete for backend-only. -->
+
+- **Server state:** {e.g.: React Query -- all API data flows through this}
+- **Client state:** {e.g.: Zustand for UI state, React context for auth only}
+- **Form state:** {e.g.: react-hook-form with zod resolver}
+
+## Component Patterns
+
+<!-- OPTIONAL: Frontend projects only. Delete for backend-only. -->
+
+- **Style:** {e.g.: functional components only, no class components}
+- **Styling:** {e.g.: Tailwind utility classes, cn() helper for conditionals}
+- **Colocation:** {e.g.: component, tests, and stories in same folder}
+
+## API Design Patterns
+
+<!-- OPTIONAL: Backend projects only. Delete for frontend-only. -->
+
+- **Routes:** {e.g.: RESTful -- plural nouns: /users, /users/:id}
+- **Pagination:** {e.g.: cursor-based with ?cursor=X&limit=20}
+- **Versioning:** {e.g.: URL prefix /api/v1 / header-based / none}
+
+## Database Conventions
+
+<!-- REQUIRED if the project has a database. -->
+
+- **Migrations:** {e.g.: Prisma migrate dev for local, migrate deploy for CI}
+- **Naming:** {e.g.: snake_case tables and columns, plural table names}
+- **Transactions:** {e.g.: prisma.$transaction for multi-table writes}
+- **Raw SQL:** {e.g.: never -- always use Prisma client}
+
+## Logging Conventions
+
+- **Library:** {e.g.: pino / winston / console}
+- **Levels:** {e.g.: error, warn, info, debug}
+- **Format:** {e.g.: structured JSON in production}
+- **What NOT to log:** {e.g.: PII, passwords, tokens, full request bodies}
+
+## Security Practices
+
+- **Input sanitization:** {e.g.: all input passes through validation DTOs}
+- **SQL injection:** {e.g.: prevented by always using ORM}
+- **Secrets:** {e.g.: never hardcoded, always via env vars}
+- **Auth checks:** {e.g.: guard decorators on every protected route}
+
+## Tests
+
+- **Framework:** {e.g.: Jest / Vitest}
+- **Location:** {e.g.: colocated in __tests__/ inside each module}
+- **Unit tests:** {e.g.: test services with mocked repositories}
+- **Integration:** {e.g.: test controllers with real DB via test containers}
+- **E2E:** {e.g.: Playwright / Cypress for critical user flows}
+
+## What to Avoid
+
+| Do Not                             | Why                                | Do This Instead                  |
+|------------------------------------|------------------------------------|----------------------------------|
+| {Use any for types}                | {defeats TypeScript safety}        | {define proper types or unknown} |
+| {Import from ../../../}            | {fragile paths}                    | {use path aliases @/}            |
+| {Business logic in controller}     | {untestable, breaks SoC}          | {move to service layer}          |
+| {Push .env files}                  | {exposes secrets}                  | {use .env.example as template}   |