Docs â€ē Reference â€ē Pattern Library
🧩 Reference

Pattern Library

The Pattern Library is the pipeline's compounding knowledge base. Solutions to non-obvious implementation problems — auth quirks, database race conditions, platform workarounds — are stored as PATTERN-NNN entries and applied automatically on every future project that matches the same stack. You never need to ask the pipeline to use a pattern — it does so on its own.

✅
Lookup and reuse are fully automatic

Agent 2 (Planner) queries PATTERN_INDEX.md at activation and records matched patterns in DECISIONS.md, applying them directly in planning. Agent 3 (Builder) queries before every architecture-class task and applies the match as implementation hypothesis 1. No command, no prompt — it just happens.

ℹī¸
Capture is human-triggered — intentionally

Adding a new pattern to the library requires !pattern-add. This is by design: the human decides what is worth preserving as institutional knowledge. Not every solved problem needs to become a pattern — only the ones with non-obvious pitfalls worth carrying forward.

How It Works

  1. 1
    Pattern is captured — human triggers once
    After completing a task with a non-obvious solution, issue !pattern-add. The Orchestrator prompts for domain, stack, and reuse signal keywords, then writes the full entry to PATTERN_LIBRARY.md and a one-line lookup to PATTERN_INDEX.md. This is the only step that requires a human action.
  2. 2
    Pattern is queried automatically — forever after
    On every subsequent project, Agent 2 (Planner) scans PATTERN_INDEX.md at activation against the project's stack keywords. Matched patterns are recorded in DECISIONS.md and incorporated into planning — no command required.
  3. 3
    Pattern is applied automatically — at the task level
    Agent 3 (Builder) queries PATTERN_INDEX.md before every architecture-class task (api, auth, data, infra). A matching pattern becomes implementation hypothesis 1 — the validated approach from a prior project, applied before any new code is written. No user command needed.

Pattern Entry Format

## PATTERN-001: NextAuth v5 + Prisma Database Sessions

**domain:** authentication
**stack:** next.js, next-auth v5, prisma, typescript
**context:** Any Next.js application that uses NextAuth v5 for authentication and stores sessions in a relational database.

**pattern:**
Use the Prisma adapter with database sessions (not JWT). JWT sessions break on server-side role checks because the JWT is only refreshed on sign-in. Database sessions allow real-time role lookups.

```typescript
// src/lib/auth.ts
import NextAuth from 'next-auth';
import { PrismaAdapter } from '@auth/prisma-adapter';
import { db } from './db';

export const { handlers, signIn, signOut, auth } = NextAuth({
  adapter: PrismaAdapter(db),
  session: { strategy: 'database' },
  // ...
});
```

**pitfall_avoided:** JWT strategy caches the user role at sign-in. If an admin downgrades a user's role, the user retains elevated permissions until their JWT expires (default 30 days).

**reuse_signal:** nextauth, next-auth, auth, authentication, prisma, session, role

**evidence:** nextjs-wellness-booking (TASK-001, 2025-05-15)

Pattern Index Format

PATTERN_INDEX.md is a compact keyword → PATTERN-NNN lookup table used by agents at startup:

| Keywords | Pattern |
|---|---|
| nextauth, next-auth, prisma, session, database-sessions | PATTERN-001 |
| env, environment, zod, validation, startup | PATTERN-002 |
| prisma, singleton, globalThis, hot-reload, dev-server | PATTERN-003 |
| sqlite, better-sqlite3, wal, tauri, desktop, local-db | PATTERN-004 |
| demucs, vram, oom, cuda, audio, ml, torch | PATTERN-005 |
| zustand, persist, localstorage, json-storage | PATTERN-006 |
ℹī¸
Pattern files persist across all projects

Both files live in the agents directory at artifacts/pipeline/PATTERN_LIBRARY.md and artifacts/pipeline/PATTERN_INDEX.md — not inside any individual project directory. Every project the pipeline touches contributes to and benefits from the same library.

Seed Patterns

The pipeline ships with 6 seed patterns pre-populated. These cover the most common cross-project problems.

IDDomainStackProblem solved
PATTERN-001 Authentication NextAuth v5 + Prisma JWT vs. database sessions: role changes don't propagate with JWT
PATTERN-002 Configuration Next.js + Zod Env validation at module load time — fail fast on missing secrets
PATTERN-003 Database Prisma + Next.js Prisma singleton via globalThis — prevents dev-server connection exhaustion
PATTERN-004 Database better-sqlite3 + Tauri WAL mode + user config dir placement for Tauri desktop apps
PATTERN-005 ML / Audio Demucs + PyTorch VRAM OOM fallback — segment halving then CPU fallback for audio separation
PATTERN-006 State Management Zustand Persist middleware with createJSONStorage(() => localStorage) for SSR safety

When to Capture a Pattern

A pattern is worth capturing when:

  • The solution is not obvious from the library documentation
  • The wrong approach causes a specific, non-obvious failure
  • The same problem is likely to appear in future projects on the same stack
  • The implementation involves a known gotcha (race condition, hot-reload issue, platform-specific quirk)

A pattern is not needed when:

  • The implementation follows standard library documentation exactly
  • The code is self-explanatory and there is no pitfall to avoid
  • The problem is project-specific and unlikely to recur
← Previous Command Reference