opencastle 0.9.2 → 0.10.1

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

@@ -0,0 +1,137 @@
+---
+name: prisma-database
+description: "Prisma ORM schema design, migrations, client generation, and query patterns. Use when designing database schemas, writing migrations, querying data, or managing Prisma Client."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+
+# Prisma Database
+
+Prisma-specific schema design, migration, and query patterns. For project-specific database schema and connection details, see [database-config.md](../../customizations/stack/database-config.md).
+
+## Commands
+
+```bash
+npx prisma init                    # Initialize Prisma in the project
+npx prisma generate                # Generate Prisma Client from schema
+npx prisma migrate dev             # Create and apply migration (dev)
+npx prisma migrate deploy          # Apply pending migrations (production)
+npx prisma migrate reset           # Reset database and apply all migrations
+npx prisma db push                 # Push schema changes without migration
+npx prisma db pull                 # Introspect database into schema
+npx prisma db seed                 # Run seed script
+npx prisma studio                  # Open visual database editor
+npx prisma format                  # Format schema file
+npx prisma validate                # Validate schema syntax
+```
+
+## Schema Design
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  posts     Post[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id        String   @id @default(cuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  authorId  String
+
+  @@index([authorId])
+  @@map("posts")
+}
+```
+
+### 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';
+
+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 Practices
+
+- 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

package/src/orchestrator/plugins/prisma/config.ts

@@ -0,0 +1,26 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'prisma',
+  name: 'Prisma',
+  category: 'tech',
+  subCategory: 'database',
+  label: 'Prisma',
+  hint: 'Type-safe ORM, migrations, schema management',
+  skillName: 'prisma-database',
+  mcpServerKey: 'Prisma',
+  mcpConfig: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@anthropic/prisma-mcp@latest'],
+  },
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {
+    'database-engineer': ['prisma/*'],
+    'developer': ['prisma/*'],
+  },
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#prisma',
+  officialDocs: 'https://www.prisma.io/docs',
+  mcpPackage: '@anthropic/prisma-mcp',
+};

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

@@ -0,0 +1,187 @@
+---
+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 .github/customizations/ 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
+```
+
+### 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';
+
+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>',
+});
+```
+
+### With React Email Template
+
+```typescript
+import { resend } from '@/lib/resend';
+import { WelcomeEmail } from '@/emails/welcome';
+
+await resend.emails.send({
+  from: 'App <no-reply@yourdomain.com>',
+  to: ['user@example.com'],
+  subject: 'Welcome to our app',
+  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;
+```
+
+### Preview Templates
+
+```bash
+npx email dev  # Start React Email dev server at localhost:3000
+```
+
+## 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)
+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 });
+}
+```
+
+## Best Practices
+
+- 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/resend/config.ts

@@ -0,0 +1,47 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'resend',
+  name: 'Resend',
+  category: 'tech',
+  subCategory: 'email',
+  label: 'Resend',
+  hint: 'Transactional email API with React templates',
+  skillName: 'resend-email',
+  mcpServerKey: 'Resend',
+  mcpConfig: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', 'resend-mcp'],
+    envFile: '${workspaceFolder}/.env',
+  },
+  authType: 'env-token',
+  envVars: [
+    {
+      name: 'RESEND_API_KEY',
+      hint: 'Generate at resend.com → API Keys',
+    },
+  ],
+  agentToolMap: {
+    'developer': [
+      'resend_send_email', 'resend_batch_send_email', 'resend_get_email',
+      'resend_list_emails', 'resend_cancel_email', 'resend_update_email',
+    ],
+    'devops-expert': [
+      'resend_create_domain', 'resend_list_domains', 'resend_get_domain',
+      'resend_verify_domain', 'resend_update_domain', 'resend_remove_domain',
+      'resend_create_api_key', 'resend_list_api_keys', 'resend_remove_api_key',
+      'resend_create_webhook', 'resend_list_webhooks', 'resend_get_webhook',
+      'resend_update_webhook', 'resend_remove_webhook',
+    ],
+    'data-expert': [
+      'resend_create_contact', 'resend_list_contacts', 'resend_get_contact',
+      'resend_update_contact', 'resend_remove_contact',
+      'resend_create_broadcast', 'resend_list_broadcasts', 'resend_get_broadcast',
+      'resend_send_broadcast',
+    ],
+  },
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#resend',
+  officialDocs: 'https://resend.com/docs',
+  mcpPackage: 'resend-mcp',
+};

package/src/orchestrator/plugins/sanity/config.ts

@@ -38,7 +38,6 @@ export const config: PluginConfig = {
       'sanity/list_projects',
     ],
   },
-  docsUrl: null,
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#sanity',
   officialDocs: 'https://www.sanity.io/docs',
-  mcpPackage: null,
 };

package/src/orchestrator/plugins/slack/config.ts

@@ -29,7 +29,7 @@ export const config: PluginConfig = {
     'team-lead': ['slack/*'],
     'release-manager': ['slack/*'],
   },
-  docsUrl: '/guides/plugins#slack',
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#slack',
   officialDocs: 'https://api.slack.com/docs',
   mcpPackage: '@kazuph/mcp-slack',
 };

package/src/orchestrator/plugins/strapi/config.ts

@@ -35,7 +35,7 @@ export const config: PluginConfig = {
       'strapi/get_entry', 'strapi/create_entry', 'strapi/update_entry',
     ],
   },
-  docsUrl: null,
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#strapi',
   officialDocs: 'https://docs.strapi.io/',
   mcpPackage: 'strapi-mcp',
 };

package/src/orchestrator/plugins/supabase/config.ts

@@ -28,7 +28,6 @@ export const config: PluginConfig = {
       'supabase/list_migrations', 'supabase/get_project',
     ],
   },
-  docsUrl: null,
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#supabase',
   officialDocs: 'https://supabase.com/docs',
-  mcpPackage: null,
 };

package/src/orchestrator/plugins/teams/config.ts

@@ -31,9 +31,8 @@ export const config: PluginConfig = {
       'Teams/mcp_graph_teams_listChannelMessages',
     ],
   },
-  docsUrl: null,
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#teams',
   officialDocs: 'https://learn.microsoft.com/en-us/microsoftteams/',
-  mcpPackage: null,
   mcpInputs: [
     {
       id: 'tenant_id',

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

@@ -0,0 +1,121 @@
+---
+name: turborepo-monorepo
+description: "Turborepo monorepo commands, pipeline configuration, caching strategies, and task orchestration. Use when running builds, tests, linting, or any development commands in a Turborepo monorepo."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+
+# Turborepo Monorepo
+
+## Commands
+
+### Running Tasks
+
+```bash
+turbo run build                    # Build all packages
+turbo run test                     # Test all packages
+turbo run lint                     # Lint all packages
+turbo run build --filter=web       # Build specific package
+turbo run build --filter=./apps/*  # Build all apps
+turbo run build --filter=...[HEAD~1]  # Only affected since last commit
+```
+
+### Common Patterns
+
+```bash
+turbo run build test lint          # Run multiple tasks
+turbo run build --dry-run          # Preview what would run
+turbo run build --graph            # Visualize task graph
+turbo run build --force            # Ignore cache, rebuild all
+turbo run build --concurrency=4    # Limit parallelism
+```
+
+### Forbidden Commands
+
+```bash
+# NEVER use these directly — always go through turbo:
+npm run build      # Skips caching and parallelism
+cd apps/web && npm test  # Skips dependency resolution
+```
+
+## Pipeline Configuration (turbo.json)
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "inputs": ["src/**", "test/**"]
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+### Key Concepts
+
+- `^build` — run `build` in dependencies first (topological)
+- `dependsOn` — declare task dependencies
+- `outputs` — files to cache (miss = rebuild)
+- `inputs` — files to hash for cache key (default: all tracked files)
+- `cache: false` — never cache (use for `dev`, `start`)
+- `persistent: true` — long-running tasks (dev servers)
+
+## Caching
+
+### Local Cache
+
+Turborepo caches task outputs automatically in `node_modules/.cache/turbo`. Cache keys are computed from:
+
+1. Task inputs (source files)
+2. Environment variables
+3. Dependencies' build outputs
+4. `turbo.json` configuration
+
+### Remote Cache
+
+```bash
+turbo login                        # Authenticate
+turbo link                         # Link project to remote cache
+turbo run build --remote-only      # Force remote cache usage
+```
+
+- Shares cache across CI and team members
+- Vercel Remote Cache or self-hosted (Ducktape, TurboCache)
+- Set `TURBO_TOKEN` and `TURBO_TEAM` in CI environment
+
+## Package Workspace Structure
+
+```
+monorepo/
+├── turbo.json
+├── package.json              # Root workspace config
+├── apps/
+│   ├── web/                  # Next.js app
+│   └── docs/                 # Documentation site
+├── packages/
+│   ├── ui/                   # Shared UI components
+│   ├── config/               # Shared config (ESLint, TS)
+│   └── utils/                # Shared utilities
+```
+
+## Best Practices
+
+- Always use `turbo run` instead of directly invoking package scripts
+- Define `outputs` for every cacheable task — missing outputs mean missing cache
+- Use `--filter` to scope commands to affected packages
+- Set `inputs` to narrow cache keys and avoid unnecessary rebuilds
+- Use `--dry-run` to debug pipeline configuration
+- Add `TURBO_TOKEN` and `TURBO_TEAM` to CI for remote caching
+- Never commit `.turbo/` or `node_modules/.cache/turbo`

package/src/orchestrator/plugins/turborepo/config.ts

@@ -0,0 +1,16 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'turborepo',
+  name: 'Turborepo',
+  category: 'tech',
+  subCategory: 'codebase-tool',
+  label: 'Turborepo',
+  hint: 'Monorepo build system with remote caching',
+  skillName: 'turborepo-monorepo',
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {},
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#turborepo',
+  officialDocs: 'https://turbo.build/repo/docs',
+};

package/src/orchestrator/plugins/types.ts

@@ -13,7 +13,7 @@ export interface PluginConfig {
   category: 'tech' | 'team';
 
   /** Sub-category for grouping */
-  subCategory: 'cms' | 'database' | 'deployment' | 'monorepo' | 'tracker' | 'notifications' | 'testing';
+  subCategory: 'cms' | 'database' | 'deployment' | 'framework' | 'codebase-tool' | 'task-management' | 'notifications' | 'testing' | 'e2e-testing' | 'design' | 'email';
 
   /** Label shown in the `npx opencastle init` multiselect */
   label: string;
@@ -24,11 +24,11 @@ export interface PluginConfig {
   /** Skill directory name (matches the old skills/ dirname). null if no skill. */
   skillName: string | null;
 
-  /** MCP server key used in the generated MCP config. null if no MCP server. */
-  mcpServerKey: string | null;
+  /** MCP server key used in the generated MCP config. Omit if no MCP server. */
+  mcpServerKey?: string;
 
-  /** Raw MCP server config */
-  mcpConfig: McpServerConfig;
+  /** Raw MCP server config (required when mcpServerKey is set) */
+  mcpConfig?: McpServerConfig;
 
   /** Authentication type */
   authType: 'oauth' | 'env-token' | 'none';
@@ -46,8 +46,8 @@ export interface PluginConfig {
   /** Official product documentation URL */
   officialDocs: string;
 
-  /** NPM package for the MCP server (null for HTTP/OAuth servers) */
-  mcpPackage: string | null;
+  /** NPM package for the MCP server (omit for HTTP/OAuth servers or plugins without MCP) */
+  mcpPackage?: string;
 
   /** Whether this plugin should be preselected in the init prompt */
   preselected?: boolean;