opencastle 0.8.2 → 0.9.1

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -58,17 +58,11 @@ Load relevant skills before writing code.
 
 ### Actions
 
-1. **Run the Pre-Response Quality Gate** — This is the single exit gate. Verify ALL items from the checklist in `general.instructions.md` § Pre-Response Quality Gate:
-   - [ ] Lessons read at session start
-   - [ ] Lessons captured for any retries
-   - [ ] Discovered issues tracked (not ignored)
-   - [ ] Lint/type/test pass (no new errors)
-   - [ ] Session logged to `sessions.ndjson` (ALWAYS)
-   - [ ] Delegations logged (Team Lead only)
-   - [ ] Reviews/panels/disputes logged (if applicable)
-2. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.github/customizations/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
-3. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
-4. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
+1. **Call Session Guard** (Team Lead only) — Delegate to the **Session Guard** agent with a session summary (delegations, retries, discoveries, files changed). Execute any fix commands it returns. This replaces the manual Pre-Response Quality Gate checklist — the guard runs it automatically with a fresh context window.
+2. **For specialist agents** (not Team Lead) — Run the Pre-Response Quality Gate checklist from `general.instructions.md` manually. Specialist agents don't have access to the Session Guard.
+3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.github/customizations/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
+4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
+5. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
 
 ### Template for Delegation Prompts
 
@@ -80,6 +74,8 @@ Load relevant skills before writing code.
 - Clean up temp files
 ```
 
+> **Note for Team Lead:** You do NOT use this template yourself. Instead, call the **Session Guard** agent (step 10 in your role). This template is only for specialist agents you delegate to.
+
 ---
 
 ## Hook: on-pre-delegate
@@ -115,8 +111,12 @@ Pre-Delegate:
 
 ### Actions
 
-0. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). Only after the fast review passes do you proceed to the remaining post-delegate actions below.
-1. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
+0. **Log the delegation NOW** — Append a record to `.github/customizations/logs/delegations.ndjson` immediately. Do this BEFORE review or verification — logging must not depend on review passing.
+   ```bash
+   echo '{"timestamp":"...","session_id":"<branch>","agent":"...","model":"...","tier":"...","mechanism":"sub-agent","outcome":"...","retries":0,"phase":N,"file_partition":["..."]}' >> .github/customizations/logs/delegations.ndjson
+   ```
+1. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). Only after the fast review passes do you proceed to the remaining post-delegate actions below.
+2. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
 2. **Run verification** — Execute appropriate checks: lint, type-check, tests, or visual inspection.
 3. **Check acceptance criteria** — Compare output against the tracker issue's acceptance criteria. Each criterion must be independently verified.
 4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new tracker ticket.
@@ -127,6 +127,7 @@ Pre-Delegate:
 
 ```
 Post-Delegate:
+☐ Delegation logged to delegations.ndjson (FIRST — before anything else)
 ☐ Changed files reviewed
 ☐ Files within partition
 ☐ Lint/test/build passes

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: decomposition
+description: "Task decomposition patterns for the Team Lead: dependency resolution, phase assignment, delegation spec templates, prompt quality examples, and orchestration patterns."
+---
+
+# Task Decomposition
+
+Detailed decomposition and delegation patterns for the Team Lead. **Load at:** Decompose & Partition phase (Step 2) or when writing delegation prompts (Step 3).
+
+## Dependency Resolution
+
+Declare dependencies between subtasks using arrow notation: `TaskB → TaskA` means B depends on A (A must finish first).
+
+**Topological sort rules:**
+1. Tasks with no dependencies go in Phase 1 (can run in parallel)
+2. Tasks depending only on Phase 1 tasks go in Phase 2
+3. Continue until all tasks are assigned to phases
+4. Tasks in the same phase with no mutual dependencies run in parallel
+
+**Cycle detection:** If A → B → C → A, break the cycle by: (a) finding a task that can partially complete independently, (b) splitting that task into an independent part and a dependent part.
+
+**Visual example:**
+
+```
+Dependency Graph:        Execution Plan:
+E → C → A               Phase 1: A, B (parallel)
+D → B                   Phase 2: C, D (parallel, depend on Phase 1)
+F → C, D                Phase 3: E, F (parallel, depend on Phase 2)
+```
+
+Always draw the dependency graph before assigning phases. Missed dependencies cause agents to block on missing inputs; redundant sequencing wastes time.
+
+## Delegation Spec Template
+
+For complex tasks (score 5+), generate a structured spec rather than a free-form prompt:
+
+```
+## Delegation Spec: [Task Title]
+
+**Tracker Issue:** TAS-XX — [Title]
+**Complexity:** [score]/13 → [tier] tier
+**Agent:** [Agent Name]
+
+### Objective
+What to build/change and why. 1-3 sentences max.
+
+### Context
+- Key files to read first: [list]
+- Related patterns to follow: [file:line references]
+- Relevant lessons: [LES-XXX references from LESSONS-LEARNED.md]
+
+### Constraints
+- File partition: Only modify files under [paths]
+- Do NOT modify: [explicit exclusions]
+- Dependencies: Requires [TAS-XX] to be Done first
+
+### Acceptance Criteria
+- [ ] Criterion 1 (copied from tracker issue)
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+### Expected Output
+Return a structured summary with:
+- Files changed (path + one-line description)
+- Verification results (lint/test/build pass/fail)
+- Acceptance criteria status (each item ✅/❌)
+- Discovered issues (if any)
+- Lessons applied or added
+
+**Note:** Follow the Structured Output Contract from the team-lead-reference skill. Include all standard fields plus agent-specific extensions.
+
+### Self-Improvement
+Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, immediately add a lesson to that file.
+```
+
+For simpler tasks (score 1-3), the existing prompt format (objective + files + criteria) is sufficient. Don't over-engineer delegation for trivial work.
+
+**For sub-agents** — also specify what information to return in the result message.
+
+**For background agents** — include full self-contained context since they cannot ask follow-up questions.
+
+## Prompt Quality Examples
+
+**Strong prompt (simple task, score 2):**
+> "**Tracker issue:** TAS-42 — [Auth] Fix token refresh logic
+> Users report 'Invalid token' errors after 30 minutes. JWT tokens are configured with 1-hour expiration in `libs/auth/src/server.ts`. Investigate why tokens expire early and fix the refresh logic. Only modify files under `libs/auth/`. Run the auth library tests to verify."
+
+**Strong prompt (complex task, score 8):**
+> Use the Delegation Spec Template above. Fill in all sections for tasks scoring 5+.
+
+**Weak prompt:**
+> "Fix the authentication bug."
+
+## Delegation Mechanism Selection
+
+```
+                         Need result immediately?
+                        /                        \
+                      YES                         NO
+                       |                           |
+              Is it a dependency              Expected duration
+              for the next step?              > 5 minutes?
+                /           \                  /          \
+              YES            NO              YES           NO
+               |              |               |             |
+          Sub-Agent      Sub-Agent       Background     Sub-Agent
+          (inline)    (if small enough,   Agent        (sequential)
+                       else Background)
+```
+
+## Mixed Delegation Orchestration
+
+Combine sub-agents and background agents for maximum efficiency:
+
+```
+Phase 1 (sub-agent):     Research — gather context, identify patterns, map files
+Phase 2 (background):    Foundation — DB migration + Component scaffolding (parallel)
+Phase 3 (sub-agent):     Integration — wire components to data (needs Phase 2 results)
+Phase 4 (background):    Validation — Security audit + Tests + Docs (parallel)
+Phase 5 (sub-agent):     QA gate — verify all phases, run builds, self-review
+Phase 6 (sub-agent):     Panel review — load panel-majority-vote skill for high-stakes validation
+```

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -19,6 +19,119 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Use short cache durations for frequently changing assets (e.g., favicon: `max-age=86400`)
 - Load the **security-hardening** skill for full header inventory and CSP configuration
 
+## Environment Variable Management
+
+### Layering & Precedence
+
+Environment variables follow a layered override model (lowest to highest priority):
+
+1. `.env` — shared defaults, committed to repo (no secrets)
+2. `.env.local` — developer-specific overrides, git-ignored
+3. `.env.production` / `.env.preview` — environment-specific values
+4. Platform-injected variables — set in hosting dashboard, highest priority
+
+### Validation at Startup
+
+Validate required variables at application startup. Fail fast with clear messages:
+
+```typescript
+// src/lib/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(32),
+  PUBLIC_SITE_URL: z.string().url(),
+  CRON_SECRET: z.string().min(16),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+### Naming & .gitignore
+
+- `PUBLIC_*` or `NEXT_PUBLIC_*` — safe to expose to the browser
+- `SECRET_*` or `*_SECRET` — server-only, never bundled into client code
+- `CRON_SECRET` — authenticates scheduled job endpoints
+- Use `SCREAMING_SNAKE_CASE` for all variable names
+- Always gitignore `.env.local`, `.env.*.local`, and `.env.production`
+
+## CI/CD Pipeline Patterns
+
+### Branch-Based Deployment
+
+```
+main branch    → Production deployment (auto)
+feature/*      → Preview deployment (auto)
+fix/*          → Preview deployment (auto)
+```
+
+### Generic Pipeline Stages
+
+Every pipeline should include these stages in order:
+
+1. **Install** — restore dependencies from lockfile (`--frozen-lockfile`)
+2. **Lint** — static analysis and formatting checks
+3. **Test** — unit and integration tests with coverage
+4. **Build** — production build (catches type errors and build-time issues)
+5. **Deploy** — push artifacts to hosting platform
+
+### Cron Job Authentication
+
+Protect scheduled endpoints with a shared secret:
+
+```typescript
+// app/api/cron/route.ts
+export async function GET(request: Request) {
+  const authHeader = request.headers.get('authorization');
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  // ... run scheduled task
+  return Response.json({ ok: true });
+}
+```
+
+## Caching Strategy
+
+### Cache Duration Reference
+
+| Asset Type | `Cache-Control` Header | Rationale |
+|---|---|---|
+| Hashed static assets (JS, CSS) | `public, max-age=31536000, immutable` | Content-addressed filenames; safe to cache forever |
+| Images / fonts | `public, max-age=31536000, immutable` | Typically fingerprinted; long-lived |
+| Favicon / manifest | `public, max-age=86400` | Changes rarely but should refresh within a day |
+| HTML pages (SSG) | `public, max-age=0, must-revalidate` | Serve stale while revalidating |
+| API responses | `private, no-cache` | User-specific or frequently changing |
+| Prerendered pages (ISR) | `public, s-maxage=3600, stale-while-revalidate=86400` | CDN caches for 1 hour, serves stale for up to 1 day |
+
+Apply cache headers via framework config (e.g., `headers()` in `next.config.js`) or CDN rules. Match each route pattern to the appropriate duration from the table above.
+
+## Security Headers
+
+Apply these headers globally via framework config or middleware. See the **security-hardening** skill for full CSP configuration.
+
+```javascript
+// Recommended security headers
+const securityHeaders = [
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-XSS-Protection', value: '1; mode=block' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Content-Security-Policy', value: "default-src 'self'; script-src 'self' 'unsafe-inline';" },
+];
+```
+
+**Key rules:**
+
+- HSTS `max-age` must be at least 1 year (31536000 seconds) for preload eligibility
+- `X-Frame-Options: DENY` prevents clickjacking — use `SAMEORIGIN` only if you embed your own pages
+- CSP should be as restrictive as possible; expand only when needed, document each exception
+- Disable unused browser features via `Permissions-Policy`
+
 ## Release Process
 
 ### 1. Pre-Release Audit
@@ -31,7 +144,7 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Identify features adjacent to changes and spot-check them
 - Run full test suites for all affected projects (not just changed files)
 - Check deployment preview builds for visual regressions
-- Verify critical user flows still work (homepage, search, venue detail)
+- Verify critical user flows still work (e.g., primary navigation, form submissions, authenticated pages)
 
 ### 3. Changelog & Release Notes
 - Generate changelog from commit messages and PR titles since last release
@@ -48,4 +161,32 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Confirm deployment succeeded on production
 - Smoke-test production URLs for critical pages
 - Monitor error rates and performance metrics post-release
-- Document rollback steps if issues arise
+- Have rollback steps documented and ready (see § Rollback Procedures)
+
+## Rollback Procedures
+
+**Two rollback strategies** (prefer platform-level when available):
+
+1. **Platform rollback** — promote the last known-good deployment from the hosting dashboard
+2. **Git revert** — `git revert -m 1 HEAD && git push origin main` (triggers a clean redeploy)
+
+### Rollback Checklist
+
+- [ ] Confirm the issue is deployment-related (not a data or third-party issue)
+- [ ] Roll back via platform or git revert — never force-push to `main`
+- [ ] Verify the rollback deployment is healthy (smoke tests)
+- [ ] Notify the team with a summary of what was rolled back and why
+- [ ] Create a post-mortem ticket to investigate root cause
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|---|---|---|
+| Hardcoding secrets in source code | Secrets leak via git history, logs, and client bundles | Use environment variables; validate with Zod at startup |
+| Skipping preview deployments | Bugs reach production without visual review | Deploy every branch to a preview environment |
+| Using `Cache-Control: no-store` everywhere | Destroys performance; every request hits origin | Use appropriate cache durations per asset type (see table above) |
+| Force-pushing to `main` to "fix" a bad deploy | Destroys git history; breaks other developers' branches | Use `git revert` to cleanly undo changes |
+| Disabling security headers "temporarily" | Temporary becomes permanent; opens attack surface | Keep headers strict; expand only with documented exceptions |
+| Running builds without `--frozen-lockfile` | Non-deterministic installs; works locally, fails in CI | Always use `--frozen-lockfile` (or equivalent) in CI |
+| Storing `.env.local` in the repository | Developer secrets and tokens leak to all contributors | Add `.env.local` to `.gitignore`; share via secure vault |
+| No startup validation of env vars | App starts but crashes later with cryptic errors | Validate all required variables at boot (fail fast) |

package/src/orchestrator/skills/documentation-standards/SKILL.md

@@ -38,11 +38,9 @@ Generic documentation templates and writing standards. For project-specific dire
 ## Roadmap Update Template
 
 When a feature is completed:
-1. Change status to `COMPLETE`
-2. Add completion date
-3. List modified files
-4. Update the summary table at the top
-5. Move to completed section if applicable
+1. Change status to `COMPLETE` and add completion date
+2. List modified files and update the summary table
+3. Move to completed section if applicable
 
 ## Architecture Decision Record Template
 
@@ -57,16 +55,107 @@ When a feature is completed:
 **Alternatives Considered:** [What else was evaluated]
 ```
 
+## README Template
+
+Use this structure for library or feature-level READMEs:
+
+```markdown
+# Feature / Library Name
+
+One-sentence summary of what this does and why it exists.
+
+## Quick Start
+
+Brief usage example or setup steps.
+
+## Architecture
+
+High-level overview. Include a Mermaid diagram for non-trivial systems.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/handler.ts` | Request handling logic |
+| `src/schema.ts` | Validation schemas |
+```
+
+## Mermaid Diagram Patterns
+
+Keep diagrams focused — one concern per diagram.
+### Flowchart (decision logic, pipelines)
+
+```mermaid
+flowchart TD
+  A[Receive Request] --> B{Authenticated?}
+  B -- Yes --> C[Process Request]
+  B -- No --> D[Return 401]
+  C --> E{Valid Input?}
+  E -- Yes --> F[Execute Action]
+  E -- No --> G[Return 400]
+```
+
+### Sequence Diagram (API flows, multi-service interactions)
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant API
+  participant DB
+  Client->>API: POST /resource
+  API->>DB: INSERT record
+  DB-->>API: OK
+  API-->>Client: 201 Created
+```
+
+### ER Diagram (data models, relationships)
+
+```mermaid
+erDiagram
+  USER ||--o{ ORDER : places
+  ORDER ||--|{ LINE_ITEM : contains
+  USER { string id PK; string email }
+  ORDER { string id PK; date created_at }
+```
+
+### Diagram Guidelines
+
+- Add a title comment (`%% Title: ...`) at the top of complex diagrams
+- Use verb labels on relationship arrows
+- Limit nodes to 10–12 per diagram; split larger systems into sub-diagrams
+- Prefer `flowchart TD` (top-down) for pipelines and `flowchart LR` (left-right) for request flows
+
+## Changelog Entry Template
+
+Follow Conventional Commits format. Group entries by type under a version heading:
+
+```markdown
+## [1.2.0] — YYYY-MM-DD
+
+### Added
+- feat: Add retry logic to API client (#123)
+
+### Fixed
+- fix: Resolve race condition in queue processor (#127)
+
+### Changed
+- refactor: Extract validation into shared module (#125)
+```
+
+### Changelog Rules
+
+- One line per change; reference the PR or issue number
+- Use imperative mood: "Add", "Fix", "Remove" — not "Added", "Fixed"
+- Group under `Added`, `Fixed`, `Changed`, `Removed`, `Deprecated`, `Security`
+- Most recent version at the top
+
 ## Writing Guidelines
 
 - Write clear, concise prose — avoid jargon unless necessary
-- Include diagrams (Mermaid or ASCII) for architecture
-- Link to related files and docs using relative paths
-- Keep line length under 400 characters; break at 80 for readability
-- Use tables for structured data
-- Include "Last Updated" dates on all documents
-- Archive outdated docs rather than deleting
-- Cross-reference between documents when relevant
+- Include Mermaid diagrams for architecture
+- Link to related files using relative paths
+- Use tables for structured data; include "Last Updated" dates on all documents
+- Archive outdated docs rather than deleting; cross-reference between documents
 
 ### Formatting Rules
 
@@ -85,3 +174,27 @@ Include YAML front matter at the beginning of instruction/skill files:
 - `title` / `name`: The title of the document
 - `description`: A brief description of the document content
 - `applyTo`: (for instruction files) Glob pattern for which files the instructions apply to
+
+## Documentation Review Checklist
+
+Before merging docs, verify:
+
+- [ ] **Accuracy** — all code snippets, file paths, and commands are correct and tested
+- [ ] **Completeness** — no TODO placeholders or empty sections remain
+- [ ] **Links** — all internal and external links resolve (no 404s)
+- [ ] **Front matter** — YAML front matter is present and valid
+- [ ] **Formatting** — consistent heading levels, list style, whitespace, and Mermaid renders
+- [ ] **Cross-references** — related docs link to each other; "Last Updated" is current
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Do This Instead |
+|-------------|-------------|-----------------|
+| Wall of text with no headings | Unnavigable; readers skip it | Break into sections with H2/H3 |
+| Duplicating content across files | Copies drift; causes confusion | Link to a single source of truth |
+| Screenshots without alt text | Inaccessible; breaks when UI changes | Use Mermaid diagrams or describe the UI |
+| Documenting implementation details | Becomes stale as code changes | Document intent and contracts |
+| Using absolute file paths | Breaks on other machines | Use relative paths from doc location |
+| Huge monolithic README | Low signal-to-noise | Split into focused docs, link from README |
+| Undated documents | No way to judge currency | Always include "Last Updated" date |
+| Using H1 inside document body | Conflicts with auto-generated title | Start body headings at H2 |

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -41,4 +41,155 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo
 
 **IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
 
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+## Design System Foundations
+
+Every design starts with a token layer. Define CSS custom properties that encode the aesthetic direction — never scatter raw values through stylesheets. A well-structured variable system makes the entire interface feel cohesive even as complexity grows.
+
+```css
+/* --- Palette: warm editorial with a punch of citron --- */
+:root {
+  --color-ink:        #1a1614;
+  --color-paper:      #f5f0e8;
+  --color-accent:     #c8e630;        /* citron — the memorable detail */
+  --color-muted:      #9b9083;
+  --color-surface:    #eae3d8;
+  --color-border:     rgba(26, 22, 20, 0.08);
+
+  /* Typography scale — modular ratio 1.25 (Major Third) */
+  --text-sm:   clamp(0.875rem, 0.83rem + 0.22vw, 1rem);
+  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
+  --text-xl:   clamp(1.563rem, 1.35rem + 1.06vw, 2rem);
+  --text-2xl:  clamp(1.953rem, 1.6rem + 1.77vw, 2.75rem);
+  --text-hero: clamp(2.441rem, 1.8rem + 3.2vw, 4.5rem);
+
+  /* Spacing — 4px base, geometric progression */
+  --space-2: 0.5rem;  --space-4: 1rem;
+  --space-6: 1.5rem;  --space-8: 2rem;
+  --space-16: 4rem;   --space-32: 8rem;
+
+  /* Motion — intentional easing curves, not defaults */
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out-back: cubic-bezier(0.68, -0.6, 0.32, 1.6);
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --duration-slow: 600ms;
+
+  /* Elevation */
+  --shadow-md: 0 4px 16px rgba(26, 22, 20, 0.08);
+  --shadow-lg: 0 12px 48px rgba(26, 22, 20, 0.12);
+}
+```
+
+**Anti-pattern:** Never scatter raw hex/px values through stylesheets. Every value should trace back to a token. Change the palette once and the entire interface follows.
+
+## Component Patterns
+
+### Distinctive Card
+
+A card should never look like a Bootstrap default. Give it tension — an unexpected border treatment, an oversized label, or a hover that reveals hidden depth.
+
+```css
+.card {
+  position: relative;
+  background: var(--color-paper);
+  border: 1px solid var(--color-border);
+  border-left: 4px solid var(--color-accent);
+  padding: var(--space-8) var(--space-6);
+  transition: transform var(--duration-normal) var(--ease-out-expo),
+              box-shadow var(--duration-normal) var(--ease-out-expo);
+}
+
+.card:hover {
+  transform: translateY(-3px);
+  box-shadow: var(--shadow-lg);
+}
+
+.card__label {
+  position: absolute;
+  top: calc(-1 * var(--space-3));
+  left: var(--space-4);
+  background: var(--color-accent);
+  color: var(--color-ink);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  padding: var(--space-1) var(--space-3);
+}
+```
+
+### Hero Section with Staggered Reveal
+
+Orchestrate entrance animations with `animation-delay` for a cinematic first impression. One coordinated sequence beats a dozen scattered `fadeIn`s.
+
+```css
+@keyframes rise {
+  from { opacity: 0; transform: translateY(24px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.hero              { overflow: hidden; padding: var(--space-32) var(--space-8); }
+.hero__eyebrow     { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 100ms; }
+.hero__headline    { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 250ms; }
+.hero__body        { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 400ms; }
+.hero__cta         { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 550ms; }
+```
+
+**Anti-pattern:** Don't animate everything. If the nav bounces, the sidebar slides, and the footer pulses — it's visual noise, not design. Motion has a narrative: one orchestrated entrance, then stillness.
+
+## Typography Pairing Examples
+
+Never reach for the same font twice. Each project deserves a pairing chosen for its specific character. These are starting points — not a rotation list.
+
+| Aesthetic | Display | Body | Mood |
+|-----------|---------|------|------|
+| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich serif contrast |
+| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp, high-contrast grotesque |
+| Warm humanist | Fraunces | Nunito Sans | Friendly optical sizes, approachable |
+| Brutalist edge | Monument Extended | JetBrains Mono | Wide + monospace = raw technical power |
+| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic sensibility |
+| Retro-futuristic | Syne | Outfit | Geometric boldness meets clean body |
+
+Always include a fallback chain that preserves metrics: `'Fraunces', 'Georgia', serif` not just `'Fraunces', serif`. And never default to the same "safe" choices (Inter, Roboto, system-ui) — if every project looks the same, the typography isn't doing its job.
+
+## Design Quality Checklist
+
+Run this checklist before delivering any frontend work. Every item is a gate — if something fails, the design isn't finished.
+
+### Identity & Cohesion
+- [ ] Can you name the aesthetic direction in 2-3 words? (e.g., "warm editorial," "cold brutalist")
+- [ ] Are color, typography, spacing, and motion all telling the same visual story?
+- [ ] Is there at least one memorable detail — something unexpected that delights?
+
+### Typography
+- [ ] Display and body fonts are distinct and intentionally paired
+- [ ] Type scale uses `clamp()` for fluid responsive sizing — no fixed `px` breakpoints
+- [ ] Line heights are tuned: ~1.1–1.2 for headings, ~1.5–1.7 for body
+- [ ] Letter-spacing is adjusted for uppercase text and small sizes
+
+### Color & Contrast
+- [ ] Palette is defined as CSS custom properties — no raw hex in component styles
+- [ ] There is a clear dominant/accent hierarchy — not five competing colors
+- [ ] Text passes WCAG AA contrast minimums (4.5:1 body, 3:1 large text)
+- [ ] Dark/light theme (if applicable) is not just color inversion — both feel intentional
+
+### Layout & Spacing
+- [ ] Spacing flows from a consistent scale — no random `margin: 37px`
+- [ ] At least one layout choice breaks the expected grid — overlap, bleed, asymmetry
+- [ ] Component padding and gaps use spacing tokens, not ad-hoc values
+- [ ] The design holds at mobile, tablet, and desktop without layout collapse
+
+### Motion & Interaction
+- [ ] Page entrance has a coordinated animation sequence (staggered reveals)
+- [ ] Hover/focus states exist for all interactive elements
+- [ ] Animations use custom easing curves — never `linear` or bare `ease`
+- [ ] Motion serves narrative purpose — no decoration-only animation
+- [ ] `prefers-reduced-motion` is respected with a `@media` query fallback
+
+### Production Readiness
+- [ ] No hardcoded widths that break at unexpected viewports
+- [ ] Images and decorative elements have proper `alt` text or `aria-hidden`
+- [ ] Focus indicators are visible and styled to match the aesthetic
+- [ ] Performance: no layout thrashing from scroll-triggered animations without `will-change`