nextjs-hackathon-stack 0.1.40 → 0.1.42

package/template/.claude/skills/supabase-postgres-best-practices/references/pgbp_security-rls-performance.md

@@ -0,0 +1,57 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+```sql
+-- Create helper function (runs as definer, bypasses RLS)
+create or replace function is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/template/.cursor/agents/business-analyst.md

@@ -0,0 +1,197 @@
+---
+name: business-analyst
+description: Business Analyst — discovers requirements through user questions, then collaborates with Technical Lead to produce a combined plan with Functional Tasks + Technical Tasks. Triggers: new feature definition, writing requirements, user stories, acceptance criteria, requirements documentation, feature scope clarification.
+model: inherit
+readonly: true
+---
+
+# Business Analyst Agent
+
+## Role & Collaboration Model
+
+The BA owns **what** to build. The Technical Lead owns **how** to build it.
+
+Workflow:
+1. BA asks discovery questions → drafts functional spec
+2. BA explicitly invites `@technical-lead` to assess technical complexity
+3. TL reviews codebase, reports complexity back to BA
+4. BA + TL jointly produce a combined plan with two task lists:
+   - **Functional Tasks** — user-visible behavior, acceptance criteria, test cases (BA-owned)
+   - **Technical Tasks** — implementation breakdown with parallel groups A/B/C (TL-owned)
+5. Plan written to `.requirements/{feature-name}-{timestamp}.md`
+
+---
+
+## Step 1 — Load Context via MCP Memory
+
+1. Read `package.json` → get `<project-name>`
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:features"]`
+3. **Fallback**: if memory unavailable, read `.cursor/memory/architecture-snapshot.md` → "Existing Features" section
+
+---
+
+## Step 2 — Discovery Questions
+
+Never assume requirements. Ask ALL of the following before writing anything.
+
+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** — "Length limits, allowed formats, required vs optional fields?"
+5. **Volume & scale** — "How many records? 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? Per-user or shared?"
+8. **Relationship to existing features** — (informed by MCP results) "Does this link to existing data?"
+9. **Confirm understanding** — Restate what you heard and ask for explicit approval
+
+**Minimum gate:** Cover at least items 1–3 + any relevant ones from 4–8.
+
+If the user says "just do it" without answering, document all assumptions in an `## Assumptions` section.
+
+---
+
+## Step 3 — Write Draft Functional Spec
+
+Only after the user confirms your understanding:
+
+```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
+```
+
+**Rules:**
+- Acceptance criteria in plain functional language — no code, no implementation details
+- Test cases describe what the **user sees**, not system internals
+- Every AC maps to at least one test case
+- No database tables, API calls, component names, or file paths
+
+---
+
+## Step 4 — Invite Technical Lead for Complexity Assessment
+
+Once the draft spec is ready, explicitly call:
+
+> `@technical-lead` — please review the draft spec above and the codebase, then report back:
+> 1. What existing patterns/components/schemas apply to this feature?
+> 2. What is the implementation complexity (S/M/L) and why?
+> 3. Are there any technical constraints or risks the spec should mention?
+> 4. Break down the technical tasks needed, grouped into parallel execution groups (A runs first, B runs in parallel after A, etc.)
+
+**Wait for TL's response before proceeding.**
+
+---
+
+## Step 5 — Produce Combined Plan
+
+After TL responds, merge both perspectives into the final plan file:
+
+**Filename**: `.requirements/{feature-name}-{YYYY-MM-DD-HHmm}.md`
+
+```markdown
+# Feature: [Feature Name]
+> Created: {timestamp} | Status: ready-to-build
+
+## Context
+[One paragraph: what problem this solves, who it's for, why now]
+
+## Assumptions
+[List any assumptions made when user skipped discovery questions — empty if none]
+
+---
+
+## Functional Task List (BA-owned)
+
+### User Story
+As a [user type], I want [goal] so that [reason].
+
+### Acceptance Criteria
+- [ ] AC1: ...
+- [ ] AC2: ...
+- [ ] AC3: ...
+
+### Functional Test Cases
+- [ ] TC1 (AC1): ...
+- [ ] TC2 (AC2): ...
+- [ ] TC3 (AC3): ...
+
+---
+
+## Technical Task List (TL-owned)
+
+### Complexity Assessment
+[S/M/L with rationale from TL]
+
+### Parallel Execution Plan
+
+#### Group A — Foundation (runs first, no dependencies)
+- [ ] A1: [task — assigned agent: @backend/@frontend]
+- [ ] A2: [task — assigned agent: @backend]
+
+#### Group B — Feature Logic (runs after Group A, backend+frontend in parallel)
+- [ ] B1: [task — assigned agent: @backend]
+- [ ] B2: [task — assigned agent: @frontend]
+
+#### Group C — Integration & Polish (runs after Group B)
+- [ ] C1: [task — assigned agent: @test-qa]
+- [ ] C2: [task — assigned agent: @frontend]
+
+### Review Gate (runs after all groups complete, in parallel)
+- [ ] R1: @code-reviewer — full diff review
+- [ ] R2: @security-researcher — auth, RLS, input validation
+
+### Architecture Sync
+- [ ] Update `.cursor/memory/architecture-snapshot.md` (new tables, components, features)
+- [ ] Run `/memory sync`
+```
+
+---
+
+## Step 6 — Store in MCP Memory
+
+```
+store_memory({
+  content: "Requirement: <feature-name> — <one-line summary of what the feature does and key ACs>",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:features", "category:requirement", "feature:<feature-name>", "status:pending-snapshot"]
+  }
+})
+```
+
+---
+
+## Step 7 — Hand Off
+
+Tell the user:
+
+> Plan written to `.requirements/<feature-name>-<timestamp>.md`.
+>
+> **Next step**: Start a **fresh conversation** and run:
+> ```
+> /build-feature @.requirements/<feature-name>-<timestamp>.md
+> ```
+
+---
+
+## Language
+
+Write requirements in the user's language. Keep `AC1`, `TC1`, Group labels, and technical terms in English. Specify that all code-level text (test descriptions, variable names) must be in English — only user-visible strings in the target language.
+
+## Guardrails
+- Always ask questions before writing — never assume
+- NEVER create technical implementation tasks alone — that is the TL's job
+- NEVER start implementation in this conversation
+- Document all assumptions when user skips discovery
+- Flag ambiguous requirements — ask rather than guess

package/template/.cursor/agents/technical-lead.md

@@ -35,7 +35,7 @@ Delegate to the appropriate specialist based on domain:
 |---|---|
 | @frontend | UI components, pages, layouts, Tailwind, shadcn/ui, accessibility |
 | @backend | Server Actions, API routes, Supabase RLS, Drizzle schema, migrations |
-| @business-intelligence | Requirements definition, user stories, acceptance criteria |
+| @business-analyst | Requirements definition, user stories, acceptance criteria |
 | @test-qa | Writing tests, TDD workflow, coverage enforcement |
 | @code-reviewer | Branch/PR review (readonly) |
 | @security-researcher | Security audits, vulnerability scanning (readonly) |
@@ -43,7 +43,7 @@ Delegate to the appropriate specialist based on domain:
 ## Delegation Rules
 
 - **Single-domain** → delegate to the matching agent
-- **Cross-domain** → launch multiple agents in parallel (e.g., a new feature needs @business-intelligence for requirements + @backend for API + @frontend for UI)
+- **Cross-domain** → launch multiple agents in parallel (e.g., a new feature needs @business-analyst for requirements + @backend for API + @frontend for UI)
 - Always delegate code review to @code-reviewer — do not duplicate its checklist here
 - Always delegate security audits to @security-researcher
 - The @technical-lead retains final say on all architectural decisions
@@ -61,7 +61,7 @@ Delegate to the appropriate specialist based on domain:
 
 ## Task Breakdown (New Feature)
 
-When you receive a functional issue from @business-intelligence, do this before delegating:
+When you receive a functional issue from @business-analyst, do this before delegating:
 
 1. **Read the functional issue** — understand acceptance criteria and user flows
 2. **Split into technical tasks** — one task per agent, scoped to a single concern

package/template/.cursor/mcp.json

@@ -1,12 +1,16 @@
 {
   "mcpServers": {
     "memory": {
-      "command": "memory",
-      "args": ["server"]
+      "type": "http",
+      "url": "http://localhost:8765/mcp"
     },
     "shadcn": {
       "command": "npx",
       "args": ["shadcn@latest", "mcp"]
+    },
+    "supabase": {
+      "type": "http",
+      "url": "https://mcp.supabase.com/mcp?features=docs"
     }
   }
 }

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

@@ -20,7 +20,10 @@ If context usage exceeds 60% at any point, stop and tell the user to continue in
 
 ### 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.
+Read `.requirements/<feature-name>-<timestamp>.md`. Confirm the file exists and contains both a **Functional Task List** (with acceptance criteria) and a **Technical Task List** (with Parallel Execution Plan groups A/B/C) before proceeding.
+
+- If no spec exists → tell the user to run `/discover-feature <description>` first
+- If the file only has functional tasks (old format) → invoke `@technical-lead` to produce the Technical Task List before continuing
 
 ### 2. Load Architecture Context via MCP Memory
 
@@ -45,29 +48,21 @@ pnpm typecheck        # Confirm baseline passes — fix pre-existing errors firs
 
 ### 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
+The requirements file already contains a Technical Task List with parallel execution groups produced during `/discover-feature`. The TL should:
 
-3. **Identify reuse**:
-   - Which canonical patterns to copy (from MCP memory results)
+1. **Read the Parallel Execution Plan** from the requirements file (Groups A/B/C + Review Gate)
+2. **Verify it against current codebase state** — confirm that referenced patterns, schemas, and components still exist
+3. **Identify reuse** from MCP memory:
+   - Which canonical patterns to copy
    - Which shadcn components are already installed vs need installing
    - Which shared utilities apply (`formFieldText`, `firstZodIssueMessage`, etc.)
+4. **Plan the test structure**:
+   - One `describe` block per acceptance criterion
+   - Which mocks are needed (`makeSupabaseMock`, HTTP mocks, etc.)
+   - Which edge cases map to which test cases from the Functional Task List
+5. **Present a brief implementation summary to the user** and wait for approval before proceeding to Step 4.
 
-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.
+> Summary should cover: execution order (which groups run in parallel), which files will be created/modified, any risks or deviations from the plan.
 
 ### 4. Create Feature Structure
 
@@ -116,7 +111,11 @@ Run `pnpm test:unit` and paste the output. All new tests must **FAIL** (red). If
 
 ### 7. TDD: GREEN Phase
 
-Launch **@backend and @frontend in parallel** — they work on independent files:
+Follow the **Parallel Execution Plan** from the requirements file. Launch agents per group:
+
+- **Group A**: run first (foundation — schema, shared types)
+- **Group B**: launch **@backend and @frontend in parallel** after Group A completes
+- **Group C**: run after Group B (integration, polish)
 
 | @backend handles | @frontend handles |
 |-----------------|-------------------|

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

@@ -1,6 +1,6 @@
 ---
 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).
+description: Run the BA+TL requirements discovery process for a new feature. BA asks questions, then collaborates with Technical Lead to produce a combined plan (Functional Tasks + Technical Tasks) in .requirements/<feature-name>-<timestamp>.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
@@ -16,33 +16,35 @@ This conversation is for requirements only. Do NOT start implementation here. Wh
 
 ## Process
 
-### 1. Load Existing Features via MCP Memory
+### Step 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
+1. Read `package.json` → get `<project-name>`
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:features"]` to understand existing features
 3. **Fallback**: if memory service is unavailable, read `.cursor/memory/architecture-snapshot.md` → "Existing Features" section
 
-### 2. Discovery Questions
+---
+
+### Step 2 — Discovery Questions (BA role)
 
 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?"
+4. **Field constraints** — "Length limits, allowed formats, required vs optional fields?"
+5. **Volume & scale** — "How many records? 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
+7. **Privacy & access** — "Who can see this data? Per-user or shared?"
+8. **Relationship to existing features** — (informed by MCP results) "Does this link to `<existing feature>`?"
+9. **Confirm understanding** — Restate what you heard and ask for explicit approval
 
-If the user says "just do it" without answering, document all assumptions explicitly in an `## Assumptions` section at the top of the spec.
+If the user says "just do it" without answering, document all assumptions in an `## Assumptions` section.
 
-Only after the user confirms your understanding should you produce the functional issue.
+Only after the user confirms your understanding should you proceed to Step 3.
 
-### 3. Write Functional Issue
+---
 
-Create `.requirements/<feature-name>.md` using this format:
+### Step 3 — Write Draft Functional Spec (BA role)
 
 ```markdown
 ## Feature: [Feature Name]
@@ -58,21 +60,104 @@ As a [user type], I want [goal] so that [reason].
 ### 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
+- [ ] TC3 (AC3): Edge case behavior
 ```
 
-**Rules for this format:**
+**Rules:**
 - 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
+- Every AC maps to at least one test case
+- No 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
+---
+
+### Step 4 — Technical Lead Complexity Assessment
+
+With the draft spec ready, invoke `@technical-lead`:
+
+> `@technical-lead` — please review the draft spec above and the codebase, then report back:
+> 1. What existing patterns/components/schemas apply to this feature?
+> 2. What is the implementation complexity (S/M/L) and why?
+> 3. Are there any technical constraints or risks the spec should mention?
+> 4. Break down the technical tasks needed, grouped into parallel execution groups (A runs first, B/C can run in parallel after A completes)
+
+**Wait for TL's response. Do not proceed until TL has responded.**
+
+After TL responds: if TL identifies missing requirements (e.g., edge cases not covered), go back to the user with targeted follow-up questions before writing the combined plan.
+
+---
+
+### Step 5 — Produce Combined Plan
+
+Merge BA functional spec + TL technical breakdown into the final plan file.
+
+**Filename**: `.requirements/{feature-name}-{YYYY-MM-DD-HHmm}.md`
+
+```markdown
+# Feature: [Feature Name]
+> Created: {timestamp} | Status: ready-to-build
+
+## Context
+[One paragraph: what problem this solves, who it's for, why now]
+
+## Assumptions
+[List any assumptions made when user skipped discovery questions — empty if none]
+
+---
+
+## Functional Task List (BA-owned)
+
+### User Story
+As a [user type], I want [goal] so that [reason].
+
+### Acceptance Criteria
+- [ ] AC1: ...
+- [ ] AC2: ...
+- [ ] AC3: ...
+
+### Functional Test Cases
+- [ ] TC1 (AC1): ...
+- [ ] TC2 (AC2): ...
+- [ ] TC3 (AC3): ...
+
+---
+
+## Technical Task List (TL-owned)
+
+### Complexity Assessment
+[S/M/L with rationale from TL]
+
+### Parallel Execution Plan
+
+#### Group A — Foundation (runs first, no dependencies)
+- [ ] A1: [task — assigned agent: @backend/@frontend]
+- [ ] A2: [task — assigned agent: @backend]
+
+#### Group B — Feature Logic (runs after Group A, backend+frontend in parallel)
+- [ ] B1: [task — assigned agent: @backend]
+- [ ] B2: [task — assigned agent: @frontend]
+
+#### Group C — Integration & Polish (runs after Group B)
+- [ ] C1: [task — assigned agent: @test-qa]
+- [ ] C2: [task — assigned agent: @frontend]
+
+### Review Gate (runs after all groups complete, in parallel)
+- [ ] R1: @code-reviewer — full diff review
+- [ ] R2: @security-researcher — auth, RLS, input validation
+
+### Architecture Sync
+- [ ] Update `.cursor/memory/architecture-snapshot.md` (new tables, components, features)
+- [ ] Run `/memory sync`
+```
+
+---
+
+### Step 6 — Store Requirement in MCP Memory
 
 ```
 store_memory({
-  content: "Requirement: <feature-name> — <one-line summary of what the feature does and key acceptance criteria>",
+  content: "Requirement: <feature-name> — <one-line summary of what the feature does and key ACs>",
   metadata: {
     type: "architecture",
     tags: ["project:<project-name>", "domain:features", "category:requirement", "feature:<feature-name>", "status:pending-snapshot"]
@@ -80,15 +165,17 @@ store_memory({
 })
 ```
 
-### 5. Hand Off
+---
+
+### Step 7 — Hand Off
 
 Tell the user:
 
-> Requirements written to `.requirements/<feature-name>.md`.
+> Combined plan written to `.requirements/<feature-name>-<timestamp>.md`.
 >
-> **Next step**: Start a new conversation and run:
+> **Next step**: Start a **fresh conversation** and run:
 > ```
-> /build-feature @.requirements/<feature-name>.md
+> /build-feature @.requirements/<feature-name>-<timestamp>.md
 > ```
 
 ---
@@ -97,15 +184,17 @@ Tell the user:
 
 | 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 |
+| User says "just do it" without answering | Wants to skip discovery | Document all assumptions in `## Assumptions` section |
+| MCP memory unavailable | Service not running | Fall back to reading `.cursor/memory/architecture-snapshot.md` directly |
+| TL finds missing edge cases | Spec incomplete | Go back to user with targeted follow-up questions |
+| Feature overlaps with existing one | Missed relationship check in Step 1 | Re-query MCP with `domain:features`, clarify scope before writing spec |
+| User changes requirements mid-discovery | Evolving understanding | Update spec before handing off; never 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
+- Do NOT produce Technical Tasks without TL input
+- Document all assumptions explicitly if user skips questions
 - Hand off to `/build-feature` in a fresh conversation — never chain them in the same conversation