nextjs-hackathon-stack 0.1.32 → 0.1.34

package/dist/index.js

@@ -43,13 +43,25 @@ async function runCli(argProjectName, skipInstall) {
     }
     projectName = result;
   }
-  return { projectName, skipInstall };
+  const templateResult = await p2.select({
+    message: "What would you like to start with?",
+    options: [
+      { value: "example", label: "Todo example app", hint: "Full working app with todos CRUD" },
+      { value: "empty", label: "Empty app", hint: "Auth + empty dashboard" }
+    ]
+  });
+  if (p2.isCancel(templateResult)) {
+    p2.cancel("Cancelled");
+    process.exit(0);
+  }
+  const template = templateResult;
+  return { projectName, skipInstall, template };
 }
 
 // src/scaffold.ts
 import { execSync } from "child_process";
-import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkSync, writeFileSync } from "fs";
-import { join, dirname } from "path";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, symlinkSync, writeFileSync } from "fs";
+import { join, dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import * as p3 from "@clack/prompts";
 import pc2 from "picocolors";
@@ -60,7 +72,7 @@ function getTemplateDir() {
 function processTemplate(content, vars) {
   return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
-function copyDir(src, dest, vars) {
+function copyDir(src, dest, vars, skip = /* @__PURE__ */ new Set(), templateRoot = src) {
   mkdirSync(dest, { recursive: true });
   for (const entry of readdirSync(src)) {
     const srcPath = join(src, entry);
@@ -70,11 +82,25 @@ function copyDir(src, dest, vars) {
     }
     const destPath = join(dest, destEntry);
     const stat = lstatSync(srcPath);
+    const relPath = srcPath.slice(templateRoot.length + 1).replace(/\\/g, "/");
+    if (skip.has(relPath)) continue;
     if (stat.isSymbolicLink()) {
       const target = readlinkSync(srcPath);
-      symlinkSync(target, destPath);
+      const resolvedTarget = resolve(dirname(srcPath), target);
+      if (existsSync(resolvedTarget)) {
+        const resolvedStat = lstatSync(resolvedTarget);
+        if (resolvedStat.isFile()) {
+          cpSync(resolvedTarget, destPath);
+        } else if (resolvedStat.isDirectory()) {
+          cpSync(resolvedTarget, destPath, { recursive: true });
+        } else {
+          symlinkSync(target, destPath);
+        }
+      } else {
+        symlinkSync(target, destPath);
+      }
     } else if (stat.isDirectory()) {
-      copyDir(srcPath, destPath, vars);
+      copyDir(srcPath, destPath, vars, skip, templateRoot);
     } else if (entry.endsWith(".tmpl")) {
       const content = readFileSync(srcPath, "utf-8");
       writeFileSync(destPath, processTemplate(content, vars));
@@ -83,7 +109,97 @@ function copyDir(src, dest, vars) {
     }
   }
 }
-async function scaffold(projectName, skipInstall) {
+var EMPTY_APP_PAGE = `import { redirect } from "next/navigation";
+import { logoutAction } from "@/features/auth/actions/logout.action";
+import { createClient } from "@/shared/lib/supabase/server";
+
+export default async function HomePage() {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) redirect("/login");
+
+  return (
+    <main className="container mx-auto max-w-2xl p-8">
+      <div className="mb-6 flex items-center justify-between">
+        <h1 className="text-2xl font-bold">Dashboard</h1>
+        <form action={logoutAction}>
+          <button type="submit" className="rounded bg-muted px-4 py-2 text-sm hover:bg-muted-foreground/10">
+            Cerrar sesi\xF3n
+          </button>
+        </form>
+      </div>
+      <p className="text-muted-foreground">\xA1Bienvenido! Empieza a construir tu aplicaci\xF3n.</p>
+    </main>
+  );
+}
+`;
+var EMPTY_APP_SCHEMA = `import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+
+export const profiles = pgTable("profiles", {
+  id: uuid("id").primaryKey(),
+  email: text("email").notNull().unique(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const insertProfileSchema = createInsertSchema(profiles);
+export const selectProfileSchema = createSelectSchema(profiles);
+
+export type InsertProfile = typeof profiles.$inferInsert;
+export type SelectProfile = typeof profiles.$inferSelect;
+`;
+var EMPTY_APP_PAGE_TEST = `import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockGetUser = vi.fn();
+const mockRedirect = vi.fn();
+
+vi.mock("@/shared/lib/supabase/server", () => ({
+  createClient: vi.fn(() =>
+    Promise.resolve({ auth: { getUser: mockGetUser } })
+  ),
+}));
+
+vi.mock("next/navigation", () => ({
+  redirect: (url: string): unknown => mockRedirect(url),
+}));
+
+describe("HomePage (protected)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRedirect.mockImplementation(() => { throw new Error("NEXT_REDIRECT"); });
+  });
+
+  it("redirects to /login when user is not authenticated", async () => {
+    // Arrange
+    mockGetUser.mockResolvedValue({ data: { user: null } });
+    const { default: HomePage } = await import("../(protected)/page");
+
+    // Act + Assert
+    await expect(HomePage()).rejects.toThrow("NEXT_REDIRECT");
+    expect(mockRedirect).toHaveBeenCalledWith("/login");
+  });
+
+  it("renders dashboard when user is authenticated", async () => {
+    // Arrange
+    mockGetUser.mockResolvedValue({ data: { user: { id: "u1", email: "user@example.com" } } });
+    const { default: HomePage } = await import("../(protected)/page");
+
+    // Act
+    const result = await HomePage();
+
+    // Assert
+    expect(result).toBeTruthy();
+  });
+});
+`;
+function buildSkipSet() {
+  return /* @__PURE__ */ new Set([
+    "src/features/todos",
+    "src/e2e/todos.spec.ts"
+  ]);
+}
+async function scaffold(projectName, skipInstall, skipMcp = false, template = "example") {
   const targetDir = join(process.cwd(), projectName);
   if (existsSync(targetDir)) {
     p3.cancel(`Directory "${projectName}" already exists`);
@@ -91,9 +207,19 @@ async function scaffold(projectName, skipInstall) {
   }
   const templateDir = getTemplateDir();
   const vars = { projectName };
+  const skip = template === "empty" ? buildSkipSet() : /* @__PURE__ */ new Set();
   const spinner2 = p3.spinner();
   spinner2.start("Copying template files");
-  copyDir(templateDir, targetDir, vars);
+  copyDir(templateDir, targetDir, vars, skip, templateDir);
+  if (template === "empty") {
+    const pageDir = join(targetDir, "src/app/(protected)");
+    mkdirSync(pageDir, { recursive: true });
+    writeFileSync(join(pageDir, "page.tsx"), EMPTY_APP_PAGE);
+    writeFileSync(join(targetDir, "src/shared/db/schema.ts"), EMPTY_APP_SCHEMA);
+    const testDir = join(targetDir, "src/app/__tests__");
+    mkdirSync(testDir, { recursive: true });
+    writeFileSync(join(testDir, "protected-page.test.tsx"), EMPTY_APP_PAGE_TEST);
+  }
   spinner2.stop("Template files copied");
   const envExamplePath = join(targetDir, ".env.example");
   const envLocalPath = join(targetDir, ".env.local");
@@ -154,6 +280,34 @@ async function scaffold(projectName, skipInstall) {
   } catch {
     spinner2.stop("Husky setup failed \u2014 run manually: pnpm exec husky");
   }
+  if (!skipMcp) {
+    spinner2.start("Installing mcp-memory-service");
+    try {
+      const pipCmd = (() => {
+        try {
+          execSync("pip3 --version", { stdio: "pipe" });
+          return "pip3";
+        } catch {
+          try {
+            execSync("pip --version", { stdio: "pipe" });
+            return "pip";
+          } catch {
+            return null;
+          }
+        }
+      })();
+      if (pipCmd) {
+        execSync(`${pipCmd} install mcp-memory-service`, { cwd: targetDir, stdio: "pipe" });
+        spinner2.stop("mcp-memory-service installed");
+      } else {
+        spinner2.stop("pip not found \u2014 skipping mcp-memory-service");
+        p3.log.warn("Install Python and run: pip install mcp-memory-service");
+      }
+    } catch {
+      spinner2.stop("mcp-memory-service installation failed");
+      p3.log.warn("Install manually: pip install mcp-memory-service");
+    }
+  }
   success(pc2.bold(`\xA1Proyecto "${projectName}" creado!`));
   console.log(`
   ${pc2.dim("Siguientes pasos:")}`);
@@ -170,10 +324,10 @@ async function scaffold(projectName, skipInstall) {
 
 // src/index.ts
 var program = new Command();
-program.name("nextjs-hackathon-stack").description("Scaffold a full-stack Next.js 15 hackathon starter").version("0.1.0").argument("[project-name]", "Name of the project to create").option("--skip-install", "Skip pnpm install and shadcn/ui init", false).action(async (projectName, opts) => {
+program.name("nextjs-hackathon-stack").description("Scaffold a full-stack Next.js 15 hackathon starter").version("0.1.0").argument("[project-name]", "Name of the project to create").option("--skip-install", "Skip pnpm install and shadcn/ui init", false).option("--skip-mcp", "Skip mcp-memory-service installation", false).action(async (projectName, opts) => {
   try {
     const options = await runCli(projectName, opts.skipInstall);
-    await scaffold(options.projectName, options.skipInstall);
+    await scaffold(options.projectName, options.skipInstall, opts.skipMcp, options.template);
     outro2("Happy hacking! \u{1F680}");
   } catch (err) {
     p4.cancel(err instanceof Error ? err.message : "Something went wrong");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

package/template/.cursor/agents/backend.md

@@ -7,6 +7,10 @@ readonly: false
 
 # Backend Agent
 
+## First Step
+
+Read `.cursor/memory/architecture-snapshot.md` to understand the existing schema, features, and proven Server Action patterns before writing new code. Use the canonical pattern references to copy the correct structure.
+
 ## Responsibilities
 - Build Next.js Server Actions, API routes, and middleware
 - Define Drizzle ORM schemas and manage migrations via CLI
@@ -23,6 +27,20 @@ readonly: false
 - Default to **Node.js runtime** for Server Actions and API routes
 - Use **Edge runtime** only when latency is critical and no Node.js APIs are needed
 
+## RLS Policy Requirement
+
+RLS is not optional and is never a post-implementation step. When you create a new table:
+
+1. Enable RLS on the table in Supabase
+2. Write the RLS policies before the feature is considered done. Default template:
+   ```sql
+   -- Users can only access their own rows
+   CREATE POLICY "users_own_rows" ON <table>
+     FOR ALL USING (user_id = auth.uid());
+   ```
+3. Document the policy in the architecture snapshot under the table entry
+4. Never leave "add RLS later" as a TODO — a table without RLS is a security vulnerability
+
 ## Dev Server
 - Before running `next dev`, check `.next/dev/lock`. If it exists and the PID is alive, an instance is already running — use that server's URL instead of starting a new one.
 - Enable `logging.browserToTerminal` in `next.config.ts` for terminal-based debugging (recommended: `'error'` for production-like sessions, `true` during active development).

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

@@ -7,6 +7,10 @@ readonly: true
 
 # Business Intelligence Agent
 
+## First Step
+
+Read `.cursor/memory/architecture-snapshot.md` to understand existing features before asking discovery questions. Use it to identify relationships with existing data and patterns.
+
 ## Responsibilities
 - Discover requirements through user questions before defining anything
 - Write functional issues describing user-visible behavior
@@ -20,10 +24,21 @@ readonly: true
 
 Never assume requirements. Always ask first.
 
+Complete ALL of these before writing a spec:
+
 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. **Confirm understanding** — Restate what you heard and ask for approval before writing anything
+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 the snapshot) "Does this link to existing data?"
+9. **Confirm understanding** — Restate what you heard and ask for approval before writing anything
+
+**Minimum gate:** Cover at least items 1–3 + any that apply from 4–8 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 a functional issue.
 

package/template/.cursor/agents/code-reviewer.md

@@ -59,6 +59,9 @@ glab --version 2>/dev/null && echo "GitLab"
 - [ ] Semantic HTML
 - [ ] ARIA labels where needed
 
+### Styling
+- [ ] No hardcoded Tailwind palette colors — only design tokens from `tailwind.css`
+
 ## Output Format
 ```
 ## Review: <branch/PR name>

package/template/.cursor/agents/frontend.md

@@ -7,6 +7,10 @@ readonly: false
 
 # Frontend Agent
 
+## First Step
+
+Read `.cursor/memory/architecture-snapshot.md` to see which shadcn/ui components are already installed before running `shadcn add`. Use the canonical component test reference to follow the established testing pattern.
+
 ## Responsibilities
 - Build accessible React components with shadcn/ui and Tailwind v4
 - Enforce Server vs Client component boundaries
@@ -35,6 +39,19 @@ export function InteractiveComponent() {
 }
 ```
 
+## Common UI Patterns
+
+Use these shadcn components for standard layouts — never roll custom alternatives:
+
+| Pattern | shadcn Component | Notes |
+|---------|-----------------|-------|
+| Master-detail (table + side panel) | `ResizablePanelGroup` + `ResizablePanel` | Or CSS grid for fixed layouts |
+| Dialog / modal form | `Dialog`, `DialogContent`, `DialogHeader` | Never use native `<dialog>` — breaks in jsdom |
+| Data table | `Table`, `TableHeader`, `TableRow`, `TableCell` | Or `DataTable` pattern from shadcn docs |
+| Empty state | Centered `<p>` in Spanish inside the table container | Always handle — never leave blank |
+| Loading/pending | `Button` with `loading` prop, or `Spinner` | Use `useTransition` for action pending state |
+| Form with validation | `Form` + `FormField` from shadcn + `zodResolver` | See `forms.mdc` |
+
 ## Toast Feedback
 
 All user-initiated actions that modify the database must show a toast (success or error) via `sonner`. Never let a mutation complete silently.
@@ -48,3 +65,4 @@ All user-initiated actions that modify the database must show a toast (success o
 - Write RTL tests for every component
 - Verify a11y before marking work done
 - No component file over 200 lines — split by responsibility
+- Never use raw Tailwind palette colors (`red-500`, `gray-400`, etc.) — only design tokens from `@theme {}` in `tailwind.css`

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

@@ -9,6 +9,10 @@ readonly: false
 
 # Technical Lead Agent
 
+## First Step
+
+Read `.cursor/memory/architecture-snapshot.md` to understand the current project state before planning. Use it to identify which patterns to reuse and what already exists.
+
 ## Responsibilities
 - Act as the default entry point for all requests
 - Classify requests and delegate to the appropriate specialist agent(s)

package/template/.cursor/agents/test-qa.md

@@ -7,12 +7,30 @@ readonly: false
 
 # Test & QA Agent
 
+## First Step
+
+Read `.cursor/memory/architecture-snapshot.md` to find the canonical test references. Import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock` — never recreate the mock chain from scratch.
+
 ## TDD Workflow
+
 1. **RED** — write failing test that describes the desired behavior
 2. **GREEN** — write minimum code to make test pass
 3. **REFACTOR** — clean up while keeping tests green
 4. **VERIFY** — run `pnpm test:coverage` and confirm 100%
 
+## Verification Gates (mandatory — show output, do not just claim)
+
+Each phase requires pasting the actual terminal output before proceeding:
+
+| Gate | Command | Expected output |
+|------|---------|-----------------|
+| After RED | `pnpm test:unit` | All new tests **FAIL** (red) |
+| After GREEN | `pnpm test:unit` | All tests **PASS** (green) |
+| After VERIFY | `pnpm test:coverage` | 100% across all metrics |
+
+**Never say "tests pass" or "tests fail" without showing the actual output.**
+**Do NOT write any implementation code until the RED gate output confirms failures.**
+
 ## Key Rules (auto-loaded by file context)
 - Testing standards, AAA pattern, coverage: `testing.mdc`
 - TDD iron rules: `coding-standards.mdc`
@@ -30,6 +48,24 @@ After every change:
 2. If below 100%, add missing tests
 3. Never mark work complete without full coverage
 
+## Supabase Mock Pattern
+
+Always use the shared helpers — never inline mock chain construction:
+
+```typescript
+import { makeChain, makeSupabaseMock } from "@/shared/test-utils/supabase-mock";
+
+// Unauthenticated
+const { mockClient } = makeSupabaseMock({ user: null });
+
+// Authenticated + DB success
+const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+mockFrom.mockReturnValue(makeChain({ data: [...], error: null }));
+
+// DB error
+mockFrom.mockReturnValue(makeChain({ error: { message: "db error" } }));
+```
+
 ## Test Plan Compliance
 
 When the Technical Lead provides a test plan, follow it:
@@ -37,7 +73,7 @@ When the Technical Lead provides a test plan, follow it:
 - Flag missing edge cases to the TL **before** adding unplanned tests — do not expand scope unilaterally
 - If the plan is ambiguous or incomplete, ask for clarification rather than guessing
 
-For Server Action test templates, see `create-feature` skill references.
+For the full Server Action test template, see `create-feature` skill references.
 
 ## Guardrails
 - Never write implementation without a failing test first

package/template/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "memory": {
+      "command": "python3",
+      "args": ["-m", "mcp_memory_service", "server"]
+    }
+  }
+}

package/template/.cursor/memory/architecture-snapshot.md

@@ -0,0 +1,50 @@
+# Architecture Snapshot
+
+> Auto-updated after each feature. Agents MUST read this before exploring the codebase.
+
+## Installed shadcn/ui Components
+
+button, card, input, label, spinner
+
+_Add new components here after `shadcn add <component>`_
+
+## DB Schema
+
+| Table | Columns |
+|-------|---------|
+| `profiles` | id (uuid PK), email (text unique), createdAt, updatedAt |
+| `todos` | id (uuid PK), userId (uuid), title (text), completed (bool), createdAt |
+
+_Add new tables here after `pnpm db:generate && pnpm db:migrate`_
+
+## Existing Features
+
+| Feature | Path | Description |
+|---------|------|-------------|
+| auth | `src/features/auth/` | Login/logout, cookie-based sessions via Supabase |
+| todos | `src/features/todos/` | CRUD todos with Supabase RLS |
+
+_Add new features here after implementation_
+
+## Canonical Pattern References
+
+Read these files to understand the project's proven patterns before writing new code:
+
+| Pattern | File |
+|---------|------|
+| Server Action | `src/features/todos/actions/todos.action.ts` |
+| Query (repository) | `src/features/todos/queries/todos.queries.ts` |
+| Client component | `src/features/todos/components/todo-list.tsx` |
+| Action test | `src/features/todos/__tests__/todos.action.test.ts` |
+| Component test | `src/features/todos/__tests__/todo-list.test.tsx` |
+| Supabase mock chain | `src/shared/test-utils/supabase-mock.ts` |
+
+## Key Rules (summary)
+
+- Runtime queries: Supabase client only — Drizzle is schema/migrations only
+- All mutations: Server Actions returning `ActionResult` from `@/shared/lib/action-result`
+- Auth check first in every Server Action: `supabase.auth.getUser()`
+- Toast feedback required for every mutation (success + error) via `sonner`
+- RLS must be enabled on every table before a feature is considered complete
+- UI text: Spanish | Code-level text: English (test descriptions, variable names)
+- 100% test coverage — no exceptions

package/template/.cursor/rules/coding-standards.mdc

@@ -14,18 +14,9 @@ globs: ["src/**/*.ts", "src/**/*.tsx"]
 - **No `!` non-null assertions** — use proper null checks
 - **No `eslint-disable` inline comments** — fix the code instead. If a rule conflict is truly unavoidable (e.g. third-party API with no non-deprecated alternative), add a file-level override in `eslint.config.ts` with a `// TODO` comment explaining why.
 
-## TDD (Test-Driven Development)
-1. **RED**: Write a failing test first
-2. **GREEN**: Write minimum code to pass the test
-3. **REFACTOR**: Improve code while tests stay green
-
-Never write implementation before tests exist.
-
-## TDD — Iron Rule
-- Tests define the contract. **NEVER modify a test to make it pass.**
-- If a test fails, the implementation is wrong — fix the code, not the test.
-- Only modify tests to: add new tests (RED), restructure without weakening (REFACTOR).
-- Weakening a test (removing assertions, loosening matchers, adding `.skip`) is a rejection-worthy offense.
+## TDD
+
+Follow the RED → GREEN → REFACTOR cycle. See `testing.mdc` for the full rules and iron rules. Summary: never write implementation without a prior failing test.
 
 ## SOLID Principles
 - **S**ingle Responsibility: one reason to change per module

package/template/.cursor/rules/components.mdc

@@ -24,6 +24,13 @@ globs: ["src/**/components/**"]
 - No inline styles, no CSS modules
 - Use Tailwind utility classes only
 
+## Design Tokens (Required)
+- Always use semantic token classes (`bg-primary`, `text-destructive`, `text-muted-foreground`, `border-border`, etc.)
+- Never use raw Tailwind palette colors (`bg-blue-500`, `text-gray-700`, `text-red-500`, etc.)
+- All colors must reference CSS variables defined in `@theme {}` in `tailwind.css`
+- Available semantic colors: primary, secondary, accent, destructive, success, warning, info, muted, background, foreground, border, input, ring
+- If a needed color does not exist as a token, add it to `@theme {}` in `tailwind.css` first
+
 ## Accessibility (Required)
 - Semantic HTML elements (`<button>`, `<nav>`, `<main>`, etc.)
 - ARIA labels for interactive elements without visible text

package/template/.cursor/rules/migrations.mdc

@@ -5,23 +5,6 @@ globs: ["src/shared/db/migrations/**"]
 
 # Migration Files — Generated Artifacts
 
-Files in `src/shared/db/migrations/` are **auto-generated** by the Drizzle CLI. Do not create, edit, or delete them by hand.
+Files in `src/shared/db/migrations/` are **auto-generated**. See `supabase.mdc` for the full migration workflow and CLI commands.
 
-## Correct Workflow
-
-1. **Edit the schema**: `src/shared/db/schema.ts`
-2. **Generate the migration**: `pnpm db:generate`
-3. **Review** the generated SQL file in `src/shared/db/migrations/`
-4. **Apply the migration**: `pnpm db:migrate`
-
-## Available CLI Commands
-
-| Command | Purpose |
-|---|---|
-| `pnpm db:generate` | Generate a new migration SQL file from schema changes |
-| `pnpm db:migrate` | Apply pending migrations to the database |
-| `pnpm db:push` | Push schema directly to DB (dev only, no migration file) |
-
-## Why
-
-Hand-editing migration files causes schema drift and breaks the migration history. The CLI is the only safe source of truth for migration SQL.
+**Never create, edit, or delete migration files by hand.**

package/template/.cursor/rules/supabase.mdc

@@ -48,8 +48,20 @@ const users = await db.select().from(usersTable); // WRONG — bypasses RLS
 
 ## RLS Mandate
 - Enable RLS on ALL tables in Supabase dashboard
-- Every table must have explicit policies
-- Test RLS policies in migrations
+- Every table must have explicit policies — RLS is not a post-step
+- Default policy template: `CREATE POLICY "users_own_rows" ON <table> FOR ALL USING (user_id = auth.uid());`
+
+## Migrations
+
+Files in `src/shared/db/migrations/` are **auto-generated** by Drizzle CLI — never create, edit, or delete them directly.
+
+| Command | Purpose |
+|---|---|
+| `pnpm db:generate` | Generate migration SQL from schema changes |
+| `pnpm db:migrate` | Apply pending migrations to the database |
+| `pnpm db:push` | Push schema directly to DB (dev only, no migration file) |
+
+Workflow: edit `src/shared/db/schema.ts` → `pnpm db:generate` → review SQL → `pnpm db:migrate`
 
 ## Environment Variables
 - `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe, used in browser + server

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

@@ -5,6 +5,17 @@ description: Scaffold a new feature following TDD and project conventions. Use w
 
 # Create Feature Skill
 
+> **Invoke as:** `/create-feature @.requirements/<feature-name>.md`
+> This skill is orchestrated by the `@technical-lead` agent — do NOT add `use @technical-lead` to the invocation, it is redundant.
+
+## IMPORTANT: Run this in a FRESH conversation
+
+If this conversation already contains requirements gathering (BI agent output), **start a new conversation** before running `/create-feature`. Reusing the same context risks hitting the token limit mid-implementation.
+
+If context usage exceeds 60% at any point during this skill, stop and tell the user to continue in a new conversation, referencing this plan file.
+
+---
+
 ## Process
 
 ### 1. Requirements First
@@ -13,7 +24,15 @@ description: Scaffold a new feature following TDD and project conventions. Use w
 - **If no spec exists, call @business-intelligence** to run the discovery process and produce a functional issue in `.requirements/<feature-name>.md`
 - Wait for the functional issue to be written and confirmed by the user before proceeding to Step 2
 
-### 2. Create Feature Structure
+### 2. Read the Architecture Snapshot
+
+Read `.cursor/memory/architecture-snapshot.md`. This tells you:
+- Which shadcn/ui components are already installed (no need to `shadcn add` duplicates)
+- The current DB schema (what tables exist, what to extend)
+- Existing features and their paths (avoid recreating patterns)
+- Canonical pattern references (copy from these, do not reinvent)
+
+### 3. Create Feature Structure
 ```
 src/features/<feature-name>/
 ├── components/
@@ -25,7 +44,7 @@ src/features/<feature-name>/
 └── __tests__/
 ```
 
-### 3. Pre-Test Setup (do this before writing any tests)
+### 4. Pre-Test Setup (do this before writing any tests)
 
 Update `vitest.config.ts` to exclude files that cannot be meaningfully tested in jsdom:
 - Drizzle schema file(s) (`src/shared/db/schema.ts`)
@@ -42,32 +61,76 @@ exclude: [
 
 Configuring exclusions upfront prevents reactive coverage fixes mid-implementation.
 
-### 4. TDD: RED Phase
-Write ALL test files first:
+### 5. 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
-- `__tests__/<action>.test.ts` — action tests (see `references/server-action-test-template.md`)
+- `__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
 
-Run `pnpm test:unit` — all tests must FAIL (RED).
+Import mock helpers from `@/shared/test-utils/supabase-mock` — do not inline mock chains.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output here. All new tests must **FAIL** (red). If any new test passes without implementation, the test is wrong — fix it before continuing.
+
+### 6. TDD: GREEN Phase
 
-### 5. TDD: GREEN Phase
-Implement minimum code to pass each test:
-- Components → actions → hooks → API routes
+Launch **@backend and @frontend in parallel** — they work on independent files:
 
-Run `pnpm test:unit` — all tests must PASS (GREEN).
+| @backend handles | @frontend handles |
+|-----------------|-------------------|
+| `actions/` | `components/` |
+| `queries/` | `page.tsx` |
+| `schema.ts` changes | shadcn component installs |
+| RLS policies | Loading/empty states |
 
-### 6. Refactor
+Do NOT serialize these — they touch different files.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All tests must **PASS** (green).
+
+### 7. Refactor
 Clean up while keeping tests green.
 
-### 7. Verify
+### 8. Verify & Self-Check
+
+Run all three and paste output:
 ```bash
-pnpm test:coverage   # Must show 100%
+pnpm test:coverage   # Must show 100% across all metrics
 pnpm lint            # Must pass with 0 warnings
 pnpm typecheck       # Must pass with 0 errors
 ```
 
+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
+
+### 9. 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.
+
+### 10. Update Architecture Snapshot
+
+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
+
+---
+
 ## Guardrails
-- NEVER start implementation before tests exist
+- NEVER start implementation before the RED gate is confirmed with actual test output
 - 100% coverage before marking done
 - Follow `features/* → shared/*` dependency direction
+- RLS is mandatory for every new table — not a post-step

package/template/.cursor/skills/create-feature/references/server-action-test-template.md

@@ -2,50 +2,102 @@
 
 Test Server Actions by mocking `createClient`, asserting on the returned `ActionResult`, and verifying side effects.
 
+## Setup
+
 ```typescript
-import { vi, it, expect, describe } from "vitest";
+import { vi, it, expect, describe, beforeEach } from "vitest";
+import { createClient } from "@/shared/lib/supabase/server";
+import { revalidatePath } from "next/cache";
+import { makeChain, makeSupabaseMock } from "@/shared/test-utils/supabase-mock";
 import { myAction } from "@/features/example/actions/my.action";
 
-vi.mock("@/shared/lib/supabase/server", () => ({
-  createClient: vi.fn(),
-}));
+vi.mock("@/shared/lib/supabase/server", () => ({ createClient: vi.fn() }));
 vi.mock("next/cache", () => ({ revalidatePath: vi.fn() }));
 
-describe("myAction", () => {
-  it("returns error when user is not authenticated", async () => {
-    // Arrange
-    const mockSupabase = {
-      auth: { getUser: vi.fn().mockResolvedValue({ data: { user: null } }) },
-    };
-    vi.mocked(createClient).mockResolvedValue(mockSupabase as never);
-    const formData = new FormData();
-
-    // Act
-    const result = await myAction(formData);
-
-    // Assert
-    expect(result).toEqual({ status: "error", message: "No autenticado" });
-    expect(revalidatePath).not.toHaveBeenCalled();
-  });
-
-  it("returns success and revalidates on valid input", async () => {
-    // Arrange
-    const mockUser = { id: "user-1" };
-    const mockSupabase = {
-      auth: { getUser: vi.fn().mockResolvedValue({ data: { user: mockUser } }) },
-      from: vi.fn().mockReturnThis(),
-      insert: vi.fn().mockResolvedValue({ error: null }),
-    };
-    vi.mocked(createClient).mockResolvedValue(mockSupabase as never);
-    const formData = new FormData();
-    formData.set("name", "Test Item");
-
-    // Act
-    const result = await myAction(formData);
-
-    // Assert
-    expect(result).toEqual({ status: "success", message: expect.any(String) });
-    expect(revalidatePath).toHaveBeenCalledWith("/");
-  });
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+```
+
+## Unauthenticated case (required in every action test)
+
+```typescript
+it("returns error when user is not authenticated", async () => {
+  // Arrange
+  const { mockClient } = makeSupabaseMock({ user: null });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  const formData = new FormData();
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: "No autenticado" });
+  expect(revalidatePath).not.toHaveBeenCalled();
 });
 ```
+
+## Happy path (insert example)
+
+```typescript
+it("returns success and revalidates on valid input", async () => {
+  // Arrange
+  const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  mockFrom.mockReturnValue(makeChain({ error: null }));
+  const formData = new FormData();
+  formData.set("title", "My item");
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "success", message: expect.any(String) });
+  expect(revalidatePath).toHaveBeenCalledWith("/");
+});
+```
+
+## DB error case
+
+```typescript
+it("returns error when db insert fails", async () => {
+  // Arrange
+  const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  mockFrom.mockReturnValue(makeChain({ error: { message: "db error" } }));
+  const formData = new FormData();
+  formData.set("title", "My item");
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: expect.any(String) });
+  expect(revalidatePath).not.toHaveBeenCalled();
+});
+```
+
+## Validation error case
+
+```typescript
+it("returns error when required field is missing", async () => {
+  // Arrange
+  const { mockClient } = makeSupabaseMock({ user: { id: "user-1" } });
+  vi.mocked(createClient).mockResolvedValue(mockClient as never);
+  const formData = new FormData(); // no fields set
+
+  // Act
+  const result = await myAction(formData);
+
+  // Assert
+  expect(result).toEqual({ status: "error", message: expect.any(String) });
+});
+```
+
+## Key Rules
+
+- Always import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock`
+- Every action test must cover: unauthenticated, validation error, DB error, happy path
+- `mockFrom` returns a chain — each chained method (`.select()`, `.insert()`, etc.) returns the same chain object
+- `then` on the chain resolves with the value you pass to `makeChain()`
+- Never use `mockReturnThis()` — it does not match Supabase's actual chaining API

package/template/CLAUDE.md

@@ -46,4 +46,14 @@ The `/create-feature` skill reads the requirements file directly, so the BI conv
 - Components: PascalCase `.tsx`
 - Tests: colocated in `__tests__/`, named `name.test.ts`
 
+# MCP Memory Service
+
+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:
+```bash
+pip install mcp-memory-service
+```
+
 # Maintenance Notes

package/template/src/app/(protected)/page.tsx

@@ -21,7 +21,7 @@ export default async function HomePage() {
         <form action={logoutAction}>
           <button
             type="submit"
-            className="rounded bg-gray-200 px-4 py-2 text-sm hover:bg-gray-300"
+            className="rounded bg-muted px-4 py-2 text-sm hover:bg-muted-foreground/10"
           >
             Cerrar sesión
           </button>

package/template/src/features/todos/components/add-todo-form.tsx

@@ -34,7 +34,7 @@ export function AddTodoForm() {
         placeholder="Nueva tarea…"
         required
         disabled={isPending}
-        className="flex-1 rounded border px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-gray-400"
+        className="flex-1 rounded border px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
         aria-label="Nueva tarea"
       />
       <Button type="submit" loading={isPending}>

package/template/src/features/todos/components/todo-list.tsx

@@ -17,7 +17,7 @@ export function TodoList({ items }: TodoListProps) {
 
   if (items.length === 0) {
     return (
-      <p className="mt-4 text-center text-sm text-gray-500">
+      <p className="mt-4 text-center text-sm text-muted-foreground">
         No tienes tareas. ¡Agrega una!
       </p>
     );
@@ -44,10 +44,10 @@ export function TodoList({ items }: TodoListProps) {
               }}
               aria-label={`Marcar "${todo.title}" como completada`}
             />
-            <span className={todo.completed ? "line-through text-gray-400" : ""}>
+            <span className={todo.completed ? "line-through text-muted-foreground" : ""}>
               {todo.title}
             </span>
-            {isPending && <Spinner className="size-4 text-gray-400" />}
+            {isPending && <Spinner className="size-4 text-muted-foreground" />}
           </label>
           <button
             type="button"
@@ -59,7 +59,7 @@ export function TodoList({ items }: TodoListProps) {
                 else toast.success(result.message);
               });
             }}
-            className="rounded px-2 py-1 text-sm text-red-500 hover:bg-red-50"
+            className="rounded px-2 py-1 text-sm text-destructive hover:bg-destructive/10"
             aria-label={`Eliminar "${todo.title}"`}
           >
             Eliminar

package/template/src/shared/components/providers.tsx

@@ -19,7 +19,16 @@ export function Providers({ children }: { children: React.ReactNode }) {
   return (
     <QueryClientProvider client={queryClient}>
       {children}
-      <Toaster />
+      <Toaster
+        toastOptions={{
+          classNames: {
+            success: "!bg-success !text-success-foreground !border-success",
+            error: "!bg-destructive !text-destructive-foreground !border-destructive",
+            warning: "!bg-warning !text-warning-foreground !border-warning",
+            info: "!bg-info !text-info-foreground !border-info",
+          },
+        }}
+      />
     </QueryClientProvider>
   );
 }

package/template/src/shared/test-utils/supabase-mock.ts

@@ -0,0 +1,59 @@
+import { vi } from "vitest";
+
+type Chain = Record<string, ReturnType<typeof vi.fn>>;
+
+/**
+ * Creates a chainable Supabase query mock.
+ *
+ * Usage:
+ *   const chain = makeChain({ data: [...], error: null });
+ *   mockSupabase.from.mockReturnValue(chain);
+ *
+ * Supports: .select() .insert() .update() .delete() .eq() .single() .order()
+ * Each method returns the same chain, so calls can be chained arbitrarily.
+ * The chain resolves with `resolvedValue` when awaited.
+ */
+export function makeChain(resolvedValue: unknown): Chain {
+  const chain: Chain = {};
+  const methods = [
+    "select",
+    "insert",
+    "update",
+    "delete",
+    "eq",
+    "single",
+    "order",
+    "limit",
+    "match",
+  ];
+  for (const method of methods) {
+    chain[method] = vi.fn().mockReturnValue(chain);
+  }
+  chain["then"] = vi.fn((cb: (v: unknown) => unknown) => cb(resolvedValue));
+  return chain;
+}
+
+/**
+ * Creates a minimal Supabase client mock with auth + from.
+ *
+ * Usage:
+ *   const { mockClient, mockFrom } = makeSupabaseMock({ user: mockUser });
+ *   vi.mocked(createClient).mockResolvedValue(mockClient as never);
+ *   mockFrom.mockReturnValue(makeChain({ data: [...], error: null }));
+ */
+export function makeSupabaseMock(authResult: {
+  user: { id: string } | null;
+  error?: unknown;
+}) {
+  const mockFrom = vi.fn();
+  const mockClient = {
+    auth: {
+      getUser: vi.fn().mockResolvedValue({
+        data: { user: authResult.user },
+        error: authResult.error ?? null,
+      }),
+    },
+    from: mockFrom,
+  };
+  return { mockClient, mockFrom };
+}

package/template/tailwind.css

@@ -13,6 +13,12 @@
   --color-accent-foreground: #ffffff;
   --color-destructive: hsl(0 84.2% 60.2%);
   --color-destructive-foreground: #ffffff;
+  --color-success: hsl(142 71% 45%);
+  --color-success-foreground: #ffffff;
+  --color-warning: hsl(38 92% 50%);
+  --color-warning-foreground: #ffffff;
+  --color-info: hsl(199 89% 48%);
+  --color-info-foreground: #ffffff;
   --color-border: #e5e5e5;
   --color-input: #e5e5e5;
   --color-ring: #022633;