opencastle 0.5.1 → 0.7.0

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -3,7 +3,7 @@ description: 'Bootstrap the .github/customizations/ directory for a new project.
 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. -->
 
 # Bootstrap Project Customizations
 
@@ -23,20 +23,53 @@ Without customizations, agents operate blind — they don't know the project's t
 
 ## Pre-Existing Stack Info
 
-Before starting discovery, check for **`.opencastle.json`** in the project root. If it exists and contains a `stack` field, the user already declared their CMS, database, project management, and notifications tool during `opencastle init`. Use these as confirmed facts — skip re-detecting them and focus discovery on the project-specific details (IDs, schemas, config values).
+Before starting discovery, check for **`.opencastle.json`** in the project root. If it exists, it contains a combined `repoInfo` field from `opencastle init` that merges two sources:
+
+1. **Auto-detected tooling** — the init command scanned config files, `package.json` dependencies, and directory structures
+2. **User-declared choices** — the user selected CMS, database, project management, and notifications via the interactive questionnaire
+
+The result is a single unified view of the project's tech stack:
 
 ```json
 {
+  "repoInfo": {
+    "packageManager": "pnpm",
+    "monorepo": "nx",
+    "language": "typescript",
+    "frameworks": ["next", "astro"],
+    "databases": ["prisma", "supabase"],
+    "cms": ["sanity"],
+    "deployment": ["vercel"],
+    "testing": ["playwright", "vitest"],
+    "cicd": ["github-actions"],
+    "styling": ["css-modules", "tailwind"],
+    "auth": ["next-auth", "supabase-auth"],
+    "pm": ["linear"],
+    "notifications": ["slack"],
+    "mcpConfig": true,
+    "configFiles": ["nx.json", "package.json", "tsconfig.json", "vercel.json"]
+  },
   "stack": {
-    "cms": "sanity",           // sanity | contentful | strapi | none
-    "db": "supabase",          // supabase | convex | none
-    "pm": "linear",            // linear | jira | none
-    "notifications": "slack"   // slack | teams | none
+    "cms": "sanity",
+    "db": "supabase",
+    "pm": "linear",
+    "notifications": "slack"
   }
 }
 ```
 
-The skill matrix (`customizations/agents/skill-matrix.md`) will already have the `cms` and `database` rows pre-filled based on this selection. The appropriate task management skill (`task-management` for Linear, `jira-management` for Jira) and notifications skill (`slack-notifications` for Slack, `teams-notifications` for Teams) will already be installed. Verify they are correct and fill in any remaining empty rows.
+**Use `repoInfo` to:**
+- Skip re-scanning for technologies already listed — go straight to reading their config files
+- Pre-fill the tech stack table in `project.instructions.md`
+- Know which `stack/` config files to create (e.g., if `repoInfo.databases` includes `"prisma"`, create `stack/prisma-config.md`)
+- Know which `project/` config files to create (e.g., if `repoInfo.pm` includes `"linear"`, create `project/linear-config.md`)
+- Identify `configFiles` to read for deep inspection (Phase 1.3)
+
+**`stack` vs `repoInfo`:** The `stack` field holds the raw user questionnaire answers (used internally for MCP server filtering and skill selection). The `repoInfo` field is the combined view you should use for discovery — it includes everything from `stack` plus all auto-detected tooling.
+
+**Still verify:** `repoInfo` detects presence, not configuration details. You still need to read the actual config files for schemas, IDs, routes, etc.
+
+The skill matrix (`.github/customizations/agents/skill-matrix.md`) will already have the `cms` and `database` rows pre-filled based on this selection. The appropriate task management skill (`linear-task-management` for Linear, `jira-management` for Jira) and notifications skill (`slack-notifications` for Slack, `teams-notifications` for Teams) will already be installed. Verify they are correct and fill in any remaining empty rows.
 
 ## Workflow
 
@@ -46,7 +79,8 @@ Explore the project systematically. Gather facts — don't assume.
 
 #### 1.1 Project Overview
 
-- **First**: Read `.opencastle.json` if it exists — note the `stack.cms` and `stack.db` values
+- **First**: Read `.opencastle.json` if it exists — note `stack` choices and `repoInfo` detections
+- If `repoInfo` is present, use it as your starting inventory — skip re-scanning for the technologies it already lists
 - Read `README.md`, `package.json`, and any workspace config (`nx.json`, `turbo.json`, `pnpm-workspace.yaml`, `lerna.json`)
 - Identify: monorepo vs single app, package manager, language, framework(s)
 - List all apps and libraries with their purpose
@@ -78,7 +112,7 @@ For each detected technology, dig into the config:
 - **API**: Find route handlers, Server Actions, middleware, external API integrations
 - **Deployment**: Read deploy config, environment variables, cron jobs, security headers
 - **Testing**: Find test config, test suites, test utilities, coverage setup
-- **Docs**: Map the `docs/` directory tree (if it exists)
+- **Docs**: Map the project's documentation directory tree (if it exists)
 - **Task tracking**: Find team IDs, project IDs, workflow states (check Linear/Jira config or docs)
 
 ### Phase 2: Generate Customization Files
@@ -88,7 +122,7 @@ Create `.github/customizations/` and generate files based on what you discovered
 Files are organized into subdirectories by domain:
 
 ```
-customizations/
+.github/customizations/
 ├── README.md                  # Directory index
 ├── project.instructions.md    # High-level project context
 ├── LESSONS-LEARNED.md         # Knowledge base (retries, workarounds)
@@ -192,7 +226,7 @@ customizations/
 
 #### `project/` — Project Management Config
 
-14. **`project/docs-structure.md`** — If a `docs/` directory exists:
+14. **`project/docs-structure.md`** — If a documentation directory exists:
     - Full directory tree
     - Purpose of each document
     - Documentation conventions
@@ -225,7 +259,20 @@ For each file created, report:
 - Number of lines
 - Key sections included
 
-End with a summary of what was discovered, what was generated, and what (if anything) needs manual input (e.g., Linear team IDs that require API access to discover).
+End with a summary of what was discovered, what was generated, and what (if anything) needs manual input (e.g., tracker team IDs that require API access to discover).
+
+After your summary, suggest next steps:
+
+### Suggested Next Steps
+
+Now that your project is configured, here's what you can do:
+
+1. **Review the generated files** — Scan `.github/customizations/` for any `<!-- TODO: verify -->` comments and fill in missing values (e.g., tracker team IDs, Supabase project IDs)
+2. **Commit the customizations** — `git add .github/customizations/ && git commit -m "chore: bootstrap OpenCastle customizations"`
+3. **Implement a feature** — Use the **"Implement Feature"** prompt to have the Team Lead orchestrate a full feature build with task tracking, delegation, and verification
+4. **Fix a bug** — Use the **"Bug Fix"** prompt for structured triage, root cause analysis, and fix with tracker tracking
+5. **Brainstorm first** — Not sure how to approach something? Use the **"Brainstorm"** prompt to explore requirements and trade-offs before committing to a plan
+6. **Create a task spec** — Use the **"Generate Task Spec"** prompt to create `opencastle.tasks.yml` for autonomous overnight runs with `npx opencastle run` CLI command.
 
 ## Guidelines
 

package/src/orchestrator/prompts/brainstorm.prompt.md

@@ -3,7 +3,7 @@ description: 'Collaborative brainstorm to explore requirements, approaches, and
 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. -->
 
 # Brainstorm
 
@@ -35,7 +35,7 @@ Before exploring solutions, make sure the problem is well-understood:
 Research before proposing. Gather data, don't guess:
 
 1. **Search existing code** — is there already a partial implementation, similar pattern, or relevant utility?
-2. **Check documentation** — read `docs/PROJECT.md`, `docs/DECISIONS.md`, `docs/KNOWN-ISSUES.md` for constraints
+2. **Check documentation** — read `.github/customizations/project.instructions.md`, `.github/customizations/project/decisions.md`, `.github/customizations/KNOWN-ISSUES.md` for constraints
 3. **Check lessons learned** — read `.github/customizations/LESSONS-LEARNED.md` for pitfalls in this area
 4. **Identify affected layers** — which apps, libs, data stores, and third-party services are involved?
 
@@ -114,4 +114,4 @@ Once the brainstorm is complete and the user confirms (or you're confident in th
 
 1. **Transition to planning** — use the brainstorm report as input for `implement-feature` or the appropriate workflow
 2. **Preserve context** — include the brainstorm report in delegation prompts so agents understand *why* an approach was chosen
-3. **Reference in Linear** — link the brainstorm findings in the Linear issue description
+3. **Reference in tracker** — link the brainstorm findings in the tracker issue description

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
@@ -109,35 +109,35 @@ Delegate to the appropriate specialist agent via **sub-agent** (inline). For bug
 
 Every bug fix must pass ALL of 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. **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
 
 ### 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,29 @@ 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
+1. **Gate 1: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — 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
 
 ### 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 +111,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 +121,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.