opencastle 0.20.0 → 0.21.0

package/src/cli/init.test.ts

@@ -31,6 +31,7 @@ import {
 } from './stack-config.js'
 import { ALL_PLUGIN_SKILL_NAMES } from '../orchestrator/plugins/index.js'
 import { IDE_ADAPTERS } from './adapters/index.js'
+import { copyDir, getOrchestratorRoot } from './copy.js'
 
 // ── Helpers ────────────────────────────────────────────────────
 
@@ -42,6 +43,16 @@ async function readJson<T = unknown>(path: string): Promise<T> {
   return JSON.parse(await readFile(path, 'utf8')) as T
 }
 
+/** Simulate the init.ts customizations scaffold step (copies customizations to .opencastle/). */
+async function scaffoldCustomizations(pkgRoot: string, projectRoot: string, stack: StackConfig): Promise<void> {
+  const custSrcDir = resolve(getOrchestratorRoot(pkgRoot), 'customizations')
+  if (existsSync(custSrcDir)) {
+    const custDestDir = join(projectRoot, '.opencastle')
+    const custTransform = getCustomizationsTransform(stack)
+    await copyDir(custSrcDir, custDestDir, { transform: custTransform })
+  }
+}
+
 /** Recursively list all files in a directory (relative paths). */
 async function listFilesRecursive(dir: string, prefix = ''): Promise<string[]> {
   if (!existsSync(dir)) return []
@@ -290,7 +301,7 @@ describe('gitignore generation', () => {
   it('creates .gitignore with framework paths ignored and customizable un-ignored', async () => {
     const managed = {
       framework: ['.github/copilot-instructions.md', '.github/agents/'],
-      customizable: ['.github/customizations/', '.vscode/mcp.json'],
+      customizable: ['.opencastle/', '.vscode/mcp.json'],
     }
 
     await updateGitignore(tempDir, managed)
@@ -300,7 +311,7 @@ describe('gitignore generation', () => {
     expect(content).toContain('.github/copilot-instructions.md')
     expect(content).toContain('.github/agents/')
     // Customizable paths should be un-ignored
-    expect(content).toContain('!.github/customizations/')
+    expect(content).toContain('!.opencastle/')
     expect(content).toContain('!.vscode/mcp.json')
     // Markers should be present
     expect(content).toContain('# >>> OpenCastle managed (do not edit) >>>')
@@ -316,14 +327,14 @@ describe('gitignore generation', () => {
 
     const managed2 = {
       framework: ['.github/agents/', '.github/skills/'],
-      customizable: ['.vscode/mcp.json', '.github/customizations/'],
+      customizable: ['.vscode/mcp.json', '.opencastle/'],
     }
     const result = await updateGitignore(tempDir, managed2)
     expect(result).toBe('updated')
 
     const content = await readFile(join(tempDir, '.gitignore'), 'utf8')
     expect(content).toContain('.github/skills/')
-    expect(content).toContain('!.github/customizations/')
+    expect(content).toContain('!.opencastle/')
     // Only one managed block
     const startCount = (content.match(/>>> OpenCastle managed/g) ?? []).length
     expect(startCount).toBe(1)
@@ -356,15 +367,15 @@ describe('VS Code adapter install', () => {
     expect(existsSync(join(githubDir, 'skills'))).toBe(true)
     expect(existsSync(join(githubDir, 'agent-workflows'))).toBe(true)
     expect(existsSync(join(githubDir, 'prompts'))).toBe(true)
-    expect(existsSync(join(githubDir, 'customizations'))).toBe(true)
     expect(existsSync(join(tempDir, '.vscode', 'mcp.json'))).toBe(true)
   })
 
-  it('creates all observability log files in customizations/logs', async () => {
+  it('creates all observability log files in .opencastle/logs', async () => {
     const adapter = await IDE_ADAPTERS['vscode']()
     await adapter.install(PKG_ROOT, tempDir, STACK_EMPTY, EMPTY_REPO_INFO)
+    await scaffoldCustomizations(PKG_ROOT, tempDir, STACK_EMPTY)
 
-    const logsDir = join(tempDir, '.github', 'customizations', 'logs')
+    const logsDir = join(tempDir, '.opencastle', 'logs')
     expect(existsSync(logsDir)).toBe(true)
     for (const file of ['events.ndjson']) {
       expect(existsSync(join(logsDir, file))).toBe(true)
@@ -516,9 +527,10 @@ describe('VS Code adapter install', () => {
   it('fills skill-matrix.json with selected DB and CMS', async () => {
     const adapter = await IDE_ADAPTERS['vscode']()
     await adapter.install(PKG_ROOT, tempDir, STACK_FULL, EMPTY_REPO_INFO)
+    await scaffoldCustomizations(PKG_ROOT, tempDir, STACK_FULL)
 
     const skillMatrix = await readFile(
-      join(tempDir, '.github', 'customizations', 'agents', 'skill-matrix.json'),
+      join(tempDir, '.opencastle', 'agents', 'skill-matrix.json'),
       'utf8'
     )
     const data = JSON.parse(skillMatrix)
@@ -533,9 +545,10 @@ describe('VS Code adapter install', () => {
   it('leaves skill-matrix.json database/cms slots empty when none selected', async () => {
     const adapter = await IDE_ADAPTERS['vscode']()
     await adapter.install(PKG_ROOT, tempDir, STACK_EMPTY, EMPTY_REPO_INFO)
+    await scaffoldCustomizations(PKG_ROOT, tempDir, STACK_EMPTY)
 
     const skillMatrix = await readFile(
-      join(tempDir, '.github', 'customizations', 'agents', 'skill-matrix.json'),
+      join(tempDir, '.opencastle', 'agents', 'skill-matrix.json'),
       'utf8'
     )
     const data = JSON.parse(skillMatrix)
@@ -554,7 +567,7 @@ describe('VS Code adapter install', () => {
     expect(paths.framework).toContain('.github/agent-workflows/')
     expect(paths.framework).toContain('.github/prompts/')
 
-    expect(paths.customizable).toContain('.github/customizations/')
+    expect(paths.customizable).toContain('.opencastle/')
     expect(paths.customizable).toContain('.vscode/mcp.json')
   })
 })
@@ -680,7 +693,7 @@ describe('Cursor adapter install', () => {
     expect(paths.framework).toContain('.cursor/rules/general.mdc')
     expect(paths.framework).toContain('.cursor/rules/ai-optimization.mdc')
 
-    expect(paths.customizable).toContain('.cursor/rules/customizations/')
+    expect(paths.customizable).toContain('.opencastle/')
     expect(paths.customizable).toContain('.cursor/mcp.json')
   })
 })
@@ -827,7 +840,7 @@ describe('Claude Code adapter install', () => {
     expect(paths.framework).toContain('.claude/skills/')
     expect(paths.framework).toContain('.claude/commands/')
 
-    expect(paths.customizable).toContain('.claude/customizations/')
+    expect(paths.customizable).toContain('.opencastle/')
     expect(paths.customizable).toContain('.claude/mcp.json')
   })
 })
@@ -867,7 +880,6 @@ describe('OpenCode adapter install', () => {
     expect(existsSync(join(tempDir, '.opencode', 'skills'))).toBe(true)
     expect(existsSync(join(tempDir, '.opencode', 'prompts'))).toBe(true)
     expect(existsSync(join(tempDir, '.opencode', 'workflows'))).toBe(true)
-    expect(existsSync(join(tempDir, '.opencode', 'customizations'))).toBe(true)
   })
 
   it('generates OpenCode MCP config with mcp format', async () => {
@@ -919,7 +931,7 @@ describe('OpenCode adapter install', () => {
     expect(paths.framework).toContain('.opencode/prompts/')
     expect(paths.framework).toContain('.opencode/workflows/')
 
-    expect(paths.customizable).toContain('.opencode/customizations/')
+    expect(paths.customizable).toContain('.opencastle/')
     expect(paths.customizable).toContain('opencode.json')
   })
 })
@@ -1078,6 +1090,7 @@ describe('full stack configuration', () => {
 
     const adapter = await IDE_ADAPTERS['vscode']()
     const result = await adapter.install(PKG_ROOT, tempDir, stack, EMPTY_REPO_INFO)
+    await scaffoldCustomizations(PKG_ROOT, tempDir, stack)
 
     expect(result.created.length).toBeGreaterThan(0)
 
@@ -1119,7 +1132,7 @@ describe('full stack configuration', () => {
 
     // Skill matrix should be filled
     const skillMatrix = await readFile(
-      join(tempDir, '.github', 'customizations', 'agents', 'skill-matrix.json'),
+      join(tempDir, '.opencastle', 'agents', 'skill-matrix.json'),
       'utf8'
     )
     const matrixData = JSON.parse(skillMatrix)

package/src/cli/init.ts

@@ -3,9 +3,9 @@ import { readFile, unlink } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { multiselect, confirm, closePrompts, c } from './prompt.js'
 import { readManifest, writeManifest, createManifest } from './manifest.js'
-import { removeDirIfExists } from './copy.js'
+import { removeDirIfExists, copyDir, getOrchestratorRoot } from './copy.js'
 import { updateGitignore } from './gitignore.js'
-import { getRequiredMcpEnvVars } from './stack-config.js'
+import { getRequiredMcpEnvVars, getCustomizationsTransform } from './stack-config.js'
 import { TECH_PLUGINS, TEAM_PLUGINS } from '../orchestrator/plugins/index.js'
 import { detectRepoInfo, mergeStackIntoRepoInfo, formatRepoInfo, buildDetectedToolsSet } from './detect.js'
 import { IDE_ADAPTERS } from './adapters/index.js'
@@ -138,7 +138,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
         console.log(`    ${c.green('+')} ${p}`)
       }
     }
-    console.log(`    ${c.green('+')} .opencastle.json`)
+    console.log(`    ${c.green('+')} .opencastle/manifest.json`)
     console.log(`    ${c.green('+')} .gitignore (OpenCastle entries)`)
     console.log(`\n  ${c.dim('No files were written.')}\n`)
     closePrompts()
@@ -217,6 +217,16 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
     }
   }
 
+  // ── Scaffold customizations to .opencastle/ ──────────────────────────────
+  const custSrcDir = resolve(getOrchestratorRoot(pkgRoot), 'customizations')
+  if (existsSync(custSrcDir)) {
+    const custDestDir = resolve(projectRoot, '.opencastle')
+    const custTransform = getCustomizationsTransform(stack)
+    const sub = await copyDir(custSrcDir, custDestDir, { transform: custTransform })
+    totalCreated += sub.created.length
+    totalSkipped += sub.skipped.length
+  }
+
   // ── Write manifest ──────────────────────────────────────────────
   const manifest = createManifest(pkg.version, ides[0], ides)
   manifest.managedPaths = allManagedPaths
@@ -311,7 +321,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
     `  ${step}. Run the ${c.cyan('"Bootstrap Customizations"')} prompt to configure for your project`
   )
   step++
-  console.log(`  ${step}. Commit the customizations/ folder to your repository`)
+  console.log(`  ${step}. Commit the .opencastle/ folder to your repository`)
   console.log()
 
   closePrompts()

package/src/cli/lesson.ts

@@ -25,7 +25,7 @@ type Severity = (typeof SEVERITIES)[number]
 const HELP = `
   opencastle lesson [options]
 
-  Append a structured lesson to .github/customizations/LESSONS-LEARNED.md
+  Append a structured lesson to .opencastle/LESSONS-LEARNED.md
 
   Required flags:
     --title <text>           Short descriptive title
@@ -70,16 +70,16 @@ async function resolveCustomizationsDir(override: string | null): Promise<string
   let dir = process.cwd()
   for (;;) {
     try {
-      const s = await stat(join(dir, '.github'))
-      if (s.isDirectory()) return join(dir, '.github', 'customizations')
+      const s = await stat(join(dir, '.opencastle'))
+      if (s.isDirectory()) return join(dir, '.opencastle')
     } catch {
-      // .github not found here, walk up
+      // .opencastle not found here, walk up
     }
     const parent = dirname(dir)
     if (parent === dir) break
     dir = parent
   }
-  return join(process.cwd(), '.github', 'customizations')
+  return join(process.cwd(), '.opencastle')
 }
 
 function nextLessonId(content: string): string {

package/src/cli/log.ts

@@ -41,22 +41,22 @@ function coerceValue(key: string, raw: string): unknown {
   return raw
 }
 
-/** Resolve the path to the logs directory (walks up to find .github/). */
+/** Resolve the path to the logs directory (walks up to find .opencastle/). */
 export async function resolveLogsDir(override?: string | null): Promise<string> {
   if (override) return override
   let dir = process.cwd()
   for (;;) {
     try {
-      const s = await stat(join(dir, '.github'))
-      if (s.isDirectory()) return join(dir, '.github', 'customizations', 'logs')
+      const s = await stat(join(dir, '.opencastle'))
+      if (s.isDirectory()) return join(dir, '.opencastle', 'logs')
     } catch {
-      // .github not in this directory, walk up
+      // .opencastle not in this directory, walk up
     }
     const parent = dirname(dir)
     if (parent === dir) break
     dir = parent
   }
-  return join(process.cwd(), '.github', 'customizations', 'logs')
+  return join(process.cwd(), '.opencastle', 'logs')
 }
 
 /** Append a structured event record to events.ndjson. */

package/src/cli/manifest.ts

@@ -1,11 +1,13 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
 import type { Manifest } from './types.js';
 
-const MANIFEST_FILE = '.opencastle.json';
+const MANIFEST_FILE = '.opencastle/manifest.json';
 
 /**
  * Read the project's OpenCastle manifest, or null if not installed.
+ * Tries the new location (.opencastle/manifest.json) first, then falls back
+ * to the legacy location (.opencastle.json) for backward compatibility.
  */
 export async function readManifest(
   projectRoot: string
@@ -17,18 +19,29 @@ export async function readManifest(
     );
     return JSON.parse(content) as Manifest;
   } catch {
-    return null;
+    // Fallback to legacy location
+    try {
+      const content = await readFile(
+        resolve(projectRoot, '.opencastle.json'),
+        'utf8'
+      );
+      return JSON.parse(content) as Manifest;
+    } catch {
+      return null;
+    }
   }
 }
 
 /**
- * Write the manifest to the project root.
+ * Write the manifest to .opencastle/manifest.json.
+ * Creates the .opencastle/ directory if it doesn't exist.
  */
 export async function writeManifest(
   projectRoot: string,
   manifest: Manifest
 ): Promise<void> {
   const path = resolve(projectRoot, MANIFEST_FILE);
+  await mkdir(dirname(path), { recursive: true });
   await writeFile(path, JSON.stringify(manifest, null, 2) + '\n');
 }
 

package/src/cli/stack-config.ts

@@ -257,20 +257,8 @@ const SUBCATEGORY_TO_SLOT: Record<string, string> = {
 /**
  * Get the filesystem path to the skill matrix file for a given IDE.
  */
-function getSkillMatrixPath(projectRoot: string, ide: string): string {
-  const relativePath = 'customizations/agents/skill-matrix.json';
-  switch (ide) {
-    case 'vscode':
-      return resolve(projectRoot, '.github', relativePath);
-    case 'cursor':
-      return resolve(projectRoot, '.cursor', 'rules', relativePath);
-    case 'claude-code':
-      return resolve(projectRoot, '.claude', relativePath);
-    case 'opencode':
-      return resolve(projectRoot, '.opencode', relativePath);
-    default:
-      return '';
-  }
+function getSkillMatrixPath(projectRoot: string, _ide: string): string {
+  return resolve(projectRoot, '.opencastle', 'agents', 'skill-matrix.json');
 }
 
 /**

package/src/cli/update.ts

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path'
 import { existsSync } from 'node:fs'
-import { readFile, appendFile, rename } from 'node:fs/promises'
+import { readFile, appendFile, rename, mkdir, writeFile, unlink, copyFile, readdir, rm } from 'node:fs/promises'
 import { readManifest, writeManifest } from './manifest.js'
 import { multiselect, confirm, closePrompts, c } from './prompt.js'
 import { isLegacyStack, migrateStackConfig, IDE_LABELS } from './types.js'
@@ -17,6 +17,8 @@ export default async function update({
 }: CliContext): Promise<void> {
   const projectRoot = process.cwd()
 
+  await migrateCustomizationsDir(projectRoot)
+
   const manifest = await readManifest(projectRoot)
   if (!manifest) {
     console.error(
@@ -326,9 +328,62 @@ export default async function update({
   closePrompts()
 }
 
+async function copyDirMigrate(srcDir: string, destDir: string): Promise<void> {
+  await mkdir(destDir, { recursive: true })
+  for (const entry of await readdir(srcDir, { withFileTypes: true })) {
+    const srcPath = resolve(srcDir, entry.name)
+    const destPath = resolve(destDir, entry.name)
+    if (entry.isDirectory()) {
+      await copyDirMigrate(srcPath, destPath)
+    } else if (!existsSync(destPath)) {
+      await copyFile(srcPath, destPath)
+    }
+  }
+}
+
+async function migrateCustomizationsDir(projectRoot: string): Promise<void> {
+  const oldManifestPath = resolve(projectRoot, '.opencastle.json')
+  const newOpencastleDir = resolve(projectRoot, '.opencastle')
+  const newManifestPath = resolve(newOpencastleDir, 'manifest.json')
+
+  // Migrate manifest from flat location to .opencastle/manifest.json
+  if (existsSync(oldManifestPath) && !existsSync(newManifestPath)) {
+    await mkdir(newOpencastleDir, { recursive: true })
+    const content = await readFile(oldManifestPath, 'utf8')
+    await writeFile(newManifestPath, content)
+    await unlink(oldManifestPath)
+    console.log(`  ${c.green('✓')} Migrated manifest to .opencastle/manifest.json`)
+  }
+
+  // Old customizations directory locations per IDE
+  const oldCustDirs = [
+    resolve(projectRoot, '.github', 'customizations'),
+    resolve(projectRoot, '.cursor', 'rules', 'customizations'),
+    resolve(projectRoot, '.claude', 'customizations'),
+    resolve(projectRoot, '.opencode', 'customizations'),
+  ]
+
+  // Copy from the first found old location (content is the same across IDEs)
+  for (const oldDir of oldCustDirs) {
+    if (!existsSync(oldDir)) continue
+    await copyDirMigrate(oldDir, newOpencastleDir)
+    console.log(`  ${c.green('✓')} Migrated customizations to .opencastle/`)
+    break
+  }
+
+  // Remove all old customizations directories
+  for (const oldDir of oldCustDirs) {
+    if (existsSync(oldDir)) {
+      await rm(oldDir, { recursive: true })
+    }
+  }
+}
+
 async function migrateLegacyLogs(projectRoot: string): Promise<void> {
-  const logsDir = resolve(projectRoot, '.github', 'customizations', 'logs')
-  if (!existsSync(logsDir)) return
+  const candidateLogsDirs = [
+    resolve(projectRoot, '.github', 'customizations', 'logs'),
+    resolve(projectRoot, '.opencastle', 'logs'),
+  ]
 
   const typeMap: Record<string, string> = {
     'sessions.ndjson': 'session',
@@ -338,48 +393,52 @@ async function migrateLegacyLogs(projectRoot: string): Promise<void> {
     'disputes.ndjson': 'dispute',
   }
 
-  const eventsFile = resolve(logsDir, 'events.ndjson')
-  let totalMigrated = 0
-
-  for (const [filename, type] of Object.entries(typeMap)) {
-    const filePath = resolve(logsDir, filename)
-    if (!existsSync(filePath)) continue
+  for (const logsDir of candidateLogsDirs) {
+    if (!existsSync(logsDir)) continue
 
-    let content: string
-    try {
-      content = await readFile(filePath, 'utf8')
-    } catch {
-      continue
-    }
+    const eventsFile = resolve(logsDir, 'events.ndjson')
+    let totalMigrated = 0
 
-    const lines = content.split('\n').filter((line) => line.trim() !== '')
-    if (lines.length === 0) continue
+    for (const [filename, type] of Object.entries(typeMap)) {
+      const filePath = resolve(logsDir, filename)
+      if (!existsSync(filePath)) continue
 
-    const migratedLines: string[] = []
-    for (const line of lines) {
+      let content: string
       try {
-        const record = JSON.parse(line) as Record<string, unknown>
-        if (!record['type']) {
-          record['type'] = type
-        }
-        migratedLines.push(JSON.stringify(record))
+        content = await readFile(filePath, 'utf8')
       } catch {
-        console.warn(`  ${c.yellow('⚠')}  Skipping malformed JSON line in ${filename}`)
+        continue
       }
-    }
 
-    if (migratedLines.length > 0) {
-      await appendFile(eventsFile, migratedLines.join('\n') + '\n', 'utf8')
-      totalMigrated += migratedLines.length
-    }
+      const lines = content.split('\n').filter((line) => line.trim() !== '')
+      if (lines.length === 0) continue
+
+      const migratedLines: string[] = []
+      for (const line of lines) {
+        try {
+          const record = JSON.parse(line) as Record<string, unknown>
+          if (!record['type']) {
+            record['type'] = type
+          }
+          migratedLines.push(JSON.stringify(record))
+        } catch {
+          console.warn(`  ${c.yellow('⚠')}  Skipping malformed JSON line in ${filename}`)
+        }
+      }
 
-    await rename(filePath, filePath + '.migrated')
-  }
+      if (migratedLines.length > 0) {
+        await appendFile(eventsFile, migratedLines.join('\n') + '\n', 'utf8')
+        totalMigrated += migratedLines.length
+      }
 
-  if (totalMigrated > 0) {
-    console.log(
-      `  ${c.green('✓')} Migrated ${c.bold(String(totalMigrated))} records from legacy log files to events.ndjson`
-    )
+      await rename(filePath, filePath + '.migrated')
+    }
+
+    if (totalMigrated > 0) {
+      console.log(
+        `  ${c.green('✓')} Migrated ${c.bold(String(totalMigrated))} records from legacy log files to events.ndjson`
+      )
+    }
   }
 }
 

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "1338aa44",
+  "hash": "efd7e9fc",
   "configHash": "30f8ea04",
-  "lockfileHash": "56ae5b5d",
-  "browserHash": "aaeb6157",
+  "lockfileHash": "851b1664",
+  "browserHash": "1b9872e1",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "2e7de42e",
+      "fileHash": "bd1b469f",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "4d71b8ca",
+      "fileHash": "796388ea",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "aa82361e",
+      "fileHash": "deadbce3",
       "needsInterop": true
     }
   },

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow Templates
 

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Bug Fix
 
@@ -29,9 +29,9 @@ Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ow
 
 ### Steps
 
-1. Check `.github/customizations/KNOWN-ISSUES.md` for existing entry
+1. Check `.opencastle/KNOWN-ISSUES.md` for existing entry
 2. Check tracker for existing bug ticket
-3. Read `.github/customizations/LESSONS-LEARNED.md` for related pitfalls
+3. Read `.opencastle/LESSONS-LEARNED.md` for related pitfalls
 4. **Reproduce the bug** — this is mandatory before any fix attempt:
    a. Start the dev server (see the **codebase-tool** skill for the serve command)
    b. Navigate to the affected page in Chrome
@@ -110,7 +110,7 @@ Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ow
 4. Test adjacent features for regressions
 5. If security-related: schedule panel review
 6. Move tracker issue to Done
-7. Update `.github/customizations/KNOWN-ISSUES.md` if the bug was listed there
+7. Update `.opencastle/KNOWN-ISSUES.md` if the bug was listed there
 8. Commit and push
 
 ### Exit Criteria

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Data Pipeline
 

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

@@ -1,10 +1,10 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Database Migration
 
 Structured workflow for database schema changes, RLS policies, and data migrations.
 
-> **Project config:** For database-specific paths, schema details, and migration conventions, see the relevant database customization file in `customizations/stack/`.
+> **Project config:** For database-specific paths, schema details, and migration conventions, see the relevant database customization file in `.opencastle/stack/`.
 
 ## Phases
 
@@ -34,8 +34,8 @@ Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ow
 
 1. Read current schema in the migrations directory (see database customization) to understand existing tables
 2. Check existing RLS policies using the database query tool
-3. Read `.github/customizations/project.instructions.md` for database architecture
-4. Check `.github/customizations/KNOWN-ISSUES.md` for database-related limitations
+3. Read `.opencastle/project.instructions.md` for database architecture
+4. Check `.opencastle/KNOWN-ISSUES.md` for database-related limitations
 5. Document the migration plan: tables affected, columns added/removed, RLS changes
 6. Write rollback strategy (how to reverse the migration)
 7. Create tracker issue with migration details and rollback plan

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Feature Implementation
 
@@ -77,7 +77,7 @@ Run the `brainstorm` prompt when the task has ambiguity, multiple valid approach
 
 ### Steps
 
-1. Read `.github/customizations/project.instructions.md`, `.github/customizations/KNOWN-ISSUES.md`, `.github/customizations/LESSONS-LEARNED.md`
+1. Read `.opencastle/project.instructions.md`, `.opencastle/KNOWN-ISSUES.md`, `.opencastle/LESSONS-LEARNED.md`
 2. Search codebase for existing implementations
 3. Identify affected apps, libs, and layers
 4. **Spec flow analysis** — Trace the complete user flow end-to-end and identify:
@@ -212,7 +212,7 @@ If there are no open questions, explicitly state: "No open questions — plan is
    - Final responsive sweep at all breakpoints (if UI changes)
 7. Move all issues to Done
 8. Update session checkpoint → delete checkpoint
-9. Update `.github/customizations/project/roadmap.md`
+9. Update `.opencastle/project/roadmap.md`
 
 ### Exit Criteria
 

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Performance Optimization
 

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

@@ -1,4 +1,4 @@
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Workflow: Code Refactoring