nextjs-hackathon-stack 0.1.40 → 0.1.42

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

@@ -0,0 +1,62 @@
+---
+name: create-api-route
+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
+
+## Process
+
+### 1. Define Schema
+```typescript
+const requestSchema = z.object({ /* fields */ });
+const responseSchema = z.object({ /* fields */ });
+type RequestBody = z.infer<typeof requestSchema>;
+```
+
+### 2. Write Test First (TDD)
+```typescript
+describe("POST /api/my-route", () => {
+  it("returns 400 on invalid input", async () => { ... });
+  it("returns 401 when unauthenticated", async () => { ... });
+  it("returns 200 with valid input", async () => { ... });
+});
+```
+
+Run test — must FAIL (RED).
+
+### 3. Implement Route
+```typescript
+// Determine runtime:
+// - AI routes: export const runtime = "edge"
+// - DB routes: no export (Node.js default)
+
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+
+  const body = await request.json() as unknown;
+  const parsed = requestSchema.safeParse(body);
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+
+  // business logic...
+
+  return Response.json(result);
+}
+```
+
+### 4. Verify
+```bash
+pnpm test:unit
+pnpm lint
+pnpm typecheck
+```
+
+## Checklist
+- [ ] Zod schema for request/response
+- [ ] Auth check (unless public endpoint)
+- [ ] Input validation
+- [ ] Correct runtime (`edge` for AI, `nodejs` default for DB)
+- [ ] Tests written BEFORE implementation
+- [ ] ≥95% statement/function/line coverage, ≥90% branch coverage

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

@@ -0,0 +1,200 @@
+---
+name: discover-feature
+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).
+user-invocable: true
+---
+
+# 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
+
+### Step 1 — Load Existing Features via MCP Memory
+
+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
+
+---
+
+### 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** — "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
+
+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 proceed to Step 3.
+
+---
+
+### Step 3 — Write Draft Functional Spec (BA role)
+
+```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
+- Write requirements in the user's language; IDs (`AC1`, `TC1`) and technical terms stay in English
+
+---
+
+### Step 4 — Technical Lead Complexity Assessment
+
+With the draft spec ready, use the `technical-lead` subagent:
+
+> 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 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:
+
+> Combined plan written to `.requirements/<feature-name>-<timestamp>.md`.
+>
+> **Next step**: Start a **fresh conversation** and run:
+> ```
+> /build-feature @.requirements/<feature-name>-<timestamp>.md
+> ```
+
+---
+
+## Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| 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 |
+
+---
+
+## Guardrails
+- Always ask questions before writing — never assume requirements
+- Do NOT start any implementation in this conversation
+- 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

package/template/.claude/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/.claude/skills/review-branch/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: review-branch
+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
+---
+
+# Review Branch Skill
+
+## Process
+
+### 1. Get Changes
+```bash
+git diff develop...HEAD
+```
+Or for a specific branch:
+```bash
+git diff develop...<branch-name>
+```
+
+### 2. Check Each Changed File
+Apply the full checklist from `references/review-checklist.md` — covers code quality, tests, architecture, security, performance, and accessibility.
+
+**You MUST check every changed file individually. Do not summarize or skip files. Show your analysis for each file before moving to the next.**
+
+### 3. Generate Report
+```
+## Branch Review: <branch-name>
+
+### Changed Files
+- [list each file]
+
+### Issues Found
+- [file:line]: [issue] → [fix]
+
+### Verdict: PASS / FAIL
+```
+
+### 4. Run Automated Checks
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test:coverage
+```

package/template/.claude/skills/review-branch/references/review-checklist.md

@@ -0,0 +1,36 @@
+# Review Checklist
+
+## Code Quality
+- Zero `any` types
+- Zero comments (excluding test AAA labels: `// Arrange`, `// Act`, `// Assert`)
+- Functions ≤ 20 lines
+- Files ≤ 200 lines
+- No magic numbers/strings
+- Proper error handling
+
+## Tests
+- Tests written BEFORE implementation (TDD)
+- ≥95% statement/function/line coverage on new/changed files
+- ≥90% branch coverage (every if/else/ternary/catch)
+- Behavior tested, not implementation
+- AAA pattern with labeled comments on every test
+- Tests NOT weakened (no removed assertions, no loosened matchers, no .skip)
+- Edge cases covered: null, empty, boundaries, errors, auth expired
+
+## Architecture
+- Correct layer (features → shared only)
+- Server Actions for mutations (not TanStack)
+- Edge runtime on AI routes
+
+## Security
+- Input validation at boundaries
+- Auth checks in protected routes
+- No exposed secrets
+
+## Performance
+- No N+1 query patterns
+- No unnecessary re-renders
+
+## Accessibility
+- Semantic HTML
+- ARIA labels where needed

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

@@ -0,0 +1,40 @@
+---
+name: security-audit
+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
+---
+
+# Security Audit Skill
+
+## Process
+
+**You MUST execute every step below. Do not skip or summarize steps. Show your findings for each step before moving to the next.**
+
+Execute all 7 audit steps from `references/audit-steps.md`:
+1. Dependency audit (`pnpm audit`)
+2. Secret scan (hardcoded keys)
+3. RLS verification (all tables)
+4. Auth coverage (routes + actions)
+5. Input validation (Zod at boundaries)
+6. XSS check (`dangerouslySetInnerHTML`)
+7. Security headers (`next.config.ts`)
+
+## Output Format
+```
+## Security Audit Report
+
+### Critical 🔴
+[findings]
+
+### High 🟠
+[findings]
+
+### Medium 🟡
+[findings]
+
+### Low 🟢
+[findings]
+
+### Passed ✅
+[clean checks]
+```

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

@@ -0,0 +1,41 @@
+# Security Audit Steps
+
+### 1. Dependency Audit
+```bash
+pnpm audit
+```
+Categorize findings by: Critical / High / Medium / Low
+
+### 2. Secret Scan
+Search for hardcoded secrets:
+```bash
+grep -r "sk_" src/ --include="*.ts"
+grep -r "apiKey\s*=" src/ --include="*.ts"
+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`:
+- Confirm RLS is enabled in Supabase dashboard
+- Confirm explicit policies exist
+
+### 4. Auth Coverage
+- Verify `proxy.ts` protects all non-public routes
+- Check every `route.ts` in protected features has auth check
+- Verify `app/(protected)/layout.tsx` has server-side auth check
+
+### 5. Input Validation
+- Every `route.ts` has Zod schema validation
+- Every `.action.ts` has Zod schema validation
+
+### 6. XSS Check
+```bash
+grep -r "dangerouslySetInnerHTML" src/ --include="*.tsx"
+```
+
+### 7. Security Headers
+Verify in `next.config.ts`:
+- `Content-Security-Policy`
+- `Strict-Transport-Security`
+- `X-Frame-Options`