opencastle 0.1.0 → 0.2.0

package/src/cli/init.ts

@@ -1,7 +1,10 @@
 import { resolve } from 'node:path'
-import { readFile } from 'node:fs/promises'
+import { readFile, unlink } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { select, confirm, closePrompts } from './prompt.js'
 import { readManifest, writeManifest, createManifest } from './manifest.js'
+import { removeDirIfExists } from './copy.js'
+import { updateGitignore } from './gitignore.js'
 import type { CliContext, IdeAdapter, CmsChoice, DbChoice, PmChoice, NotifChoice, StackConfig } from './types.js'
 
 const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
@@ -11,11 +14,13 @@ const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
     import('./adapters/claude-code.js') as Promise<IdeAdapter>,
 }
 
-export default async function init({ pkgRoot }: CliContext): Promise<void> {
+export default async function init({ pkgRoot, args }: CliContext): Promise<void> {
   const projectRoot = process.cwd()
+  const dryRun = args.includes('--dry-run')
 
   // Check for existing installation
   const existing = await readManifest(projectRoot)
+  let isReinit = false
   if (existing) {
     const proceed = await confirm(
       `OpenCastle already installed (v${existing.version}, ${existing.ide}). Re-initialize?`,
@@ -25,6 +30,7 @@ export default async function init({ pkgRoot }: CliContext): Promise<void> {
       console.log('  Aborted.')
       return
     }
+    isReinit = true
   }
 
   const pkg = JSON.parse(
@@ -89,6 +95,49 @@ export default async function init({ pkgRoot }: CliContext): Promise<void> {
   console.log(`\n  Installing for ${ide}...`)
   console.log(`  Stack: CMS=${stack.cms}, DB=${stack.db}, PM=${stack.pm}, Notifications=${stack.notifications}\n`)
 
+  // ── Dry run ─────────────────────────────────────────────────────
+  if (dryRun) {
+    const adapter = await ADAPTERS[ide]()
+    const managed = adapter.getManagedPaths()
+    console.log('  [dry-run] Files that would be created:\n')
+    for (const p of managed.framework) {
+      console.log(`    + ${p}`)
+    }
+    for (const p of managed.customizable) {
+      console.log(`    + ${p}`)
+    }
+    console.log(`    + .opencastle.json`)
+    console.log(`    + .gitignore (OpenCastle entries)`)
+    console.log('\n  No files were written.\n')
+    closePrompts()
+    return
+  }
+
+  // ── Clean up previous installation on re-init ────────────────
+  if (isReinit && existing) {
+    const frameworkPaths = existing.managedPaths?.framework ?? []
+    for (const p of frameworkPaths) {
+      const fullPath = resolve(projectRoot, p)
+      if (p.endsWith('/')) {
+        await removeDirIfExists(fullPath)
+      } else if (existsSync(fullPath)) {
+        await unlink(fullPath)
+      }
+    }
+    // Remove MCP config so it gets regenerated with new stack
+    const mcpCandidates = [
+      '.vscode/mcp.json',
+      '.cursor/mcp.json',
+      '.claude/mcp.json',
+    ]
+    for (const mcpPath of mcpCandidates) {
+      const fullPath = resolve(projectRoot, mcpPath)
+      if (existsSync(fullPath)) {
+        await unlink(fullPath)
+      }
+    }
+  }
+
   // ── Run adapter ─────────────────────────────────────────────────
   const adapter = await ADAPTERS[ide]()
   const results = await adapter.install(pkgRoot, projectRoot, stack)
@@ -99,16 +148,34 @@ export default async function init({ pkgRoot }: CliContext): Promise<void> {
   manifest.stack = stack
   await writeManifest(projectRoot, manifest)
 
+  // ── Update .gitignore ───────────────────────────────────────────
+  const managedPaths = adapter.getManagedPaths()
+  const gitignoreResult = await updateGitignore(projectRoot, managedPaths)
+
   // ── Summary ─────────────────────────────────────────────────────
   const created = results.created.length
   const skipped = results.skipped.length
 
   console.log(`  ✓ Created ${created} files`)
+  if (gitignoreResult === 'created') {
+    console.log('  ✓ Created .gitignore with OpenCastle entries')
+  } else if (gitignoreResult === 'updated') {
+    console.log('  ✓ Updated .gitignore with OpenCastle entries')
+  }
   if (skipped > 0) {
     console.log(`  → Skipped ${skipped} existing files`)
   }
 
   console.log(`\n  Next steps:`)
+  if (ide === 'vscode') {
+    console.log(
+      '  0. Reload VS Code window (Cmd+Shift+P → "Reload Window") to pick up agents'
+    )
+  } else if (ide === 'cursor') {
+    console.log(
+      '  0. Reload Cursor window to pick up the new rule files'
+    )
+  }
   console.log(
     '  1. Run the "Bootstrap Customizations" prompt to configure for your project'
   )

package/src/cli/mcp.ts

@@ -6,7 +6,7 @@ import { getIncludedMcpServers } from './stack-config.js';
 import type { ScaffoldResult, StackConfig } from './types.js';
 
 /**
- * Scaffold the MCP server config into the target project.
+ * Scaffold or merge the MCP server config into the target project.
  *
  * Reads the template from `opencastle/src/orchestrator/mcp.json`,
  * writes it to `<projectRoot>/<destRelPath>` (e.g. `.vscode/mcp.json`).
@@ -14,7 +14,8 @@ import type { ScaffoldResult, StackConfig } from './types.js';
  * When a StackConfig is provided, only servers relevant to the chosen
  * CMS/DB stack (plus core servers) are included.
  *
- * This is a customizable file — scaffolded once, never overwritten on update.
+ * If the file already exists, missing servers are merged in without
+ * overwriting any existing server configs.
  */
 export async function scaffoldMcpConfig(
   pkgRoot: string,
@@ -24,10 +25,6 @@ export async function scaffoldMcpConfig(
 ): Promise<ScaffoldResult> {
   const destPath = resolve(projectRoot, destRelPath);
 
-  if (existsSync(destPath)) {
-    return { path: destPath, action: 'skipped' };
-  }
-
   const srcRoot = getOrchestratorRoot(pkgRoot);
   const templatePath = resolve(srcRoot, 'mcp.json');
   const content = await readFile(templatePath, 'utf8');
@@ -42,6 +39,34 @@ export async function scaffoldMcpConfig(
     );
   }
 
+  if (existsSync(destPath)) {
+    // Merge: add missing servers without overwriting existing ones
+    const existingContent = await readFile(destPath, 'utf8');
+    const existing = JSON.parse(existingContent) as {
+      servers?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+
+    if (!existing.servers) {
+      existing.servers = {};
+    }
+
+    let added = 0;
+    for (const [key, value] of Object.entries(template.servers)) {
+      if (!(key in existing.servers)) {
+        existing.servers[key] = value;
+        added++;
+      }
+    }
+
+    if (added === 0) {
+      return { path: destPath, action: 'skipped' };
+    }
+
+    await writeFile(destPath, JSON.stringify(existing, null, 2) + '\n');
+    return { path: destPath, action: 'created' };
+  }
+
   await mkdir(dirname(destPath), { recursive: true });
   await writeFile(destPath, JSON.stringify(template, null, 2) + '\n');
 

package/src/cli/run/schema.ts

@@ -340,11 +340,36 @@ function parseBlockScalar(lines: string[], startIdx: number, parentIndent: numbe
 
 /**
  * Parse a flow sequence: [item1, item2, item3]
+ * Handles quoted strings that may contain commas.
  */
 function parseFlowSequence(text: string): Array<string | number | boolean | null> {
   const inner = text.slice(1, -1).trim()
   if (inner === '') return []
-  return inner.split(',').map((s) => castScalar(s.trim()))
+
+  const items: string[] = []
+  let current = ''
+  let inQuote: string | null = null
+
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null
+      } else {
+        current += ch
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch
+    } else if (ch === ',') {
+      items.push(current.trim())
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current.trim()) items.push(current.trim())
+
+  return items.map(castScalar)
 }
 
 // ── Schema validation ──────────────────────────────────────────────

package/src/cli/run.ts

@@ -43,6 +43,7 @@ function parseArgs(args: string[]): RunOptions {
         break
       case '--file':
       case '-f':
+        if (i + 1 >= args.length) { console.error('  \u2717 --file requires a path'); process.exit(1) }
         opts.file = args[++i]
         break
       case '--dry-run':
@@ -50,6 +51,7 @@ function parseArgs(args: string[]): RunOptions {
         break
       case '--concurrency':
       case '-c': {
+        if (i + 1 >= args.length) { console.error('  \u2717 --concurrency requires a number'); process.exit(1) }
         const val = parseInt(args[++i], 10)
         if (!Number.isFinite(val) || val < 1) {
           console.error(`  ✗ --concurrency must be an integer >= 1`)
@@ -60,9 +62,11 @@ function parseArgs(args: string[]): RunOptions {
       }
       case '--adapter':
       case '-a':
+        if (i + 1 >= args.length) { console.error('  \u2717 --adapter requires a name'); process.exit(1) }
         opts.adapter = args[++i]
         break
       case '--report-dir':
+        if (i + 1 >= args.length) { console.error('  \u2717 --report-dir requires a path'); process.exit(1) }
         opts.reportDir = args[++i]
         break
       case '--verbose':

package/src/cli/update.ts

@@ -38,18 +38,33 @@ export default async function update({
     await readFile(resolve(pkgRoot, 'package.json'), 'utf8')
   ) as { version: string }
 
-  if (manifest.version === pkg.version && !args.includes('--force')) {
+  const dryRun = args.includes('--dry-run')
+
+  if (manifest.version === pkg.version && !args.includes('--force') && !dryRun) {
     console.log(`  Already up to date (v${pkg.version}).`)
     return
   }
 
   console.log(
-    `\n  🏰 OpenCastle update: v${manifest.version} → v${pkg.version}\n`
+    `\n  🏰 OpenCastle ${dryRun ? 'dry-run' : 'update'}: v${manifest.version} → v${pkg.version}\n`
   )
   console.log(`  IDE: ${manifest.ide}`)
   console.log('  Framework files will be overwritten.')
   console.log('  Customization files will be preserved.\n')
 
+  if (dryRun) {
+    console.log('  [dry-run] Framework files that would be updated:\n')
+    for (const p of manifest.managedPaths?.framework ?? []) {
+      console.log(`    ↻ ${p}`)
+    }
+    console.log('\n  Customization files that would be preserved:\n')
+    for (const p of manifest.managedPaths?.customizable ?? []) {
+      console.log(`    ✓ ${p}`)
+    }
+    console.log('\n  No files were written.\n')
+    return
+  }
+
   const proceed = await confirm('Proceed with update?')
   if (!proceed) {
     console.log('  Aborted.')
@@ -57,7 +72,7 @@ export default async function update({
   }
 
   const adapter = await ADAPTERS[manifest.ide]()
-  const results = await adapter.update(pkgRoot, projectRoot)
+  const results = await adapter.update(pkgRoot, projectRoot, manifest.stack)
 
   // Update manifest
   manifest.version = pkg.version

package/src/orchestrator/agent-workflows/README.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow Templates
 
 Declarative workflow templates for common orchestration patterns. Inspired by Sandcastle's YAML workflow engine, these templates provide reproducible execution plans that the Team Lead and prompts can reference.

package/src/orchestrator/agent-workflows/bug-fix.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Bug Fix
 
 Structured workflow for investigating and fixing reported bugs.

package/src/orchestrator/agent-workflows/data-pipeline.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Data Pipeline
 
 Standard execution plan for scraping, processing, and importing data.

package/src/orchestrator/agent-workflows/database-migration.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Database Migration
 
 Structured workflow for database schema changes, RLS policies, and data migrations.

package/src/orchestrator/agent-workflows/feature-implementation.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Feature Implementation
 
 Standard execution plan for multi-layer features. Customize file paths, agents, and criteria per task.

package/src/orchestrator/agent-workflows/performance-optimization.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Performance Optimization
 
 Measure-first optimization workflow. Never optimize without profiling data.

package/src/orchestrator/agent-workflows/refactoring.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Code Refactoring
 
 Structured workflow for safe code refactoring — improving code quality without changing behavior.

package/src/orchestrator/agent-workflows/schema-changes.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Schema / CMS Changes
 
 Structured workflow for CMS schema modifications, query updates, and content model changes.

package/src/orchestrator/agent-workflows/security-audit.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Workflow: Security Audit
 
 Comprehensive security review workflow for auth, RLS, headers, and API security.

package/src/orchestrator/agent-workflows/shared-delivery-phase.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Shared Delivery Phase
 
 This phase is referenced by all workflow templates. It covers the final delivery steps after all implementation and verification is complete.

package/src/orchestrator/agents/api-designer.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # API Designer
 
 You are an API designer specializing in route architecture, endpoint conventions, request/response schemas, versioning, error handling patterns, and API documentation.

package/src/orchestrator/agents/architect.agent.md

@@ -5,6 +5,8 @@ model: Claude Opus 4.6
 tools: ['search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'search', 'search/usages', 'execute/runInTerminal', 'execute/getTerminalOutput', 'read/terminalLastCommand', 'nx-mcp-server/nx_workspace', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_visualize_graph']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Software Architect
 
 You are a senior software architect specializing in strategic architecture decisions, roadmap planning, system design, and technology evaluation.

package/src/orchestrator/agents/content-engineer.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'sanity/get_schema', 'sanity/get_sanity_rules', 'sanity/list_sanity_rules', 'sanity/query_documents', 'sanity/get_document', 'sanity/create_documents_from_json', 'sanity/create_documents_from_markdown', 'sanity/patch_document_from_json', 'sanity/patch_document_from_markdown', 'sanity/deploy_schema', 'sanity/publish_documents', 'sanity/unpublish_documents', 'sanity/discard_drafts', 'sanity/list_projects', 'sanity/list_datasets', 'sanity/list_workspace_schemas', 'sanity/list_embeddings_indices', 'sanity/search_docs', 'sanity/read_docs', 'sanity/semantic_search', 'sanity/migration_guide', 'sanity/create_version', 'sanity/generate_image', 'sanity/transform_image', 'sanity/add_cors_origin']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Content Engineer
 
 You are a content engineer specializing in CMS schema design, content queries, content modeling, plugin development, and studio customization.

package/src/orchestrator/agents/copywriter.agent.md

@@ -5,6 +5,8 @@ model: GPT-5 mini
 tools: ['search/codebase', 'edit/editFiles', 'web/fetch', 'search', 'read/problems', 'search/usages', 'sanity/get_schema', 'sanity/query_documents', 'sanity/get_document', 'sanity/patch_document_from_json', 'sanity/patch_document_from_markdown', 'sanity/list_datasets', 'sanity/list_projects', 'resend/send-email']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Copywriter
 
 You are a copywriter specializing in user-facing text for web applications — UI microcopy, marketing copy, email content, SEO text, error messages, and content polish.

package/src/orchestrator/agents/data-expert.agent.md

@@ -5,6 +5,8 @@ model: GPT-5.3-Codex
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'sanity/get_schema', 'sanity/query_documents', 'sanity/create_documents_from_json', 'sanity/patch_document_from_json', 'sanity/get_document', 'sanity/list_datasets', 'sanity/list_projects']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Data Expert
 
 You are an expert in building ETL pipelines, web scrapers, data processors, and CLI tools for data ingestion.

package/src/orchestrator/agents/database-engineer.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'supabase/apply_migration', 'supabase/execute_sql', 'supabase/list_tables', 'supabase/list_migrations', 'supabase/list_extensions', 'supabase/get_logs', 'supabase/get_project', 'supabase/get_project_url', 'supabase/list_projects', 'supabase/search_docs', 'supabase/generate_typescript_types', 'supabase/get_advisors', 'supabase/create_branch', 'supabase/list_branches']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Database Engineer
 
 You are a database engineer specializing in schema design, migrations, row-level security, performance optimization, and auth integration.

package/src/orchestrator/agents/developer.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_workspace', 'nx-mcp-server/nx_generators']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Developer
 
 You are a full-stack developer specializing in building pages, components, routing, layouts, API routes, server-side logic, and feature implementation.

package/src/orchestrator/agents/devops-expert.agent.md

@@ -5,6 +5,8 @@ model: GPT-5.3-Codex
 tools: ["search/changes", "search/codebase", "edit/editFiles", "web/fetch", "vscode/getProjectSetupInfo", "vscode/installExtension", "vscode/newWorkspace", "vscode/runCommand", "read/problems", "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search", "execute/testFailure", "search/usages", "vercel/deploy_to_vercel", "vercel/get_deployment", "vercel/get_deployment_build_logs", "vercel/get_project", "vercel/get_runtime_logs", "vercel/list_deployments", "vercel/list_projects", "vercel/list_teams", "vercel/search_vercel_documentation", "vercel/check_domain_availability_and_price", "nx-mcp-server/nx_project_details", "nx-mcp-server/nx_workspace", "nx-mcp-server/nx_workspace_path"]
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # DevOps Expert
 
 You are a DevOps expert specializing in Vercel deployments, CI/CD pipelines, cron jobs, security headers, caching strategies, and build optimization.

package/src/orchestrator/agents/documentation-writer.agent.md

@@ -5,6 +5,8 @@ model: GPT-5 mini
 tools: ['search/codebase', 'edit/editFiles', 'web/fetch', 'search', 'read/problems']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Documentation Writer
 
 You are a technical documentation specialist. You maintain project documentation, roadmaps, architecture records, and technical guides.

package/src/orchestrator/agents/performance-expert.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_workspace']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Performance Expert
 
 You are an expert in frontend and backend performance optimization.

package/src/orchestrator/agents/release-manager.agent.md

@@ -5,6 +5,8 @@ model: GPT-5.3-Codex
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'vercel/get_deployment', 'vercel/get_deployment_build_logs', 'vercel/get_runtime_logs', 'vercel/list_deployments', 'vercel/list_projects', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_workspace', 'nx-mcp-server/nx_workspace_path']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Release Manager
 
 You are a release manager responsible for pre-release verification, changelog generation, version management, regression checks, and coordinating the release process.

package/src/orchestrator/agents/researcher.agent.md

@@ -5,6 +5,8 @@ model: GPT-5 mini
 tools: ['search/codebase', 'search/textSearch', 'search/fileSearch', 'search/usages', 'read/readFile', 'search/listDirectory', 'web/fetch', 'execute/runInTerminal', 'read/terminalLastCommand']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Researcher
 
 You are a codebase exploration specialist. Your job is to **find information, map patterns, and report back** — never to implement changes. You are the team's scout: fast, thorough, and focused on delivering actionable intelligence.

package/src/orchestrator/agents/reviewer.agent.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 ```chatagent
 ---
 description: 'Mandatory fast reviewer that validates every agent delegation output before acceptance. Checks acceptance criteria, file partitions, regressions, type safety, and security basics.'

package/src/orchestrator/agents/security-expert.agent.md

@@ -5,6 +5,8 @@ model: Claude Opus 4.6
 tools: ["search/changes", "search/codebase", "edit/editFiles", "web/fetch", "vscode/getProjectSetupInfo", "vscode/installExtension", "vscode/newWorkspace", "vscode/runCommand", "read/problems", "execute/getTerminalOutput", "execute/runInTerminal", "read/terminalLastCommand", "read/terminalSelection", "search", "execute/testFailure", "search/usages", "supabase/execute_sql", "supabase/list_tables", "supabase/get_advisors", "supabase/list_migrations", "supabase/get_project"]
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Security Expert
 
 You are a security expert specializing in authentication, authorization, security headers, input validation, API security, and vulnerability management for Next.js applications with Supabase.

package/src/orchestrator/agents/seo-specialist.agent.md

@@ -5,6 +5,8 @@ model: GPT-5 mini
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'search', 'search/usages', 'chrome-devtools/*']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # SEO Specialist
 
 You are an SEO specialist focused on technical SEO implementation — meta tags, structured data, sitemaps, Open Graph, crawlability, and search performance for web applications.

package/src/orchestrator/agents/team-lead.agent.md

@@ -71,6 +71,8 @@ handoffs:
     send: true
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Team Lead
 
 You are a **team lead and task orchestrator**. You do **not** implement code yourself. Your role is to:

package/src/orchestrator/agents/testing-expert.agent.md

@@ -5,6 +5,8 @@ model: GPT-5.3-Codex
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Testing Expert
 
 You are an expert tester who validates UI changes using Chrome DevTools MCP automation and writes E2E/integration test suites.
@@ -49,7 +51,7 @@ Every test suite must cover:
 - Verify server-side behavior — confirm filter changes trigger new server requests
 - Start the dev server before browser testing
 - Reload between major test flows to prevent stale state
-- **MANDATORY: Test every UI change at all three responsive breakpoints (Mobile 375px, Tablet 768px, Desktop 1440px) — never test at desktop only. Use `mcp_chrome-devtoo_resize_page()` to switch viewports. See the browser-testing skill for exact commands and per-breakpoint checklists.**
+- **MANDATORY: Test every UI change at all responsive breakpoints defined in the project's testing config — never test at desktop only. Use `mcp_chrome-devtoo_resize_page()` to switch viewports. See the browser-testing skill for exact commands and per-breakpoint checklists.**
 
 ## Critical Rules
 

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -5,6 +5,8 @@ model: Gemini 3.1 Pro
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # UI/UX Expert
 
 You are an expert UI/UX developer specializing in building accessible, visually consistent React components based on a design system template.
@@ -29,7 +31,7 @@ Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
 ## Guidelines
 
 - Design with mobile-first responsive approach
-- **Validate every UI change at all three breakpoints:** Mobile (375px), Tablet (768px), Desktop (1440px) — load the **e2e-testing** skill (resolved via matrix) for resize commands and per-breakpoint checklists
+- **Validate every UI change at all responsive breakpoints** defined in the project's testing config — load the **e2e-testing** skill (resolved via matrix) for resize commands and per-breakpoint checklists
 - Use semantic HTML before adding ARIA
 - Test with keyboard-only navigation
 - Implement hover, focus, and active states for all interactive elements
@@ -38,7 +40,7 @@ Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
 
 ## Done When
 
-- Components render correctly at all three breakpoints (375px, 768px, 1440px)
+- Components render correctly at all project-defined responsive breakpoints
 - WCAG 2.2 AA compliance verified (keyboard navigation, contrast, semantics)
 - Components are exported from the UI library index
 - Hover, focus, and active states are implemented for all interactive elements
@@ -57,7 +59,7 @@ When completing a task, return a structured summary:
 
 1. **Components** — List components created/modified with purpose
 2. **Accessibility** — WCAG checks performed and results
-3. **Responsive** — Breakpoints tested (mobile 375px, tablet 768px, desktop 1440px)
+3. **Responsive** — Breakpoints tested (per project testing config)
 4. **Visual Evidence** — Screenshots at each breakpoint
 
 See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).

package/src/orchestrator/copilot-instructions.md

@@ -1,3 +1,5 @@
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Copilot Instructions
 
 All conventions, architecture, and project context live in `.github/instructions/`. Read those files before making changes.

package/src/orchestrator/instructions/ai-optimization.instructions.md

@@ -3,6 +3,8 @@ description: 'AI assistant optimization techniques for efficient context usage a
 applyTo: '**'
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # AI Assistant Optimization Instructions
 
 ## Batch Processing

package/src/orchestrator/instructions/general.instructions.md

@@ -2,6 +2,8 @@
 applyTo: '**'
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Coding Standards
 
 ## Constitution

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -3,6 +3,8 @@ description: 'Bootstrap the .github/customizations/ directory for a new project.
 agent: Researcher
 ---
 
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+
 # Bootstrap Project Customizations
 
 You are setting up the AI agent framework for a new project. Your job is to **discover** the project's structure, tech stack, and configuration, then **generate** the customization files that skills reference for project-specific context.