opencastle 0.32.12 → 0.33.0

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

@@ -1,13 +1,13 @@
 ---
 name: playwright-testing
-description: "Playwright E2E testing patterns, cross-browser configuration, page objects, and CI setup. Use when writing E2E tests, visual regression tests, or configuring Playwright in CI pipelines."
+description: "Playwright E2E testing patterns, cross-browser configuration, page objects, and CI setup. Use when creating E2E specs, visual regression suites, or configuring Playwright in CI. Trigger terms: playwright, e2e, trace, page object, cross-browser"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Playwright Testing
 
-Playwright-specific E2E testing patterns. For project-specific test configuration and breakpoints, see [testing-config.md](../../.opencastle/stack/testing-config.md).
+For project-specific test configuration and breakpoints, see [testing-config.md](../../.opencastle/stack/testing-config.md).
 
 ## Commands
 
@@ -24,85 +24,29 @@ npx playwright show-report                # View HTML test report
 npx playwright install                    # Install browsers
 ```
 
-## Test Structure
+## File Conventions
 
-```
-tests/
-├── e2e/
-│   ├── auth/
-│   │   ├── login.spec.ts
-│   │   └── signup.spec.ts
-│   └── dashboard/
-│       └── overview.spec.ts
-├── fixtures/
-│   └── auth.fixture.ts      # Custom test fixtures
-└── pages/
-    ├── login.page.ts         # Page object
-    └── dashboard.page.ts
-```
+Tests: `tests/e2e/{feature}/`, page objects: `tests/pages/`, fixtures: `tests/fixtures/`.
 
 ## Writing Tests
 
 ### Basic Test Pattern
 
-```typescript
+```ts
 import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/login-page';
 
 test.describe('Login', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/login');
-  });
-
-  test('should log in with valid credentials', async ({ page }) => {
-    await page.getByTestId('email-input').fill('user@example.com');
-    await page.getByTestId('password-input').fill('password123');
-    await page.getByTestId('login-button').click();
-
-    await expect(page).toHaveURL(/.*dashboard/);
-    await expect(page.getByTestId('user-menu')).toBeVisible();
-  });
-
-  test('should show error for invalid credentials', async ({ page }) => {
-    await page.getByTestId('email-input').fill('wrong@example.com');
-    await page.getByTestId('password-input').fill('wrong');
-    await page.getByTestId('login-button').click();
-
-    await expect(page.getByTestId('error-message')).toContainText('Invalid credentials');
+  test('submits valid credentials', async ({ page }) => {
+    const login = new LoginPage(page);
+    await login.goto();
+    await login.fill('user@example.com', 'password123');
+    await page.getByRole('button', { name: 'Sign in' }).click();
+    await expect(page.getByTestId('dashboard')).toBeVisible();
   });
 });
 ```
 
-### Page Object Model
-
-```typescript
-// tests/pages/login.page.ts
-import { type Page, type Locator } from '@playwright/test';
-
-export class LoginPage {
-  readonly emailInput: Locator;
-  readonly passwordInput: Locator;
-  readonly submitButton: Locator;
-  readonly errorMessage: Locator;
-
-  constructor(private readonly page: Page) {
-    this.emailInput = page.getByTestId('email-input');
-    this.passwordInput = page.getByTestId('password-input');
-    this.submitButton = page.getByTestId('login-button');
-    this.errorMessage = page.getByTestId('error-message');
-  }
-
-  async goto() {
-    await this.page.goto('/login');
-  }
-
-  async login(email: string, password: string) {
-    await this.emailInput.fill(email);
-    await this.passwordInput.fill(password);
-    await this.submitButton.click();
-  }
-}
-```
-
 ## API Mocking
 
 ```typescript
@@ -114,13 +58,22 @@ await page.route('/api/login', (route) => {
 
 ## Locator Strategy
 
-Use Playwright's built-in locators in priority order:
+Prefer semantic locators; avoid brittle CSS selectors:
+
+```ts
+page.getByRole('button', { name: 'Sign in' })   // preferred: ARIA role + accessible name
+page.getByLabel('Email address')                  // form inputs by label
+page.getByTestId('login-form')                    // test-id for complex containers
+page.getByText('Welcome back')                    // visible text
+page.locator('[data-state="open"]')               // CSS only when no semantic alternative
+```
 
-1. `page.getByTestId()` — most resilient
-2. `page.getByRole()` — accessible, meaningful
-3. `page.getByLabel()` — for form elements
-4. `page.getByText()` — for unique visible text
-5. `page.locator()` with CSS — last resort
+## Quick Workflow: Write → Run → Debug → Verify
+1. Write a focused spec using page objects and `test.describe`.
+2. Run locally with `npx playwright test --ui` to iterate interactively.
+3. On failure: collect a trace (`trace: 'on-first-retry'`), save an HTML report, and inspect via `npx playwright show-report`.
+4. Validation checkpoint: confirm `npx playwright show-report` shows 0 failures and that saved traces contain the failing trace id.
+5. Fix the test or app; re-run the spec and verify the HTML report is green.
 
 ## Configuration (playwright.config.ts)
 
@@ -153,27 +106,9 @@ export default defineConfig({
 });
 ```
 
-## MCP Tools
-
-The Playwright MCP server enables AI agents to interact with browsers directly:
-
-| Tool | Purpose |
-|------|---------|
-| `playwright/navigate` | Navigate to a URL |
-| `playwright/screenshot` | Take page screenshots |
-| `playwright/click` | Click elements |
-| `playwright/fill` | Fill form inputs |
-| `playwright/evaluate` | Execute JavaScript in browser |
-| `playwright/expect` | Assert page state |
-
-## Best Practices
-
-- Use `test.describe` to group related tests
-- Use `test.beforeEach` for common setup — keep tests independent
-- Prefer `getByTestId` and `getByRole` over CSS selectors
-- Use `expect(locator).toBeVisible()` before interacting
-- Use `page.waitForURL()` or `page.waitForResponse()` instead of arbitrary waits
-- Run tests in parallel (`fullyParallel: true`) for speed
-- Use `trace: 'on-first-retry'` to debug flaky tests
-- Use `codegen` to bootstrap tests, then refactor into page objects
-- Use `page.route()` to mock API responses — create isolated, deterministic tests without backend dependencies
+See REFERENCE.md for MCP tools and advanced config (moved to a referenced file).
+## Best Practices (non-obvious)
+
+- Use `trace: 'on-first-retry'` selectively for flaky suites; attach trace IDs to failure tickets
+- Favor page-object reuse across specs but avoid global singletons that leak state between parallel workers
+- For CI visual diffs, snapshot only stable regions and mask dynamic content before comparison

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

@@ -0,0 +1,42 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Prisma Reference: Queries & Patterns
+
+### Basic CRUD
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient();
+
+// Create
+await prisma.user.create({ data: { email: 'user@example.com', name: 'Alice' } });
+
+// Read (with relations)
+await prisma.user.findUnique({ where: { id: userId }, include: { posts: true } });
+
+// Update
+await prisma.user.update({ where: { id: userId }, data: { name: 'Updated Name' } });
+
+// Delete
+await prisma.user.delete({ where: { id: userId } });
+```
+
+### Singleton client pattern
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+export const prisma = globalForPrisma.prisma ?? new PrismaClient();
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+### Best-practice reminders
+- Use `select` for narrow reads; prefer transactions (`prisma.$transaction`) for multi-step updates.
+- Catch `P2002` for unique constraint violations and handle gracefully.
+Last Updated: 2026-03-31
+
+Reference: Prisma migration & production checklist
+
+- Inspection checklist for generated SQL and destructive changes
+- CI pipeline snippet for `prisma migrate deploy` and `prisma generate`
+- Handling `P2002` unique constraint errors and remediation patterns

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

@@ -7,7 +7,7 @@ description: "Prisma ORM schema design, migrations, client generation, and query
 
 # Prisma Database
 
-Prisma-specific schema design, migration, and query patterns. For project-specific database schema and connection details, see [database-config.md](../../.opencastle/stack/database-config.md).
+For project-specific database schema and connection details, see [database-config.md](../../.opencastle/stack/database-config.md).
 
 ## Commands
 
@@ -63,75 +63,25 @@ model Post {
 }
 ```
 
-### Schema Best Practices
-
-- Use `cuid()` or `uuid()` for IDs — never auto-increment in distributed systems
-- Always add `createdAt` and `updatedAt` timestamps
-- Use `@map` and `@@map` to control database table/column names
-- Add `@@index` for frequently queried columns
-- Use `onDelete: Cascade` where appropriate
-- Define relations explicitly with `@relation`
-- Use enums for constrained string values
-
-## Migration Rules
-
-1. Always use `prisma migrate dev` in development — never `db push` for schema changes that need history
-2. Name migrations descriptively: `npx prisma migrate dev --name add_reviews_table`
-3. Review generated SQL before applying — Prisma auto-generates but may need manual adjustments
-4. Test migrations locally before deploying
-5. Use `prisma migrate deploy` in CI/CD — never `migrate dev` in production
-6. Write seed scripts for development data in `prisma/seed.ts`
-7. Never edit applied migration files — create new migrations instead
-8. Run `prisma generate` after every schema change to update the client
-
-## Query Patterns
-
-### Basic CRUD
-
-```typescript
-import { PrismaClient } from '@prisma/client';
-const prisma = new PrismaClient();
-
-// Create
-const user = await prisma.user.create({
-  data: { email: 'user@example.com', name: 'Alice' },
-});
-
-// Read (with relations)
-const userWithPosts = await prisma.user.findUnique({
-  where: { id: userId },
-  include: { posts: true },
-});
-
-// Update
-const updated = await prisma.user.update({
-  where: { id: userId },
-  data: { name: 'Updated Name' },
-});
-
-// Delete
-await prisma.user.delete({ where: { id: userId } });
-```
-
-### Singleton Pattern
-
-```typescript
-// lib/prisma.ts
-import { PrismaClient } from '@prisma/client';
+### Schema Best Practices (Prisma gotchas)
 
-const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+- Use `cuid()` or `uuid()` for IDs in distributed systems (avoid serial increments).
+- Always include `createdAt` and `updatedAt` timestamps for auditability and migrations.
+- Prefer explicit `@relation` definitions and add `@@index` on frequently queried columns.
+- Review `@map`/`@@map` uses when renaming to prevent accidental column/table mismatches.
+- Avoid editing applied migration files; create corrective migrations instead.
 
-export const prisma = globalForPrisma.prisma ?? new PrismaClient();
+## Migration Rules (Prisma-specific)
 
-if (process.env.NODE_ENV !== 'production') {
-  globalForPrisma.prisma = prisma;
-}
-```
+1. Use `npx prisma migrate dev` during development to generate migrations; inspect the generated SQL before applying.
+2. Use `npx prisma migrate deploy` in CI/CD; never run `migrate dev` in production.
+3. Name migrations descriptively and include backfill steps for destructive changes.
+4. Regenerate the client after schema changes: `npx prisma generate`.
 
-### Best Practices
+## Migration Workflow: validate → fix → retry (Prisma-focused)
+1. Run `npx prisma migrate dev --name <desc>` locally to generate SQL.
+2. Inspect `prisma/migrations/<timestamp>/migration.sql` for destructive operations and add backfills as needed.
+3. Apply to a local/ephemeral DB and run tests; revert and adjust if failures occur.
+4. Push migration to CI with `npx prisma migrate deploy` and assert clean application.
 
-- Always use the singleton pattern to avoid connection pool exhaustion
-- Use `select` instead of `include` when you only need specific fields
-- Use transactions (`prisma.$transaction`) for multi-step operations
-- Paginate large result sets with `skip` and `take`
-- Handle unique constraint violations with try/catch on `P2002` error code
+For query patterns, singleton client pattern, and runnable CRUD examples see REFERENCE.md in this directory.

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

@@ -0,0 +1,61 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Resend Reference: Templates & Webhook Handler
+
+### React Email template (compact example)
+
+```tsx
+// emails/welcome.tsx
+import { Html, Head, Body, Container, Heading, Text, Button } from '@react-email/components';
+
+export function WelcomeEmail({ name, loginUrl = 'https://app.example.com/login' }: { name: string; loginUrl?: string }) {
+  return (
+    <Html>
+      <Head />
+      <Body>
+        <Container>
+          <Heading>Welcome, {name}!</Heading>
+          <Text>Your account is ready.</Text>
+          <Button href={loginUrl}>Get started</Button>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+```
+
+### Webhook handler (verify signature)
+
+```typescript
+// app/api/webhooks/resend/route.ts
+import { Webhook } from 'resend';
+
+export async function POST(request: Request) {
+  const body = await request.text();
+  const signature = request.headers.get('svix-signature');
+  if (!signature || !process.env.RESEND_WEBHOOK_SECRET) return new Response('Missing signature', { status: 400 });
+
+  try {
+    const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET);
+    const event = webhook.verify(body, {
+      'svix-id': request.headers.get('svix-id')!,
+      'svix-timestamp': request.headers.get('svix-timestamp')!,
+      'svix-signature': signature,
+    });
+
+    // handle event.type (delivered, bounced, complained)
+
+    return new Response('OK', { status: 200 });
+  } catch (err) {
+    console.error('resend webhook verify failed', (err as Error).message);
+    return new Response('Invalid signature', { status: 400 });
+  }
+}
+```
+Last Updated: 2026-03-31
+
+Reference: Resend verification & webhook troubleshooting
+
+- DNS verification commands (dig examples) and expected DKIM/SPF headers
+- Sample webhook test payloads and replay instructions
+- Email header inspection checklist for deliverability debugging

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

@@ -3,185 +3,71 @@ name: resend-email
 description: "Resend transactional email patterns, React Email templates, domain configuration, and webhook handling. Use when sending emails, building email templates, or configuring email delivery."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Resend Email
 
-Resend-specific email sending patterns and React Email template conventions.
 
 ## Setup
 
 ```bash
 npm install resend
-npm install @react-email/components  # For React Email templates
+npm install @react-email/components
 ```
 
-### Client Initialization
-
-```typescript
-// lib/resend.ts
-import { Resend } from 'resend';
-
-if (!process.env.RESEND_API_KEY) {
-  throw new Error('RESEND_API_KEY is required');
-}
 
-export const resend = new Resend(process.env.RESEND_API_KEY);
-```
 
 ## Sending Emails
 
-### Basic Send
-
 ```typescript
-import { resend } from '@/lib/resend';
+import { Resend } from 'resend';
+import { WelcomeEmail } from '@/emails/welcome';
 
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// Plain text
 await resend.emails.send({
   from: 'App <no-reply@yourdomain.com>',
   to: ['user@example.com'],
-  subject: 'Welcome to our app',
-  html: '<p>Welcome! Your account is ready.</p>',
+  subject: 'Welcome',
+  html: '<p>Your account is ready.</p>',
 });
-```
-
-### With React Email Template
-
-```typescript
-import { resend } from '@/lib/resend';
-import { WelcomeEmail } from '@/emails/welcome';
 
+// With React Email template
 await resend.emails.send({
   from: 'App <no-reply@yourdomain.com>',
   to: ['user@example.com'],
-  subject: 'Welcome to our app',
+  subject: 'Welcome',
   react: WelcomeEmail({ name: 'Alice' }),
 });
 ```
 
 ## React Email Templates
 
-### Template Structure
 
-```
-emails/
-├── welcome.tsx
-├── password-reset.tsx
-├── invoice.tsx
-└── components/
-    ├── header.tsx
-    ├── footer.tsx
-    └── button.tsx
-```
-
-### Template Pattern
-
-```tsx
-// emails/welcome.tsx
-import {
-  Html, Head, Body, Container, Section,
-  Heading, Text, Button, Img, Hr,
-} from '@react-email/components';
-
-interface WelcomeEmailProps {
-  name: string;
-  loginUrl?: string;
-}
-
-export function WelcomeEmail({
-  name,
-  loginUrl = 'https://app.example.com/login',
-}: WelcomeEmailProps) {
-  return (
-    <Html lang="en">
-      <Head />
-      <Body style={bodyStyle}>
-        <Container style={containerStyle}>
-          <Heading style={headingStyle}>Welcome, {name}!</Heading>
-          <Text style={textStyle}>
-            Your account has been created successfully.
-          </Text>
-          <Section style={{ textAlign: 'center' as const }}>
-            <Button href={loginUrl} style={buttonStyle}>
-              Get Started
-            </Button>
-          </Section>
-          <Hr style={hrStyle} />
-          <Text style={footerStyle}>
-            © 2026 Your App. All rights reserved.
-          </Text>
-        </Container>
-      </Body>
-    </Html>
-  );
-}
-
-const bodyStyle = { backgroundColor: '#f6f9fc', fontFamily: 'sans-serif' };
-const containerStyle = { margin: '0 auto', padding: '40px 20px', maxWidth: '580px' };
-const headingStyle = { fontSize: '24px', color: '#1a1a1a' };
-const textStyle = { fontSize: '16px', color: '#4a4a4a', lineHeight: '26px' };
-const buttonStyle = {
-  backgroundColor: '#3b82f6', color: '#fff', fontSize: '16px',
-  padding: '12px 24px', borderRadius: '6px', textDecoration: 'none',
-};
-const hrStyle = { borderColor: '#e6e6e6', margin: '32px 0' };
-const footerStyle = { fontSize: '12px', color: '#999' };
-
-export default WelcomeEmail;
-```
+Template pattern and webhook handler examples: see [REFERENCE.md](./REFERENCE.md).
 
 ### Preview Templates
 
 ```bash
-npx email dev  # Start React Email dev server at localhost:3000
+npx email dev
 ```
 
 ## Domain Configuration
 
 1. Add your domain at resend.com → Domains
-2. Configure DNS records (SPF, DKIM, DMARC) as instructed
-3. Wait for domain verification (usually < 1 hour)
+2. Configure DNS records (SPF, DKIM, DMARC) and await verification (<1h)
+3. Post-verify: send one canned test to `postmaster@` and confirm headers (SPF/DKIM pass).
 4. Use `from: 'Name <no-reply@yourdomain.com>'` in sends
 
 ## Webhook Handling
 
-```typescript
-// app/api/webhooks/resend/route.ts
-import { Webhook } from 'resend';
-
-export async function POST(request: Request) {
-  const body = await request.text();
-  const signature = request.headers.get('svix-signature');
-
-  const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET!);
-  const event = webhook.verify(body, {
-    'svix-id': request.headers.get('svix-id')!,
-    'svix-timestamp': request.headers.get('svix-timestamp')!,
-    'svix-signature': signature!,
-  });
-
-  switch (event.type) {
-    case 'email.delivered':
-      // Handle successful delivery
-      break;
-    case 'email.bounced':
-      // Handle bounce — remove from mailing list
-      break;
-    case 'email.complained':
-      // Handle spam complaint — unsubscribe immediately
-      break;
-  }
-
-  return new Response('OK', { status: 200 });
-}
-```
+Webhook handling patterns and a safe, verified handler example are in REFERENCE.md (this directory).
+
+## Quick Verification Workflow
+1. Add domain and copy DNS records.
+2. Verify DNS propagation: `dig TXT yourdomain.com` — confirm SPF/DKIM records appear.
+3. Send a test email and confirm SPF/DKIM pass in headers.
+4. Deploy webhook handler; test with: `curl -X POST -H 'Content-Type: application/json' -d '{"type":"email.delivered"}' https://yourapp.com/api/webhooks/resend` — assert 200.
+5. If verification fails: re-check DNS, API keys, and webhook secret.
 
-## Best Practices
+See REFERENCE.md for detailed verification commands and troubleshooting.
 
-- Always use a verified custom domain — never send from `onboarding@resend.dev` in production
-- Use React Email templates for complex emails — plain HTML for simple transactional messages
-- Handle bounces and complaints via webhooks — remove invalid addresses promptly
-- Use `RESEND_API_KEY` as an environment variable — never commit it
-- Test emails locally with React Email dev server before deploying
-- Set appropriate `from` addresses: `no-reply@` for transactional, named sender for marketing
-- Include unsubscribe links where legally required (CAN-SPAM, GDPR)
-- Keep email templates responsive — test in major email clients

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

@@ -1,6 +1,6 @@
 ---
 name: sanity-cms
-description: "Sanity CMS development rules, GROQ query patterns, and content management best practices. Use when working with Sanity schemas, writing GROQ queries, modifying content models, or managing CMS configuration."
+description: "Manages Sanity CMS schemas, GROQ queries, dataset exports/imports, and Studio configuration. Use when updating Sanity schemas, running GROQ or Vision queries, exporting datasets, modifying content models, or configuring a headless CMS with Sanity.io."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -13,8 +13,55 @@ Generic Sanity CMS development methodology. For project-specific configuration,
 
 1. **Always check the schema before querying** — use `get_schema` to understand document types and field structures before writing GROQ queries
 2. **Array vs single reference** — always verify whether a field is an array of references or a single reference; using the wrong query operator causes silent failures
-3. **Local schema files are source of truth** — the Studio schema directory takes precedence over deployed schemas; deploying schemas from a local Studio context creates drift
+3. **Local schema files are source of truth** — never edit deployed schemas directly; always change local files and redeploy
 4. **Follow `defineType` and `defineField` patterns** — always use Sanity helpers for type safety and consistency
 5. **Test GROQ queries in Vision** — validate queries against real data in the Vision plugin before deploying
-6. **Handle draft/publish workflow** — remember drafts have `drafts.` prefix; mutations create drafts, not published documents
+6. **Handle draft/publish workflow** — always account for the `drafts.` prefix when querying or mutating documents
 7. **Keep queries in the shared library** — queries belong in a shared queries library, never inline in components
+
+## Quick GROQ examples
+
+Fetch published articles with authors populated:
+
+```groq
+*[_type == "article" && defined(publishedAt)] | order(publishedAt desc) {
+	_id,
+	title,
+	"author": author-> { name, _id },
+	body
+}
+```
+
+Filter by tag and return first 10:
+
+```groq
+*[_type == "article" && "tech" in tags[]] | order(_createdAt desc)[0..9] { title, slug }
+```
+
+## Example schema (executable)
+
+```js
+// schemas/article.js
+import { defineType, defineField } from 'sanity'
+
+export default defineType({
+	name: 'article',
+	title: 'Article',
+	type: 'document',
+	fields: [
+		defineField({ name: 'title', type: 'string', title: 'Title' }),
+		defineField({ name: 'slug', type: 'slug', options: { source: 'title' } }),
+		defineField({ name: 'author', type: 'reference', to: [{ type: 'author' }] }),
+		defineField({ name: 'body', type: 'array', of: [{ type: 'block' }] }),
+	],
+})
+```
+
+## Workflow: change schema → validate → deploy
+
+1. Update local schema files and run `sanity start` to surface schema errors locally.
+2. Run Vision queries to validate GROQ results against local data: execute representative queries (see examples above).
+3. Create a migration or dataset export if needed and test changes in a staging project/dataset.
+	 - Validation checkpoint: run `sanity dataset export` and `sanity dataset import` into a temporary dataset and run queries.
+4. Deploy the schema to Studio and run end-to-end site builds to confirm runtime behavior.
+5. If validation fails at any step, revert schema changes locally, fix, and repeat from step 1.