nextjs-hackathon-stack 0.1.35 → 0.1.37

package/template/.cursor/skills/build-feature/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: build-feature
+description: Plan and implement a new feature following TDD — tech-lead planning, backend + frontend in parallel, review gate, and memory sync. Run in a fresh conversation after /discover-feature. Triggers: 'build feature', 'implement feature', 'start building', 'build from requirements'. NOT for: bug fixes, refactors, or API-only routes (use /create-api-route).
+---
+
+# Build Feature Skill
+
+> **Invoke as:** `/build-feature @.requirements/<feature-name>.md`
+> Run in **Agent mode** in a **fresh conversation** (not the same one where you ran `/discover-feature`).
+
+## IMPORTANT: Fresh Conversation Required
+
+If this conversation already contains requirements gathering, **start a new conversation** first. Reusing the same context risks hitting the token limit mid-implementation.
+
+If context usage exceeds 60% at any point, stop and tell the user to continue in a new conversation referencing the current step.
+
+---
+
+## Process
+
+### 1. Read the Requirements
+
+Read `.requirements/<feature-name>.md`. Confirm the spec exists and has acceptance criteria before proceeding. If no spec exists, tell the user to run `/discover-feature <description>` first.
+
+### 2. Load Architecture Context via MCP Memory
+
+Load project context with targeted queries (token-efficient):
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. `search_memory` with `tags: ["project:<project-name>", "domain:ui"]` — installed shadcn/ui components
+3. `search_memory` with `tags: ["project:<project-name>", "domain:database"]` — existing schema
+4. `search_memory` with `tags: ["project:<project-name>", "domain:features"]` — existing features and paths
+5. `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` — canonical pattern references
+6. `search_memory` with `tags: ["project:<project-name>", "domain:rules"]` — active lint/TS rules
+
+**Fallback**: if memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly.
+
+**Also read `eslint.config.ts` and `tsconfig.json`** to confirm active rules and compiler flags before writing any code.
+
+**Dependency pre-flight:**
+```bash
+pnpm ls drizzle-orm   # Confirm installed version
+pnpm typecheck        # Confirm baseline passes — fix pre-existing errors first
+```
+
+### 3. Planning (Tech Lead)
+
+Before any code is written, produce a technical plan and get user approval.
+
+Using the requirements + MCP memory context:
+
+1. **Map acceptance criteria to technical tasks** — one task per agent, scoped to a single concern:
+   - Backend tasks: schema changes, Server Actions, queries, RLS policies
+   - Frontend tasks: components, pages, hooks, shadcn installs
+   - Shared: Zod schemas, type definitions
+
+2. **Plan the test structure**:
+   - List which test files will be created
+   - One `describe` block per acceptance criterion
+   - Which mocks are needed (`makeSupabaseMock`, HTTP mocks, etc.)
+   - Which edge cases map to which criteria
+
+3. **Identify reuse**:
+   - Which canonical patterns to copy (from MCP memory results)
+   - Which shadcn components are already installed vs need installing
+   - Which shared utilities apply (`formFieldText`, `firstZodIssueMessage`, etc.)
+
+4. **Present the plan to the user** and wait for approval before proceeding to Step 4.
+
+> Present as a brief summary: what backend will do, what frontend will do, which tests will be written, any risks or decisions that need user input.
+
+### 4. Create Feature Structure
+
+```
+src/features/<feature-name>/
+├── components/
+├── actions/
+├── queries/
+├── hooks/
+├── api/
+├── lib/
+└── __tests__/
+```
+
+### 5. Pre-Test Setup
+
+Update `vitest.config.ts` to exclude files that cannot be meaningfully tested in jsdom:
+- Drizzle schema file(s) (`src/shared/db/*.schema.ts`)
+- Pure type-only files
+- Portal/browser-API-dependent UI wrappers (e.g., `src/shared/components/ui/sonner.tsx`)
+
+```typescript
+// vitest.config.ts — add to coverage.exclude before writing tests
+exclude: [
+  "src/shared/db/*.schema.ts",
+  "src/shared/components/ui/sonner.tsx",
+]
+```
+
+### 6. TDD: RED Phase
+
+Write ALL test files first — zero implementation code at this stage:
+- `__tests__/<component>.test.tsx` — component tests
+- `__tests__/use-<feature>.test.ts` — hook tests (if applicable)
+- `__tests__/<action>.action.test.ts` — action tests (see `references/server-action-test-template.md`)
+- `__tests__/<feature>.queries.test.ts` — query tests
+
+Import mock helpers from `@/shared/test-utils/supabase-mock` — do not inline mock chains.
+
+**Coverage guidance:** Threshold is 95% statements/functions/lines and 90% branches. Use `/* v8 ignore next */` for genuinely unreachable defensive branches.
+
+**For standard CRUD features**: write tests and implementation per module (queries test+impl → actions test+impl → UI test+impl) instead of strict all-RED-then-all-GREEN.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All new tests must **FAIL** (red). If any new test passes without implementation, the test is wrong — fix it before continuing.
+
+### 7. TDD: GREEN Phase
+
+Launch **@backend and @frontend in parallel** — they work on independent files:
+
+| @backend handles | @frontend handles |
+|-----------------|-------------------|
+| `actions/` | `components/` |
+| `queries/` | `page.tsx` |
+| `schema.ts` changes | shadcn component installs |
+| RLS policies | Loading/empty states |
+
+Do NOT serialize these — they touch different files.
+
+**Do NOT run intermediate verification between sub-tasks.** Complete all GREEN phase work, then run a single verification pass in Step 9.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All tests must **PASS** (green).
+
+### 8. Refactor
+
+Clean up while keeping tests green.
+
+### 9. Verify & Self-Check
+
+Run all three **together** (single pass) and paste output:
+```bash
+pnpm test:coverage   # Must meet thresholds: 95% statements/functions/lines, 90% branches
+pnpm lint            # Must pass with 0 warnings
+pnpm typecheck       # Must pass with 0 errors
+```
+
+If issues are found, fix **all** of them, then run the full trio again once.
+
+Before moving to the review gate, verify manually:
+- [ ] No `any` types: `grep -r ": any" src/features/<feature>/`
+- [ ] No `eslint-disable` comments
+- [ ] All UI text in Spanish, all `it()`/`describe()` text in English
+- [ ] No file over 200 lines
+- [ ] No function over 20 lines
+- [ ] AAA pattern (`// Arrange`, `// Act`, `// Assert`) in every test
+- [ ] `ActionResult` returned from every Server Action mutation
+- [ ] Toast feedback (`toast.success` / `toast.error`) for every mutation
+- [ ] RLS policies written for every new table
+
+### 10. Review Gate
+
+Run @code-reviewer and @security-researcher **in parallel** on the changed files. Fix any findings before marking the feature complete.
+
+This step is not optional. The feature is not done until both reviewers pass.
+
+> **Note for time-critical work:** if the user explicitly says to skip the review gate, you may proceed — but flag the skipped step so it can be done as a follow-up.
+
+### 11. Update Architecture Snapshot & MCP Memory
+
+Update `.cursor/memory/architecture-snapshot.md`:
+- Add new DB tables to the schema table
+- Add new shadcn components to the installed list
+- Add the new feature to the Existing Features table
+- Add any new canonical pattern references that differ from existing ones
+
+Then run `/memory sync` to persist all changes to MCP memory so future sessions load context efficiently.
+
+---
+
+## Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| MCP memory returns no results | Memory not synced yet | Run `/memory sync` first, then retry |
+| Test passes without implementation (RED fails) | Test asserts on falsy/default values | Ensure the test expects a specific truthy result that only a real implementation can produce |
+| `pnpm typecheck` fails on schema file | Schema imported in test without mock | Add the schema file to `coverage.exclude` in `vitest.config.ts` |
+| Context exceeds 60% mid-build | Feature too large for one conversation | Stop, note the current step, start a new conversation referencing it |
+| `lint-staged` blocks commit | ESLint warnings treated as errors | Fix all warnings; never use `eslint-disable` inline — fix the code |
+
+---
+
+## Guardrails
+- NEVER start implementation before the user approves the plan (Step 3)
+- NEVER start implementation before the RED gate is confirmed with actual test output
+- Coverage threshold: 95% statements/functions/lines, 90% branches
+- Follow `features/* → shared/*` dependency direction
+- RLS is mandatory for every new table — not a post-step
+- Write lint-compliant code from the start — read the Strict Rules Reference before the first line of code

package/template/.cursor/skills/create-api-route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-api-route
-description: Create a new Next.js API route with validation, auth, and tests. Use when adding API endpoints to a feature.
+description: Create a new Next.js API route with Zod validation, auth check, and TDD tests. Use when adding API endpoints to a feature. Triggers: 'create API route', 'add endpoint', 'new route handler', 'API endpoint'. NOT for: Server Actions (those go in features/*/actions/).
 ---
 
 # Create API Route Skill

package/template/.cursor/skills/discover-feature/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: discover-feature
+description: Run the requirements discovery process for a new feature. Produces a functional issue in .requirements/<feature-name>.md. Use this in Conversation 1, then start a new conversation and run /build-feature. Triggers: 'new feature', 'define requirements', 'discover feature', 'I want to build'. NOT for: already-defined features (use /build-feature directly).
+---
+
+# Discover Feature Skill
+
+> **Invoke as:** `/discover-feature <feature-description>`
+> Run in **Agent mode**. After this skill completes, **start a new conversation** before running `/build-feature`.
+
+## IMPORTANT: Token Budget
+
+This conversation is for requirements only. Do NOT start implementation here. When done, start a fresh conversation to keep the implementation context clean.
+
+---
+
+## Process
+
+### 1. Load Existing Features via MCP Memory
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:features"]` to understand existing features and their relationships to the new request
+3. **Fallback**: if memory service is unavailable, read `.cursor/memory/architecture-snapshot.md` → "Existing Features" section
+
+### 2. Discovery Questions
+
+Ask ALL of the following before writing anything. Cover at minimum questions 1–3 + any relevant ones from 4–8.
+
+1. **Problem & audience** — "What problem does this solve? Who experiences it?"
+2. **User flows** — "Walk me through the happy path. What happens on error?"
+3. **Edge cases & constraints** — "What are the limits? What should NOT happen?"
+4. **Field constraints** — "What are the length limits, allowed formats, required vs optional fields?"
+5. **Volume & scale** — "How many records are expected? Do you need search or pagination?"
+6. **File/upload specifics** — (if applicable) "What file types and size limits are allowed?"
+7. **Privacy & access** — "Who can see this data? Is it per-user or shared?"
+8. **Relationship to existing features** — (informed by MCP memory results) "Does this link to `<existing feature>`?"
+9. **Confirm understanding** — Restate what you heard and ask for approval before writing
+
+If the user says "just do it" without answering, document all assumptions explicitly in an `## Assumptions` section at the top of the spec.
+
+Only after the user confirms your understanding should you produce the functional issue.
+
+### 3. Write Functional Issue
+
+Create `.requirements/<feature-name>.md` using this format:
+
+```markdown
+## Feature: [Feature Name]
+
+### User Story
+As a [user type], I want [goal] so that [reason].
+
+### Acceptance Criteria
+- [ ] AC1: When [user does X], they see [Y]
+- [ ] AC2: When [error condition], user sees [message/state]
+- [ ] AC3: [Edge case]: [expected outcome]
+
+### Functional Test Cases
+- [ ] TC1 (AC1): User does X → sees Y (happy path)
+- [ ] TC2 (AC2): User triggers error → sees error message
+- [ ] TC3 (AC3): Edge case behavior visible to user
+```
+
+**Rules for this format:**
+- Acceptance criteria in plain functional language — no code, no implementation details
+- Test cases describe what the **user sees**, not system internals
+- Every acceptance criterion maps to at least one test case
+- No mention of database tables, API calls, component names, or file paths
+- Write requirements in the user's language; IDs (`AC1`, `TC1`) and technical terms stay in English
+
+### 4. Store Requirement in MCP Memory
+
+```
+store_memory({
+  content: "Requirement: <feature-name> — <one-line summary of what the feature does and key acceptance criteria>",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:features", "category:requirement", "feature:<feature-name>", "status:pending-snapshot"]
+  }
+})
+```
+
+### 5. Hand Off
+
+Tell the user:
+
+> Requirements written to `.requirements/<feature-name>.md`.
+>
+> **Next step**: Start a new conversation and run:
+> ```
+> /build-feature @.requirements/<feature-name>.md
+> ```
+
+---
+
+## Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| User says "just do it" without answering | Wants to skip discovery | Document all assumptions in an `## Assumptions` section at the top of the spec |
+| MCP memory unavailable | Service not running or not installed | Fall back to reading `.cursor/memory/architecture-snapshot.md` directly |
+| Feature overlaps with existing one | Missed relationship check in Step 1 | Re-query MCP with `domain:features`, clarify scope with user before writing spec |
+| User changes requirements mid-discovery | Evolving understanding | Update the spec before handing off; don't start `/build-feature` with stale requirements |
+
+---
+
+## Guardrails
+- Always ask questions before writing — never assume requirements
+- Do NOT start any implementation in this conversation
+- Document all assumptions explicitly if the user skips questions
+- Hand off to `/build-feature` in a fresh conversation — never chain them in the same conversation

package/template/.cursor/skills/memory/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: memory
+description: Sync architecture-snapshot.md with MCP memory service and recall project knowledge semantically. Use when starting a new session, after completing a feature, or to search project context efficiently. Triggers: 'memory sync', 'memory recall', 'memory update', 'sync architecture', 'search project knowledge', 'what components are installed'.
+---
+
+# Memory Skill
+
+> **Invoke as:** `/memory sync`, `/memory recall "query"`, `/memory update`
+
+## Preflight Check
+
+Before running any subcommand, verify the memory service is running:
+
+```
+retrieve_memory({ query: "test", n_results: 1 })
+```
+
+If this fails, tell the user: "Memory service is unavailable. Run `pip install mcp-memory-service` and ensure the `memory` binary is in PATH (check `.cursor/mcp.json`)."
+
+---
+
+## `/memory sync` — Snapshot → MCP
+
+Parses `architecture-snapshot.md` into individual entries and stores each in MCP memory. Run this after scaffolding a new project or after `/memory update`.
+
+### Steps
+
+1. Read `package.json` — get `name` field as `<project-name>`
+2. Read `.cursor/memory/architecture-snapshot.md`
+3. For each section, parse into individual entries and call `store_memory`:
+
+**Installed shadcn/ui Components** (one memory for the full list):
+```
+store_memory({
+  content: "Installed shadcn/ui components: button, card, input, label, spinner",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:ui", "category:components"]
+  }
+})
+```
+
+**DB Schema** (one memory per table row):
+```
+store_memory({
+  content: "DB table: profiles — columns: id (uuid PK), email (text unique), createdAt, updatedAt",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:database", "category:schema", "table:profiles"]
+  }
+})
+```
+
+**Existing Features** (one memory per feature row):
+```
+store_memory({
+  content: "Feature: auth — path: src/features/auth/ — Login/logout, cookie-based sessions via Supabase",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:features", "category:feature", "feature:auth"]
+  }
+})
+```
+
+**Canonical Pattern References** (one memory per pattern row):
+```
+store_memory({
+  content: "Canonical pattern: Server Action — file: src/features/todos/actions/todos.action.ts",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:patterns", "category:pattern", "pattern:server-action"]
+  }
+})
+```
+
+**Key Rules** (one memory per bullet):
+```
+store_memory({
+  content: "Rule: Runtime queries use Supabase client only — Drizzle is schema/migrations only",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:rules", "category:rule"]
+  }
+})
+```
+
+**Shared Utilities** (one memory per utility row):
+```
+store_memory({
+  content: "Utility: formFieldText(formData, key) — location: src/shared/lib/form-utils.ts — Safe FormData text extraction, avoids no-base-to-string lint error",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:shared", "category:utility"]
+  }
+})
+```
+
+**Strict Rules Reference** (one memory per `###` sub-heading group):
+```
+store_memory({
+  content: "TypeScript strict rules: noUncheckedIndexedAccess (guard arr[i]), exactOptionalPropertyTypes (omit key instead of undefined), noImplicitReturns (explicit return in all branches), noUnusedLocals/noUnusedParameters (prefix unused with _), useUnknownInCatchVariables (narrow with instanceof Error)",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:rules", "category:lint-rule", "subcategory:typescript"]
+  }
+})
+```
+
+4. After all entries are stored, call:
+```
+trigger_consolidation({ time_horizon: "daily", immediate: true })
+```
+
+5. Report: "Stored N memories for project `<project-name>`. Consolidation triggered."
+
+---
+
+## `/memory recall "query"` — Semantic Search
+
+Use to find project context without reading the full snapshot.
+
+### Steps
+
+1. Read `package.json` — get `<project-name>`
+2. Call broad semantic search:
+```
+retrieve_memory({ query: "<user-query>", n_results: 10 })
+```
+3. If results are too broad, narrow with tags:
+```
+search_memory({
+  query: "<user-query>",
+  tags: ["project:<project-name>"],
+  limit: 5,
+  min_score: 0.6
+})
+```
+4. Present results as a summary. If no results found, tell the user to run `/memory sync` first.
+
+---
+
+## `/memory update` — MCP → Snapshot
+
+Merges new entries (tagged `status:pending-snapshot`) back into `architecture-snapshot.md`. Run after agents store new knowledge via `store_memory`.
+
+### Steps
+
+1. Read `package.json` — get `<project-name>`
+2. Search for pending entries:
+```
+search_memory({
+  query: "new pending architecture update",
+  tags: ["project:<project-name>", "status:pending-snapshot"],
+  limit: 50
+})
+```
+3. For each result, determine the target section from the `domain` and `category` tags:
+   - `domain:ui` → "Installed shadcn/ui Components"
+   - `domain:database` → "DB Schema"
+   - `domain:features` → "Existing Features"
+   - `domain:patterns` → "Canonical Pattern References"
+   - `domain:rules` + `category:rule` → "Key Rules"
+   - `domain:shared` → "Shared Utilities"
+4. Read `.cursor/memory/architecture-snapshot.md` and merge new entries into the correct sections
+5. Write the updated snapshot
+6. Re-store each processed memory WITHOUT the `status:pending-snapshot` tag:
+```
+store_memory({
+  content: "<same content>",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:...", "category:..."]
+    // pending-snapshot tag removed
+  }
+})
+```
+7. Call `trigger_consolidation({ time_horizon: "daily", immediate: true })`
+8. Report: "Merged N entries into architecture-snapshot.md."
+
+---
+
+## Tag Schema Reference
+
+All memories must include `type: "architecture"` and `project:<project-name>`. Use lowercase with hyphens for multi-word values.
+
+| Snapshot Section | Required Tags | Optional Tags |
+|---|---|---|
+| shadcn Components | `domain:ui`, `category:components` | — |
+| DB Schema | `domain:database`, `category:schema` | `table:<name>` |
+| Existing Features | `domain:features`, `category:feature` | `feature:<name>` |
+| Canonical Patterns | `domain:patterns`, `category:pattern` | `pattern:<type>` |
+| Key Rules | `domain:rules`, `category:rule` | — |
+| Shared Utilities | `domain:shared`, `category:utility` | — |
+| Strict Rules (TS) | `domain:rules`, `category:lint-rule` | `subcategory:typescript` |
+| Strict Rules (ESLint) | `domain:rules`, `category:lint-rule` | `subcategory:eslint` |
+
+When storing **new** architecture knowledge (e.g., after `/build-feature`), add `status:pending-snapshot` so `/memory update` can sync it back.
+
+---
+
+## Guardrails
+
+- NEVER store secrets, API keys, `.env` values, or credentials in memory
+- ALWAYS scope memories with `project:<project-name>` to prevent cross-project pollution
+- ALWAYS use `type: "architecture"` for snapshot-derived memories
+- Keep individual memory content under 300 words for effective semantic retrieval
+- The snapshot file (`.cursor/memory/architecture-snapshot.md`) is the source of truth — MCP memory is a search index
+- If the memory service is unavailable, agents fall back to reading the snapshot file directly

package/template/.cursor/skills/review-branch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-branch
-description: Review current branch changes against develop. Runs full code quality checklist.
+description: Review current branch changes against develop — runs full code quality, testing, architecture, and security checklist. Triggers: 'review branch', 'review my changes', 'check branch quality', 'review PR'.
 disable-model-invocation: true
 ---
 

package/template/.cursor/skills/security-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-audit
-description: Run a security audit on the codebase. Checks OWASP Top 10, RLS, secrets, and dependencies.
+description: Run a full security audit on the codebase — checks OWASP Top 10, RLS policies, hardcoded secrets, auth coverage, input validation, XSS vectors, and security headers. Triggers: 'security audit', 'audit security', 'check vulnerabilities', 'scan for secrets', 'check RLS'.
 disable-model-invocation: true
 ---
 

package/template/.cursor/skills/security-audit/references/audit-steps.md

@@ -16,7 +16,7 @@ grep -r "password\s*=" src/ --include="*.ts"
 Check `.env.example` has no real values.
 
 ### 3. RLS Verification
-For each table in `src/shared/db/schema.ts`:
+For each table in `src/shared/db/*.schema.ts`:
 - Confirm RLS is enabled in Supabase dashboard
 - Confirm explicit policies exist
 

package/template/AGENTS.md

@@ -1,3 +1,31 @@
+# Agent Routing
+
+Use the specialist agents in `.cursor/agents/` for focused tasks:
+
+| Agent | Use when |
+|-------|----------|
+| `@technical-lead` | Default entry point — task breakdown, architecture decisions, orchestration |
+| `@backend` | Server Actions, Drizzle schema, Supabase RLS, API routes, migrations |
+| `@frontend` | React components, shadcn/ui, Tailwind, pages, form UI |
+| `@test-qa` | TDD workflow, test writing, coverage gaps, mock setup |
+| `@code-reviewer` | Branch/PR review — readonly, fast model |
+| `@security-researcher` | Security audit, vulnerability check, auth review — readonly |
+| `@business-intelligence` | Requirements discovery, user stories, acceptance criteria — readonly |
+
+# Feature Development Workflow
+
+**New feature** (2 conversations):
+```
+Conversation 1: /discover-feature <description>  →  writes .requirements/<name>.md
+Conversation 2 (fresh): /build-feature @.requirements/<name>.md
+```
+
+**Bug fix:** `@test-qa` (reproduce) → `@backend`/`@frontend` (fix) → `@code-reviewer`
+
+**Refactor:** `@technical-lead` (plan) → `@backend`/`@frontend` (implement) → `@test-qa` (verify) → `@code-reviewer`
+
+**API endpoint only:** `/create-api-route` → `@code-reviewer`
+
 <!-- BEGIN:nextjs-agent-rules -->
 
 # Next.js: ALWAYS read docs before coding
@@ -23,7 +51,7 @@ Read `.env.example` for the full list. Key vars:
 # Migrations
 
 Migration files in `src/shared/db/migrations/` are auto-generated. NEVER create, edit, or delete them directly.
-- Edit schema: `src/shared/db/schema.ts`
+- Edit schema: `src/shared/db/*.schema.ts` (one file per table)
 - Generate migration: `pnpm db:generate`
 - Apply migration: `pnpm db:migrate`
 - Push schema (dev only): `pnpm db:push`

package/template/CLAUDE.md

@@ -19,25 +19,25 @@ Read these rules when working on related files:
 
 This project uses specialist agents in `.claude/agents/`. Follow the technical-lead workflow:
 
-- **New feature**: requirements (`business-intelligence`) → task breakdown (`technical-lead`) → tests first (`test-qa`) → implementation (`backend` + `frontend` **in parallel**) → review (`code-reviewer` + `security-researcher` **in parallel**)
+- **New feature**: `/discover-feature` (Conversation 1) → `/build-feature` (Conversation 2, fresh)
 - **Bug fix**: reproduce with failing test (`test-qa`) → fix (`backend`/`frontend`) → review (`code-reviewer`)
 - **Refactor**: plan (`technical-lead`) → implement (`backend`/`frontend`) → verify (`test-qa`) → review (`code-reviewer`)
 
 ## Recommended: 2-Conversation Workflow for New Features
 
-Split new feature work across two conversations to avoid context exhaustion (hitting >80% context mid-implementation):
+Split new feature work across two conversations to avoid context exhaustion:
 
-**Conversation 1 — Requirements** (low context, can be discarded after)
+**Conversation 1 — Requirements** (Agent mode)
 ```
-@business-intelligence → write .requirements/<feature-name>.md → confirm with user
+/discover-feature <description>  →  discovery questions  →  writes .requirements/<name>.md
 ```
 
-**Conversation 2 — Implementation** (fresh context, reads spec from file)
+**Conversation 2 — Build** (Agent mode, fresh conversation)
 ```
-/create-feature  →  reads .requirements/<feature-name>.md  →  full TDD pipeline
+/build-feature @.requirements/<name>.md  →  planning → TDD pipeline → review → memory sync
 ```
 
-The `/create-feature` skill reads the requirements file directly, so the BI conversation history is not needed during implementation. This keeps each conversation well under 50% context usage.
+The `/build-feature` skill reads the requirements file directly and runs the full pipeline — tech-lead planning, TDD implementation (backend + frontend in parallel), review gate, and memory sync. This keeps each conversation well under 60% context usage.
 
 # File Naming
 
@@ -51,9 +51,31 @@ The `/create-feature` skill reads the requirements file directly, so the BI conv
 This project uses [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) for persistent semantic memory across sessions.
 Config is shared via `.cursor/mcp.json` (symlinked to `.mcp.json`).
 
-If not installed automatically during scaffolding:
+If not installed automatically during scaffolding, install via `pipx` (works on macOS, Linux, Windows):
+
 ```bash
-pip install mcp-memory-service
+# macOS
+brew install pipx && pipx ensurepath
+pipx install mcp-memory-service
+
+# Linux / Windows
+pip install pipx
+pipx install mcp-memory-service
 ```
 
+> **macOS note:** If you see `SQLite extension loading not supported`, pipx picked Apple's Python.
+> Fix: `pipx install mcp-memory-service --python $(brew --prefix python@3.12)/bin/python3.12`
+
+## Memory Skill
+
+Use `/memory` to sync and query project knowledge:
+
+- `/memory sync` — Parse `architecture-snapshot.md` and store each entry in MCP memory (run after scaffolding; `/build-feature` runs this automatically at the end of each feature)
+- `/memory recall "query"` — Semantic search across stored memories (avoids reading the full snapshot)
+- `/memory update` — Merge `status:pending-snapshot` memories back into the snapshot file
+
+## How Agents Use Memory
+
+All agents (`technical-lead`, `frontend`, `backend`, `business-intelligence`, `test-qa`) load context via targeted `search_memory` calls instead of reading the full snapshot. Each agent queries only the domains it needs, saving tokens. If the memory service is unavailable, agents fall back to reading `.cursor/memory/architecture-snapshot.md` directly.
+
 # Maintenance Notes