opencastle 0.6.0 → 0.8.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
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Resolve PR Comments
 
@@ -57,10 +57,21 @@ Acceptance criteria:
 
 ### Phase 4: Verify & Report
 
-1. **Run verification** — `yarn nx affected -t lint,test,build` on all affected projects
-2. **Commit fixes** — Use descriptive commit messages referencing the PR: `TAS-XX: Address PR review — [summary]`
-3. **Push to the same branch** — The PR updates automatically
-4. **Report back** — Provide a structured summary of what was resolved
+> Load the **validation-gates** skill for detailed steps on each gate.
+
+All fixes must pass applicable gates before pushing:
+
+1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
+2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
+3. **Gate 3: Blast Radius Check** — verify changes are scoped to commented files only; flag any files modified outside the comment scope
+4. **Gate 4: Fast Review** (MANDATORY) — single reviewer sub-agent validates the combined PR comment fixes
+5. **Gate 5: Regression Testing** — run tests for all projects consuming modified files
+
+After all gates pass:
+
+6. **Commit fixes** — Use descriptive commit messages referencing the PR: `TAS-XX: Address PR review — [summary]`
+7. **Push to the same branch** — The PR updates automatically
+8. **Report back** — Provide a structured summary of what was resolved
 
 ## Output Format
 
@@ -85,9 +96,12 @@ After resolving comments, report:
 | path/to/file.ts | [question/debate] | [your take + options] |
 
 ### Verification
+- Secret Scanning: PASS/FAIL
 - Lint: PASS/FAIL
 - Tests: PASS/FAIL
 - Build: PASS/FAIL
+- Blast Radius: PASS/ESCALATED
+- Fast Review: PASS/FAIL
 
 ### Commits
 - `abc1234` TAS-XX: Address PR review — [summary]

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Agent Lifecycle Hooks
 
@@ -29,8 +29,8 @@ 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 `docs/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.notifications` to determine the provider. If no messaging is configured, skip this step.
+2. **Check for checkpoint** — If `.github/customizations/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. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
 
@@ -40,7 +40,7 @@ Include this reminder in every delegation:
 
 ```
 **Session Start:** Read `.github/customizations/LESSONS-LEARNED.md` before starting.
-Check `docs/SESSION-CHECKPOINT.md` for prior state and pending approvals.
+Check `.github/customizations/SESSION-CHECKPOINT.md` for prior state and pending approvals.
 If pending approvals exist, check for replies via the messaging provider.
 Load relevant skills before writing code.
 ```
@@ -51,22 +51,31 @@ Load relevant skills before writing code.
 
 **When:** Before the agent yields control back to the user — every time, unconditionally.
 
-> **You MUST log every session.** No threshold, no exceptions, no "too small to log."
+> **⛔ HARD GATE — Run the Pre-Response Quality Gate checklist from `general.instructions.md` before responding.**
+> A session without log records is a failed session. A session without lessons captured after retries is a failed session.
 
 ### Actions
 
-1. **Log the session (MANDATORY)** — Append a JSON line to `.github/customizations/logs/sessions.ndjson` with: agent name, task summary, files changed, duration estimate, outcome (success/partial/failed), and lessons count. See `general.instructions.md` § Observability Logging for full rules.
-2. **Save checkpoint** (Team Lead only) — If work is incomplete, write `docs/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
-3. **Verify lessons captured** — If any retries occurred during the session, confirm that each retry resulted in a lesson entry in `LESSONS-LEARNED.md`.
-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).
+1. **Run the Pre-Response Quality Gate** — This is the single exit gate. Verify ALL items from the checklist in `general.instructions.md` § Pre-Response Quality Gate:
+   - [ ] Lessons read at session start
+   - [ ] Lessons captured for any retries
+   - [ ] Discovered issues tracked (not ignored)
+   - [ ] Lint/type/test pass (no new errors)
+   - [ ] Session logged to `sessions.ndjson` (ALWAYS)
+   - [ ] Delegations logged (Team Lead only)
+   - [ ] Reviews/panels/disputes logged (if applicable)
+2. **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. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
+4. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
 
 ### Template for Delegation Prompts
 
 ```
-**Session End:** Log your session to `.github/customizations/logs/sessions.ndjson`.
-If you retried anything with a different approach that worked, add a lesson
-to `.github/customizations/LESSONS-LEARNED.md`. Clean up temp files.
+**Session End:** Run the Pre-Response Quality Gate from general.instructions.md:
+- Log your session to `.github/customizations/logs/sessions.ndjson` (Constitution rule #6)
+- If you retried anything with a different approach that worked, add a lesson to `.github/customizations/LESSONS-LEARNED.md`
+- Track any discovered issues in KNOWN-ISSUES.md or a tracker ticket
+- Clean up temp files
 ```
 
 ---
@@ -77,7 +86,7 @@ to `.github/customizations/LESSONS-LEARNED.md`. Clean up temp files.
 
 ### Actions
 
-1. **Linear issue exists** — Verify the task has a Linear issue. If not, create one first.
+1. **Tracker issue exists** — Verify the task has a tracker issue. If not, create one first.
 2. **File partition clean** — Confirm no overlap with other active agents' file ownership.
 3. **Dependencies verified** — All prerequisite tasks are marked Done with independent verification.
 4. **Prompt is specific** — Includes: objective, file paths, acceptance criteria, patterns to follow, self-improvement reminder.
@@ -88,7 +97,7 @@ to `.github/customizations/LESSONS-LEARNED.md`. Clean up temp files.
 
 ```
 Pre-Delegate:
-☐ Linear issue ID included
+☐ Tracker issue ID included
 ☐ File partition specified
 ☐ Dependencies are Done
 ☐ Prompt has file paths + acceptance criteria
@@ -107,10 +116,10 @@ Pre-Delegate:
 0. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). Only after the fast review passes do you proceed to the remaining post-delegate actions below.
 1. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
 2. **Run verification** — Execute appropriate checks: lint, type-check, tests, or visual inspection.
-3. **Check acceptance criteria** — Compare output against the Linear issue's acceptance criteria. Each criterion must be independently verified.
-4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new Linear ticket.
+3. **Check acceptance criteria** — Compare output against the tracker issue's acceptance criteria. Each criterion must be independently verified.
+4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new tracker ticket.
 5. **Lessons captured** — If the agent retried anything, verify a lesson was added to LESSONS-LEARNED.md.
-6. **Update Linear** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing).
+6. **Update tracker** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing).
 
 ### Quick Checklist
 

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Agent Memory Protocol
 
@@ -30,7 +30,7 @@ Template structure:
 ### Weak Areas
 | Area | Evidence | Last Updated |
 |------|----------|-------------|
-| CSS Modules | Required 2 retries on styling task (TAS-AA) | YYYY-MM-DD |
+| Styling approach | Required 2 retries on styling task (TAS-AA) | YYYY-MM-DD |
 
 ### File Familiarity
 - `apps/tastebeer.eu/app/places/` — 3 tasks completed
@@ -67,8 +67,8 @@ Add relevant expertise context to delegation prompts. Example addition:
 
 ```
 ### Agent Context (from expertise registry)
-- Strong: Server Components, GROQ queries (3 successful tasks)
-- Weak: CSS Modules (1 retry on TAS-AA)
+- Strong: Server Components, CMS queries (3 successful tasks)
+- Weak: Component styling (1 retry on TAS-AA)
 - Familiar files: libs/queries/src/lib/search/ (2 tasks)
 ```
 
@@ -95,7 +95,7 @@ Capture structured relationships between concepts, files, agents, and decisions.
 |-------------|---------|---------|
 | `depends-on` | X requires Y to function | `F:places/page.tsx depends-on F:searchModule.ts` |
 | `caused-by` | X was caused by Y | `B:KI-042 caused-by D:use-server-components` |
-| `expert-in` | Agent X has expertise in Y | `A:Content Engineer expert-in P:GROQ-queries` |
+| `expert-in` | Agent X has expertise in Y | `A:Content Engineer expert-in P:CMS-queries` |
 | `related-to` | Loose conceptual connection | `L:LES-15 related-to P:RLS-policies` |
 | `obsoletes` | X replaces/supersedes Y | `D:use-app-router obsoletes D:use-pages-router` |
 | `blocks` | X prevents Y from working | `B:KI-099 blocks F:auth/middleware.ts` |
@@ -113,8 +113,8 @@ Template structure:
 
 | Source | Relationship | Target | Added | Context |
 |--------|-------------|--------|-------|---------|
-| A:Security Expert | expert-in | P:RLS-policies | 2026-02-23 | Completed 3 RLS audits |
-| F:searchModule.ts | depends-on | F:sanity-client.ts | 2026-02-23 | Search uses Sanity client |
+| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | Completed 3 CMS query tasks |
+| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | Search uses CMS client |
 | L:LES-15 | related-to | P:cookie-sessions | 2026-02-23 | Lesson about auth token format |
 ```
 

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

@@ -3,15 +3,15 @@ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # API Patterns
 
-Generic API design patterns for Next.js App Router 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](../../customizations/stack/api-config.md).
 
 ## Architecture
 
-This project uses **Next.js App Router** API patterns:
+This project uses **App Router** API patterns (resolve the specific framework via the **framework** capability slot in the skill matrix):
 
 - **Server Actions** (preferred for mutations) — form submissions, data writes, auth operations
 - **Route Handlers** (`route.ts`) — analytics endpoints, autocomplete, external integrations
@@ -43,12 +43,12 @@ export async function GET(request: NextRequest) {
 
 ```typescript
 'use server';
-import { createServerClient } from '@libs/supabase-auth';
+import { createServerClient } from '@libs/auth';
 import { revalidatePath } from 'next/cache';
 
 export async function submitAction(formData: FormData) {
-  const supabase = await createServerClient();
-  const { data: { user } } = await supabase.auth.getUser();
+  const client = await createServerClient();
+  const { data: { user } } = await client.auth.getUser();
   if (!user) return { error: 'Unauthorized' };
   // ... validate and process
   revalidatePath('/places');

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Skill: Context Map
 
@@ -43,7 +43,7 @@ For each entry point, trace what depends on it:
 
 For each entry point, trace what it depends on:
 
-1. **Data sources** — which Sanity schemas, GROQ queries, or Supabase tables feed this code?
+1. **Data sources** — which CMS schemas, content queries, or database tables feed this code?
 2. **Shared utilities** — which `libs/` modules does it use?
 3. **Configuration** — which config files affect its behavior?
 
@@ -75,8 +75,8 @@ Produce a structured map in this format:
 ### Unaffected (explicitly safe)
 | Area | Why |
 |------|-----|
-| `supabase/migrations/` | No DB changes |
-| `libs/supabase-auth/` | No auth changes |
+| `db/migrations/` | No DB changes |
+| `libs/auth/` | No auth changes |
 | `apps/cms-studio/` | No schema changes |
 ```
 

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

@@ -1,9 +1,9 @@
 ---
 name: data-engineering
-description: "Data pipeline ETL workflows, web scraping with Puppeteer, NDJSON processing, and CMS data import. Use when building scrapers, processing data, running CLI tools, or importing to a CMS."
+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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Data Engineering
 
@@ -31,9 +31,12 @@ abstract class BaseScraper {
 }
 ```
 
-### Puppeteer Cluster Setup
+### Browser-Based Scraper Setup
+
+Use a headless browser cluster for concurrent scraping (e.g., Puppeteer Cluster, Playwright):
 
 ```typescript
+// Example using Puppeteer Cluster — adapt to your project's scraping library
 const cluster = await Cluster.launch({
   concurrency: Cluster.CONCURRENCY_CONTEXT,
   maxConcurrency: config.concurrency,
@@ -53,7 +56,7 @@ const cluster = await Cluster.launch({
 - Random delays between requests (2-5 seconds default)
 - Randomize viewport sizes
 - Block unnecessary resources (images, fonts, CSS) for speed
-- Use stealth plugin for Puppeteer
+- Use stealth plugin for the scraping library
 - Request interception for resource optimization
 
 ### Error Recovery

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

@@ -3,7 +3,7 @@ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Deployment Infrastructure
 
@@ -22,7 +22,7 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 ## Release Process
 
 ### 1. Pre-Release Audit
-- Run `yarn nx affected -t lint,test,build` to verify all affected projects
+- Run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands)
 - Review all changed files since last release (`git diff` against last tag/release)
 - Check for uncommitted work or unmerged branches
 - Verify no draft PRs are accidentally included

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

@@ -3,7 +3,7 @@ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Documentation Standards
 

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 ````skill
 ---
@@ -123,7 +123,9 @@ CONFIDENCE: low | medium | high
 **Auto-PASS conditions (skip reviewer):**
 - The delegation was pure research/exploration with no code changes
 - The delegation only modified documentation files (`.md`)
-- All deterministic gates already passed AND the change is ≤10 lines across ≤2 files
+- All deterministic gates already passed AND the change is ≤10 lines across ≤2 files AND **no sensitive files were touched** (see validation-gates Gate 3 sensitive file list)
+
+> **Sensitive file override:** Changes to auth/middleware files, database migrations, RLS policies, security headers, CSP configuration, environment variable schemas, or CI/CD configuration **always** require a reviewer — even for 1-line changes. Auto-PASS never applies to these files.
 
 ### Step 4: Handle Verdict
 
@@ -218,12 +220,12 @@ CONFIDENCE: low | medium | high
 
 ## Logging
 
-Append a JSON line to `customizations/logs/reviews.ndjson` after each fast review:
+Append a JSON line to `.github/customizations/logs/reviews.ndjson` after each fast review:
 
 ```json
 {
   "timestamp": "2026-02-28T14:30:00Z",
-  "linear_issue": "PRJ-42",
+  "tracker_issue": "PRJ-42",
   "agent": "Developer",
   "reviewer_model": "gpt-5-mini",
   "verdict": "pass",
@@ -247,14 +249,23 @@ Fast review sits between the agent's output and the Team Lead's acceptance:
 Agent completes work
        │
        ▼
-Deterministic checks (lint, test, build)  ← validation-gates Gate 1
+Secret Scanning                           ← validation-gates Gate 1
+       │
+       ▼
+Deterministic checks (lint, test, build)  ← validation-gates Gate 2
+       │
+       ▼
+Blast Radius Check                        ← validation-gates Gate 3
+       │
+       ▼
+Dependency Audit (if packages changed)    ← validation-gates Gate 4
        │
        ▼
-Fast Review (this skill)                  ← validation-gates Gate 1.5
+Fast Review (this skill)                  ← validation-gates Gate 5
        │
        ├── PASS → Accept, move to next task
        ├── FAIL → Retry loop (up to 2x)
-       └── 3x FAIL → Escalate to Panel (Gate 5)
+       └── 3x FAIL → Escalate to Panel (Gate 9)
 ```
 
 ### Relationship to on-post-delegate Hook

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ 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/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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Skill: Memory Merger
 
@@ -35,7 +35,7 @@ Read `.github/customizations/LESSONS-LEARNED.md` and identify lessons that meet
 | **High severity** | Marked `high` severity |
 | **Age** | Added more than 60 days ago and still relevant |
 | **Category concentration** | 5+ lessons in the same category → extract a pattern |
-| **Tool-specific** | Lesson about a specific MCP tool, NX command, or framework pattern |
+| **Tool-specific** | Lesson about a specific MCP tool, codebase-tool command, or framework pattern |
 
 ### Step 2: Map Lessons to Target Files
 
@@ -43,17 +43,17 @@ Each lesson has a natural home in the instruction/skill hierarchy:
 
 | Lesson Category | Target File |
 |----------------|-------------|
-| `linear` | `.github/skills/task-management/SKILL.md` |
+| `task-management` | The skill mapped by the `task-management` slot in the skill matrix |
 | `mcp-tools` | The corresponding agent file or skill that uses the tool |
-| `nx-commands` | `.github/skills/nx-workspace/SKILL.md` |
-| `sanity` | `.github/skills/sanity-cms/SKILL.md` |
-| `supabase` | `.github/skills/supabase-database/SKILL.md` |
-| `browser-testing` | `.github/skills/browser-testing/SKILL.md` |
+| `codebase-tool` | The skill mapped by the `codebase-tool` slot in the skill matrix |
+| `cms` | The skill mapped by the `cms` slot in the skill matrix |
+| `database` | The skill mapped by the `database` slot in the skill matrix |
+| `browser-testing` | The skill mapped by the `e2e-testing` slot in the skill matrix |
 | `git-workflow` | `.github/instructions/general.instructions.md` |
 | `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
 | `delegation` | `.github/agents/team-lead.agent.md` or `.github/skills/team-lead-reference/SKILL.md` |
 | `testing` | `.github/skills/testing-workflow/SKILL.md` |
-| `react` / `nextjs` | Corresponding global skill file |
+| `ui-library` / `framework` | The skill mapped by the corresponding slot in the skill matrix |
 | Cross-cutting pattern | `.github/instructions/general.instructions.md` |
 
 ### Step 3: Draft the Merge

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

@@ -3,7 +3,7 @@ name: nextjs-patterns
 description: "Next.js App Router best practices for server/client components, routing, API routes, and project structure. Use when creating or modifying Next.js pages, layouts, route handlers, or Server Actions."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Next.js Patterns (2025)
 

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Skill: Panel majority vote (3 reviewers)
 
@@ -136,7 +136,7 @@ Each reviewer gets a weight based on 3 factors:
 
 ```text
 Reviewer 1 (Security Expert, reviewing auth): base 1 + domain 2 + confidence 1 = weight 4
-Reviewer 2 (Next.js Dev, reviewing auth):     base 1 + domain 0 + confidence 1 = weight 2
+Reviewer 2 (Frontend Dev, reviewing auth):    base 1 + domain 0 + confidence 1 = weight 2
 Reviewer 3 (Architect, reviewing auth):        base 1 + domain 1 + confidence 0 = weight 2
 ```
 

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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ 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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # Performance Optimization
 

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

@@ -1,9 +1,9 @@
 ---
 name: react-development
-description: "React development standards for functional components, hooks, TypeScript integration, state management, styling with CSS Modules/Sass, and testing patterns. Use when creating or modifying React components, custom hooks, or component tests."
+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 customizations/ directory instead. -->
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
 # React Development Standards
 
@@ -108,7 +108,7 @@ Modern React patterns following the official React documentation at https://reac
 - Co-locate tests in `__tests__` subdirectory.
 - **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libraries in tests.
 - Use `jest.requireMock()` instead of `require()` in test functions.
-- Use `jest.requireActual()` in mock setup.
+- Use `jest.requireActual()` or equivalent in mock setup.
 
 ## Security