nextjs-hackathon-stack 0.1.35 → 0.1.37

package/template/README.md

@@ -98,5 +98,219 @@ Husky runs `vitest --coverage` on every commit. The commit is blocked if coverag
 Cursor rules, agents, and skills are preconfigured in `.cursor/`:
 
 - **Rules** (11): always-on guardrails for coding standards, architecture, security, and more
-- **Agents** (7): specialized roles (technical-lead, frontend, backend, test-qa, etc.)
-- **Skills** (4): repeatable workflows (`/create-feature`, `/create-api-route`, `/review-branch`, `/security-audit`)
+- **Agents** (7): specialized roles (`technical-lead`, `frontend`, `backend`, `test-qa`, `business-intelligence`, `code-reviewer`, `security-researcher`)
+- **Skills** (5): `/discover-feature`, `/build-feature`, `/create-api-route`, `/review-branch`, `/security-audit`
+
+### Initial Setup (once per project)
+
+**1. Install mcp-memory-service** (if not already installed):
+
+```bash
+# 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`, run:
+> `pipx install mcp-memory-service --python $(brew --prefix python@3.12)/bin/python3.12`
+
+**2. Populate MCP memory** so agents load context efficiently:
+
+```
+/memory sync
+```
+
+This parses `.cursor/memory/architecture-snapshot.md` into semantic memory. Agents query only what they need instead of reading the full file.
+
+---
+
+### New Feature Workflow
+
+Everything runs in **Agent mode**. Only two prompts across two conversations.
+
+#### Conversation 1 — Requirements
+
+**Prompt:**
+```
+/discover-feature <describe your feature in plain language>
+```
+
+**What happens:**
+1. Loads existing features from MCP memory to identify relationships
+2. Asks you 9 discovery questions (problem, user flows, edge cases, access rules, etc.)
+3. Confirms understanding with you before writing anything
+4. Writes the functional issue to `.requirements/<feature-name>.md`
+5. Stores the requirement in MCP memory
+
+**Output:** `.requirements/<feature-name>.md` with user story, acceptance criteria, and functional test cases.
+
+> Start a new conversation before the next step.
+
+---
+
+#### Conversation 2 — Build (fresh conversation)
+
+**Prompt:**
+```
+/build-feature @.requirements/<feature-name>.md
+```
+
+**What happens (automated, step by step):**
+
+| Step | What it does |
+|------|-------------|
+| 1. Read spec | Reads `.requirements/<feature-name>.md` |
+| 2. Load context | Queries MCP memory for schema, features, patterns, rules (targeted — no full file read) |
+| 3. **Plan** | Tech-lead role: maps acceptance criteria to tasks, plans test structure, identifies reusable patterns → **asks your approval before coding** |
+| 4. Feature structure | Creates `src/features/<name>/` directory layout |
+| 5. Pre-test setup | Updates `vitest.config.ts` exclusions |
+| 6. TDD RED | Writes all test files. Runs `pnpm test:unit` → must FAIL |
+| 7. TDD GREEN | Runs `@backend` + `@frontend` in parallel. Runs `pnpm test:unit` → must PASS |
+| 8. Refactor | Cleans up while keeping tests green |
+| 9. Verify | Runs `pnpm test:coverage` + `pnpm lint` + `pnpm typecheck` in single pass |
+| 10. Review gate | Runs `@code-reviewer` + `@security-researcher` in parallel |
+| 11. Memory sync | Updates architecture snapshot + runs `/memory sync` |
+
+**Output:** Fully implemented, tested, reviewed feature. Memory updated for the next session.
+
+---
+
+### Example: Hiring Candidates Feature
+
+A real end-to-end walkthrough using the two-conversation workflow.
+
+#### Conversation 1 — Requirements
+
+**Prompt (Agent mode):**
+```
+/discover-feature Gestión de candidatos de contratación.
+
+Vista principal: tabla de candidatos con columnas nombre e identificación (la
+identificación es única por candidato).
+Comportamiento maestro-detalle: al seleccionar una fila de la tabla, mostrar en
+un panel lateral derecho todos los soportes (documentos adjuntos) que pertenecen
+al candidato seleccionado.
+Encima de la tabla, un botón "Agregar candidato" que abre un formulario con los
+campos nombre e identificación. El número de identificación no puede repetirse.
+Toda la UI en español.
+```
+
+> **Why this prompt works well:**
+> - One concern per line — table, selection behavior, side panel, add form, uniqueness rule
+> - Names the UI pattern ("maestro-detalle") so the agent picks the right shadcn components (`ResizablePanelGroup`)
+> - Clarifies "soportes" = documentos adjuntos — no ambiguity
+> - States uniqueness constraint explicitly (becomes a DB unique index + validation rule)
+> - Declares language upfront — no back-and-forth later
+
+**What happens:** The BI agent asks clarifying questions (upload limits? who can add candidates? pagination?), then writes `.requirements/hiring-candidates.md`.
+
+**Output:**
+```
+.requirements/hiring-candidates.md
+├── User Story
+├── Acceptance Criteria (AC1–AC6)
+└── Functional Test Cases (TC1–TC8)
+```
+
+> Start a new conversation before the next step.
+
+---
+
+#### Conversation 2 — Build
+
+**Prompt (Agent mode):**
+```
+/build-feature @.requirements/hiring-candidates.md
+```
+
+**What the automated pipeline produces:**
+
+```
+src/features/hiring-candidates/
+├── components/
+│   ├── candidates-table.tsx         # Table with row selection
+│   ├── candidate-detail-panel.tsx   # Right panel — soportes list
+│   ├── add-candidate-dialog.tsx     # Dialog with name + ID form
+│   └── __tests__/
+│       ├── candidates-table.test.tsx
+│       ├── candidate-detail-panel.test.tsx
+│       └── add-candidate-dialog.test.tsx
+├── actions/
+│   ├── candidates.action.ts         # createCandidate Server Action
+│   └── __tests__/
+│       └── candidates.action.test.ts
+└── queries/
+    ├── candidates.queries.ts        # getCandidates, getSoportes
+    └── __tests__/
+        └── candidates.queries.test.ts
+```
+
+**Planning output (step 3 — shown before coding starts):**
+
+> Backend: new `candidates` table (name, identification UNIQUE), new `soportes` table (candidateId FK), RLS policies, Server Action for createCandidate with Zod validation.
+> Frontend: ResizablePanelGroup layout, CandidatesTable with row selection state, CandidateDetailPanel, AddCandidateDialog with React Hook Form + zodResolver.
+> Tests: 8 unit tests covering unauthenticated, duplicate ID, DB error, happy path for action; RTL tests for each component.
+> Approve to proceed?
+
+**Final output:** Fully tested feature, 0 lint warnings, review gate passed, architecture snapshot updated.
+
+---
+
+### Other Workflows
+
+#### Bug Fix (Agent mode)
+
+```
+@test-qa Reproduce this bug: <describe what's broken and where>
+```
+→ Produces a failing test, then:
+```
+@backend Fix the failing test in <file>
+```
+or `@frontend` for UI bugs, then:
+```
+@code-reviewer Review the changes in src/features/<feature>/
+```
+
+#### Refactor (Agent mode)
+
+```
+@technical-lead Plan refactor for <scope/reason>
+```
+→ Plan output, then:
+```
+@backend Implement the refactor plan
+```
+Then verify + review:
+```
+@test-qa Verify all tests still pass
+@code-reviewer Review the refactor changes
+```
+
+#### Find Context Fast (any mode)
+
+```
+/memory recall "form validation patterns"
+/memory recall "existing auth tables"
+/memory recall "how are errors handled in actions"
+```
+
+---
+
+### Quick Reference
+
+| Task | Mode | Prompt |
+|------|------|--------|
+| Define requirements | Agent | `/discover-feature <description>` |
+| Implement feature | Agent | `/build-feature @.requirements/<name>.md` |
+| Sync memory after changes | Agent | `/memory sync` |
+| Search project knowledge | Any | `/memory recall "query"` |
+| Create API route | Agent | `/create-api-route` |
+| Review a branch or PR | Agent | `/review-branch` |
+| Security audit | Agent | `/security-audit` |
+| Reproduce a bug | Agent | `@test-qa Reproduce: <description>` |
+| Plan an architectural change | Agent | `@technical-lead Plan: <description>` |

package/template/drizzle.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from "drizzle-kit";
 loadEnvConfig(process.cwd());
 
 export default defineConfig({
-  schema: "./src/shared/db/schema.ts",
+  schema: "./src/shared/db/*.schema.ts",
   out: "./src/shared/db/migrations",
   dialect: "postgresql",
   dbCredentials: {

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

@@ -6,7 +6,7 @@ import { toast } from "sonner";
 import { deleteTodoAction, toggleTodoAction } from "../actions/todos.action";
 
 import { Spinner } from "@/shared/components/ui/spinner";
-import type { SelectTodo } from "@/shared/db/schema";
+import type { SelectTodo } from "@/shared/db/todos.schema";
 
 interface TodoListProps {
   items: SelectTodo[];

package/template/src/shared/__tests__/schema.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 
-import { insertProfileSchema, selectProfileSchema } from "../db/schema";
+import { insertProfileSchema, selectProfileSchema } from "../db/profiles.schema";
 
 describe("profiles schema", () => {
   it("insertProfileSchema validates required fields", () => {

package/template/src/shared/db/index.ts

@@ -1,7 +1,10 @@
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 
-import * as schema from "./schema";
+import * as profiles from "./profiles.schema";
+import * as todos from "./todos.schema";
+
+const schema = { ...profiles, ...todos };
 
 const client = postgres(process.env.DATABASE_URL ?? "");
 

package/template/src/shared/db/profiles.schema.ts

@@ -0,0 +1,15 @@
+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;

package/template/src/shared/db/schema.ts

@@ -1,29 +1,2 @@
-import { boolean, 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;
-
-export const todos = pgTable("todos", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  userId: uuid("user_id").notNull(),
-  title: text("title").notNull(),
-  completed: boolean("completed").notNull().default(false),
-  createdAt: timestamp("created_at").notNull().defaultNow(),
-});
-
-export const insertTodoSchema = createInsertSchema(todos);
-export const selectTodoSchema = createSelectSchema(todos);
-
-export type InsertTodo = typeof todos.$inferInsert;
-export type SelectTodo = typeof todos.$inferSelect;
+export * from "./profiles.schema";
+export * from "./todos.schema";

package/template/src/shared/db/todos.schema.ts

@@ -0,0 +1,16 @@
+import { boolean, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+
+export const todos = pgTable("todos", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id").notNull(),
+  title: text("title").notNull(),
+  completed: boolean("completed").notNull().default(false),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});
+
+export const insertTodoSchema = createInsertSchema(todos);
+export const selectTodoSchema = createSelectSchema(todos);
+
+export type InsertTodo = typeof todos.$inferInsert;
+export type SelectTodo = typeof todos.$inferSelect;

package/template/vitest.config.ts

@@ -12,10 +12,10 @@ export default defineConfig({
     coverage: {
       provider: "v8",
       thresholds: {
-        branches: 100,
-        functions: 100,
-        lines: 100,
-        statements: 100,
+        branches: 90,
+        functions: 95,
+        lines: 95,
+        statements: 95,
       },
       exclude: [
         "node_modules/**",

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

@@ -1,136 +0,0 @@
----
-name: create-feature
-description: Scaffold a new feature following TDD and project conventions. Use when starting a new feature or user story.
----
-
-# 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
-- Check `.requirements/` for an existing functional issue
-- If a spec exists, read it and proceed to Step 2
-- **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. 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/
-├── actions/
-├── queries/
-├── hooks/
-├── api/
-├── lib/
-└── __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`)
-- Pure type-only files (no runtime logic)
-- 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",
-]
-```
-
-Configuring exclusions upfront prevents reactive coverage fixes mid-implementation.
-
-### 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 (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.
-
-**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
-
-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.
-
-**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.
-
-### 8. Verify & Self-Check
-
-Run all three and paste output:
-```bash
-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 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