opencastle 0.1.0 → 0.3.0

package/src/cli/adapters/cursor.ts

@@ -1,5 +1,5 @@
 import { resolve, basename } from 'node:path'
-import { mkdir, writeFile, readdir, readFile } from 'node:fs/promises'
+import { mkdir, writeFile, readdir, readFile, unlink } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { copyDir, getOrchestratorRoot, removeDirIfExists } from '../copy.js'
 import { scaffoldMcpConfig } from '../mcp.js'
@@ -130,13 +130,16 @@ export async function install(
   const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
   const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
 
-  // 1. .cursorrules  ← copilot-instructions.md (body only)
+  // 1. .cursorrules  ← Cursor-specific intro (not copilot-instructions.md verbatim)
   const cursorrules = resolve(projectRoot, '.cursorrules')
   if (!existsSync(cursorrules)) {
-    const { body } = stripFrontmatter(
-      await readFile(resolve(srcRoot, 'copilot-instructions.md'), 'utf8')
-    )
-    await writeFile(cursorrules, body.trim() + '\n')
+    const cursorIntro = [
+      '# Project Instructions',
+      '',
+      'All conventions, architecture, and project context live in `.cursor/rules/`. Read those files before making changes.',
+      '',
+    ].join('\n')
+    await writeFile(cursorrules, cursorIntro)
     results.created.push(cursorrules)
   } else {
     results.skipped.push(cursorrules)
@@ -166,7 +169,7 @@ export async function install(
     'agent-workflows',
     resolve(rulesRoot, 'agent-workflows'),
     results,
-    { descriptionPrefix: 'Workflow: ' }
+    { descriptionPrefix: 'Workflow: ', excludeFiles: new Set(['README.md']) }
   )
 
   // 6. Prompts → .cursor/rules/prompts/*.mdc
@@ -210,11 +213,14 @@ export async function update(
   const excludedSkills = stack ? getExcludedSkills(stack) : new Set<string>()
   const excludedAgents = stack ? getExcludedAgents(stack) : new Set<string>()
 
-  // Overwrite .cursorrules
-  const { body } = stripFrontmatter(
-    await readFile(resolve(srcRoot, 'copilot-instructions.md'), 'utf8')
-  )
-  await writeFile(resolve(projectRoot, '.cursorrules'), body.trim() + '\n')
+  // Overwrite .cursorrules with Cursor-specific intro
+  const cursorIntro = [
+    '# Project Instructions',
+    '',
+    'All conventions, architecture, and project context live in `.cursor/rules/`. Read those files before making changes.',
+    '',
+  ].join('\n')
+  await writeFile(resolve(projectRoot, '.cursorrules'), cursorIntro)
   results.copied.push('.cursorrules')
 
   const rulesRoot = resolve(projectRoot, '.cursor', 'rules')
@@ -225,6 +231,15 @@ export async function update(
     await removeDirIfExists(resolve(rulesRoot, dir))
   }
 
+  // Remove stale root-level instruction .mdc files (in case instructions were renamed)
+  if (existsSync(rulesRoot)) {
+    for (const file of await readdir(rulesRoot)) {
+      if (file.endsWith('.mdc')) {
+        await unlink(resolve(rulesRoot, file))
+      }
+    }
+  }
+
   // Overwrite framework rules
   await convertDir(srcRoot, 'instructions', rulesRoot, results, {
     alwaysApply: true,
@@ -243,7 +258,7 @@ export async function update(
     'agent-workflows',
     resolve(rulesRoot, 'agent-workflows'),
     results,
-    { descriptionPrefix: 'Workflow: ', overwrite: true }
+    { descriptionPrefix: 'Workflow: ', overwrite: true, excludeFiles: new Set(['README.md']) }
   )
   await convertDir(
     srcRoot,

package/src/cli/dashboard.ts

@@ -78,16 +78,21 @@ function tryListen(
     let attempt = 0
 
     function attemptListen(): void {
-      server.listen(port + attempt, '127.0.0.1', () => {
-        res(port + attempt)
-      })
-      server.once('error', (err: Error & { code?: string }) => {
+      const currentPort = port + attempt
+
+      const onError = (err: Error & { code?: string }): void => {
         if (err.code === 'EADDRINUSE' && attempt < maxAttempts) {
           attempt++
           attemptListen()
         } else {
           rej(err)
         }
+      }
+
+      server.once('error', onError)
+      server.listen(currentPort, '127.0.0.1', () => {
+        server.removeListener('error', onError)
+        res(currentPort)
       })
     }
 

package/src/cli/eject.ts

@@ -6,9 +6,10 @@ import type { CliContext } from './types.js'
 
 export default async function eject({
   pkgRoot: _pkgRoot,
-  args: _args,
+  args,
 }: CliContext): Promise<void> {
   const projectRoot = process.cwd()
+  const dryRun = args.includes('--dry-run')
 
   const manifest = await readManifest(projectRoot)
   if (!manifest) {
@@ -24,6 +25,11 @@ export default async function eject({
     '    • You can safely uninstall the opencastle package after this\n'
   )
 
+  if (dryRun) {
+    console.log('  [dry-run] No files were changed.\n')
+    return
+  }
+
   const proceed = await confirm('Continue?')
   if (!proceed) {
     console.log('  Aborted.')

package/src/cli/gitignore.ts

@@ -0,0 +1,77 @@
+import { resolve } from 'node:path'
+import { readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import type { ManagedPaths } from './types.js'
+
+const START_MARKER = '# >>> OpenCastle managed (do not edit) >>>'
+const END_MARKER = '# <<< OpenCastle managed <<<'
+
+/**
+ * Build the gitignore block for OpenCastle-managed files.
+ *
+ * Ignores all framework-managed paths plus the manifest file.
+ * Explicitly un-ignores customizable directories so user edits
+ * are committed even when a parent directory is ignored.
+ */
+function buildBlock(managed: ManagedPaths): string {
+  const lines: string[] = [START_MARKER]
+
+  // Framework-managed paths (overwritten on `opencastle update`)
+  for (const p of managed.framework) {
+    lines.push(p)
+  }
+
+  // Manifest file
+  lines.push('.opencastle.json')
+
+  // Un-ignore customizable paths so they stay tracked
+  for (const p of managed.customizable) {
+    lines.push(`!${p}`)
+  }
+
+  lines.push(END_MARKER)
+  return lines.join('\n')
+}
+
+/**
+ * Create or update the project's `.gitignore` with OpenCastle entries.
+ *
+ * - If no `.gitignore` exists, creates one with the managed block.
+ * - If `.gitignore` exists but has no OpenCastle block, appends it.
+ * - If `.gitignore` already contains an OpenCastle block, replaces it
+ *   (handles re-init or IDE switch cleanly).
+ */
+export async function updateGitignore(
+  projectRoot: string,
+  managed: ManagedPaths
+): Promise<'created' | 'updated' | 'unchanged'> {
+  const gitignorePath = resolve(projectRoot, '.gitignore')
+  const block = buildBlock(managed)
+
+  if (!existsSync(gitignorePath)) {
+    await writeFile(gitignorePath, block + '\n', 'utf8')
+    return 'created'
+  }
+
+  const existing = await readFile(gitignorePath, 'utf8')
+
+  // Replace existing block
+  const startIdx = existing.indexOf(START_MARKER)
+  const endIdx = existing.indexOf(END_MARKER)
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    const before = existing.slice(0, startIdx)
+    const after = existing.slice(endIdx + END_MARKER.length)
+    const updated = before + block + after
+
+    if (updated === existing) return 'unchanged'
+
+    await writeFile(gitignorePath, updated, 'utf8')
+    return 'updated'
+  }
+
+  // Append block to existing file
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n'
+  await writeFile(gitignorePath, existing + separator + block + '\n', 'utf8')
+  return 'updated'
+}

package/src/cli/init.ts

@@ -1,7 +1,11 @@
 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 { getRequiredMcpEnvVars } from './stack-config.js'
 import type { CliContext, IdeAdapter, CmsChoice, DbChoice, PmChoice, NotifChoice, StackConfig } from './types.js'
 
 const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
@@ -11,11 +15,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 +31,7 @@ export default async function init({ pkgRoot }: CliContext): Promise<void> {
       console.log('  Aborted.')
       return
     }
+    isReinit = true
   }
 
   const pkg = JSON.parse(
@@ -89,6 +96,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,21 +149,54 @@ 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`)
   }
 
+  // ── Env var notice ──────────────────────────────────────────────
+  const envVars = getRequiredMcpEnvVars(stack)
+  if (envVars.length > 0) {
+    console.log(`\n  ⚠  Required environment variables for MCP servers:\n`)
+    for (const { envVar, hint } of envVars) {
+      console.log(`     ${envVar}`)
+      console.log(`     └ ${hint}\n`)
+    }
+  }
+
   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'
+    )
+  }
+  if (envVars.length > 0) {
+    console.log(
+      `  1. Set the environment variable${envVars.length > 1 ? 's' : ''} listed above`
+    )
+  }
   console.log(
-    '  1. Run the "Bootstrap Customizations" prompt to configure for your project'
+    `  ${envVars.length > 0 ? '2' : '1'}. Run the "Bootstrap Customizations" prompt to configure for your project`
   )
-  console.log('  2. Customize agent definitions for your tech stack')
-  console.log('  3. Commit the generated files to your repository')
+  console.log(`  ${envVars.length > 0 ? '3' : '2'}. Customize agent definitions for your tech stack`)
+  console.log(`  ${envVars.length > 0 ? '4' : '3'}. Commit the generated files to your repository`)
   console.log()
 
   closePrompts()

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/stack-config.ts

@@ -105,6 +105,30 @@ const NOTIF_MCP_MAP: Record<NotifChoice, string[]> = {
 /** Always-included MCP servers */
 const CORE_MCP_SERVERS = ['chrome-devtools', 'Vercel'];
 
+// ── MCP environment variable requirements ─────────────────────
+
+export interface McpEnvRequirement {
+  /** MCP server key (must match mcp.json) */
+  server: string;
+  /** Environment variable name */
+  envVar: string;
+  /** Short description of where to get the key */
+  hint: string;
+}
+
+/**
+ * Registry of MCP servers that require API keys via environment variables.
+ * Only servers with `env` fields in mcp.json need to be listed here.
+ * HTTP-based servers (Sanity, Slack, Vercel, etc.) handle auth via OAuth.
+ */
+const MCP_ENV_REQUIREMENTS: McpEnvRequirement[] = [
+  {
+    server: 'Linear',
+    envVar: 'LINEAR_API_KEY',
+    hint: 'Create at linear.app → Settings → API → Personal API keys',
+  },
+];
+
 export function getExcludedSkills(stack: StackConfig): Set<string> {
   return new Set([
     ...CMS_SKILL_MAP[stack.cms],
@@ -131,6 +155,15 @@ export function getIncludedMcpServers(stack: StackConfig): Set<string> {
   ]);
 }
 
+/**
+ * Returns env var requirements for the MCP servers included in the stack.
+ * Only returns entries for servers that actually need API keys.
+ */
+export function getRequiredMcpEnvVars(stack: StackConfig): McpEnvRequirement[] {
+  const included = getIncludedMcpServers(stack);
+  return MCP_ENV_REQUIREMENTS.filter((req) => included.has(req.server));
+}
+
 // ── Customization file transforms ─────────────────────────────
 
 /**

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.