add SKILL

.claude/skills/a11y-audit/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: a11y-audit
+description: Run a WCAG 2.2 AA accessibility audit on a component or page. Checks semantic HTML, ARIA, keyboard navigation, color contrast, and screen reader compatibility.
+disable-model-invocation: true
+argument-hint: "[file-or-directory]"
+context: fork
+agent: frontend-architect
+---
+
+# Accessibility Audit
+
+Audit `$ARGUMENTS` for WCAG 2.2 Level AA compliance.
+
+## Steps
+
+1. **Read the target code** — understand the component/page structure
+2. **Check against this checklist:**
+
+### Semantic HTML
+- [ ] Correct heading hierarchy (h1 → h2 → h3, no skips)
+- [ ] Landmark elements used (`nav`, `main`, `aside`, `footer`)
+- [ ] Lists use `ul`/`ol`/`li`, not styled divs
+- [ ] Buttons are `<button>`, links are `<a>`, not divs with onClick
+
+### ARIA
+- [ ] Interactive elements have accessible names (label, aria-label, aria-labelledby)
+- [ ] Form inputs have associated labels
+- [ ] Dynamic content updates use `aria-live` regions
+- [ ] Decorative images have `aria-hidden="true"` or empty alt
+- [ ] No redundant ARIA (e.g., `role="button"` on `<button>`)
+
+### Keyboard
+- [ ] All interactive elements are focusable and operable via keyboard
+- [ ] Focus order follows visual order
+- [ ] Focus is trapped in modals/dialogs
+- [ ] Skip-to-content link present (page-level)
+- [ ] No keyboard traps
+
+### Visual
+- [ ] Text contrast ratio >= 4.5:1 (normal), >= 3:1 (large)
+- [ ] Focus indicators visible on all interactive elements
+- [ ] `prefers-reduced-motion` respected for animations
+- [ ] `prefers-color-scheme` supported if applicable
+- [ ] Content readable at 200% zoom
+
+### States
+- [ ] Loading states announced (`aria-busy`)
+- [ ] Error messages programmatically associated with inputs (`aria-describedby`)
+- [ ] Disabled states use `disabled` attribute, not just styling
+
+3. **Report format:**
+
+```
+## Accessibility Audit: [component/file name]
+
+### Issues Found
+1. [CRITICAL/HIGH/MEDIUM/LOW] — description + file:line + fix
+
+### Passes
+- [What's done well]
+
+### Recommendations
+- [Improvements beyond minimum compliance]
+```

.claude/skills/api-endpoint/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: api-endpoint
+description: Scaffold a new REST API endpoint with input validation (Zod), error handling, types, and basic test.
+disable-model-invocation: true
+argument-hint: "[resource-name]"
+context: fork
+agent: backend-architect
+---
+
+# Scaffold API Endpoint
+
+Create a production-ready API endpoint for resource `$ARGUMENTS`.
+
+## Steps
+
+1. **Read project context first:**
+   - Check `docs/backend/architecture.md` for module structure
+   - Check `docs/backend/api-design.md` for conventions (naming, pagination, errors)
+   - Check `RECOMMENDATIONS.md` for locked stack (framework, ORM, validation)
+   - Look at existing endpoints in `apps/api/` for patterns
+
+2. **Create endpoint with:**
+   - RESTful routes: `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id` (only applicable ones)
+   - Zod schemas for request validation (params, query, body)
+   - TypeScript types derived from Zod schemas
+   - Consistent error responses: `{ error: string, code: string, details?: unknown }`
+   - Pagination for list endpoints (`cursor` or `offset/limit`)
+   - Proper HTTP status codes (200, 201, 400, 404, 422, 500)
+
+3. **Security considerations:**
+   - Input validation before processing
+   - No SQL/NoSQL injection (parameterized queries)
+   - Auth middleware placeholder (if applicable)
+   - Rate limiting note (if public endpoint)
+
+4. **Files to create:**
+   - Route handler / controller
+   - Zod validation schemas
+   - Types file (if separate)
+   - Basic integration test
+
+5. **Output:** working code following project conventions. Note any assumptions made.

.claude/skills/component/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: component
+description: Scaffold a new React component with TypeScript, accessibility, all states (loading, error, empty, success), and variant support via cva.
+disable-model-invocation: true
+argument-hint: "[ComponentName]"
+context: fork
+agent: frontend-architect
+---
+
+# Scaffold Component
+
+Create a production-ready React component named `$ARGUMENTS`.
+
+## Requirements
+
+1. **Read project context first:**
+   - Check `docs/frontend/architecture.md` for component conventions
+   - Check `RECOMMENDATIONS.md` for locked stack decisions (styling, state management)
+   - Look at existing components in `apps/web/` for patterns to follow
+
+2. **Component structure:**
+   - TypeScript with explicit props interface extending native HTML attributes
+   - Variants via `class-variance-authority` (cva) if multiple visual variants needed
+   - All states: loading (`aria-busy`), error, empty, success
+   - Forward ref if wrapping native elements
+
+3. **Accessibility (WCAG 2.2 AA):**
+   - Semantic HTML elements (not div soup)
+   - ARIA attributes where needed (`aria-label`, `aria-describedby`, `aria-live`)
+   - Keyboard navigation support
+   - Focus management for interactive elements
+   - Color contrast compliance
+
+4. **Files to create:**
+   - `ComponentName.tsx` — component implementation
+   - `ComponentName.test.tsx` — unit tests (Vitest + Testing Library, accessible queries)
+
+5. **Output:** working code, not explanations. Include a brief usage example at the end.

.claude/skills/db-schema/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: db-schema
+description: Design a database schema for an entity — tables, relationships, indexes, migration, and access patterns.
+disable-model-invocation: true
+argument-hint: "[entity-name]"
+context: fork
+agent: backend-architect
+---
+
+# Design Database Schema
+
+Design the database schema for entity `$ARGUMENTS`.
+
+## Steps
+
+1. **Read project context first:**
+   - Check `docs/backend/architecture.md` for database conventions
+   - Check `RECOMMENDATIONS.md` for locked ORM (Prisma/Drizzle/other)
+   - Look at existing schemas/migrations in the project
+
+2. **Gather requirements** — ask the user:
+   - What fields does this entity need?
+   - What are the relationships (belongs to, has many, many-to-many)?
+   - What are the primary query patterns (list, search, filter, aggregate)?
+   - Are there soft deletes, audit fields, or multi-tenancy requirements?
+
+3. **Design the schema:**
+   - Table definition with column types, constraints, defaults
+   - Primary key strategy (UUID v7 / auto-increment / CUID)
+   - Foreign keys with ON DELETE behavior
+   - Indexes based on query patterns (composite where needed)
+   - Unique constraints where applicable
+   - Timestamps: `created_at`, `updated_at`
+   - Soft delete: `deleted_at` if required
+
+4. **Provide deliverables:**
+   - Schema definition in the project's ORM format (Prisma/Drizzle/raw SQL)
+   - Migration file
+   - ER diagram (Mermaid) showing relationships
+   - Access pattern notes (which queries this schema optimizes for)
+   - Index justification (why each index exists)
+
+5. **Verify via context7** — check current ORM syntax and best practices before writing.

.claude/skills/improve-prompt/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: improve-prompt
+description: Diagnose and improve an LLM prompt — fix ambiguity, add constraints, specify output format, add examples and edge case handling.
+disable-model-invocation: true
+argument-hint: "[prompt-text-or-file]"
+context: fork
+agent: prompt-engineer
+---
+
+# Improve Prompt
+
+Diagnose and improve the provided prompt.
+
+## Input
+
+$ARGUMENTS
+
+## Steps
+
+1. **Diagnose the current prompt:**
+   - Ambiguity: vague instructions, unclear scope
+   - Missing output format: no schema or structure specified
+   - Weak constraints: "try to", "avoid if possible"
+   - No examples: complex tasks without few-shot
+   - Missing edge cases: no error/fallback handling
+   - No safety rules: missing refusal/deferral instructions
+   - Token bloat: redundant or filler text
+
+2. **Improve following these principles:**
+   - Constraints before instructions (what NOT to do first)
+   - Explicit output schema with required fields and types
+   - 2-3 representative examples for complex tasks
+   - Edge case handling (empty input, malicious input, ambiguous request)
+   - Refusal rules for user-facing prompts
+   - Remove every sentence that doesn't change model behavior
+
+3. **Verify via context7** — check target model capabilities and best practices
+
+4. **Output:**
+
+```markdown
+## Diagnosis
+- [Bullet list of issues found in the original prompt]
+
+## Improved Prompt
+[Clean, copy-ready prompt with clear sections]
+
+## Changes Made
+- [What changed and why — 3-5 items max]
+
+## Usage Notes
+- [Model, temperature, any caveats — only if non-obvious]
+```

.claude/skills/init-project/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: init-project
+description: Initialize a new project from this template — choose archetype, fill in RECOMMENDATIONS.md, and configure the workspace.
+disable-model-invocation: true
+---
+
+# Project Initialization
+
+Guide the user through setting up a new project from this template.
+
+## Reference files
+
+- `docs/archetypes.md` — 5 product archetypes and optional modules
+- `RECOMMENDATIONS.md` — template to fill in
+- `docs/examples/RECOMMENDATIONS-example.md` — filled-in example for reference
+- `docs/project-overview.md` — project definition template
+
+## Steps
+
+1. **Choose archetype** — Read `docs/archetypes.md` and present the 5 archetypes to the user:
+   - A: Chat-first Assistant
+   - B: Workflow / Generation Tool
+   - C: Classification / Decision Pipeline
+   - D: Agentic Automation
+   - E: Internal / One-off Tool
+
+   Ask the user to pick one.
+
+2. **Select modules** — Based on the chosen archetype, present the optional modules from `docs/archetypes.md` and ask which ones are in scope.
+
+3. **Fill RECOMMENDATIONS.md** — Walk through each section of `RECOMMENDATIONS.md` with the user:
+   - Section 1: Project Context (domain, archetype, modules, users, metrics)
+   - Section 2: Locked Stack Decisions (frontend, backend, infra)
+   - Section 3: Non-Negotiable Constraints (compliance, performance, cost)
+   - Section 4: Deviations from template defaults
+   - Section 5: Open Questions
+
+   Use `docs/examples/RECOMMENDATIONS-example.md` as a reference for the expected format.
+
+4. **Fill project-overview.md** — Update `docs/project-overview.md` with the project-specific information gathered above.
+
+5. **Update README.md** — Replace the template description in README.md with the actual project name and description.
+
+6. **Update .github config** — Replace `YOUR_ORG/YOUR_REPO` in `.github/ISSUE_TEMPLATE/config.yml` with the actual repository path.
+
+7. **Summary** — Show the user what was configured and suggest next steps:
+   - Review filled documents
+   - Create initial ADR for major stack decisions (`docs/adr/`)
+   - Begin Phase 1 planning

.claude/skills/phase-transition/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: phase-transition
+description: Handle a full phase transition — update the phase number, status, and documentation across all project files atomically.
+disable-model-invocation: true
+argument-hint: "[new-phase-number]"
+---
+
+# Phase Transition
+
+Update all project documentation when moving to a new development phase.
+
+## Steps
+
+1. Read `RULES.md` section 6.2 to determine the current phase
+2. Confirm the target phase with the user: $ARGUMENTS
+3. Read `.claude/status-update-checklist.md` and follow the **Phase Transition Checklist** section
+4. Update ALL files listed in the checklist — this must be atomic (all or nothing):
+
+   **Required updates:**
+   - `RULES.md` section 6.2 — change `Current phase: Phase N`
+   - `README.md` — update status block (phase badge and status line) and footer
+   - `DOCS.md` — update footer `**Last Updated:** Phase N (Description)`
+   - `RECOMMENDATIONS.md` — update `Current phase` in section 1, add Change Log entry in section 6
+   - `docs/phases-plan.md` — update header Phase/Status, mark completed phase tasks
+
+   **Conditional updates (check if relevant):**
+   - `docs/frontend/architecture.md` — lock decisions after Phase 1
+   - `docs/backend/architecture.md` — lock decisions after Phase 1
+   - `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` — archive after Phase 1
+
+5. Run the verification commands:
+   ```bash
+   grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases-plan.md
+   ```
+6. Confirm all files show the same phase number
+7. Show the user a summary of all changes made

.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: review-pr
+description: Review a specific GitHub pull request by number — fetches PR diff and comments via gh CLI, then provides structured review.
+disable-model-invocation: true
+argument-hint: "[pr-number]"
+context: fork
+agent: code-reviewer
+allowed-tools: Bash(gh:*), Read, Grep, Glob
+---
+
+# Review Pull Request
+
+Review GitHub PR #$ARGUMENTS.
+
+## Context
+
+PR details:
+!`gh pr view $ARGUMENTS`
+
+PR diff:
+!`gh pr diff $ARGUMENTS`
+
+PR comments:
+!`gh pr view $ARGUMENTS --comments 2>/dev/null || echo "No comments"`
+
+Changed files:
+!`gh pr diff $ARGUMENTS --name-only`
+
+## Steps
+
+1. **Understand the PR** — read title, description, and comments for context
+2. **Analyze all changed files** — not just the latest commit, ALL changes in the PR
+3. **Read relevant source files** for full context (not just the diff)
+4. **Verify dependencies** — check new packages for CVEs via context7
+5. **Check against project rules** — read `RULES.md`
+6. **Review in priority order:** Security → Reliability → Performance → Maintainability → Testing
+
+7. **Report:**
+
+```markdown
+# PR Review: #[number] — [title]
+
+## Summary
+[What this PR does, overall assessment]
+
+**Verdict**: APPROVE / APPROVE WITH COMMENTS / REQUEST CHANGES
+
+## Critical Issues
+[Security vulnerabilities, data loss risks — with fixes]
+
+## High Priority
+[Significant issues — with fixes]
+
+## Medium Priority
+[Improvements — grouped]
+
+## What's Done Well
+- [Specific praise]
+
+## Recommendations
+1. [Prioritized next steps]
+```

.claude/skills/review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: review
+description: Review current git diff for security, quality, performance, and maintainability issues. Provides actionable feedback with code fixes.
+disable-model-invocation: true
+context: fork
+agent: code-reviewer
+---
+
+# Code Review
+
+Review current changes for security, quality, and performance issues.
+
+## Context
+
+Staged changes:
+!`git diff --cached --stat`
+
+Detailed diff:
+!`git diff --cached`
+
+Unstaged changes:
+!`git diff --stat`
+
+Recent commit message:
+!`git log -1 --format="%s%n%b" 2>/dev/null || echo "No commits yet"`
+
+## Steps
+
+1. **Analyze the diff** — identify scope, languages, frameworks, data sensitivity
+2. **Verify dependencies** — check new imports/packages for CVEs via context7
+3. **Review in priority order:**
+   - Security (OWASP Top 10, secrets, auth, injection)
+   - Reliability (error handling, race conditions, resource leaks)
+   - Performance (N+1 queries, blocking I/O, missing pagination)
+   - Maintainability (complexity, naming, duplication, types)
+   - Testing (coverage for critical paths)
+
+4. **Check against project rules** — read `RULES.md` for constraints
+
+5. **Report:**
+
+```markdown
+# Code Review
+
+## Summary
+[2-3 sentences: what changed, assessment]
+
+**Verdict**: APPROVE / APPROVE WITH COMMENTS / REQUEST CHANGES
+
+## Critical Issues
+[Must fix before merge — with code fixes]
+
+## High Priority
+[Should fix — with code fixes]
+
+## Medium Priority
+[Consider fixing — grouped if similar]
+
+## What's Done Well
+- [Specific praise with file references]
+
+## Recommendations
+1. [Prioritized action items]
+```

.claude/skills/security-audit/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: security-audit
+description: Run a security audit on current git changes against OWASP Top 10. Checks for injection, auth issues, secrets, and misconfigurations.
+disable-model-invocation: true
+context: fork
+agent: security-auditor
+---
+
+# Security Audit
+
+Audit current changes for security vulnerabilities.
+
+## Context
+
+Current git diff:
+!`git diff --cached --diff-filter=ACMR`
+
+Unstaged changes:
+!`git diff --diff-filter=ACMR`
+
+Changed files:
+!`git diff --cached --name-only --diff-filter=ACMR && git diff --name-only --diff-filter=ACMR`
+
+## Steps
+
+1. **Analyze the diff** — identify security-relevant changes (auth, input handling, DB queries, file uploads, API endpoints, secrets)
+
+2. **Check against OWASP Top 10 2021 + API Top 10 2023:**
+   - Injection (SQL, NoSQL, Command, XSS)
+   - Broken Access Control (IDOR, privilege escalation)
+   - Cryptographic Failures (weak algorithms, hardcoded secrets)
+   - Insecure Design (business logic flaws, race conditions)
+   - Security Misconfiguration (defaults, verbose errors, missing headers)
+   - Vulnerable Components (check imports against known CVEs via context7)
+   - Auth Failures (session management, JWT issues)
+   - SSRF
+   - Missing input validation
+
+3. **False positive check** — verify framework mitigations before reporting (ORM, React escaping, CSRF tokens)
+
+4. **Report format:**
+
+```
+## Security Audit Report
+
+### Summary
+[Secure / Needs Improvement / Critical Issues Found]
+
+### Findings (sorted by severity)
+1. [CRITICAL/HIGH/MEDIUM/LOW] Title
+   - Location: `file:line`
+   - Impact: what can an attacker do
+   - Fix: copy-pasteable corrected code
+   - Reference: CWE/OWASP ID
+
+### No Issues Found In
+- [Areas that were checked and passed]
+```

.claude/skills/test-plan/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: test-plan
+description: Create a test strategy for a feature — test types, coverage targets, mocking approach, and CI integration.
+disable-model-invocation: true
+argument-hint: "[feature-name]"
+context: fork
+agent: test-engineer
+---
+
+# Test Plan
+
+Create a test strategy for `$ARGUMENTS`.
+
+## Steps
+
+1. **Understand the feature:**
+   - Read relevant code and documentation
+   - Identify critical paths (auth, payments, data mutations)
+   - Map dependencies (APIs, databases, external services)
+
+2. **Read project context:**
+   - `RECOMMENDATIONS.md` — testing stack, coverage targets
+   - `docs/backend/security.md` — security-critical flows that need tests
+   - Existing test infrastructure and patterns
+
+3. **Design the strategy:**
+
+## Output Format
+
+```markdown
+# Test Plan: [feature name]
+
+## Scope
+[What is being tested and why]
+
+## Test Types
+
+### Unit Tests
+- What: [functions, components, utilities]
+- Tools: Vitest + Testing Library
+- Coverage target: [%]
+- Key scenarios: [list]
+
+### Integration Tests
+- What: [API routes, DB operations, service interactions]
+- Tools: Vitest + MSW / Testcontainers
+- Key scenarios: [list]
+
+### E2E Tests
+- What: [critical user journeys]
+- Tools: Playwright
+- Key scenarios: [list]
+
+## Mocking Strategy
+| Dependency | Mock Approach | Justification |
+|------------|--------------|---------------|
+
+## Test Data
+- Factories: [what needs factories]
+- Fixtures: [static test data]
+- Seeds: [database seeds if needed]
+
+## Edge Cases & Error Paths
+- [list of scenarios to cover]
+
+## CI Integration
+- PR: [what runs, time budget]
+- Main: [what runs, time budget]
+- Artifacts: [traces, screenshots, coverage reports]
+
+## Risks
+- [What could go wrong, flake risks, external dependencies]
+```

.claude/skills/threat-model/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: threat-model
+description: Create a threat model for a feature or system — trust boundaries, attack vectors, risk assessment, and mitigations.
+disable-model-invocation: true
+argument-hint: "[feature-or-system]"
+context: fork
+agent: security-auditor
+---
+
+# Threat Model
+
+Create an AppSec-grade threat model for `$ARGUMENTS`.
+
+## Steps
+
+1. **Scope & Extract:**
+   - Read relevant code and documentation
+   - Map primary components, data stores, entry points
+   - Identify external integrations and trust boundaries
+
+2. **Derive Boundaries & Assets:**
+   - Enumerate trust boundaries with protocol/auth/encryption details
+   - List risk-driving assets (user data, credentials, payment info, API keys)
+
+3. **Attacker Profile:**
+   - Define realistic attacker goals tied to the assets
+   - Consider: anonymous external, authenticated user, compromised internal service
+   - Note what attackers cannot do (scoping assumptions)
+
+4. **Enumerate Threats:**
+   - Frame as abuse paths: exfiltration, privilege escalation, integrity compromise, DoS
+   - Tie each threat to a specific asset and boundary
+
+5. **Prioritize:**
+   - Rate: likelihood (low/medium/high) × impact (low/medium/high)
+   - Risk tiers:
+     - **High**: pre-auth RCE, auth bypass, cross-tenant access, key theft
+     - **Medium**: targeted DoS, partial data exposure, rate-limit bypass
+     - **Low**: low-sensitivity info leaks, noisy DoS
+
+6. **Validate** — ask 1-3 targeted questions about deployment, auth, data sensitivity
+
+7. **Recommend Mitigations** — concrete, tied to specific code locations and control types
+
+## Output Format
+
+```markdown
+# Threat Model: [feature/system name]
+
+## Scope
+[Components, data flows, boundaries]
+
+## Architecture Diagram
+[Mermaid diagram showing components and trust boundaries]
+
+## Assets
+| Asset | Sensitivity | Location |
+|-------|-------------|----------|
+
+## Threats
+| # | Threat | Asset | Likelihood | Impact | Priority | Mitigation |
+|---|--------|-------|------------|--------|----------|------------|
+
+## Assumptions
+[What was assumed about deployment, auth, environment]
+
+## Open Questions
+[Questions for the team]
+```

.claude/skills/update-status/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: update-status
+description: Run the milestone status update checklist — synchronize phase, status, and progress across all project documentation files.
+disable-model-invocation: true
+---
+
+# Status Update
+
+Synchronize project status across documentation after a milestone is completed.
+
+## Current state
+
+Read these files to understand the current project state:
+
+- `RULES.md` section 6.2 — current phase (canonical source of truth)
+- `RECOMMENDATIONS.md` section 1 — current phase field
+- `.claude/status-update-checklist.md` — full checklist reference
+
+## Steps
+
+1. Read `.claude/status-update-checklist.md` and follow the **Milestone Update Checklist** section
+2. Ask the user what milestone was completed: $ARGUMENTS
+3. Update the files listed in the checklist:
+   - `RECOMMENDATIONS.md` — add entry to Change Log (section 6), remove resolved Open Questions (section 5)
+   - `README.md` — update status block if progress indicators changed
+   - `docs/phases-plan.md` — mark completed tasks
+4. Run the verification commands from the checklist to confirm consistency
+5. Show the user a summary of what was updated

.claude/skills/write-tests/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: write-tests
+description: Write tests for a specific file — unit and integration tests with Vitest, Testing Library, accessible queries, and AAA pattern.
+disable-model-invocation: true
+argument-hint: "[file-path]"
+context: fork
+agent: test-engineer
+---
+
+# Write Tests
+
+Write comprehensive tests for `$ARGUMENTS`.
+
+## Steps
+
+1. **Read the target file** and understand:
+   - What it does (component, service, utility, API handler)
+   - Its dependencies and side effects
+   - Edge cases and error paths
+
+2. **Read project context:**
+   - Check `RECOMMENDATIONS.md` for testing stack decisions
+   - Look at existing test files for patterns and conventions
+   - Check test config (vitest.config, playwright.config)
+
+3. **Write tests following these rules:**
+
+   **Structure:**
+   - AAA pattern (Arrange → Act → Assert)
+   - Behavior-focused names: `it('displays error when API fails')`
+   - Group by concern: `describe('when user is logged in', ...)`
+   - Co-locate with source file: `Component.test.tsx` next to `Component.tsx`
+
+   **Queries (for React components):**
+   - `getByRole` → `getByLabelText` → `getByText` → `getByTestId` (last resort)
+   - Use `userEvent` over `fireEvent`
+
+   **Mocking:**
+   - MSW for HTTP APIs
+   - `vi.mock()` only for third-party services
+   - Real implementations for internal logic
+   - Deterministic test data via factories
+
+   **Coverage:**
+   - Happy path
+   - Error states
+   - Empty/loading states
+   - Edge cases (null, undefined, empty arrays, boundary values)
+   - Accessibility: keyboard interaction, ARIA states
+
+4. **No arbitrary waits** — use `waitFor`, `findBy`, or proper async handling.
+
+5. **Output:** working test file, ready to run with `vitest`.

.claude/status-update-checklist.md

@@ -1,91 +1,82 @@
 # Status Update Checklist
 
-**Use this checklist when updating project status to ensure ALL documentation stays synchronized.**
-
-## Files to Update When Status Changes
-
-When marking a milestone as complete or updating progress, check ALL these files:
-
-### 1. RECOMMENDATIONS.md
-- [ ] Update header status line
-- [ ] Update current milestone/phase progress
-- [ ] Update "Completed Tasks" section
-- [ ] Move "Active Tasks" to "Completed Tasks" if done
-- [ ] Update "Next Focus" section
-- [ ] Update "Last Updated" date
-
-### 2. README.md
-- [ ] Update "Current Status" section
-- [ ] Update "Recent Updates" or changelog section
-- [ ] Update any progress indicators
-- [ ] Update footer status/date if present
-
-### 3. DOCS.md (if exists)
-- [ ] Update relevant phase/milestone descriptions
-- [ ] Update changelog reference
-- [ ] Update "Current Development Status" section
-
-### 4. Phase/Milestone Documentation (if exists)
-- [ ] Update status header
-- [ ] Update progress percentage
-- [ ] Update "Overall Progress" section
-- [ ] Update "Last Updated" date
-
-### 5. CHANGELOG.md (if exists)
-- [ ] Add new entry for completed work
-- [ ] Follow semantic versioning or project conventions
-
-## Quick Commands to Find Status References
-
-```bash
-# Search for progress indicators across documentation
-grep -ri "progress\|status\|complete\|in progress\|todo" \
-  RECOMMENDATIONS.md README.md DOCS.md docs/
-
-# Search for date references that may need updating
-grep -ri "last updated\|updated:\|date:" \
-  RECOMMENDATIONS.md README.md DOCS.md
-
-# Find percentage indicators
-grep -r "[0-9]\+%" RECOMMENDATIONS.md README.md DOCS.md docs/
-```
-
-## Standard Update Workflow
-
-1. **Identify** — What milestone/task was completed?
-2. **Check ALL** — Go through this entire checklist
-3. **Update** — Edit all relevant files in one batch
-4. **Verify** — Run grep commands to ensure consistency
-5. **Commit** — Single commit with all changes together
-
-```bash
-# Good workflow — atomic updates
-git add RECOMMENDATIONS.md README.md DOCS.md CHANGELOG.md docs/
-git commit -m "docs: update status for [milestone/feature] completion"
-
-# Bad workflow — fragmented updates
-git commit -m "Update RECOMMENDATIONS.md"
-# ... later notice README not updated
-git commit -m "Update README.md too"
-# ... creates inconsistent history
-```
-
-## Principles
-
-- **Atomic updates** — All status changes in one commit
-- **Consistency** — Same information across all docs
-- **Discoverability** — Users should find accurate status anywhere
-- **Traceability** — Clear commit history of progress
-
-## Customization
-
-Adapt this checklist for your project:
-
-1. **Add project-specific files** — Include any additional docs that track status
-2. **Define status indicators** — Decide on consistent progress format (%, fractions, checkboxes)
-3. **Set update triggers** — Define what events require a status update
-4. **Assign ownership** — Who is responsible for keeping docs in sync?
+Instructions for keeping project documentation synchronized when status changes.
+AI agents and developers should follow this checklist to prevent drift between files.
 
 ---
 
-**Remember: When status changes, update EVERYTHING at once. No exceptions.**
+## When to Use This Checklist
+
+| Trigger | Scope |
+|---------|-------|
+| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files |
+| **Milestone completed** within a phase | Sections 1–3 only |
+| **Architecture decision locked** | RECOMMENDATIONS.md + new ADR in `docs/adr/` |
+
+---
+
+## Phase Transition Checklist
+
+Run every item when the project moves to a new phase.
+
+### 1. RULES.md
+- [ ] Update section 6.2: change `Current phase: Phase N` to the new phase
+
+### 2. README.md
+- [ ] Update "Current Status" block (phase badge and status line)
+- [ ] Update footer status line at the bottom of the file
+
+### 3. DOCS.md
+- [ ] Update footer: `**Last Updated:** Phase N (Description)`
+
+### 4. RECOMMENDATIONS.md
+- [ ] Update `Current phase` field in section 1
+- [ ] Add entry to section 6 (Change Log)
+
+### 5. docs/phases-plan.md
+- [ ] Update `**Phase:**` and `**Status:**` in the header
+- [ ] Mark completed phase tasks as done
+
+### 6. Architecture docs (if phase affects them)
+- [ ] `docs/frontend/architecture.md` — lock decisions after Phase 1
+- [ ] `docs/backend/architecture.md` — lock decisions after Phase 1
+- [ ] Archive `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` after Phase 1
+
+---
+
+## Milestone Update Checklist
+
+Run when a significant milestone is completed within the current phase.
+
+### 1. RECOMMENDATIONS.md
+- [ ] Add entry to section 6 (Change Log)
+- [ ] Update section 5 (Open Questions) — remove resolved items
+
+### 2. README.md
+- [ ] Update "Current Status" block if progress indicators changed
+
+### 3. docs/phases-plan.md
+- [ ] Mark completed tasks
+
+---
+
+## Verification
+
+After updating, run these commands to check consistency:
+
+```bash
+# All files should show the SAME phase number
+grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases-plan.md
+
+# Check for stale status markers
+grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md
+```
+
+---
+
+## Principles
+
+- **Atomic** — all status changes in one commit
+- **Concrete** — update actual sections listed above, not vague references
+- **Verifiable** — run the grep commands to confirm consistency
+- **Single source of truth** — `RULES.md` section 6.2 is the canonical phase indicator