opencastle 0.32.4 → 0.32.6

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

@@ -3,150 +3,100 @@ name: agent-hooks
 description: "Lifecycle hooks for AI agent sessions — reusable actions that run at specific points (session start, session end, pre-delegation, post-delegation). Defines what to do at each lifecycle event so agents behave consistently."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Agent Lifecycle Hooks
 
-Hooks are **standardized actions** that agents execute at specific points during their lifecycle. They enforce consistency across sessions and prevent common oversights (missing lessons, forgotten checkpoints, untracked issues).
-
-## Hook Execution Model
-
-Hooks are **conventions, not automated triggers**. Agents must explicitly follow them. The Team Lead includes hook reminders in delegation prompts; specialist agents include them in their own workflow.
+Conventions (not auto-triggers) agents execute at specific lifecycle points. Team Lead includes hook reminders in delegation prompts; specialists follow them in their own workflow.
 
 ```
-Session Lifecycle:
-  on-session-start  →  [work loop]  →  on-session-end
-                          ↓   ↑
-                    on-pre-delegate → on-post-delegate
+on-session-start → [work loop] → on-session-end
+                        ↓   ↑
+               on-pre-delegate → on-post-delegate
 ```
 
 ---
 
-## Hook: on-session-start
-
-**When:** First action in any agent session (Team Lead or specialist).
-
-### Actions
-
-1. **Read lessons learned** — Scan `.opencastle/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
-2. **Check for checkpoint** — If `.opencastle/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
-3. **Check pending approvals** — If the checkpoint has a `## Pending Approvals` section, check for replies using the configured messaging provider's MCP tools (e.g., `conversations_replies` for Slack). Read `.opencastle.json` → `stack.teamTools` to determine the provider. If no messaging is configured, skip this step.
-4. **Check dead letter queue** — Scan `.opencastle/AGENT-FAILURES.md` for pending failures related to the current scope.
-5. **Validate skill-matrix bindings** — Open `.opencastle/agents/skill-matrix.json` and check whether the `bindings` object has any slots with non-empty `entries` arrays. If all entries are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
-6. **Check project context** — If `.opencastle/project.instructions.md` has only empty template rows (`| | | |`), warn the user that bootstrap hasn't populated project context.
-7. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
-
-### Template for Delegation Prompts
+## on-session-start — First action in any session
 
-Include this reminder in every delegation:
+| # | Action | Detail |
+|---|--------|--------|
+| 1 | Read lessons | Scan `.opencastle/LESSONS-LEARNED.md` for task-relevant entries. |
+| 2 | Check checkpoint | If `.opencastle/SESSION-CHECKPOINT.md` exists, resume from it. |
+| 3 | Check pending approvals | If checkpoint has `## Pending Approvals`, check replies via messaging provider (`stack.teamTools` in `.opencastle.json`). Skip if no messaging configured. |
+| 4 | Check DLQ | Scan `.opencastle/AGENT-FAILURES.md` for failures in current scope. |
+| 5 | Validate skill-matrix | Open `.opencastle/agents/skill-matrix.json` — if all `bindings` entries are empty, **warn** user to run *"Bootstrap Customizations"* prompt first. |
+| 6 | Check project context | If `.opencastle/project.instructions.md` has only empty template rows, warn bootstrap hasn't run. |
+| 7 | Load domain skills | Load appropriate skills before writing code. |
 
+**Delegation reminder:**
 ```
-**Session Start:** Read `.opencastle/LESSONS-LEARNED.md` before starting.
-Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals.
-If pending approvals exist, check for replies via the messaging provider.
-Validate `.opencastle/agents/skill-matrix.json` — warn if skill bindings are empty (bootstrap not run).
-Load relevant skills before writing code.
+Session Start: Read `.opencastle/LESSONS-LEARNED.md`. Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals. Validate `.opencastle/agents/skill-matrix.json` — warn if bindings empty. Load relevant skills before coding.
 ```
 
 ---
 
-## Hook: on-session-end
+## on-session-end — Before yielding control, every time unconditionally
 
-**When:** Before the agent yields control back to the user — every time, unconditionally.
+> **⛔ HARD GATE** — See [logging-mandatory](../../snippets/logging-mandatory.md). Run the Pre-Response Quality Gate from the **observability-logging** skill.
 
-> **⛔ HARD GATE — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill before responding.**
-> A session without log records is a failed session. A session without lessons captured after retries is a failed session.
-
-### Actions
-
-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 the **observability-logging** skill manually. Specialist agents don't have access to the Session Guard.
-3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.opencastle/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
+| # | Action | Who |
+|---|--------|-----|
+| 1 | Call Session Guard with session summary; execute fix commands it returns | Team Lead only |
+| 2 | Run Pre-Response Quality Gate checklist from **observability-logging** skill | Specialists only |
+| 3 | Write `.opencastle/SESSION-CHECKPOINT.md` if work is incomplete (load **session-checkpoints** skill) | Team Lead only |
+| 4 | Flag for memory merge if 5+ new lessons this session | All |
+| 5 | Remove temp files created during session | All |
 
+**Delegation reminder (specialists):**
 ```
-**Session End:** Run the Pre-Response Quality Gate from the **observability-logging** skill:
-- Log your session using the observability-logging skill's session record command (Constitution rule #6)
-- If you retried anything with a different approach that worked, use the **self-improvement** skill to add a lesson
-- Track any discovered issues in KNOWN-ISSUES.md or a tracker ticket
-- Clean up temp files
+Session End: Log session via observability-logging skill (Constitution rule #6). Add lesson via self-improvement if retried. Track discovered issues in KNOWN-ISSUES.md or tracker. 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
-
-**When:** Team Lead only — before every delegation (sub-agent or background agent).
-
-Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker issue exists, (2) File partition clean, (3) Dependencies verified Done, (4) Prompt has file paths + acceptance criteria, (5) Self-improvement reminder included. For complex tasks (5+ files), also generate a context map.
-
 ---
 
-## Hook: on-post-delegate
-
-**When:** Team Lead only — after receiving results from a delegated agent.
+## on-pre-delegate — Team Lead only, before every delegation
 
-### Actions
+Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker issue exists, (2) File partition clean, (3) Dependencies verified Done, (4) Prompt has file paths + acceptance criteria, (5) Self-improvement reminder included. For 5+ files, generate a context map.
 
-0. **Log the delegation (⛔ hard gate)** — Use the **observability-logging** skill's delegation record command. Do NOT proceed to review or any other action until the delegation is logged and verified.
-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). **Log the review (⛔ hard gate)** using the **observability-logging** skill's review record command immediately after — do NOT proceed until logged. Only after both the fast review passes and the review is logged 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.
-5. **Lessons captured** — If the agent retried anything, verify a lesson was added via the **self-improvement** skill.
-6. **Update tracker** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing). On 3rd failure → log to `.opencastle/AGENT-FAILURES.md` (DLQ format in file header).
-7. **Update agent expertise** — In `.opencastle/AGENT-EXPERTISE.md`: first-attempt success → add strong area; 2+ retries → add weak area. Update file familiarity with touched files.
-8. **Append knowledge graph** — Add file-to-file relationships the agent touched to `.opencastle/KNOWLEDGE-GRAPH.md` (one row per dependency discovered).
+## on-post-delegate — Team Lead only, after receiving delegation results
 
-### Quick Checklist
+| # | Action |
+|---|--------|
+| 0 | **⛔ Log delegation** via observability-logging skill — BLOCKING |
+| 1 | **Fast review (mandatory)** — run `fast-review` skill; **⛔ log review** — BLOCKING. Escalate to panel if needed; **⛔ log panel** — BLOCKING |
+| 2 | Read changed files; verify within file partition |
+| 3 | Run lint, type-check, tests |
+| 4 | Verify each acceptance criterion against tracker issue |
+| 5 | Confirm Discovered Issues Policy followed (KNOWN-ISSUES.md or tracker ticket) |
+| 6 | If agent retried, verify lesson added via **self-improvement** skill |
+| 7 | Move issue to Done or re-delegate; on 3rd failure → log to `.opencastle/AGENT-FAILURES.md` |
+| 8 | Update `.opencastle/AGENT-EXPERTISE.md` (strong/weak area + file familiarity) |
+| 9 | Append file relationships to `.opencastle/KNOWLEDGE-GRAPH.md` |
 
+**Quick checklist:**
 ```
-Post-Delegate:
-☐ ⛔ Delegation logged (observability-logging skill — verify with tail -1) — BLOCKING
-☐ Changed files reviewed
-☐ Files within partition
+☐ ⛔ Delegation logged (verify: tail -1 events.ndjson) — BLOCKING
+☐ Changed files reviewed; within partition
 ☐ Lint/test/build passes
-☐ Fast review PASS (mandatory — load fast-review skill)
-☐ ⛔ Review logged (observability-logging skill — verify with tail -1) — BLOCKING
-☐ ⛔ Panel logged if escalated (observability-logging skill — verify with tail -1) — BLOCKING
+☐ Fast review PASS; ⛔ Review logged — BLOCKING
+☐ ⛔ Panel logged if escalated — BLOCKING
 ☐ Acceptance criteria met
-☐ Discovered issues tracked (not ignored)
-☐ Lessons captured (if retries occurred)
+☐ Discovered issues tracked
+☐ Lessons captured (if retries)
 ☐ Issue updated
-☐ Agent expertise updated (AGENT-EXPERTISE.md — strong/weak area + file familiarity)
-☐ Knowledge graph appended (KNOWLEDGE-GRAPH.md — file relationships)
+☐ AGENT-EXPERTISE.md updated
+☐ KNOWLEDGE-GRAPH.md appended
 ```
 
 ---
 
-## Hook Integration
-
-### For Team Lead
-
-The on-pre-delegate and on-post-delegate hooks are already encoded in the Team Lead's orchestration workflow. Reference this skill to ensure consistency.
-
-### For Specialist Agents
-
-Include on-session-start and on-session-end actions in every delegation prompt. Use the templates above.
-
-### For Workflow Templates
-
-Each workflow's **Delivery phase** naturally serves as the on-session-end hook for that workflow type. The Delivery phase steps should include session logging, lesson verification, and memory merge checks.
-
----
-
 ## Anti-Patterns
 
-- **Skipping on-session-start** — Leads to repeated mistakes already documented in lessons learned
-- **Forgetting session logging** — Makes the observability dashboard empty and performance tracking impossible. This is the #1 most common failure.
-- **Treating logging as optional** — Every session gets logged. No threshold, no exceptions.
-- **Batch-logging retrospectively** — Log each task as it completes, not all at once at the end of a long conversation.
-- **Partial post-delegate checks** — "It compiled, ship it" without checking acceptance criteria
-- **No cleanup** — Temp files accumulate and confuse future sessions
-- **Hooks as blockers** — Hooks should add ~2 minutes overhead, not 20. If a hook takes too long, skip the optional parts
+| Anti-pattern | Why it matters |
+|---|---|
+| Skipping on-session-start | Repeated mistakes already in lessons learned |
+| Forgetting session logging | Observability dashboard empty; #1 most common failure |
+| Treating logging as optional | Every session logged — no threshold, no exceptions |
+| Batch-logging retrospectively | Log each task as it completes, not all at end |
+| Partial post-delegate checks | Must verify acceptance criteria, not just "it compiled" |
+| No cleanup | Temp files accumulate and confuse future sessions |
+| Hooks as blockers | Hooks add ~2 min overhead — skip optional parts if needed |

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

@@ -3,19 +3,11 @@ name: agent-memory
 description: "Agent expertise tracking and cross-session knowledge graph. Use when delegating tasks to track agent strengths/weaknesses, or when building context about file relationships and patterns."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Agent Memory Protocol
 
-## Purpose
-
-Track which agents have expertise with which files, patterns, and tools across sessions. This information helps the Team Lead make better delegation decisions by matching tasks to agents with proven track records.
-
 ## Expertise File
 
-Location: `.opencastle/AGENT-EXPERTISE.md` — a structured record of agent performance per domain.
-
-Template structure:
+**Location:** `.opencastle/AGENT-EXPERTISE.md`
 
 ```markdown
 # Agent Expertise Registry
@@ -24,123 +16,82 @@ Template structure:
 ### Strong Areas
 | Area | Evidence | Last Updated |
 |------|----------|-------------|
-| Feature implementation | Successfully built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
-| Server-side logic | Fixed auth flow (TAS-ZZ) | YYYY-MM-DD |
+| Feature implementation | Built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
 
 ### Weak Areas
 | Area | Evidence | Last Updated |
 |------|----------|-------------|
-| Styling approach | Required 2 retries on styling task (TAS-AA) | YYYY-MM-DD |
+| Styling | 2 retries on TAS-AA | YYYY-MM-DD |
 
 ### File Familiarity
-- `apps/web-app/places/` — 3 tasks completed
-- `libs/queries/src/lib/` — 2 tasks completed
+- `apps/web-app/places/` — 3 tasks
 ```
 
-## Memory Update Triggers
+## Update Triggers
 
 | Trigger | Action |
 |---------|--------|
-| Agent completes task successfully on first attempt | Add/update Strong Area entry |
-| Agent requires 2+ retries | Add/update Weak Area entry |
-| Agent modifies a file | Update File Familiarity count |
-| Agent fails a task entirely (DLQ) | Add Weak Area with failure reference |
-| >3 months since last update in an area | Mark as "stale" — needs re-evaluation |
-
-## Memory Retrieval Protocol
-
-1. Before delegating, check `.opencastle/AGENT-EXPERTISE.md` for the candidate agent
-2. If the task matches a Strong Area, include in the prompt: *"You have prior experience with [area] from [TAS-XX]. Apply the same patterns."*
-3. If the task matches a Weak Area, either: (a) add extra context to the prompt to compensate, or (b) consider a different agent
-4. If the file has high familiarity, mention it: *"You've worked on [file] before in [TAS-XX]."*
-
-## Memory Pruning Rules
-
-- Remove entries older than 6 months without recent updates
-- Consolidate similar entries (e.g., 5 "App Router pages" entries → 1 entry with count)
-- Remove File Familiarity entries for files that no longer exist
-- The Team Lead should prune at the start of major feature work (not every session)
+| First-attempt success | Add/update Strong Area |
+| 2+ retries | Add/update Weak Area |
+| File modified | Increment File Familiarity |
+| DLQ failure | Add Weak Area with ref |
+| >3 months stale | Mark as "stale" |
 
-## Integration with Delegation
+## Retrieval & Delegation
 
-Add relevant expertise context to delegation prompts. Example addition:
+Check `.opencastle/AGENT-EXPERTISE.md` before delegating. Add to prompt:
 
 ```
-### Agent Context (from expertise registry)
-- Strong: Server Components, CMS queries (3 successful tasks)
-- Weak: Component styling (1 retry on TAS-AA)
-- Familiar files: libs/queries/src/lib/search/ (2 tasks)
+### Agent Context
+- Strong: Server Components, CMS queries (3 tasks)  → "Prior experience from TAS-XX."
+- Weak: Component styling (retry TAS-AA)            → add context or reassign
+- Familiar: libs/queries/src/lib/search/ (2 tasks)  → "You've worked on [file] in TAS-XX."
 ```
 
-## Cross-Session Knowledge Graph
+## Pruning
 
-### Purpose
+- Remove entries >6 months old; consolidate repetitive entries; remove familiarity for deleted files
+- Prune at start of major feature work
 
-Capture structured relationships between concepts, files, agents, and decisions. Goes beyond flat lesson lists to show how pieces of the system connect.
+## Knowledge Graph
 
-### Entity Types
+**Location:** `.opencastle/KNOWLEDGE-GRAPH.md` (append-only)
 
-| Entity Type | Examples | Notation |
-|-------------|----------|----------|
-| `File` | `libs/queries/src/lib/search/searchModule.ts` | `F:path` |
-| `Agent` | Developer, Security Expert | `A:name` |
-| `Pattern` | Server Component data fetching, RLS policy structure | `P:name` |
-| `Decision` | "Use Jotai over Redux" (from DECISIONS.md) | `D:name` |
-| `Bug` | Known issue KI-XXX | `B:id` |
-| `Lesson` | LES-XXX from LESSONS-LEARNED.md | `L:id` |
+### Entities & Relationships
 
-### Relationship Types
+| Entity | Notation | Relationships |
+|--------|----------|--------------|
+| File | `F:path` | `depends-on`, `blocks` |
+| Agent | `A:name` | `expert-in` |
+| Pattern/Decision | `P:name` / `D:name` | `related-to`, `obsoletes` |
+| Bug/Lesson | `B:id` / `L:id` | `caused-by`, `related-to` |
 
-| Relationship | Meaning | Example |
-|-------------|---------|---------|
-| `depends-on` | X requires Y to function | `F:places/page.tsx depends-on F:searchModule.ts` |
-| `caused-by` | X was caused by Y | `B:KI-042 caused-by D:use-server-components` |
-| `expert-in` | Agent X has expertise in Y | `A:Content Engineer expert-in P:CMS-queries` |
-| `related-to` | Loose conceptual connection | `L:LES-15 related-to P:RLS-policies` |
-| `obsoletes` | X replaces/supersedes Y | `D:use-app-router obsoletes D:use-pages-router` |
-| `blocks` | X prevents Y from working | `B:KI-099 blocks F:auth/middleware.ts` |
-
-### Knowledge Graph File
-
-Location: `.opencastle/KNOWLEDGE-GRAPH.md` — an append-only relationship log.
-
-Template structure:
+### Graph Template
 
 ```markdown
 # Knowledge Graph
-
 ## Relationships
-
 | Source | Relationship | Target | Added | Context |
 |--------|-------------|--------|-------|---------|
-| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | Completed 3 CMS query tasks |
-| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | Search uses CMS client |
-| L:LES-15 | related-to | P:cookie-sessions | 2026-02-23 | Lesson about auth token format |
+| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | 3 tasks |
+| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | |
 ```
 
-### When to Add Relationships
-
-| Trigger | What to Record |
-|---------|---------------|
-| Agent completes a task touching multiple files | `depends-on` between the files |
-| A lesson is added that relates to a pattern | `related-to` between lesson and pattern |
-| An agent demonstrates expertise | `expert-in` between agent and domain |
-| A decision causes a known issue | `caused-by` between bug and decision |
-| A new pattern supersedes an old approach | `obsoletes` between decisions/patterns |
+### Add Relationships When
 
-### Query Patterns
+| Trigger | Record |
+|---------|--------|
+| Task touches multiple files | `depends-on` |
+| Lesson relates to a pattern | `related-to` |
+| Agent demonstrates expertise | `expert-in` |
+| Decision causes known issue | `caused-by` |
+| Pattern supersedes old approach | `obsoletes` |
 
-When gathering context for a delegation:
+### Pre-Delegation Queries
 
-1. Find the target file(s) in the graph
-2. Follow `depends-on` edges to identify related files the agent might need to read
-3. Follow `expert-in` edges to confirm the right agent is assigned
-4. Follow `related-to` edges from relevant lessons to discover applicable patterns
-5. Check for `blocks` edges that might indicate known issues affecting the task
+Follow `depends-on` for related reads, `expert-in` to confirm agent, `related-to` for patterns, `blocks` for known issues.
 
-### Maintenance Rules
+### Maintenance
 
-- Add relationships as you discover them — don't batch
-- Review and prune at the start of major features (remove obsolete relationships)
-- Keep the graph focused — max ~100 active relationships. Archive old ones quarterly
-- Relationships are append-only during a session; pruning happens between sessions
+- Add as discovered; prune between sessions
+- Max ~100 active relationships; archive quarterly

package/src/orchestrator/skills/api-patterns/SKILL.md

@@ -3,19 +3,17 @@ name: api-patterns
 description: "API design patterns for route handlers, Server Actions, Zod validation, and external API integration. Use when creating API routes, Server Actions, or integrating external services."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # API Patterns
 
-Generic API design patterns for server-rendered framework projects. For project-specific endpoints, actions, and external API inventory, see [api-config.md](../../.opencastle/stack/api-config.md).
+Project-specific config: [api-config.md](../../.opencastle/stack/api-config.md).
 
 ## Architecture
 
-This project uses **App Router** API patterns (resolve the specific framework via the **framework** capability slot in the skill matrix):
-
-- **Server Actions** (preferred for mutations) — form submissions, data writes, auth operations
-- **Route Handlers** (`route.ts`) — analytics endpoints, autocomplete, external integrations
-- **Proxy layer** — IP rate limiting, fingerprinting, bot detection
+| Layer | Use for |
+|-------|---------|
+| **Server Actions** (preferred) | mutations, form submissions, data writes, auth |
+| **Route Handlers** (`route.ts`) | analytics, autocomplete, external integrations |
+| **Proxy layer** | IP rate limiting, fingerprinting, bot detection |
 
 ## Code Patterns
 
@@ -25,16 +23,11 @@ This project uses **App Router** API patterns (resolve the specific framework vi
 // app/api/example/route.ts
 import { NextRequest, NextResponse } from 'next/server';
 import { z } from 'zod';
-
 const schema = z.object({ query: z.string().min(1).max(200) });
 
 export async function GET(request: NextRequest) {
-  const params = Object.fromEntries(request.nextUrl.searchParams);
-  const result = schema.safeParse(params);
-  if (!result.success) {
-    return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
-  }
-  // ... process
+  const result = schema.safeParse(Object.fromEntries(request.nextUrl.searchParams));
+  if (!result.success) return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
   return NextResponse.json(data);
 }
 ```
@@ -47,62 +40,21 @@ import { createServerClient } from '@libs/auth';
 import { revalidatePath } from 'next/cache';
 
 export async function submitAction(formData: FormData) {
-  const client = await createServerClient();
-  const { data: { user } } = await client.auth.getUser();
+  const { data: { user } } = await (await createServerClient()).auth.getUser();
   if (!user) return { error: 'Unauthorized' };
-  // ... validate and process
   revalidatePath('/places');
   return { success: true };
 }
 ```
 
-## Design Principles
-
-- Prefer Server Actions for mutations over API routes
-- Always validate input with Zod schemas on the server side
-- Return appropriate HTTP status codes and error messages
-- Protect sensitive routes with middleware or role checks
-- Rate limit public endpoints to prevent abuse
-- Use Web `Request`/`Response` APIs with `NextRequest`/`NextResponse`
-- Use CDN caching headers for public, cacheable responses
-- Document new API endpoints in project documentation
-
-## API Design Principles
-
-### Route Architecture
-- RESTful resource naming: `/api/v1/places`, `/api/v1/places/:slug`
-- Use HTTP methods correctly: `GET` (read), `POST` (create), `PATCH` (partial update), `DELETE` (remove)
-- Group related endpoints under a common prefix
-- Keep URLs noun-based, not verb-based (`/api/places` not `/api/getPlaces`)
-
-### Request/Response Schemas
-- Define Zod schemas for all request bodies, query params, and responses
-- Use consistent envelope format for responses:
-  ```json
-  { "data": ..., "meta": { "total": 42, "page": 1 } }
-  ```
-- Error responses follow a standard shape:
-  ```json
-  { "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
-  ```
-
-### Error Handling
-- Use appropriate HTTP status codes (400, 401, 403, 404, 422, 429, 500)
-- Return machine-readable error codes alongside human-readable messages
-- Never leak internal errors — sanitize stack traces in production
-- Provide actionable error messages when possible
-
-### Pagination & Filtering
-- Cursor-based pagination for large datasets (offset-based as fallback)
-- Consistent query parameter names: `limit`, `cursor`, `sort`, `order`
-- Filter parameters match field names: `?type=brewery&city=prague`
-
-### Versioning
-- URL-based versioning: `/api/v1/...`
-- Never break existing contracts — add fields, never remove or rename
-- Deprecation notices in response headers before removal
-
-### Rate Limiting & Caching
-- Define rate limits per endpoint sensitivity
-- Set `Cache-Control` headers appropriate to content freshness
-- Use `ETag` / `If-None-Match` for conditional requests where applicable
+## Design Rules
+
+- Server Actions for mutations; Route Handlers for external/public endpoints
+- Validate all input with Zod on the server
+- RESTful nouns: `/api/v1/places/:slug`; HTTP methods: `GET` read, `POST` create, `PATCH` update, `DELETE` remove
+- Response envelope: `{ "data": ..., "meta": { "total": 42, "page": 1 } }`
+- Error shape: `{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }`
+- Status codes: 400, 401, 403, 404, 422, 429, 500 — never leak stack traces
+- Pagination: cursor-based preferred; params: `limit`, `cursor`, `sort`, `order`
+- Versioning: `/api/v1/...`; add fields only, never remove/rename; deprecation headers before removal
+- Rate-limit public endpoints; set `Cache-Control` and `ETag`/`If-None-Match` headers