opencastle 0.5.1 → 0.7.0

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -1,13 +1,13 @@
 ---
-description: 'Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, and adjustments that are too small for Linear tracking.'
+description: 'Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, and adjustments that are too small for issue tracking.'
 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. -->
 
 # Follow-Up Refinement
 
-You are the Team Lead. Handle the follow-up refinement described below. This is a **post-task adjustment** — a bug fix, UI tweak, or polish item that came up after reviewing a completed roadmap task. It does NOT require Linear tracking.
+You are the Team Lead. Handle the follow-up refinement described below. This is a **post-task adjustment** — a bug fix, UI tweak, or polish item that came up after reviewing a completed roadmap task. It does NOT require issue tracking.
 
 ## Request
 
@@ -19,7 +19,7 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 
 | Aspect | Roadmap Task | Follow-Up |
 |--------|-------------|-----------|
-| Linear issues | Required (hard gate) | Depends on scope (see triage) |
+| Tracker issues | Required (hard gate) | Depends on scope (see triage) |
 | Panel review | For high-stakes changes | Only if security/data-related |
 | Documentation updates | Roadmap + known issues + ADRs | Only if behavior changes significantly |
 | Scope | Multi-step feature | Focused fix or adjustment |
@@ -31,9 +31,9 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 
 ### 1. Triage: Decide Tracking Level
 
-Before doing anything, decide whether this follow-up needs Linear tracking:
+Before doing anything, decide whether this follow-up needs issue tracking:
 
-**Create a Linear issue if ANY of these are true:**
+**Create a tracker issue if ANY of these are true:**
 - The change affects user-visible behavior (not just cosmetic)
 - It touches more than 2–3 files
 - It modifies shared library code (`libs/`)
@@ -41,13 +41,13 @@ Before doing anything, decide whether this follow-up needs Linear tracking:
 - It could introduce regressions in other features
 - You want a record for future reference (e.g., "why was this changed?")
 
-**Skip Linear if ALL of these are true:**
+**Skip tracking if ALL of these are true:**
 - Pure cosmetic/spacing/copy tweak
 - Isolated to a single component or page
 - No behavioral change
 - Trivial to verify visually
 
-If creating a Linear issue, use:
+If creating a tracker issue, use:
 - **Title**: `[Follow-up] Short description`
 - **Label**: agent name + `follow-up`
 - **Priority**: Low or Medium
@@ -59,11 +59,11 @@ Before touching any code:
 
 1. **Clarify scope** — Identify exactly which pages, components, or behaviors need to change
 2. **Find affected files** — Search the codebase for the relevant components, styles, queries, and tests
-3. **Check known issues** — Scan `docs/KNOWN-ISSUES.md` in case this is a documented limitation
+3. **Check known issues** — Scan `.github/customizations/KNOWN-ISSUES.md` in case this is a documented limitation
 4. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for relevant pitfalls before starting
 5. **Assess complexity** — If the request turns out to be larger than expected (touches >5 files, needs a migration, or affects auth/security), escalate it:
    - Inform the user that this should be a tracked task
-   - Create a Linear issue (if not already created in triage) and switch to the `implement-feature` workflow
+   - Create a tracker issue (if not already created in triage) and switch to the `implement-feature` workflow
 
 ### 3. Plan the Fix
 
@@ -100,15 +100,15 @@ Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and
 
 Every follow-up, no matter how small, must pass these checks:
 
-1. **Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
+1. **Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
 2. **Browser Testing** (MANDATORY for any visual change) — clear cache, start server, verify scenario + responsive + screenshot evidence
 3. **Regression Check** — if shared component/library modified, run tests for all consuming projects and browser-test at least one page per affected app
 
 ### 6. Delivery
 
-If triage determined this follow-up needs Linear tracking, follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+If triage determined this follow-up needs tracker tracking, follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
 
-If triage determined no Linear tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
+If triage determined no tracker tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
 
 ### 7. Escalation Triggers
 
@@ -128,12 +128,12 @@ When escalating, explain to the user what you found and why it needs proper trac
 The follow-up is complete when:
 
 - [ ] The specific request is resolved
-- [ ] Linear issue created and moved to Done (if triage determined tracking was needed)
+- [ ] Tracker issue created and moved to Done (if triage determined tracking was needed)
 - [ ] Lint, test, and build pass for all affected projects
-- [ ] **Dev server started with CLEAN cache** (`rm -rf .next && yarn nx reset` before serving)
+- [ ] **Dev server started with CLEAN cache** (clear framework + task runner caches before serving — see the **codebase-tool** skill)
 - [ ] **Visual changes verified in Chrome with screenshot taken as proof**
 - [ ] No regressions in adjacent functionality
 - [ ] Shared component changes tested across all consuming apps
-- [ ] Delivery Outcome completed if tracked (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+- [ ] Delivery Outcome completed if tracked (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Lessons learned captured if any retries occurred
 - [ ] Known issues updated if a new limitation was discovered

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,7 +57,7 @@ Acceptance criteria:
 
 ### Phase 4: Verify & Report
 
-1. **Run verification** — `yarn nx affected -t lint,test,build` on all affected projects
+1. **Run verification** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands)
 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

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
 ---
@@ -218,12 +218,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",

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