@dennisrongo/skills 0.1.3 → 0.3.0

package/skills/nextjs-app-router/references/templates/route-group-layouts.md

@@ -1,8 +1,8 @@
 # Route group layouts
 
-Layouts are **server components** by default. Push interactive chrome into `'use client'` children.
+Group layouts are **server components** that render zero data — they just delegate to a `'use client'` shell. Pages inside the group are `'use client'`.
 
-## `src/app/(public)/layout.tsx` (SERVER)
+## `src/app/(public)/layout.tsx` (SERVER, zero data)
 
 ```tsx
 export default function PublicLayout({ children }: { children: React.ReactNode }) {
@@ -20,12 +20,14 @@ export default function PublicLayout({ children }: { children: React.ReactNode }
 import { AppShell } from './_components/AppShell';
 
 export default function AppLayout({ children }: { children: React.ReactNode }) {
-  // Server-side session check happens in middleware.ts.
-  // This layout assumes the request reached here because the user is authenticated.
+  // Server-side session check is done in middleware.ts — by the time we render here,
+  // the user is authenticated. We do NOT call `await auth()` here; the gate is the middleware.
   return <AppShell>{children}</AppShell>;
 }
 ```
 
+**No `await auth()` here.** The middleware already gated the request. Calling `auth()` again from this layout adds a round-trip and doesn't change the outcome.
+
 ## `src/app/(app)/_components/AppShell.tsx` (CLIENT, holds interactive UI state)
 
 ```tsx
@@ -50,9 +52,40 @@ export function AppShell({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## `src/app/(app)/loading.tsx` (SERVER)
+## `src/app/(app)/_components/UserMenu.tsx` (CLIENT — uses NextAuth)
 
 ```tsx
+'use client';
+
+import { signOut, useSession } from 'next-auth/react';
+import { Button } from '@/components/ui/button';
+
+export function UserMenu() {
+  const { data: session, status } = useSession();
+
+  if (status === 'loading') return null;
+  if (!session?.user) return null;
+
+  return (
+    <div className="flex items-center gap-3">
+      <span className="text-sm text-muted-foreground">{session.user.email}</span>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => signOut({ callbackUrl: '/auth/login', redirect: true })}
+      >
+        Sign out
+      </Button>
+    </div>
+  );
+}
+```
+
+## `src/app/(app)/loading.tsx` (CLIENT — Suspense fallback)
+
+```tsx
+'use client';
+
 export default function Loading() {
   return (
     <div className="flex h-[50vh] items-center justify-center">
@@ -87,4 +120,11 @@ export default function AppError({ error, reset }: { error: Error & { digest?: s
 
 ## `src/app/(admin)/layout.tsx` (OPTIONAL, SERVER)
 
-Same shape as `(app)/layout.tsx`. The role check happens in `middleware.ts`; this layout just renders an admin-flavored shell.
+Same shape as `(app)/layout.tsx`. The role check happens in `middleware.ts` (Variant B in [`middleware.md`](middleware.md)); this layout just renders an admin-flavored shell.
+
+## Forbidden in any layout
+
+- `await auth()` — duplicates middleware's job.
+- `await db.*` — server data fetching is banned.
+- `'use client'` directly on a `layout.tsx` — push interactive chrome into a client child.
+- `redirect()` — middleware handles all redirects.

package/skills/nextjs-app-router/references/templates/route-handler.md

@@ -0,0 +1,168 @@
+# Route Handler template
+
+Route Handlers under `src/app/api/**/route.ts` are the backend. Every one (except `/api/auth/[...nextauth]` and explicit public endpoints like `/api/health`) authenticates with `requireSession()`, validates inputs with the feature's Zod schema, and accesses the DB through the Prisma singleton.
+
+## `src/app/api/{{feature}}s/route.ts` — list + create
+
+```ts
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { requireSession, withApiErrors } from '@/lib/api-auth';
+import { {{feature}}Schema } from '@/app/(app)/{{feature}}s/schema';
+
+export const GET = withApiErrors(async () => {
+  const session = await requireSession();
+
+  const rows = await db.{{feature}}.findMany({
+    where: { userId: session.user.id },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return NextResponse.json(rows);
+});
+
+export const POST = withApiErrors(async (req: Request) => {
+  const session = await requireSession();
+
+  const body = await req.json().catch(() => null);
+  const parsed = {{feature}}Schema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+  }
+
+  const created = await db.{{feature}}.create({
+    data: {
+      ...parsed.data,
+      userId: session.user.id,
+    },
+  });
+
+  return NextResponse.json(created, { status: 201 });
+});
+```
+
+## `src/app/api/{{feature}}s/[id]/route.ts` — get + update + delete
+
+```ts
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { requireSession, withApiErrors, assertOwnership } from '@/lib/api-auth';
+import { {{feature}}Schema } from '@/app/(app)/{{feature}}s/schema';
+
+interface RouteContext {
+  params: Promise<{ id: string }>;
+}
+
+export const GET = withApiErrors(async (_req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const row = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+  });
+  if (!row) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  return NextResponse.json(row);
+});
+
+export const PATCH = withApiErrors(async (req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const body = await req.json().catch(() => null);
+  const parsed = {{feature}}Schema.partial().safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+  }
+
+  // Ownership check via findFirst + userId predicate.
+  const existing = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+    select: { id: true },
+  });
+  if (!existing) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  const updated = await db.{{feature}}.update({
+    where: { id },
+    data: parsed.data,
+  });
+
+  return NextResponse.json(updated);
+});
+
+export const DELETE = withApiErrors(async (_req: Request, ctx: RouteContext) => {
+  const session = await requireSession();
+  const { id } = await ctx.params;
+
+  const existing = await db.{{feature}}.findFirst({
+    where: { id, userId: session.user.id },
+    select: { id: true },
+  });
+  if (!existing) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+  await db.{{feature}}.delete({ where: { id } });
+
+  return new NextResponse(null, { status: 204 });
+});
+```
+
+## Public handlers (e.g. health check)
+
+The matcher in `middleware.ts` already excludes `/api/auth/*`. Other `/api/*` routes aren't redirected by middleware (they run their own `requireSession()`). A public handler simply omits the session check:
+
+```ts
+// src/app/api/health/route.ts
+import { NextResponse } from 'next/server';
+export const GET = () => NextResponse.json({ ok: true });
+```
+
+Comment in the file so the absence of `requireSession()` is intentional, not an oversight.
+
+## Forbidden
+
+- **No `requireSession()` call** in any handler outside `/api/auth/*` and explicitly-public ones (and the public ones must comment why).
+- **Trusting `userId` from the request body.** Always read it from the session: `session.user.id`.
+- **Returning the full record on POST/PATCH without checking ownership first** on updates — the `where: { id, userId }` predicate is the gate.
+- **`prisma.$queryRaw` with string concatenation.** Use parameterized template literals (`prisma.$queryRaw\`... ${value} ...\``) or stick to the typed query builder.
+- **Catching and re-throwing without logging.** `withApiErrors` logs unexpected errors; if you write your own try/catch, log unexpected ones at least once.
+- **Returning 500 with the raw error message.** Leaks stack traces. `withApiErrors` returns a generic message; if you write your own, do the same.
+- **Long-running work in a handler.** Route Handlers run per-request. For background work, dispatch to a queue (the skill doesn't ship one — ask the user to pick).
+- **`Set-Cookie` headers writing your own session cookie.** NextAuth owns the session cookie; setting a parallel one is the "custom JWT alongside NextAuth" anti-pattern.
+
+## Why we import the schema from the feature folder
+
+The form (`_components/{{Feature}}Form.tsx`) and the handler validate the same shape. If the handler had its own schema, drift would silently let the form post payloads the handler accepts but the form's UI hasn't accounted for — or vice versa. One Zod schema in `(app)/{{feature}}s/schema.ts` is the contract; both sides import it.
+
+## Handler test (optional but recommended)
+
+```ts
+// tests/unit/{{feature}}.handler.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/auth', () => ({ auth: vi.fn() }));
+vi.mock('@/lib/db', () => ({
+  db: { {{feature}}: { findMany: vi.fn(), create: vi.fn() } },
+}));
+
+import { GET, POST } from '@/app/api/{{feature}}s/route';
+import { auth } from '@/auth';
+import { db } from '@/lib/db';
+
+describe('GET /api/{{feature}}s', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('401s when unauthenticated', async () => {
+    (auth as ReturnType<typeof vi.fn>).mockResolvedValueOnce(null);
+    const res = await GET();
+    expect(res.status).toBe(401);
+  });
+
+  it('returns the current user's rows', async () => {
+    (auth as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ user: { id: 'u1' } });
+    (db.{{feature}}.findMany as ReturnType<typeof vi.fn>).mockResolvedValueOnce([{ id: 'r1', userId: 'u1' }]);
+    const res = await GET();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 'r1', userId: 'u1' }]);
+  });
+});
+```

package/skills/nextjs-app-router/references/templates/testing.md

@@ -1,6 +1,6 @@
 # Testing setup (Vitest + RTL + Playwright)
 
-A new project ships with three real tests: a reducer test, a component test, and an E2E auth spec. Three is enough to make CI meaningful; the user adds more as features grow.
+A new project ships with a small set of real tests: a Zod schema test, a Route Handler test, a component test, and an E2E auth spec. Just enough to make CI meaningful.
 
 ## `vitest.config.ts`
 
@@ -38,61 +38,123 @@ afterEach(() => {
 });
 ```
 
-## `tests/unit/auth.slice.test.ts`
+## `tests/unit/customer.schema.test.ts`
 
 ```ts
 import { describe, expect, it } from 'vitest';
-import { authSlice, logout, setUser } from '@/redux/features/authSlice';
+import { customerSchema } from '@/app/(app)/customers/schema';
 
-const initial = authSlice.getInitialState();
+describe('customerSchema', () => {
+  it('accepts a valid payload', () => {
+    expect(customerSchema.safeParse({ name: 'Acme', email: 'ops@acme.test' }).success).toBe(true);
+  });
+
+  it('rejects an empty name', () => {
+    expect(customerSchema.safeParse({ name: '', email: 'ops@acme.test' }).success).toBe(false);
+  });
+
+  it('rejects an invalid email', () => {
+    expect(customerSchema.safeParse({ name: 'Acme', email: 'nope' }).success).toBe(false);
+  });
+});
+```
+
+This is the test that pays for itself most often. The same schema validates form input *and* the Route Handler's request body, so regressions on either side fail here.
+
+## `tests/unit/customers.handler.test.ts` (Route Handler test with mocked `auth` + `db`)
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/auth', () => ({ auth: vi.fn() }));
+vi.mock('@/lib/db', () => ({
+  db: {
+    customer: {
+      findMany: vi.fn(),
+      create: vi.fn(),
+    },
+  },
+}));
 
-describe('authSlice', () => {
-  it('starts logged out', () => {
-    expect(initial.user).toBeNull();
-    expect(initial.token).toBeNull();
+import { GET, POST } from '@/app/api/customers/route';
+import { auth } from '@/auth';
+import { db } from '@/lib/db';
+
+const mockAuth = auth as ReturnType<typeof vi.fn>;
+const mockFindMany = db.customer.findMany as ReturnType<typeof vi.fn>;
+const mockCreate = db.customer.create as ReturnType<typeof vi.fn>;
+
+describe('GET /api/customers', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('401s when unauthenticated', async () => {
+    mockAuth.mockResolvedValueOnce(null);
+    const res = await GET();
+    expect(res.status).toBe(401);
   });
 
-  it('sets the user', () => {
-    const state = authSlice.reducer(initial, setUser({ id: '1', email: 'a@b.c', name: 'A', roles: [] }));
-    expect(state.user?.id).toBe('1');
+  it('returns the current user\'s customers', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    mockFindMany.mockResolvedValueOnce([{ id: 'c1', userId: 'u1', name: 'Acme' }]);
+    const res = await GET();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ id: 'c1', userId: 'u1', name: 'Acme' }]);
   });
+});
 
-  it('logout resets state', () => {
-    const seeded = { ...initial, user: { id: '1', email: 'a@b.c', name: 'A', roles: [] } };
-    expect(authSlice.reducer(seeded, logout())).toEqual(initial);
+describe('POST /api/customers', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('400s on an invalid payload', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    const req = new Request('http://x/api/customers', {
+      method: 'POST',
+      body: JSON.stringify({ name: '', email: 'nope' }),
+    });
+    const res = await POST(req);
+    expect(res.status).toBe(400);
+  });
+
+  it('attaches the session userId to the created row', async () => {
+    mockAuth.mockResolvedValueOnce({ user: { id: 'u1' } });
+    mockCreate.mockResolvedValueOnce({ id: 'c2', userId: 'u1', name: 'Acme', email: 'ops@acme.test' });
+    const req = new Request('http://x/api/customers', {
+      method: 'POST',
+      body: JSON.stringify({ name: 'Acme', email: 'ops@acme.test' }),
+    });
+    await POST(req);
+    expect(mockCreate).toHaveBeenCalledWith({
+      data: { name: 'Acme', email: 'ops@acme.test', userId: 'u1' },
+    });
   });
 });
 ```
 
+This test catches three common regressions: missing `requireSession`, body validation that silently accepts garbage, and userId tampering.
+
 ## `tests/unit/login-form.test.tsx`
 
 ```tsx
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { Provider } from 'react-redux';
-import { configureStore } from '@reduxjs/toolkit';
-import { api } from '@/redux/api/api';
-import { authSlice } from '@/redux/features/authSlice';
 import { LoginForm } from '@/app/(public)/auth/login/_components/LoginForm';
 
-function renderWithStore(ui: React.ReactElement) {
-  const store = configureStore({
-    reducer: { [api.reducerPath]: api.reducer, auth: authSlice.reducer },
-    middleware: (gdm) => gdm().concat(api.middleware),
-  });
-  return render(<Provider store={store}>{ui}</Provider>);
-}
+vi.mock('next-auth/react', () => ({
+  signIn: vi.fn().mockResolvedValue({ ok: true, error: null }),
+}));
 
 describe('<LoginForm />', () => {
-  it('shows a validation error for an empty email', async () => {
-    renderWithStore(<LoginForm />);
+  it('shows a validation error when fields are empty', async () => {
+    render(<LoginForm />);
     await userEvent.click(screen.getByRole('button', { name: /sign in/i }));
     expect(await screen.findByText(/required|invalid/i)).toBeInTheDocument();
   });
 });
 ```
 
+Mocking `next-auth/react` lets the form test run in isolation — we're testing the form, not NextAuth.
+
 ## `playwright.config.ts`
 
 ```ts
@@ -124,14 +186,26 @@ export default defineConfig({
 import { test, expect } from '@playwright/test';
 
 test('unauthenticated user is redirected to login', async ({ page }) => {
-  await page.goto('/dashboard');
+  await page.goto('/app/dashboard');
   await expect(page).toHaveURL(/\/auth\/login/);
   await expect(page.getByRole('heading', { name: /sign in/i })).toBeVisible();
 });
+
+// Requires `pnpm db:seed` to have run — provides test@example.com / test1234.
+test('seeded user can sign in and land on the dashboard', async ({ page }) => {
+  await page.goto('/auth/login');
+  await page.getByLabel(/email/i).fill('test@example.com');
+  await page.getByLabel(/password/i).fill('test1234');
+  await page.getByRole('button', { name: /sign in/i }).click();
+  await expect(page).toHaveURL(/\/app\/dashboard/);
+});
 ```
 
-That spec alone validates: middleware fires, the login page renders, the route group split works. If any of those regress, this test breaks.
+Together those two specs validate: middleware fires, the login page renders, NextAuth's Credentials provider works against the seeded user, and the route-group split holds.
 
 **Notes:**
-- Do not include Playwright in the default `pnpm test` script — keep it as `pnpm test:e2e` so CI can run Vitest fast and Playwright separately (or in a different job).
+
+- Do not include Playwright in the default `pnpm test` script — keep it as `pnpm test:e2e`.
+- The seed-then-login test requires the CI workflow's `pnpm db:seed` step (see [`ci-and-hooks.md`](ci-and-hooks.md)).
 - Real backend mocking (MSW) is *not* in the default scaffold. Add only if the user asks.
+- **Forbidden:** an `authSlice.test.ts`. There is no `authSlice` in this project — NextAuth owns session state. If you see a test importing `@/redux/features/authSlice`, delete it.

package/skills/plan-and-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-and-build
-description: Plan-first feature builder. Grills the user about the feature until the design is unambiguous, presents a plan, gates on `ExitPlanMode` approval, then builds the feature using the project's existing patterns — TDD-first with NUnit when the work touches a .NET API (appending to the matching test class if one already exists), and writing migration files but never executing SQL or `dotnet ef database update`. Use this skill whenever the user says "build a feature", "add a feature", "implement this feature", "/plan-and-build", "plan and build", "new feature", or pastes a feature spec and asks you to design + implement it — even if they don't name the skill.
+description: Plan-first feature builder. Grills the user about the feature until the design is unambiguous, presents a plan, gates on `ExitPlanMode` approval, then builds the feature using the project's existing patterns — TDD-first with NUnit when the work touches a .NET API (appending to the matching test class if one already exists), and writing migration files but never executing SQL or `dotnet ef database update`. When Phase 3 hits a genuine design fork (e.g. service-layer vs. CQRS handler, sync vs. async, new table vs. nullable columns), runs **Design It Twice**: two parallel sub-agents each draft the strongest plan for one approach, then a debate round names the trade-offs and recommends one — the user sees a recommended plan with the rejected alternative noted so they can redirect. Skipped when an existing pattern in the repo already dictates the approach. Use this skill whenever the user says "build a feature", "add a feature", "implement this feature", "/plan-and-build", "plan and build", "new feature", or pastes a feature spec and asks you to design + implement it — even if they don't name the skill.
 ---
 
 # Plan and Build
@@ -66,9 +66,43 @@ Before designing, look at what the repo already does so the plan reuses it. Run
 
 Record what you find. The plan will reference these directly so the user can see you're not inventing new patterns.
 
+**Library API lookup — use `context7` when available.** If the plan needs an API from a third-party library or framework that's pinned in this repo (e.g. EF Core 8, Next.js 15, Prisma 5, NextAuth v5, Stripe SDK), check `context7` (or any docs-MCP server in the environment) for the *current* docs before drafting the plan: `context7__resolve-library-id` → `context7__query-docs` for the specific topic. Training-data API knowledge can be a major version behind, and a plan built on the wrong API shape wastes a Plan Mode round. Skip the lookup for libraries the user has already named in this session or for general programming concepts — only reach for it when the plan depends on a specific library symbol or pattern.
+
 ### Phase 3 — Plan
 
-Enter Plan Mode (`EnterPlanMode`). The plan must include:
+#### Decision gate: single plan vs. Design It Twice
+
+Before drafting, ask: **is there a genuine design fork here that the existing codebase doesn't already resolve?**
+
+- **Single plan** — when Phase 2 found a clear precedent (e.g. every other feature in this codebase uses CQRS handlers, or the project's slice template dictates the layout). Draft one plan and proceed.
+- **Design It Twice** — when there's a real choice with real trade-offs, and Phase 2 didn't settle it. Typical forks:
+  - Service-layer method vs. CQRS handler
+  - New table vs. nullable columns on an existing table
+  - Sync request/response vs. background job + status endpoint
+  - In-process event vs. message-queue publish
+  - REST endpoint vs. WebSocket / SSE
+  - Lifting state up vs. introducing a context/store
+  - One denormalised read model vs. join at query time
+
+Don't manufacture a fork to perform ceremony. If the answer is clear, the single plan is faster *and* better.
+
+#### Design It Twice (when convened)
+
+1. **Name the axis.** State the single design choice the two plans disagree on in one sentence (e.g. *"Add an `OrderAuditLog` table vs. extend `Orders` with `priority_set_by_user_id` + `priority_set_at`."*). If you can't name the axis cleanly, you don't have a genuine fork — drop to single plan.
+2. **Spawn two planners in parallel.** Send a **single message** with 2 `Agent` calls (general-purpose). Each gets:
+   - Phase 1 grilling outputs (verbatim, including the canonical terminology).
+   - Phase 2 stack and convention findings (verbatim).
+   - The named axis and **one** side of it to defend.
+   - Instructions: "Draft the BEST plan for your assigned approach. Include the seven items below ([Plan contents](#plan-contents)). Defend why this approach beats the alternative *on this codebase*. Where you must invent a new pattern (no Phase 2 precedent), justify it. Report in ≤700 words."
+3. **Debate round.** When both plans return, write inline:
+   - **3 things Plan A does better than Plan B.**
+   - **3 things Plan B does better than Plan A.**
+   - **The recommendation** (one paragraph) — which plan, and why it wins on this codebase. Cite the Phase 1 / Phase 2 evidence that broke the tie.
+4. **Pick the recommended plan** as the one to present. Carry forward only the winning plan's contents — but keep a one-line note of the rejected alternative for the user.
+
+#### Plan contents
+
+Whether you drafted one plan or chose between two, the presented plan must include:
 
 1. **Restatement of the feature** in one short paragraph, using the project's canonical terminology from `CONTEXT.md` (if present).
 2. **Files to create**, grouped by layer, each with a one-line purpose.
@@ -82,7 +116,11 @@ Enter Plan Mode (`EnterPlanMode`). The plan must include:
 6. **Pattern reuse table.** Two columns: "New code I'm about to write" and "Existing example it follows" with a path. If a row has no existing example, justify the new pattern.
 7. **Open questions** still unresolved, if any. If there are any, loop back to Phase 1 — do not exit plan mode with open questions.
 
-Then exit with `ExitPlanMode` and wait. **Do not write a single file until the user approves the plan.** If the user pushes back, revise and re-present; don't half-implement against an unapproved plan.
+If Design It Twice ran, end the plan with: **"Considered alternative: `<approach B name>`. Rejected because `<one-line reason>`."** This lets the user redirect to B with a single sentence if they disagree.
+
+#### Enter and exit plan mode
+
+Enter Plan Mode (`EnterPlanMode`) to present. Then exit with `ExitPlanMode` and wait. **Do not write a single file until the user approves the plan.** If the user pushes back — including "actually let's go with the alternative" — revise and re-present; don't half-implement against an unapproved plan.
 
 ### Phase 4 — Build (test-first when an API changes)
 
@@ -173,6 +211,10 @@ When appending:
 - ❌ Writing production code before the test it makes pass (when the feature touches an API).
 - ❌ Creating `FooServiceTests2.cs` because `FooServiceTests.cs` already exists. Always append.
 - ❌ Inventing a new pattern for something the codebase already has a pattern for. If you can't find the precedent, ask before forking.
+- ❌ Running Design It Twice when the codebase already dictates the approach. Ceremony, not value.
+- ❌ Manufacturing a fake axis to perform a debate. If you can't name the axis in one sentence, you don't have a fork.
+- ❌ Spawning the two planners serially instead of in parallel — one message, two agents.
+- ❌ Presenting both plans to the user. The user sees the recommended plan plus a one-line "considered alternative" note — not two full plans to grade.
 - ❌ Running `dotnet ef database update`, `prisma migrate deploy`, or any DDL against the user's DB.
 - ❌ Running ad-hoc `SELECT` / `UPDATE` queries against the user's DB to "check something" — ask the user instead.
 - ❌ Block comments and "what this does" comments. Names should do that work.

package/skills/pr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-review
-description: Conduct a thorough, structured code review of a local branch, grouped by task number (#NNN) referenced in commit messages. Use this skill whenever the user asks to review a PR, asks for feedback on a diff or branch, mentions "review my changes", or pastes code asking what could be improved. Auto-detects all tasks on the branch and produces one verdict per task. Covers correctness, design, tests, security, performance, and readability in that priority order.
+description: Conduct a thorough, structured code review of a local branch, grouped by task number (#NNN) referenced in commit messages. On non-trivial tasks, convenes a **per-task lens council** — parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests) — then an adversarial critique round that challenges each lens's blocking flags against context from the others, demoting false positives and surfacing contradictions for the user. Small tasks skip the council. Use this skill whenever the user asks to review a PR, asks for feedback on a diff or branch, mentions "review my changes", or pastes code asking what could be improved. Auto-detects all tasks on the branch and produces one verdict per task. Covers correctness, design, tests, security, performance, and readability in that priority order.
 ---
 
 # Pull Request Review
@@ -36,8 +36,10 @@ Review in this order — earlier categories matter more, and finding issues ther
 4. **For each task, read its intent first.** What is `#123` trying to accomplish? Infer from the commit subjects/bodies in that bucket. If intent is unclear, ask the user before reviewing — "is the code correct" is unanswerable without it.
 5. **Get the per-task diff.** For each task, view its commits with `git show <sha>` per commit, or `git diff <first>^..<last>` if the commits are contiguous. Don't merge tasks into one combined diff — keep them scoped.
 6. **Skim each task once, top to bottom.** Get a mental model of what changed before commenting on specifics.
-7. **Re-read each task with the priority list in mind.** Note issues as you go.
-8. **Look at the tests in each task.** Do they test the new behavior or just exercise the new lines?
+7. **Per-task decision: single-pass vs. lens council** (see [Lens council](#lens-council-for-non-trivial-tasks)):
+   - **Single-pass (inline)** when the task is small and tightly scoped — roughly: < 100 lines of task-scoped diff, < 5 files, no security-sensitive paths. Walk the priority list yourself.
+   - **Lens council** otherwise. Spawn parallel `Explore` sub-agents per lens, then run a critique round before the per-task verdict.
+8. **Look at the tests in each task.** Do they test the new behavior or just exercise the new lines? (The lens council's Tests agent handles this when convened.)
 9. **Check what's *not* in each task's diff.** Missing error handling, missing tests for edge cases, missing migration for a schema change.
 
 ## How to phrase feedback
@@ -85,6 +87,46 @@ Lead with the *why*, not just the *what*. "This will deadlock if two callers hit
 - Synchronous I/O in hot paths
 - Repeated work that could be hoisted out of a loop
 
+## Lens council (for non-trivial tasks)
+
+A single chain of reasoning across all priority categories anchors on whatever was seen first. For non-trivial tasks, run the lenses **in parallel** per task, then critique before the verdict.
+
+### When to convene the council (per task)
+
+- The task's diff is ≥ ~100 lines, **or** touches ≥ 5 files, **or** edits security-sensitive paths (auth, crypto, input validation, SQL/shell/HTML sinks, file paths from user input).
+- Or first-skim turned up contradictions you can't resolve from memory.
+
+Otherwise stay single-pass for that task. Some branches have one trivial task and one huge one — convene only for the huge one.
+
+### Lenses
+
+Spawn one sub-agent per lens for the task being reviewed. Default set:
+
+| Lens | Looks for |
+|---|---|
+| **Correctness** | Off-by-one, null/undefined at boundaries, concurrent-access bugs, swallowed exceptions, default-value behaviour shifts |
+| **Design** | New abstractions that don't earn their keep, tight coupling, duplication that should unify, public-API breakage, state in the wrong place |
+| **Security** | Untrusted input into sinks, secrets in code/logs/errors, missing authn/authz on new endpoints, weak/hand-rolled crypto |
+| **Tests** | Assertion-free / over-mocked tests, missing edge cases, flaky-by-design tests, new behaviour in the diff with **no** new test |
+
+Performance + Readability usually fold into Design — only spawn a dedicated lens for them if the task is genuinely perf-sensitive or the project has no linter.
+
+### How to run it (per task)
+
+1. **Spawn in parallel.** Send a **single message** with N `Agent` calls (`subagent_type=Explore`), one per lens. Each gets:
+   - The per-task diff (commits from this `#NNN` only — not the whole branch).
+   - The inferred task intent from step 4.
+   - **One** lens with its checklist verbatim from [What to look for](#what-to-look-for).
+   - Instructions: "Find issues only in your lens. Categorize each as `blocking` / `suggestion` / `question` / `nit`. Cite `file:line` for every finding. Lead each with the *why*. If no findings, say 'no findings' explicitly. Report in ≤500 words."
+2. **Critique round.** Read all lenses side by side, then:
+   - **Challenge every `blocking`** against context from the other lenses. Demote to `suggestion` or drop if it's defused by another lens's evidence.
+   - **Surface contradictions** as `question` items the user adjudicates (e.g. Correctness flags missing null guard; Security found the caller validates).
+   - **Merge near-duplicates** across lenses.
+   - **Promote** any finding multiple lenses raised independently — that's a real signal.
+3. **Verdict.** With the surviving findings, decide: Approve / Approve with suggestions / Request changes / Comment.
+
+Each task gets its own council pass. Tasks remain independent — the council scope **never** crosses task boundaries.
+
 ## Output format
 
 Produce one section per task, with comments grouped by file and line inside each. Each task gets its own verdict — tasks are independent units of work and should be approvable or blockable on their own.
@@ -130,3 +172,8 @@ End with a one-line roll-up: e.g. `Overall: 2 approve, 1 request changes, 1 unsc
 - ❌ "I would have done it differently" without a concrete reason
 - ❌ Collapsing multiple tasks into one verdict — each `#NNN` is independent and should stand or fall on its own
 - ❌ Silently ignoring commits with no task reference — surface them in the `unscoped` bucket
+- ❌ Convening the lens council on a 20-line task. Single-pass it.
+- ❌ Spawning lens agents serially instead of in parallel — one message, N agents, per task.
+- ❌ Letting the council span tasks. Each `#NNN` is its own review — sub-agents see only that task's diff.
+- ❌ Publishing the raw union of lens findings without the critique round. False-positive blockers erode trust.
+- ❌ Dumping per-agent transcripts into the user's report. The council is internal deliberation — the user sees the synthesized per-task verdict.

package/skills/tauri-2-app/SKILL.md

@@ -191,6 +191,7 @@ Full templates are in [`references/templates/`](references/templates/). The full
 - **`tauri.conf.json` `windows[].devtools: false`** (or omitted — Tauri defaults to off in release). DevTools should be opened from a build-time feature flag, not the production config.
 - **Reset-state-on-startup pattern** — in `pub fn run()`'s `.setup(|app| { ... })`, clear any in-progress / stuck state from a previous run before showing the window. Crashes leave globals in odd places; treat each startup as recovering from "the app was force-quit".
 - **Show window FIRST in `.setup()`** before any blocking initialization. Heavy work (ML model loading, large config parses) goes on a background thread that emits events back to the frontend.
+- **Minimal comments in generated code (Rust and TS).** Default to no comments. Only add one when the *why* is non-obvious — `// SAFETY:` on an `unsafe` block, a workaround for a specific upstream bug (with a link), a non-trivial invariant the code depends on, a platform quirk that isn't visible from the names. Never write Rust doc-comment blocks (`///`) on internal items; reserve them for genuinely public API surface (`pub` types crossing crate boundaries). Never restate *what* the next line does, never leave `// TODO` without an issue link. One short line max — no multi-line comment blocks. `// SAFETY:` on `unsafe` is the one place verbose justification is *required*; everywhere else, well-named identifiers carry the *what* and comments earn their place only when they carry *why*.
 
 ### Eliminate (anti-patterns)