opencastle 0.20.0 → 0.21.0

package/src/orchestrator/prompts/resolve-pr-comments.prompt.md

@@ -3,7 +3,7 @@ description: 'Resolve GitHub PR review comments by reading them, grouping by fil
 agent: 'Team Lead (OpenCastle)'
 ---
 
-<!-- ⚠️ 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. -->
 
 # Resolve PR Comments
 

package/src/orchestrator/skills/accessibility-standards/SKILL.md

@@ -3,7 +3,7 @@ name: accessibility-standards
 description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, and inclusive language."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Accessibility Standards
 

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -3,7 +3,7 @@ name: agent-hooks
 description: "Lifecycle hooks for AI agent sessions — reusable actions that run at specific points (session start, session end, pre-delegation, post-delegation). Defines what to do at each lifecycle event so agents behave consistently."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Agent Lifecycle Hooks
 
@@ -28,11 +28,11 @@ Session Lifecycle:
 
 ### Actions
 
-1. **Read lessons learned** — Scan `.github/customizations/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
-2. **Check for checkpoint** — If `.github/customizations/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
+1. **Read lessons learned** — Scan `.opencastle/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
+2. **Check for checkpoint** — If `.opencastle/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
 3. **Check pending approvals** — If the checkpoint has a `## Pending Approvals` section, check for replies using the configured messaging provider's MCP tools (e.g., `conversations_replies` for Slack). Read `.opencastle.json` → `stack.teamTools` to determine the provider. If no messaging is configured, skip this step.
-4. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures related to the current scope.
-5. **Validate skill-matrix bindings** — Open `.github/customizations/agents/skill-matrix.json` and check whether the `bindings` object has any slots with non-empty `entries` arrays. If all entries are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
+4. **Check dead letter queue** — Scan `.opencastle/AGENT-FAILURES.md` for pending failures related to the current scope.
+5. **Validate skill-matrix bindings** — Open `.opencastle/agents/skill-matrix.json` and check whether the `bindings` object has any slots with non-empty `entries` arrays. If all entries are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
 6. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
 
 ### Template for Delegation Prompts
@@ -40,10 +40,10 @@ Session Lifecycle:
 Include this reminder in every delegation:
 
 ```
-**Session Start:** Read `.github/customizations/LESSONS-LEARNED.md` before starting.
-Check `.github/customizations/SESSION-CHECKPOINT.md` for prior state and pending approvals.
+**Session Start:** Read `.opencastle/LESSONS-LEARNED.md` before starting.
+Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals.
 If pending approvals exist, check for replies via the messaging provider.
-Validate `.github/customizations/agents/skill-matrix.json` — warn if skill bindings are empty (bootstrap not run).
+Validate `.opencastle/agents/skill-matrix.json` — warn if skill bindings are empty (bootstrap not run).
 Load relevant skills before writing code.
 ```
 
@@ -60,7 +60,7 @@ Load relevant skills before writing code.
 
 1. **Call Session Guard** (Team Lead only) — Delegate to the **Session Guard** agent with a session summary (delegations, retries, discoveries, files changed). Execute any fix commands it returns. This replaces the manual Pre-Response Quality Gate checklist — the guard runs it automatically with a fresh context window.
 2. **For specialist agents** (not Team Lead) — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill manually. Specialist agents don't have access to the Session Guard.
-3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.github/customizations/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
+3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.opencastle/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
 4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
 5. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
 

package/src/orchestrator/skills/agent-memory/SKILL.md

@@ -3,7 +3,7 @@ name: agent-memory
 description: "Agent expertise tracking and cross-session knowledge graph. Use when delegating tasks to track agent strengths/weaknesses, or when building context about file relationships and patterns."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Agent Memory Protocol
 
@@ -13,7 +13,7 @@ Track which agents have expertise with which files, patterns, and tools across s
 
 ## Expertise File
 
-Location: `.github/customizations/AGENT-EXPERTISE.md` — a structured record of agent performance per domain.
+Location: `.opencastle/AGENT-EXPERTISE.md` — a structured record of agent performance per domain.
 
 Template structure:
 
@@ -49,7 +49,7 @@ Template structure:
 
 ## Memory Retrieval Protocol
 
-1. Before delegating, check `.github/customizations/AGENT-EXPERTISE.md` for the candidate agent
+1. Before delegating, check `.opencastle/AGENT-EXPERTISE.md` for the candidate agent
 2. If the task matches a Strong Area, include in the prompt: *"You have prior experience with [area] from [TAS-XX]. Apply the same patterns."*
 3. If the task matches a Weak Area, either: (a) add extra context to the prompt to compensate, or (b) consider a different agent
 4. If the file has high familiarity, mention it: *"You've worked on [file] before in [TAS-XX]."*
@@ -102,7 +102,7 @@ Capture structured relationships between concepts, files, agents, and decisions.
 
 ### Knowledge Graph File
 
-Location: `.github/customizations/KNOWLEDGE-GRAPH.md` — an append-only relationship log.
+Location: `.opencastle/KNOWLEDGE-GRAPH.md` — an append-only relationship log.
 
 Template structure:
 

package/src/orchestrator/skills/api-patterns/SKILL.md

@@ -3,11 +3,11 @@ name: api-patterns
 description: "API design patterns for route handlers, Server Actions, Zod validation, and external API integration. Use when creating API routes, Server Actions, or integrating external services."
 ---
 
-<!-- ⚠️ 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. -->
 
 # API Patterns
 
-Generic API design patterns for server-rendered framework projects. For project-specific endpoints, actions, and external API inventory, see [api-config.md](../../customizations/stack/api-config.md).
+Generic API design patterns for server-rendered framework projects. For project-specific endpoints, actions, and external API inventory, see [api-config.md](../../.opencastle/stack/api-config.md).
 
 ## Architecture
 

package/src/orchestrator/skills/code-commenting/SKILL.md

@@ -3,7 +3,7 @@ name: code-commenting
 description: "Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. Use when writing or reviewing code comments."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Self-explanatory Code Commenting
 

package/src/orchestrator/skills/context-map/SKILL.md

@@ -3,7 +3,7 @@ name: context-map
 description: "Generate a structured file impact map before making changes. Identifies all files that will be affected, their relationships, and cascade effects — improving file partitioning for parallel work and reducing unexpected side effects."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Skill: Context Map
 

package/src/orchestrator/skills/data-engineering/SKILL.md

@@ -3,11 +3,11 @@ name: data-engineering
 description: "Data pipeline ETL workflows, web scraping, NDJSON processing, and CMS data import. Use when building scrapers, processing data, running CLI tools, or importing to a CMS."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Data Engineering
 
-Generic data pipeline patterns and scraping methodology. For project-specific pipeline architecture, sources, CLI commands, and data status, see [data-pipeline-config.md](../../customizations/stack/data-pipeline-config.md).
+Generic data pipeline patterns and scraping methodology. For project-specific pipeline architecture, sources, CLI commands, and data status, see [data-pipeline-config.md](../../.opencastle/stack/data-pipeline-config.md).
 
 ## Scraper Architecture
 

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -70,7 +70,7 @@ Return a structured summary with:
 **Note:** Follow the Structured Output Contract from the team-lead-reference skill. Include all standard fields plus agent-specific extensions.
 
 ### Self-Improvement
-Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
+Read `.opencastle/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
 ```
 
 For simpler tasks (score 1-3), the existing prompt format (objective + files + criteria) is sufficient. Don't over-engineer delegation for trivial work.

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -3,11 +3,11 @@ name: deployment-infrastructure
 description: "Deployment architecture, environment variables, cron jobs, security headers, and caching patterns. Use when configuring deployments, managing environment variables, setting up cron jobs, or troubleshooting build/deployment issues."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Deployment Infrastructure
 
-All deployment configuration is project-specific. See [deployment-config.md](../../customizations/stack/deployment-config.md) for the full architecture, environment variables, cron jobs, caching headers, and key files.
+All deployment configuration is project-specific. See [deployment-config.md](../../.opencastle/stack/deployment-config.md) for the full architecture, environment variables, cron jobs, caching headers, and key files.
 
 ## Generic Deployment Principles
 

package/src/orchestrator/skills/documentation-standards/SKILL.md

@@ -3,11 +3,11 @@ name: documentation-standards
 description: "Documentation templates, structure, and standards for project docs, roadmaps, ADRs, and known issues. Use when writing or updating documentation files."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Documentation Standards
 
-Generic documentation templates and writing standards. For project-specific directory structure and practices, see [docs-structure.md](../../customizations/project/docs-structure.md).
+Generic documentation templates and writing standards. For project-specific directory structure and practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
 
 ## Issue Documentation Template
 

package/src/orchestrator/skills/fast-review/SKILL.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. -->
 
 ````skill
 ---
@@ -155,7 +155,7 @@ CONFIDENCE: low | medium | high
 4. The panel decides PASS/BLOCK with the standard majority vote protocol
 5. If panel PASS → accept with a note that it required escalation
 6. If panel BLOCK → follow the standard panel retry flow (max 3 panel attempts)
-7. If panel BLOCKs 3 times → create a **dispute record** in `.github/customizations/DISPUTES.md` (see **team-lead-reference** skill § Dispute Protocol)
+7. If panel BLOCKs 3 times → create a **dispute record** in `.opencastle/DISPUTES.md` (see **team-lead-reference** skill § Dispute Protocol)
 
 ```
 Fast Review Attempt 1: FAIL → retry

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -4,7 +4,7 @@ description: "Create distinctive, production-grade frontend interfaces with high
 license: Complete terms in LICENSE.txt
 ---
 
-<!-- ⚠️ 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. -->
 
 This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
 

package/src/orchestrator/skills/git-workflow/SKILL.md

@@ -46,11 +46,11 @@ Every task that produces code changes — whether a roadmap feature, bug fix, fo
 When you encounter a bug, error, or unexpected behavior that is unrelated to the current task:
 
 1. **Check if already tracked:**
-   - Search `.github/customizations/KNOWN-ISSUES.md` for a matching entry
+   - Search `.opencastle/KNOWN-ISSUES.md` for a matching entry
    - If you have task tracker tools available, also search for open bugs (use `search_issues` or `list_issues` with bug label)
 2. **If found tracked** — skip it, continue with your current work
 3. **If NOT tracked** — you must act:
-   - **Unfixable limitation** (third-party constraint, platform restriction, upstream dependency) → add it to `.github/customizations/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Unfixable limitation** (third-party constraint, platform restriction, upstream dependency) → add it to `.opencastle/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
    - **Fixable bug** → if you have task tracker tools, create a ticket with label `bug`, appropriate priority, and a clear description of the symptoms, reproduction steps, and affected files. If you do NOT have task tracker tools, add a `**Discovered Issues**` section to your output listing the bug details so the Team Lead can track it.
 
 Never assume a pre-existing issue is somebody else's problem. If it's not tracked, track it.

package/src/orchestrator/skills/memory-merger/SKILL.md

@@ -3,7 +3,7 @@ name: memory-merger
 description: "Protocol for graduating mature lessons from LESSONS-LEARNED.md into permanent instruction and skill files. Closes the self-improvement loop by codifying validated knowledge at the source level."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Skill: Memory Merger
 
@@ -11,7 +11,7 @@ This skill automates the final step of the self-improvement cycle: promoting val
 
 ## Why Merge?
 
-`.github/customizations/LESSONS-LEARNED.md` is a flatfile that grows over time. Lessons buried in a 400+ line file lose their impact — agents skim past them or miss relevant entries. The most valuable lessons should **graduate** into the instruction/skill files where they're encountered naturally during every task.
+`.opencastle/LESSONS-LEARNED.md` is a flatfile that grows over time. Lessons buried in a 400+ line file lose their impact — agents skim past them or miss relevant entries. The most valuable lessons should **graduate** into the instruction/skill files where they're encountered naturally during every task.
 
 ## When to Run
 
@@ -27,7 +27,7 @@ Invoke a memory merge when:
 
 ### Step 1: Scan for Merge Candidates
 
-Read `.github/customizations/LESSONS-LEARNED.md` and identify lessons that meet any of these criteria:
+Read `.opencastle/LESSONS-LEARNED.md` and identify lessons that meet any of these criteria:
 
 | Criterion | Signal |
 |-----------|--------|

package/src/orchestrator/skills/observability-logging/SKILL.md

@@ -19,11 +19,11 @@ description: "Session logging, delegation records, review/panel/dispute NDJSON l
 |------|------------|------------|------|
 | `events.ndjson` | `session`, `delegation`, `review`, `panel`, `dispute` | All agents / Team Lead / Panel runner | After every applicable event — use `--type` to discriminate |
 
-See `.github/customizations/logs/README.md` for the full schema of each record type.
+See `.opencastle/logs/README.md` for the full schema of each record type.
 
 ### How to log
 
-Use the `opencastle log` CLI to append events to `.github/customizations/logs/events.ndjson`. When the Team Lead works directly, use the agent role that best describes the work (e.g., `--agent Developer`, `--agent "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
+Use the `opencastle log` CLI to append events to `.opencastle/logs/events.ndjson`. When the Team Lead works directly, use the agent role that best describes the work (e.g., `--agent Developer`, `--agent "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
 
 **Session record** (ALL agents, EVERY session):
 ```sh
@@ -39,7 +39,7 @@ opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
   --tracker_issue PRJ-57 --outcome success --retries 0 --phase 2 \
   --file_partition "src/components/"
 ```
-Verify: `tail -1 .github/customizations/logs/events.ndjson`
+Verify: `tail -1 .opencastle/logs/events.ndjson`
 
 > **`model` and `tier` must reflect the delegated agent's assignment from the agent registry** — not the Team Lead's own model.
 
@@ -50,7 +50,7 @@ opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
   --issues_critical 0 --issues_major 0 --issues_minor 2 \
   --confidence high --escalated false --duration_sec 45
 ```
-Verify: `tail -1 .github/customizations/logs/events.ndjson`
+Verify: `tail -1 .opencastle/logs/events.ndjson`
 
 **Panel record** (Panel runner, **immediately after each panel majority vote**):
 ```sh
@@ -59,7 +59,7 @@ opencastle log --type panel --panel_key auth-review --verdict pass \
   --reviewer_model claude-opus-4-6 --weighted false --attempt 1 \
   --tracker_issue PRJ-42 --artifacts_count 5
 ```
-Verify: `tail -1 .github/customizations/logs/events.ndjson`
+Verify: `tail -1 .opencastle/logs/events.ndjson`
 
 **Dispute record** (Team Lead, **immediately after each dispute**):
 ```sh
@@ -67,7 +67,7 @@ opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
   --priority high --trigger panel-3x-block --implementing_agent Developer \
   --reviewing_agents "Reviewer,Panel (3x)" --total_attempts 6 --status pending
 ```
-Verify: `tail -1 .github/customizations/logs/events.ndjson`
+Verify: `tail -1 .opencastle/logs/events.ndjson`
 
 ### Pre-Response Logging Checklist
 
@@ -94,8 +94,8 @@ These rules apply to ALL specialist agents automatically. **Do not duplicate the
 
 1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents. If work requires another domain, document the need in your output contract.
 2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see the **git-workflow** skill).
-3. **Read and update lessons** — Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
-4. **Log every session** — Append to `.github/customizations/logs/events.ndjson` after every session using `opencastle log --type session ...`. No exceptions. This is Constitution rule #6 — a blocking gate, not optional.
+3. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
+4. **Log every session** — Append to `.opencastle/logs/events.ndjson` after every session using `opencastle log --type session ...`. No exceptions. This is Constitution rule #6 — a blocking gate, not optional.
 
 ## Base Output Contract
 
@@ -108,7 +108,7 @@ Every specialist agent's Output Contract MUST end with these standard items (in
   - `--type panel` — if panel reviews occurred
   - `--type dispute` — if disputes were created
 - **Discovered Issues** — Pre-existing bugs or anomalies found during work, with tracking action taken per the Discovered Issues Policy
-- **Lessons Applied** — Lessons from `.github/customizations/LESSONS-LEARNED.md` that influenced this work, and any new lessons added
+- **Lessons Applied** — Lessons from `.opencastle/LESSONS-LEARNED.md` that influenced this work, and any new lessons added
 
 Agents reference this contract with: `See **Base Output Contract** in the observability-logging skill for the standard closing items.`
 
@@ -118,7 +118,7 @@ Agents reference this contract with: `See **Base Output Contract** in the observ
 
 This is the single exit gate for every session. All items are mandatory unless marked conditional.
 
-- [ ] **Lessons read** — `.github/customizations/LESSONS-LEARNED.md` was read at session start (Self-Improvement Protocol)
+- [ ] **Lessons read** — `.opencastle/LESSONS-LEARNED.md` was read at session start (Self-Improvement Protocol)
 - [ ] **Lessons captured** — If any retry occurred, a new lesson was added via the **self-improvement** skill
 - [ ] **Discovered issues tracked** — Any pre-existing bugs found were added to `KNOWN-ISSUES.md` or a tracker ticket was created (Discovered Issues Policy)
 - [ ] **Lint/type/test pass** — No new errors introduced; verification ran after code changes (Constitution rule #5)

package/src/orchestrator/skills/orchestration-protocols/SKILL.md

@@ -113,7 +113,7 @@ Monitor delegated agents for failure signals. Intervene early rather than waitin
 
 1. **First failure:** Re-delegate with more specific prompt + error context
 2. **Second failure:** Downscope the task (split into smaller pieces) and re-delegate
-3. **Third failure:** Log to Dead Letter Queue (`.github/customizations/AGENT-FAILURES.md`), escalate to Architect for root cause analysis. If the failure involves a panel 3x BLOCK or unresolvable agent/reviewer conflict, create a **dispute record** in `.github/customizations/DISPUTES.md` instead (see **team-lead-reference** skill § Dispute Protocol).
+3. **Third failure:** Log to Dead Letter Queue (`.opencastle/AGENT-FAILURES.md`), escalate to Architect for root cause analysis. If the failure involves a panel 3x BLOCK or unresolvable agent/reviewer conflict, create a **dispute record** in `.opencastle/DISPUTES.md` instead (see **team-lead-reference** skill § Dispute Protocol).
 
 ## Error Recovery Playbook
 

package/src/orchestrator/skills/panel-majority-vote/SKILL.md

@@ -3,7 +3,7 @@ name: panel-majority-vote
 description: "Run 3 isolated reviewer sub-agents against the same question and decide PASS/BLOCK by majority vote (2/3 wins). Use when deterministic verification is insufficient."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Skill: Panel majority vote (3 reviewers)
 
@@ -91,7 +91,7 @@ Finally: ensure whatever produced the claim being verified links the consolidate
 
 ## Notes
 - If the panel output is BLOCK, prefer to change the underlying work and re-run the same panel question over re-wording the question.
-- After 3 consecutive BLOCKs on the same panel key, create a **dispute record** in `.github/customizations/DISPUTES.md` instead of retrying further. The dispute packages the agent's position, all reviewer feedback, attempt history, and resolution options for human decision-making. See the **team-lead-reference** skill § Dispute Protocol for the full procedure.
+- After 3 consecutive BLOCKs on the same panel key, create a **dispute record** in `.opencastle/DISPUTES.md` instead of retrying further. The dispute packages the agent's position, all reviewer feedback, attempt history, and resolution options for human decision-making. See the **team-lead-reference** skill § Dispute Protocol for the full procedure.
 
 ## Model Selection for Reviewers
 

package/src/orchestrator/skills/panel-majority-vote/panel-report.template.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. -->
 
 # Panel Report
 

package/src/orchestrator/skills/performance-optimization/SKILL.md

@@ -3,7 +3,7 @@ name: performance-optimization
 description: "Frontend and backend performance optimization patterns including rendering, asset optimization, JavaScript performance, caching, profiling, and code review checklist. Use when optimizing components, reviewing code for performance, or analyzing bundle size and Core Web Vitals."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Performance Optimization
 

package/src/orchestrator/skills/react-development/SKILL.md

@@ -3,7 +3,7 @@ name: react-development
 description: "React development standards for functional components, hooks, TypeScript integration, state management, styling, and testing patterns. Use when creating or modifying React components, custom hooks, or component tests."
 ---
 
-<!-- ⚠️ 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. -->
 
 # React Development Standards
 

package/src/orchestrator/skills/security-hardening/SKILL.md

@@ -3,7 +3,7 @@ name: security-hardening
 description: "Security architecture including authentication, authorization, RLS policies, security headers, CSP, input validation, API security, and OAuth patterns. Use when implementing auth flows, writing RLS policies, configuring security headers, validating inputs, or auditing security."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Security Hardening
 

package/src/orchestrator/skills/self-improvement/SKILL.md

@@ -3,7 +3,7 @@ name: self-improvement
 description: "Protocol for reading and updating the lessons-learned knowledge base. MUST be followed by ALL agents — read lessons before work, write lessons after retries. This makes the agent team self-improving across sessions."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Self-Improvement Protocol
 
@@ -15,7 +15,7 @@ This skill defines how agents learn from mistakes and share knowledge so the sam
 
 ## The Lessons File
 
-Location: `.github/customizations/LESSONS-LEARNED.md`
+Location: `.opencastle/LESSONS-LEARNED.md`
 
 This is the team's collective memory — a structured log of tool/command pitfalls, workarounds, and correct approaches discovered through execution.
 

package/src/orchestrator/skills/seo-patterns/SKILL.md

@@ -3,7 +3,7 @@ name: seo-patterns
 description: "Technical SEO patterns for meta tags, structured data, sitemaps, URL strategy, and rendering. Use when optimizing pages for search engines or implementing SEO features."
 ---
 
-<!-- ⚠️ 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. -->
 
 # SEO Patterns
 

package/src/orchestrator/skills/session-checkpoints/SKILL.md

@@ -3,7 +3,7 @@ name: session-checkpoints
 description: "Protocol for saving and restoring session state across agent sessions. Enables replay, fork, and resume of interrupted work — inspired by Sandcastle Run Time Machine."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Skill: Session Checkpoints
 
@@ -21,7 +21,7 @@ Create a checkpoint:
 
 ## Checkpoint Format
 
-Create or update the file `.github/customizations/SESSION-CHECKPOINT.md` with this structure:
+Create or update the file `.opencastle/SESSION-CHECKPOINT.md` with this structure:
 
 ```markdown
 # Session Checkpoint
@@ -93,7 +93,7 @@ Track each delegation to monitor budget and optimize future model assignments:
 ```
 Agent A: dir1/, dir2/
 Agent B: dir3/, dir4/
-Agent C: .github/customizations/
+Agent C: .opencastle/
 ```
 
 ## Resume Instructions
@@ -109,7 +109,7 @@ Step-by-step instructions for a new session to pick up where this one left off:
 
 When starting a new session:
 
-1. **Check for checkpoint** — Read `.github/customizations/SESSION-CHECKPOINT.md` if it exists
+1. **Check for checkpoint** — Read `.opencastle/SESSION-CHECKPOINT.md` if it exists
 2. **Verify state** — Run `git status`, check branch, verify files match checkpoint
 3. **Check tracker** — List in-progress and todo issues for current feature
 4. **Follow resume instructions** — Execute the specific steps listed in the checkpoint
@@ -120,7 +120,7 @@ When starting a new session:
 After a feature is fully complete (all tracker issues Done):
 
 1. Archive the checkpoint content to the relevant tracker issue comments
-2. Delete `.github/customizations/SESSION-CHECKPOINT.md` to keep the workspace clean
+2. Delete `.opencastle/SESSION-CHECKPOINT.md` to keep the workspace clean
 3. The next feature starts with a fresh checkpoint
 
 ## Integration with Team Lead

package/src/orchestrator/skills/team-lead-reference/SKILL.md

@@ -3,11 +3,11 @@ name: team-lead-reference
 description: "Reference data for Team Lead orchestration — model routing, pre-delegation checks, cost tracking template, and DLQ format. Load when starting a delegation session."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Team Lead Reference
 
-For the specialist agent registry and model assignments, see [agent-registry.md](../../customizations/agents/agent-registry.md).
+For the specialist agent registry and model assignments, see [agent-registry.md](../../.opencastle/agents/agent-registry.md).
 
 ## Cost-Aware Model Routing
 
@@ -81,7 +81,7 @@ Fire one **Researcher** sub-agent with this prompt:
 Research the following planned subtasks and enrich each with:
 1. Exact file paths and line numbers for code that will change
 2. Existing patterns to follow (with file:line examples)
-3. Related lessons from .github/customizations/LESSONS-LEARNED.md
+3. Related lessons from .opencastle/LESSONS-LEARNED.md
 4. Risks or blockers (missing dependencies, known issues)
 
 Subtasks:
@@ -94,7 +94,7 @@ Return a structured report per subtask.
 
 ### Full Deepen (Parallel Researchers)
 
-For large plans, split research by domain and fire parallel Researcher sub-agents. See [agent-registry.md](../../customizations/agents/agent-registry.md) for project-specific scope examples.
+For large plans, split research by domain and fire parallel Researcher sub-agents. See [agent-registry.md](../../.opencastle/agents/agent-registry.md) for project-specific scope examples.
 
 ### What Deepening Produces
 
@@ -166,7 +166,7 @@ This prevents the Team Lead from confusing which agent produced what, especially
 
 ## Dead Letter Queue Format
 
-Log to `.github/customizations/AGENT-FAILURES.md` when:
+Log to `.opencastle/AGENT-FAILURES.md` when:
 - A delegated agent fails to complete its task after 2+ attempts
 - A background agent produces output that fails all verification gates
 - An agent encounters an unrecoverable error (e.g., MCP server down, tool unavailable)
@@ -210,7 +210,7 @@ For common failure modes and recovery procedures, load the **orchestration-proto
 
 ## Dispute Protocol
 
-When automated resolution is exhausted (panel 3x BLOCK, approach conflicts, or criteria contradictions), create a **formal dispute record** in `.github/customizations/DISPUTES.md`. Inspired by the [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli) dispute/escalation pattern.
+When automated resolution is exhausted (panel 3x BLOCK, approach conflicts, or criteria contradictions), create a **formal dispute record** in `.opencastle/DISPUTES.md`. Inspired by the [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli) dispute/escalation pattern.
 
 ### When to Create a Dispute (vs. DLQ Entry)
 

package/src/orchestrator/skills/testing-workflow/SKILL.md

@@ -3,7 +3,7 @@ name: testing-workflow
 description: "Comprehensive testing workflow including test planning, unit/integration/E2E testing patterns, coverage requirements, and common testing mistakes. Use when writing tests, planning test strategies, or validating feature completeness."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Testing Workflow
 
@@ -22,11 +22,11 @@ description: "Comprehensive testing workflow including test planning, unit/integ
 2. **MAX 3 screenshots** per session.
 3. **Use `evaluate_script()` over `take_snapshot()`** — returns less data.
 4. **Reload between major test flows** to clear state.
-5. **Log results separately** — append to `.github/customizations/logs/e2e-results.md`.
+5. **Log results separately** — append to `.opencastle/logs/e2e-results.md`.
 
 ### Suite Files
 
-See `.github/customizations/project.instructions.md` for the full list of E2E test suite files.
+See `.opencastle/project.instructions.md` for the full list of E2E test suite files.
 
 ## Pre-Implementation Test Plan
 

package/src/orchestrator/skills/validation-gates/SKILL.md

@@ -3,7 +3,7 @@ name: validation-gates
 description: "Shared validation gates for all orchestration workflows — secret scanning, deterministic checks, blast radius analysis, dependency auditing, browser testing, cache management, regression checks, and final smoke tests. Referenced by prompt templates to maintain single source of truth."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Validation Gates