opencastle 0.32.12 → 0.33.0

package/src/orchestrator/plugins/nextjs/SKILL.md

@@ -1,170 +1,81 @@
 ---
 name: nextjs-framework
-description: "Next.js framework best practices covering App Router, server/client components, data fetching, caching, rendering strategies, middleware, configuration, and deployment. Use when creating or modifying Next.js pages, layouts, route handlers, Server Actions, or project configuration."
+description: "Explains how to configure App Router, implement server/client components, optimize data fetching, and secure routes. Use when the user mentions: 'add an authenticated route', 'migrate to App Router', 'optimize fetch caching', or 'fix RSC hydration'."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Next.js Framework
 
-## Project Structure
-
-```
-├── app/                     # App Router (file-based routing)
-│   ├── layout.tsx           # Root layout (required)
-│   ├── page.tsx             # Home route → /
-│   ├── loading.tsx          # Loading UI (Suspense boundary)
-│   ├── error.tsx            # Error boundary (Client Component)
-│   ├── not-found.tsx        # 404 page
-│   ├── (marketing)/         # Route group (no URL segment)
-│   │   └── about/page.tsx   # → /about
-│   ├── dashboard/
-│   │   ├── layout.tsx       # Nested layout
-│   │   └── [id]/page.tsx    # → /dashboard/:id
-│   └── api/
-│       └── users/route.ts   # API route handler
-├── components/              # Shared React components
-├── lib/                     # Utilities, helpers, server logic
-├── public/                  # Static assets
-├── next.config.ts           # Next.js configuration
-├── middleware.ts            # Edge middleware
-└── .env.local               # Environment variables (not committed)
-```
-
-Route Groups `(name)` organize routes without affecting the URL. Private Folders `_internal` opt out of routing. Parallel Routes `@modal` render multiple pages in the same layout.
-
-## Rendering Strategies
-
-| Strategy | When | How |
-|----------|------|-----|
-| **Static (SSG)** | Build time | Default for pages with no dynamic data |
-| **ISR** | Build + revalidation | `fetch` with `next: { revalidate: N }` or route segment config |
-| **SSR** | Every request | `export const dynamic = 'force-dynamic'` or dynamic functions |
-| **CSR** | Browser | `'use client'` components with `useEffect`/SWR |
-| **Streaming** | Progressive | `<Suspense>` boundaries + `loading.tsx` |
-| **PPR** | Build + streaming | Static shell with dynamic holes via `<Suspense>` |
-
-Route segment config: `export const dynamic = 'force-dynamic'`, `export const revalidate = 60`, `export const runtime = 'edge'`.
-
-## Server and Client Components
-
-**Default: Server Components** — data fetching, heavy logic, non-interactive UI.  
-**Client Components** — add `'use client'` at top. Use for interactivity, state, browser APIs.
-
-| Need | Component Type |
-|------|---------------|
-| Fetch data / read cookies/headers | Server |
-| Interactive UI (clicks, inputs) | Client |
-| `useState` / `useEffect` / browser APIs | Client |
-| Static/non-interactive content | Server |
-| Async children with loading state | Server + `<Suspense>` |
-
 ### Critical Rule
 
-**Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** Extract to a dedicated `'use client'` component and import it normally.
+**Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** Extract the dynamic piece to a dedicated `'use client'` component and import it from server components normally.
 
-## Data Fetching
+```tsx
+// ✅ Correct: wrap dynamic import in a 'use client' component
+// components/MapClient.tsx
+'use client';
+import dynamic from 'next/dynamic';
+const Map = dynamic(() => import('./Map'), { ssr: false });
+export function MapClient(props: MapProps) { return <Map {...props} />; }
+
+// Then import from a Server Component as normal:
+// app/page.tsx
+import { MapClient } from '@/components/MapClient';
+export default function Page() { return <MapClient center={[0, 0]} />; }
+```
 
-### Server-Side
+### Authenticated Routes
 
 ```tsx
-export default async function ProjectsPage() {
-  const data = await fetch('/api/projects', { next: { revalidate: 60 } }).then((r) => r.json());
-  return <ul>{data.map((p: { id: string; name: string }) => <li key={p.id}>{p.name}</li>)}</ul>;
+// app/dashboard/page.tsx
+import { redirect } from 'next/navigation';
+import { getSession } from '@/lib/auth';
+export default async function Page() {
+  const session = await getSession();
+  if (!session) redirect('/login');
+  // ... render dashboard
 }
 ```
 
+For middleware-based protection see `REFERENCE.md § Middleware examples`.
+
 ### Server Actions
 
-```tsx
+```ts
+// app/actions.ts
 'use server';
 import { revalidatePath } from 'next/cache';
-export async function createItem(formData: FormData) {
-  await db.items.create({ data: { name: formData.get('name') as string } });
-  revalidatePath('/items');
+export async function updatePost(id: string, data: FormData) {
+  await db.posts.update(id, Object.fromEntries(data));
+  revalidatePath('/posts');
 }
 ```
 
-Use from a Client Component: `<form action={createItem}>...</form>`
-
-### Parallel Fetching
-
-```tsx
-const [metrics, activity] = await Promise.all([getMetrics(), getRecentActivity()]);
-```
-
-## Caching
-
-| Mechanism | Scope | How to Use |
-|-----------|-------|------------|
-| **Request Memoization** | Per-request | Automatic deduplication of identical `fetch` calls |
-| **Data Cache** | Cross-request | Cached by default; opt out with `cache: 'no-store'` |
-| **Full Route Cache** | Build time | Static routes cached as HTML + RSC payload |
-| **Router Cache** | Client-side | Prefetched and visited routes cached in browser |
-
-On-demand revalidation: `revalidatePath('/blog')` or `revalidateTag('posts')`. Tag a fetch: `fetch(url, { next: { tags: ['posts'] } })`.
-
-## Routing
-
-### File Conventions
-
-| File | Purpose |
-|------|---------|
-| `page.tsx` | Route UI |
-| `layout.tsx` | Shared layout (persists across navigation) |
-| `template.tsx` | Like layout but re-mounts on navigation |
-| `loading.tsx` | Loading UI (automatic Suspense boundary) |
-| `error.tsx` | Error UI (Client Component) |
-| `not-found.tsx` | 404 UI |
-| `route.ts` | API endpoint |
-| `default.tsx` | Fallback for parallel routes |
-
-### Dynamic Routes
-
-- `app/blog/[slug]/page.tsx` → `/blog/:slug`
-- `app/shop/[...slug]/page.tsx` → `/shop/:slug+` (catch-all)
-- `app/shop/[[...slug]]/page.tsx` → `/shop` or `/shop/:slug+` (optional)
-
-## Middleware
-
-Runs at the Edge before every matched request. Use for auth, redirects, rewrites.
+### Data Fetching & Caching
 
 ```ts
-import { NextResponse, type NextRequest } from 'next/server';
-export function middleware(req: NextRequest) {
-  if (!req.cookies.get('session') && req.nextUrl.pathname.startsWith('/dashboard'))
-    return NextResponse.redirect(new URL('/login', req.url));
-  return NextResponse.next();
+// Server Component — cached by default; opt out with cache: 'no-store'
+async function getPosts() {
+  const res = await fetch('/api/posts', { next: { tags: ['posts'] } });
+  return res.json() as Promise<Post[]>;
 }
-export const config = { matcher: ['/dashboard/:path*'] };
+// On-demand revalidation: revalidateTag('posts') or revalidatePath('/posts')
 ```
 
-## Environment Variables
-
-| Prefix | Available in | Use Case |
-|--------|-------------|----------|
-| `NEXT_PUBLIC_` | Server + Client | Public values (API base URLs, feature flags) |
-| No prefix | Server only | Secrets (DB URLs, API keys, tokens) |
-
-Files (priority order): `.env.local`, `.env.development` / `.env.production`, `.env`.
-
-## Image, Font, and Metadata
+Caching tiers (request memo → data cache → full route cache → router cache) and revalidation patterns are in `REFERENCE.md § Caching Details`.
 
-- **Images**: Use `<Image>` from `next/image` — auto lazy loading, responsive sizing, format conversion. Configure `images.remotePatterns` in `next.config.ts` for remote URLs.
-- **Fonts**: Use `next/font/google` — zero layout shift, self-hosted, no external network request.
-- **Metadata**: Export `metadata` (static) or `generateMetadata` (dynamic) per page/layout for SEO and social previews.
+### Adding an Authenticated Route — Checklist
 
-## Anti-Patterns
+1. Create `app/<route>/page.tsx` as an async Server Component.
+  - Validate: file exists and exports a default async component.
+2. Call `getSession()` at the top and `redirect('/login')` when missing.
+  - Validate: confirm there is no render path when session is falsy (no UI returned before redirect).
+3. Add `app/<route>/error.tsx` for error boundaries.
+  - Validate: `tsc --noEmit` recognizes the file and there are no missing imports.
+4. Run `tsc --noEmit` and fix type errors.
+  - Validate: `tsc --noEmit` exits with code 0.
+5. Test: access the route without an auth cookie and confirm redirect to `/login`.
+  - Validate: an unauthenticated HTTP request receives a 302/307 redirect to `/login`.
 
-| Anti-Pattern | Why It's Wrong | Do This Instead |
-|-------------|---------------|-----------------|
-| `'use client'` on every component | Bloats JS bundle, defeats RSC benefits | Default to Server Components |
-| Sequential `await` for independent data | Waterfall, slows page load | Use `Promise.all()` |
-| `next/dynamic` with `ssr: false` in Server Components | Build/runtime crash | Extract to Client Component |
-| Fetching in `useEffect` when server fetch works | Extra roundtrip, loading flash | Fetch in Server Component or Server Actions |
-| Giant `layout.tsx` with all providers | Hard to test, couples concerns | Split into a `Providers` Client Component |
-| No `error.tsx` per segment | Unhandled errors crash the page | Add `error.tsx` per route segment |
-| Hardcoding secrets in source | Security risk, version control leak | Use `.env.local` and `process.env` |
-| Skipping `loading.tsx` / `<Suspense>` | Blank screen while data loads | Add `loading.tsx` or wrap in `<Suspense>` |
-| `getServerSideProps` / `getStaticProps` | Legacy Pages Router | Use App Router with async Server Components |
-| Missing `metadata` exports | Poor SEO, no social previews | Export `metadata` or `generateMetadata` per page |
+Project-specific conventions and deeper tables (routing, caching, component guidance) live in [REFERENCE.md](./REFERENCE.md).

package/src/orchestrator/plugins/notion/SKILL.md

@@ -1,205 +1,63 @@
 ---
 name: notion-knowledge-management
-description: "Notion workspace patterns for knowledge capture, research documentation, architectural decisions, and spec management. Use when capturing research findings, writing specs, documenting decisions, or managing a team knowledge base."
+description: "Creates Notion pages and databases, applies templates for research docs, ADRs, and specs, and manages team knowledge bases. Use when creating Notion pages, structuring databases, documenting decisions, or capturing research findings."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Knowledge Management with Notion
 
-Conventions for working with the team's Notion workspace via the official Notion MCP server. Covers page and database operations, research capture, decision documentation, and permission-aware workflows.
-
-## MCP Server
-
-| Field | Value |
-|-------|-------|
-| **Endpoint** | `https://mcp.notion.com/mcp` (HTTP, remote) |
-| **Auth** | OAuth — users authenticate via Notion account when the MCP connection is established |
-| **Type** | HTTP MCP (no local process to spawn) |
-
-### Authentication
-
-The Notion MCP server uses OAuth. When the MCP connection is first opened in your IDE, you will be prompted to authorise access to your Notion workspace. No API key or token is required in `.env`.
-
-> **Scope:** The integration is granted access only to pages and databases explicitly shared with it. Before using MCP tools, ensure the relevant pages/databases are shared with the OpenCastle integration in Notion.
-
-## Available MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `search` | Search pages and databases across the workspace by keyword |
-| `create_page` | Create a new page (standalone or inside a parent page/database) |
-| `update_page` | Update page properties or archive a page |
-| `append_block_children` | Append content blocks (paragraphs, headings, bullets, code) to a page |
-| `query_database` | Query a Notion database with filters and sorts |
+MCP endpoint: `https://mcp.notion.com/mcp` (OAuth). Tools: `search`, `create_page`, `update_page`, `append_block_children`, `query_database`.
 
 ## Working with Pages and Databases
 
-### Page Hierarchy Hygiene
+### Page Hierarchy
 
-Keep the workspace navigable by placing new pages in the right location:
+Use `search` first to check if a page already exists. Place new pages under the appropriate parent (e.g., Engineering/Specs).
 
-```
-Workspace root
-├── Engineering/
-│   ├── Architecture Decisions/   ← ADRs go here
-│   ├── Specs/                    ← Feature specs go here
-│   └── Research/                 ← Research notes go here
-├── Team/
-│   ├── Meeting Notes/            ← Meeting intelligence
-│   └── Decisions Log/            ← Key team decisions
-└── Project: <name>/              ← Per-project space
-    ├── Roadmap
-    ├── Known Issues
-    └── Release Notes/
-```
-
-- Always use `search` first to check if a page already exists before creating a new one.
-- Create pages as children of the appropriate parent — never at the workspace root unless explicitly requested.
-- Use databases (not flat pages) for collections that need filtering, sorting, or status tracking (e.g., ADRs, specs).
+### Create & verify page (end-to-end)
 
-### Page Creation Pattern
+1. `search` for parent page (by title) to obtain `page_id`.
 
-When creating a page:
+```json
+// tool: notion/search
+{ "query": "Engineering/Specs", "page_size": 5 }
+// response.example: { results: [{ id: "abc123", title: "Engineering/Specs" }] }
+```
 
-1. `search` for an existing page with a similar title to avoid duplicates
-2. `create_page` with `parent` set to the correct parent page or database
-3. `append_block_children` to add structured content
+2. `create_page` using the found `page_id` as `parent`.
 
 ```json
-// Example: Create a spec page
+// tool: notion/create_page
 {
-  "parent": { "page_id": "<Engineering/Specs parent ID>" },
-  "properties": {
-    "title": [{ "type": "text", "text": { "content": "[Spec] Price Range Filter" } }]
-  }
+  "parent": { "page_id": "abc123" },
+  "properties": { "title": [{ "type": "text", "text": { "content": "[Spec] Price Range Filter" } }] }
 }
 ```
 
-## Capturing Research and Decisions
-
-### Research Note Structure
-
-Use this outline when capturing research findings:
-
-```
-# [Research] <Topic>
-
-## Summary
-One-paragraph overview of findings.
-
-## Sources
-- <URL or reference> — <why it is relevant>
-
-## Key Findings
-- Finding 1
-- Finding 2
-
-## Implications
-How these findings affect the current task or architecture.
-
-## Open Questions
-- Question 1
-```
-
-### Architectural Decision Record (ADR) Structure
-
-```
-# ADR-NNN: <Short title>
-
-**Status:** Proposed | Accepted | Deprecated | Superseded
-**Date:** YYYY-MM-DD
-
-## Context
-What is the problem or decision to be made?
-
-## Decision
-What was decided?
-
-## Consequences
-What tradeoffs or follow-on work does this create?
-
-## Alternatives Considered
-- Option A — why rejected
-- Option B — why rejected
-```
-
-### Spec-to-Implementation Link
-
-When a spec page drives implementation, add an **Implementation** section at the bottom:
-
-```
-## Implementation
-- **Branch:** `feat/price-range-filter`
-- **PR:** <link>
-- **Tracker:** <Linear/Jira/Trello card link>
-- **Status:** In Progress / Done
-```
-
-This closes the loop between the knowledge base and the task tracker.
-
-## Meeting Intelligence
-
-When capturing meeting notes, use the following structure:
+3. Verify creation by searching for the exact title and confirming `parent` matches.
 
+```json
+// tool: notion/search
+{ "query": "[Spec] Price Range Filter" }
 ```
-# Meeting: <Title> — YYYY-MM-DD
-
-**Attendees:** Name1, Name2
-**Type:** Planning / Review / Retrospective / Decision
-
-## Summary
 
-## Decisions Made
-- Decision 1 (owner: Name)
+Recovery: if search returns empty, retry after 30s (indexing delay) or confirm integration access.
 
-## Action Items
-- [ ] Action item (owner: Name, due: YYYY-MM-DD)
+## Capturing Research and Decisions
 
-## Context / Discussion Notes
-```
+Use the templates in [TEMPLATES.md](TEMPLATES.md) for Research Notes, ADRs, Specs, and Meeting notes. Create pages using the end-to-end pattern above and append implementation links to close the loop between spec and code.
 
-After the meeting, add action items to the task tracker.
+Meeting notes: use [TEMPLATES.md](TEMPLATES.md) and append action items to the tracker (Linear/GitHub) with links.
 
 ## Permission-Aware Workflows
 
-Notion access is page-scoped. Follow these rules to avoid permission errors:
-
-1. **Before writing** — run `search` to verify you can see the target page. If it does not appear, the integration has not been granted access.
-2. **Sharing** — ask the user to share the relevant page or database with the OpenCastle integration before running MCP tools against it.
-3. **Databases vs pages** — use `query_database` only on pages that are databases. Use `append_block_children` to add content to regular pages.
-4. **Archived pages** — `search` does not return archived pages. If a page is missing, it may have been archived. Ask the user to restore it.
+`search` the target parent first to confirm integration visibility. If missing, request user share the parent page. Use `query_database` for databases; `append_block_children` for regular pages.
 
 ## Database Query Patterns
 
-### Filter by Status
-
-```json
-{
-  "filter": {
-    "property": "Status",
-    "select": { "equals": "In Progress" }
-  }
-}
-```
-
-### Sort by Last Edited
-
 ```json
-{
-  "sorts": [
-    { "timestamp": "last_edited_time", "direction": "descending" }
-  ]
-}
+// tool: notion/query_database
+{ "database_id": "db_id", "filter": { "property": "Status", "select": { "equals": "In Progress" } }, "sorts": [{ "timestamp": "last_edited_time", "direction": "descending" }] }
 ```
 
-## Agent Usage Guidelines
-
-| Agent | Primary Use |
-|-------|-------------|
-| **Team Lead** | Create spec pages, capture decisions, link tracker issues to specs |
-| **Researcher** | Capture research notes, query databases for prior art, document findings |
-| **Documentation Writer** | Write and update documentation pages, maintain page hierarchy |
-| **Architect** | Write ADRs, create technical specs, link specs to implementation PRs |
-
-**Never** delete pages via MCP — use `update_page` with `archived: true` if a page needs to be removed, and confirm with the user first.

package/src/orchestrator/plugins/notion/TEMPLATES.md

@@ -0,0 +1,88 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Notion Templates (TEMPLATES.md)
+
+Last Updated: 2026-03-31
+
+## Research Note
+
+```
+# [Research] <Topic>
+
+## Summary
+One-paragraph overview of findings.
+
+## Sources
+- <URL or reference> — <why it is relevant>
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Implications
+How these findings affect the current task or architecture.
+
+## Open Questions
+- Question 1
+```
+
+## ADR (Architectural Decision Record)
+
+```
+## ADR-NNN: <Short title>
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** YYYY-MM-DD
+
+### Context
+What is the problem or decision to be made?
+
+### Decision
+What was decided?
+
+### Consequences
+What tradeoffs or follow-on work does this create?
+
+### Alternatives Considered
+- Option A — why rejected
+- Option B — why rejected
+```
+
+## Spec Template
+
+```
+# [Spec] <Feature>
+
+## Objective
+One-sentence deliverable
+
+## Background
+Why this feature exists
+
+## Acceptance Criteria
+- [ ] Specific, verifiable outcome 1
+- [ ] Specific, verifiable outcome 2
+
+## Implementation
+- Branch: `feat/...`
+- PR: <link>
+- Tracker: <link>
+```
+
+## Meeting Note Template
+
+```
+# Meeting: <Title> — YYYY-MM-DD
+
+**Attendees:** Name1, Name2
+**Type:** Planning / Review / Retrospective / Decision
+
+## Summary
+
+## Decisions Made
+- Decision 1 (owner: Name)
+
+## Action Items
+- [ ] Action item (owner: Name, due: YYYY-MM-DD)
+
+## Context / Discussion Notes
+```

package/src/orchestrator/plugins/nx/REFERENCE.md

@@ -0,0 +1,10 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: NX deep dive
+
+- Generator schemas: examples and option tables
+- `project.json` vs `workspace.json` migrations
+- Visualize graph examples and troubleshooting cache hits
+- CI examples: using `nx affected` in pipelines

package/src/orchestrator/plugins/nx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nx-workspace
-description: "NX monorepo commands, conventions, code generation, and task running patterns. Use when running builds, tests, linting, code generation, or any development commands."
+description: "Run and generate NX targets, configure project.json, and visualize dependency graphs. Use when you say: 'run affected tests', 'nx generate a library', 'configure project.json', or 'show dependency graph'."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -43,8 +43,11 @@ yarn nx run <project-name>:dev
 ### Code Generation
 
 ```bash
-yarn nx generate <generator-name> --no-interactive
-yarn nx g <generator-name> --no-interactive
+# Generate a library
+yarn nx generate @nrwl/js:library ui --no-interactive
+# Run affected builds/tests
+yarn nx affected -t build
+yarn nx affected -t test
 ```
 
 ### Formatting
@@ -71,10 +74,8 @@ jest --coverage | eslint --fix
 
 ## Best Practices
 
-1. Always use `yarn nx run <project-name>:<target>` format.
+1. Use `yarn nx run <project-name>:<target>` for explicit runs.
 2. Use `yarn nx affected -t <target>` for multi-project changes.
-3. Use exact project names from `project.json` files.
-4. NX automatically handles task caching and parallel execution.
 
 ## NX MCP Server
 
@@ -96,13 +97,12 @@ The NX MCP server provides tools for understanding and working with the workspac
 
 ## Code Generation Workflow
 
-Always prefer generators over manual file creation when a generator exists.
+See [REFERENCE.md](REFERENCE.md) for generator schemas and `project.json` examples.
 
 ### Phase 1: Discover
-
-1. List available generators using `nx_generators` MCP tool (plugin + local workspace generators)
-2. Prefer local generators over plugin generators — they're customized for this repo
-3. If no generator fits, check `nx_available_plugins`; only fall back to manual creation after exhausting all generator options
+1. List available generators using the `nx_generators` MCP tool (plugin + local workspace generators).
+2. Prefer local generators over plugin generators — they're customized for this repo.
+3. If no generator fits, check `nx_available_plugins`; only fall back to manual creation after exhausting all generator options.
 
 ### Phase 2: Understand
 
@@ -121,7 +121,7 @@ yarn nx generate <generator-name> <options> --no-interactive
 
 **CRITICAL**: Verify cwd before running — generators may use it to determine file placement.
 
-On failure: read the error, adjust options, and retry. Use the **self-improvement** skill for non-obvious fixes.
+On failure: read the error, adjust options, and retry. Use the [self-improvement skill](../../skills/self-improvement/SKILL.md) for non-obvious fixes.
 
 ### Phase 4: Post-Generation
 

package/src/orchestrator/plugins/playwright/REFERENCE.md

@@ -0,0 +1,12 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Playwright REFERENCE: MCP tools table, advanced `playwright.config.ts` snippets, and trace handling examples.
+
+Keep large tables and MCP tool schemas here; `SKILL.md` references this file for quick workflows.
+Last Updated: 2026-03-31
+
+Reference: Playwright advanced
+
+- CI examples for running `npx playwright test --project=chromium --reporter=html`
+- Debugging: using `trace` files and `npx playwright show-report` walkthrough
+- Example page-object templates and fixtures