opencastle 0.6.0 → 0.8.0

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -1,9 +1,9 @@
 ---
-description: 'Investigate and fix a reported bug with proper triage, root cause analysis, Linear tracking, and verification.'
+description: 'Investigate and fix a reported bug with proper triage, root cause analysis, issue tracking, and verification.'
 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. -->
 
 # Fix Bug
 
@@ -21,7 +21,7 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 
 | Aspect | Roadmap Task | Follow-Up | Bug Fix |
 |--------|-------------|-----------|---------|
-| Linear tracking | Required | Not required | **Required** |
+| Issue tracking | Required | Not required | **Required** |
 | Urgency | Planned | Low | Can be critical |
 | Root cause analysis | Feature design | Not needed | **Required** |
 | Reproduction steps | N/A | N/A | **Required** |
@@ -35,11 +35,11 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 
 Before fixing anything, understand the bug:
 
-1. **Check known issues** — Search `docs/KNOWN-ISSUES.md` for an existing entry. If found, note workarounds and decide if a fix is now feasible
-2. **Check Linear** — Search for existing bug tickets. If one exists, take it over instead of creating a duplicate
+1. **Check known issues** — Search `.github/customizations/KNOWN-ISSUES.md` for an existing entry. If found, note workarounds and decide if a fix is now feasible
+2. **Check tracker** — Search for existing bug tickets. If one exists, take it over instead of creating a duplicate
 3. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for related pitfalls
 4. **Reproduce the bug** — Start the dev server and confirm you can trigger the issue:
-   - `yarn nx run <app>:serve`
+   - Start the dev server (see the **codebase-tool** skill for the serve command)
    - Navigate to the affected page in Chrome
    - Follow the reproduction steps from the bug report
    - Take a screenshot of the broken state as evidence
@@ -50,9 +50,9 @@ Before fixing anything, understand the bug:
    - **Medium** — Minor functional issue, cosmetic but noticeable
    - **Low** — Edge case, minor visual glitch
 
-### 2. Create Linear Issue
+### 2. Create Tracker Issue
 
-Every bug gets tracked. Create a Linear issue with:
+Every bug gets tracked. Create a tracker issue with:
 
 - **Title**: `[Bug] Short description of the symptom`
 - **Label**: `bug`
@@ -79,7 +79,7 @@ Find WHY the bug happens, not just WHERE:
    - **Race condition** — Timing issue, hydration mismatch, async ordering
    - **CSS/Layout** — Specificity conflict, missing responsive rule, overflow
    - **Integration** — API contract mismatch, schema drift, stale cache
-5. **Update the Linear issue** — Add root cause findings and affected file paths
+5. **Update the tracker issue** — Add root cause findings and affected file paths
 
 ### 4. Implement the Fix
 
@@ -87,7 +87,7 @@ Delegate to the appropriate specialist agent via **sub-agent** (inline). For bug
 
 #### Delegation Prompt Must Include
 
-- **Linear issue ID and title** — e.g., `TAS-XX — [Bug] Description`
+- **Tracker issue ID and title** — e.g., `TAS-XX — [Bug] Description`
 - **Root cause** — What's wrong and why
 - **Fix approach** — How to fix it (be specific)
 - **File paths** — Exact files to read and modify
@@ -107,37 +107,42 @@ Delegate to the appropriate specialist agent via **sub-agent** (inline). For bug
 
 > Load the **validation-gates** skill for detailed steps on each gate.
 
-Every bug fix must pass ALL of these checks:
+Every bug fix must pass ALL applicable gates:
 
-1. **Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
-2. **Bug-Specific Verification** (mandatory) — start dev server, reproduce original bug (should be gone), verify correct behavior, test edge cases, screenshot before/after, check both apps if shared code
-3. **Regression Check** — run tests for all projects consuming modified files, browser-test adjacent functionality
-4. **Panel Review** (only if needed) — use **panel-majority-vote** skill if fix touches auth/authorization, RLS, security headers/CSP, or sensitive data
+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 the fix is minimal and scoped (bug fixes should be ≤100 lines, ≤3 files; escalate if larger)
+4. **Gate 4: Dependency Audit** (when `package.json` or lockfiles change) — vulnerability scan, license check, bundle size, duplicates
+5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates the fix. No auto-PASS for sensitive files
+6. **Gate 6: Bug-Specific Verification** (MANDATORY) — start dev server, reproduce original bug (should be gone), verify correct behavior, test edge cases, screenshot before/after, check both apps if shared code
+7. **Gate 7: Browser Testing** (for UI-related bugs) — clear cache, start server, verify fix + responsive + screenshots
+8. **Gate 8: Regression Testing** — run tests for all projects consuming modified files, browser-test adjacent functionality
+9. **Gate 9: Panel Review** (only if needed) — use **panel-majority-vote** skill if fix touches auth/authorization, RLS, security headers/CSP, or sensitive data
 
 ### 6. Delivery
 
-Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
 
 ### 7. Wrap Up
 
-1. **Move Linear issue to Done** — Only after all validation passes
-2. **Update Known Issues** — If this was a documented known issue, remove or update the entry in `docs/KNOWN-ISSUES.md`
+1. **Move tracker issue to Done** — Only after all validation passes
+2. **Update Known Issues** — If this was a documented known issue, remove or update the entry in `.github/customizations/KNOWN-ISSUES.md`
 3. **Capture lessons** — If the root cause reveals a pattern that other agents should know about, add it to `.github/customizations/LESSONS-LEARNED.md`
-4. **Note prevention** — If this class of bug could be caught earlier (by a lint rule, test, or type check), note that in the Linear issue as a follow-up suggestion
+4. **Note prevention** — If this class of bug could be caught earlier (by a lint rule, test, or type check), note that in the tracker issue as a follow-up suggestion
 
 ### 8. Completion Criteria
 
 The bug fix is complete when:
 
 - [ ] Bug is reproduced and root cause identified
-- [ ] Linear issue created with full details
+- [ ] Tracker issue created with full details
 - [ ] Fix implemented with minimal change
 - [ ] Test added covering the bug scenario
 - [ ] Lint, test, and build pass for all affected projects
 - [ ] Bug verified fixed in the browser
 - [ ] No regressions in adjacent functionality
 - [ ] Both apps checked if shared code was modified
-- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
-- [ ] Linear issue moved to Done
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Tracker issue moved to Done
 - [ ] Known issues updated if applicable
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -1,9 +1,9 @@
 ---
-description: 'Scaffold a new skill directory with proper frontmatter, structure, and content sections. Use when adding a new domain skill to the AI configuration.'
+description: 'Scaffold a new skill file with proper frontmatter, structure, and registration. Use when adding a new domain skill to the AI configuration.'
 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. -->
 
 # Create Skill
 
@@ -15,27 +15,44 @@ Scaffold a new skill for the AI agent configuration. Skills encode domain-specif
 
 ---
 
+## Skill Types
+
+OpenCastle has two kinds of skills with different locations and registration paths:
+
+| Type | Location | Bound Via | Purpose |
+|------|----------|-----------|---------|
+| **Process skill** | `skills/<name>/SKILL.md` | Direct reference in agent files | Stack-agnostic methodology (testing workflow, self-improvement, validation gates) |
+| **Plugin skill** | `plugins/<plugin>/SKILL.md` | Capability slot in the skill matrix | Technology-specific knowledge (CMS queries, database patterns, deployment config) |
+
+> **Rule of thumb:** If the skill would need to be rewritten when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If it's useful regardless of stack, it's a **process skill**.
+
+---
+
 ## Workflow
 
-### Step 1: Determine Scope
+### Step 1: Classify the Skill
 
-Classify the skill:
+Determine the type:
 
-| Scope | Prefix | When to Use |
-|-------|--------|-------------|
-| **Global** | `global-` | Domain knowledge applicable to any project (React, testing, security) |
-| **Local** | `local-` | Project-specific conventions (Linear config, Sanity schema patterns, this project's API structure) |
+| Question | If Yes → | If No → |
+|----------|----------|---------|
+| Is this tied to a specific technology/tool? | Plugin skill | Process skill |
+| Would switching tech stacks invalidate this content? | Plugin skill | Process skill |
+| Does a plugin already exist for this tool in `plugins/`? | Add `SKILL.md` to existing plugin | Create new plugin or process skill |
 
 ### Step 2: Name the Skill
 
-- Format: `<scope>-<domain>` (e.g., `global-react-development`, `local-sanity-cms`)
-- Use kebab-case
-- Be specific enough to distinguish from other skills, broad enough to be reusable
-- Check existing skills in `.github/skills/` to avoid overlap
+- Use `kebab-case`
+- **Process skills:** descriptive domain name (e.g., `testing-workflow`, `context-map`, `security-hardening`)
+- **Plugin skills:** `skillName` field in the plugin's `config.ts` (e.g., `sanity-cms`, `supabase-database`, `nx-workspace`)
+- Check existing skills in `skills/` and `plugins/` to avoid overlap
 
 ### Step 3: Create the Skill File
 
-Create `.github/skills/<skill-name>/SKILL.md` with this structure:
+**Process skill:** Create `skills/<skill-name>/SKILL.md`
+**Plugin skill:** Create `plugins/<plugin-name>/SKILL.md`
+
+Use this template:
 
 ```markdown
 ````skill
@@ -44,16 +61,10 @@ name: <skill-name>
 description: "<One-line description of what the skill covers. Include key topics and when to use it.>"
 ---
 
-# Skill: <Display Name>
+# <Display Name>
 
 <1-2 sentence overview of the skill's purpose and scope.>
 
-## When to Use
-
-- <Trigger condition 1>
-- <Trigger condition 2>
-- <Trigger condition 3>
-
 ## Core Principles
 
 1. **<Principle>** — <Explanation>
@@ -68,11 +79,6 @@ description: "<One-line description of what the skill covers. Include key topics
 
 <More domain content.>
 
-## Checklist
-
-- [ ] <Verification item 1>
-- [ ] <Verification item 2>
-
 ## Anti-Patterns
 
 - **<Bad pattern>** — <Why it's bad and what to do instead>
@@ -82,24 +88,36 @@ description: "<One-line description of what the skill covers. Include key topics
 
 ### Step 4: Register the Skill
 
-1. **Add to the skill matrix** — Update `.github/customizations/agents/skill-matrix.md` with the new skill mapping
-2. **Add to relevant agents** — Update the `skills` section in each agent that should use this skill
-3. **Reference in instructions** — If the skill is loaded by default, add it to the appropriate `.github/instructions/` file
+Registration differs by type:
+
+#### Process Skill
+
+1. **Add to the skill matrix** — Add a row to the **Process Skills (Always Direct)** table in `.github/customizations/agents/skill-matrix.md`
+2. **Reference in agent files** — Add to the `Direct Skills` section of each agent that should use it
+3. **Optional: reference in instructions** — If the skill should be loaded by default, add it to the appropriate `.github/instructions/` file
+
+#### Plugin Skill
+
+1. **Set `skillName` in the plugin's `config.ts`** — This connects the skill to the plugin
+2. **Update the skill matrix** — Set the Skill column for the matching capability slot row in `.github/customizations/agents/skill-matrix.md`
+3. **No agent changes needed** — Agents resolve plugin skills through capability slots automatically
 
 ### Step 5: Validate
 
-- [ ] File created at `.github/skills/<name>/SKILL.md`
+- [ ] File created at the correct path (`skills/` or `plugins/`)
 - [ ] Frontmatter has `name` and `description` fields
 - [ ] Description is a single line (no line breaks)
 - [ ] Content follows the template structure
 - [ ] No overlap with existing skills
-- [ ] Skill matrix updated
-- [ ] At least one agent references the skill
+- [ ] Skill matrix updated (process skill table or capability slot binding)
+- [ ] For process skills: at least one agent references the skill directly
+- [ ] For plugin skills: `config.ts` `skillName` matches the `name` in frontmatter
 
 ## Quality Guidelines
 
 - **Be prescriptive** — Skills should give clear instructions, not vague advice. "Use `fetchPlaces()` from `libs/queries`" beats "use the query library"
-- **Include examples** — Code snippets, file path examples, and table references from the actual codebase
+- **Include examples** — Code snippets, file path examples, and table references
 - **Keep it scannable** — Use headings, tables, bullets, and code blocks. Agents need to find information fast
 - **Avoid duplication** — If a rule already exists in `.github/instructions/`, reference it instead of repeating it
+- **Stay stack-agnostic in process skills** — Never hardcode technology names; use capability slot references (e.g., "the **database** skill" not "Supabase")
 - **Size target** — 100-300 lines. Under 100 is probably too thin; over 300 should be split into multiple skills

package/src/orchestrator/prompts/generate-task-spec.prompt.md

@@ -3,7 +3,7 @@ description: 'Generate a valid opencastle.tasks.yml spec file for autonomous ove
 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. -->
 
 # Generate Task Spec for Autonomous Run
 
@@ -107,11 +107,11 @@ Each task `prompt` must be a **complete, standalone instruction**. Include:
 - **Why** — business context so the agent can make good decisions.
 - **Constraints** — coding standards, conventions, do-not-touch files.
 - **Acceptance criteria** — bullet list of pass conditions.
-- **Verification command** — e.g., `Run: yarn nx run project:test` so the agent self-checks.
+- **Verification command** — e.g., `Run the project's test command with coverage` (see the **codebase-tool** skill) so the agent self-checks.
 
 > **Weak prompt:** "Add tests for the auth module."
 >
-> **Strong prompt:** "Write unit tests for `libs/auth/src/server.ts` covering token refresh, expiry edge cases, and invalid signatures. Place tests in `libs/auth/src/__tests__/server.test.ts`. Follow the existing Jest conventions (see `jest.preset.js`). Achieve ≥ 95 % coverage for `server.ts`. Run: `yarn nx run auth:test --coverage` and fix any failures."
+> **Strong prompt:** "Write unit tests for `libs/auth/src/server.ts` covering token refresh, expiry edge cases, and invalid signatures. Place tests in `libs/auth/src/__tests__/server.test.ts`. Follow the existing test conventions. Achieve ≥ 95 % coverage for `server.ts`. Run the project's test command with coverage (see the **codebase-tool** skill) and fix any failures."
 
 ### 6. Validate Before Outputting
 

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -3,11 +3,11 @@ description: 'Instruct the Team Lead to implement a specific task from the post-
 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. -->
 
 # Implement Roadmap Task
 
-You are the Team Lead. Implement the roadmap task described below following this strict workflow. The task comes from `docs/ROADMAP-POST-MVP.md`.
+You are the Team Lead. Implement the roadmap task described below following this strict workflow. The task comes from `.github/customizations/project/roadmap.md`.
 
 ## Task
 
@@ -15,29 +15,29 @@ You are the Team Lead. Implement the roadmap task described below following this
 
 ---
 
-> **Canonical workflow:** `.github/agent-workflows/feature-implementation.md` defines the phase structure. This prompt adds Linear traceability, validation gate references, and completion criteria.
+> **Canonical workflow:** `.github/agent-workflows/feature-implementation.md` defines the phase structure. This prompt adds tracker traceability, validation gate references, and completion criteria.
 
 ## Workflow
 
-> **HARD GATE:** Steps 1→2 are **blocking prerequisites**. Do NOT write, edit, or delegate any code until Linear issues exist for every subtask. If you catch yourself writing code before issues are created, STOP immediately, create the issues, then resume.
+> **HARD GATE:** Steps 1→2 are **blocking prerequisites**. Do NOT write, edit, or delegate any code until tracker issues exist for every subtask. If you catch yourself writing code before issues are created, STOP immediately, create the issues, then resume.
 
 ### 1. Research & Context Gathering
 
 Before writing any code, gather all relevant context:
 
-1. **Read the roadmap** — Open `docs/ROADMAP-POST-MVP.md` and find the full scope, status, and acceptance criteria for this task
-2. **Read known issues** — Check `docs/KNOWN-ISSUES.md` for blockers or workarounds that affect this task
-3. **Read architecture docs** — Check `docs/PROJECT.md` and `docs/DECISIONS.md` for constraints and prior decisions
+1. **Read the roadmap** — Open `.github/customizations/project/roadmap.md` and find the full scope, status, and acceptance criteria for this task
+2. **Read known issues** — Check `.github/customizations/KNOWN-ISSUES.md` for blockers or workarounds that affect this task
+3. **Read architecture docs** — Check `.github/customizations/project.instructions.md` and `.github/customizations/project/decisions.md` for constraints and prior decisions
 4. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for pitfalls relevant to this feature area
 5. **Search existing code** — Find all files, components, queries, and tests related to this feature area
 6. **Identify reusable code** — Before creating anything new, check if similar logic, components, or utilities already exist in the codebase that can be reused or extended
 
-### 2. Linear Board Setup (BLOCKING — must complete before Step 3)
+### 2. Task Board Setup (BLOCKING — must complete before Step 3)
 
-Every subtask must be tracked on Linear. **No issue = no implementation.** This step produces the issues that gate all downstream work.
+Every subtask must be tracked. **No issue = no implementation.** This step produces the issues that gate all downstream work.
 
 1. **Check existing issues** — Search the board for any in-progress or completed work related to this task
-2. **Decompose into issues** — Create one Linear issue per subtask using `[Area] Short description` naming
+2. **Decompose into issues** — Create one tracker issue per subtask using `[Area] Short description` naming
 3. **Set metadata** — Assign labels (agent name), priority, dependencies, and file partitions
 4. **Write descriptions** — Each issue must include:
    - **Objective:** One sentence
@@ -49,9 +49,9 @@ Every subtask must be tracked on Linear. **No issue = no implementation.** This
 
 ### 3. Implementation Rules
 
-#### Linear Issue Traceability
+#### Issue Traceability
 
-- **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the Linear issue ID and title in the prompt so the agent knows which tracked task it is completing
+- **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the tracker issue ID and title in the prompt so the agent knows which tracked task it is completing
 - **Reference in commits** — Include the issue ID (e.g., `TAS-42`) in commit messages when possible
 - **Update issue status** — Move issues to In Progress before starting, Done after verification passes
 
@@ -79,29 +79,34 @@ Include the self-improvement reminder in every delegation prompt (see `general.i
 
 Every subtask must pass ALL gates before being marked Done:
 
-1. **Gate 1: Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
-2. **Gate 2: Browser Testing** (MANDATORY for UI changes) — clear cache, start server, verify features + responsive + screenshots
-3. **Gate 3: Regression Testing** — full test suite for affected projects, browser-test adjacent pages if shared components changed
-4. **Gate 4: Panel Review** (for high-stakes changes) — use **panel-majority-vote** skill for security, DB migrations, architecture
+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 scope is expected (≤200 lines, ≤5 files normal; escalate if >500 lines or >10 files)
+4. **Gate 4: Dependency Audit** (when `package.json` changes) — vulnerability scan, license check, bundle size, duplicates
+5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates every delegation output. No auto-PASS for sensitive files
+6. **Gate 6: Browser Testing** (MANDATORY for UI changes) — clear cache, start server, verify features + responsive + screenshots
+7. **Gate 7: Regression Testing** — full test suite for affected projects, browser-test adjacent pages if shared components changed
+8. **Gate 8: Panel Review** (for high-stakes changes) — use **panel-majority-vote** skill for security, DB migrations, architecture
+9. **Gate 9: Final Smoke Test** — after all tasks Done, verify the complete feature end-to-end as a cohesive unit
 
 ### 5. Delivery
 
-Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+Follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to the tracker.
 
 ### 6. Documentation & Traceability
 
 Keep documentation current so future sessions have full context:
 
-1. **Update roadmap** — Mark completed items in `docs/ROADMAP-POST-MVP.md` with ✅ and the completion date. **Include Linear issue IDs and links** next to each scope item so progress is traceable across sessions. Format:
+1. **Update roadmap** — Mark completed items in `.github/customizations/project/roadmap.md` with ✅ and the completion date. **Include tracker issue IDs and links** next to each scope item so progress is traceable across sessions. Format:
    ```
-   **Linear Issues:**
-   - [PREFIX-6](https://linear.app/<workspace>/issue/PREFIX-6) — [Search] Description ✅ Done
-   - [PREFIX-7](https://linear.app/<workspace>/issue/PREFIX-7) — [UI] Description 📋 Todo
+   **Tracker Issues:**
+   - [PREFIX-6](<tracker-url>/PREFIX-6) — [Search] Description ✅ Done
+   - [PREFIX-7](<tracker-url>/PREFIX-7) — [UI] Description 📋 Todo
    ```
-   > Replace `PREFIX` and `<workspace>` with the project's Linear prefix and workspace slug (see `linear-config.md`).
-2. **Update known issues** — If new limitations are discovered, add them to `docs/KNOWN-ISSUES.md`
-3. **Update architecture docs** — If architectural decisions were made, add an ADR to `docs/DECISIONS.md`
-4. **Link Linear issues** — Every issue description should reference:
+   > Replace `PREFIX` with the project's issue prefix (see `tracker-config.md`).
+2. **Update known issues** — If new limitations are discovered, add them to `.github/customizations/KNOWN-ISSUES.md`
+3. **Update architecture docs** — If architectural decisions were made, add an ADR to `.github/customizations/project/decisions.md`
+4. **Link tracker issues** — Every issue description should reference:
    - Related roadmap section
    - Files modified (the partition)
    - Related issues (dependencies and follow-ups)
@@ -111,9 +116,9 @@ Keep documentation current so future sessions have full context:
 
 The roadmap task is complete when:
 
-- [ ] All Linear subtask issues are Done
+- [ ] All tracker subtask issues are Done
 - [ ] All deterministic checks pass (lint, test, build) for 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)
 - [ ] **All UI changes verified in Chrome browser via MCP with screenshots taken as proof**
 - [ ] **Every feature in the acceptance criteria visually confirmed** — not just "page loads"
 - [ ] Regression tests confirm no existing functionality is broken
@@ -121,6 +126,6 @@ The roadmap task is complete when:
 - [ ] Visual consistency maintained across all affected pages and apps
 - [ ] Documentation updated (roadmap, known issues, decisions)
 - [ ] Panel review passed for any high-stakes changes
-- [ ] Roadmap item marked complete in `docs/ROADMAP-POST-MVP.md`
-- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+- [ ] Roadmap item marked complete in `.github/customizations/project/roadmap.md`
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/metrics-report.prompt.md

@@ -1,9 +1,9 @@
 ---
-description: 'Collect and report metrics from agent logs, GitHub PRs, Linear issues, and Vercel deployments'
+description: 'Collect and report metrics from agent logs, GitHub PRs, tracker issues, and deployments'
 agent: Researcher
 ---
 
-<!-- ⚠️ 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. -->
 
 # Metrics Report
 
@@ -46,9 +46,9 @@ Compute:
 - **Commit frequency** — commits per day/week on main
 - **Bogus/closed PRs** — PRs closed without merge (potential failed agent work)
 
-### 3. Linear Issues
+### 3. Tracker Issues
 
-Use Linear MCP tools (`list_issues`, `search_issues`):
+Use tracker MCP tools (`list_issues`, `search_issues`):
 
 ```
 list_issues with status filter for each state: Backlog, Todo, In Progress, Done, Cancelled
@@ -62,9 +62,9 @@ Compute:
 - **Cycle time** — average time from In Progress → Done (if dates available)
 - **Stale issues** — In Progress for >7 days without updates
 
-### 4. Vercel Deployments
+### 4. Deployments
 
-Use Vercel MCP tools (`list_deployments`, `get_deployment`):
+Use deployment platform tools (if available via MCP or CLI):
 
 Query deployments for all configured apps (see `project.instructions.md` for the app inventory).
 
@@ -74,7 +74,7 @@ Compute:
 - **Failure rate** — error / total
 - **Build times** — average, median, p95
 - **Deployments per day** — activity timeline
-- **Failed deployment details** — which commits/branches failed and why (use `get_deployment_build_logs` for recent failures)
+- **Failed deployment details** — which commits/branches failed and why
 
 ### 5. Panel Reviews (local)
 
@@ -110,7 +110,7 @@ Present the report as a structured markdown summary with these sections:
 - X agent sessions, Y% success rate
 - Z PRs merged, W% merge rate  
 - N deployments, M% success rate
-- P Linear issues completed
+- P tracker issues completed
 
 ## Agent Activity
 {sessions table, success rates, model usage}
@@ -121,10 +121,10 @@ Present the report as a structured markdown summary with these sections:
 ## GitHub
 {PR stats, merge rates, commit frequency}
 
-## Linear Board
+## Task Board
 {issue distribution, completion rate, stale issues}
 
-## Vercel Deployments
+## Deployments
 {success rate, failure rate, build times}
 
 ## Panel Reviews
@@ -141,4 +141,4 @@ Present the report as a structured markdown summary with these sections:
 
 Run this prompt periodically (weekly recommended) to track project health. Compare with previous reports to identify trends.
 
-If session logs are empty (no data yet), still collect GitHub/Linear/Vercel data and note that agent logging has just been enabled.
+If session logs are empty (no data yet), still collect GitHub/tracker/deployment data and note that agent logging has just been enabled.

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
 
@@ -98,17 +98,21 @@ Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and
 
 > Load the **validation-gates** skill for detailed steps on each gate.
 
-Every follow-up, no matter how small, must pass these checks:
+Every follow-up, no matter how small, must pass these gates:
 
-1. **Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — 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
+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 scope matches the "small follow-up" expectation (≤100 lines, ≤3 files normal; if larger, escalate to `implement-feature` workflow)
+4. **Gate 4: Dependency Audit** (when `package.json` or lockfiles change) — vulnerability scan, license check, bundle size, duplicates
+5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates the change. No auto-PASS for sensitive files
+6. **Gate 6: Browser Testing** (MANDATORY for any visual change) — clear cache, start server, verify scenario + responsive + screenshot evidence
+7. **Gate 7: Regression Testing** — 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 +132,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