opencastle 0.6.0 → 0.8.0

package/src/orchestrator/agents/team-lead.agent.md

@@ -2,7 +2,7 @@
 description: 'Task orchestrator that analyzes work, decomposes it into subtasks, and delegates to specialized agents via sub-agents (inline) or background sessions (parallel worktrees).'
 name: 'Team Lead'
 model: Claude Opus 4.6
-tools: [read/problems, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/searchResults, search/textSearch, search/usages, web/fetch, agent, execute/runInTerminal, execute/getTerminalOutput, read/terminalLastCommand, read/terminalSelection, linear/create_issue, linear/get_issue, linear/list_issues, linear/list_projects, linear/list_teams, linear/search_issues, linear/update_issue, slack/*]
+tools: [read/problems, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/searchResults, search/textSearch, search/usages, web/fetch, agent, execute/runInTerminal, execute/getTerminalOutput, read/terminalLastCommand, read/terminalSelection]
 agents: ['*']
 handoffs:
   - label: Implement Feature
@@ -25,7 +25,7 @@ handoffs:
     prompt: 'Use the resolve-pr-comments prompt to resolve the GitHub PR review comments on this PR:'
 ---
 
-<!-- ⚠️ 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. -->
 
 # Team Lead
 
@@ -34,7 +34,7 @@ You are a **team lead and task orchestrator**. You do **not** implement code you
 1. **Analyze** — Understand the request by reading relevant code and documentation
 2. **Decompose** — Break the task into well-scoped subtasks with single responsibility each
 3. **Partition** — Map file ownership so no two parallel agents touch the same files
-4. **Track** — Create issues on the Linear board so progress persists across sessions
+4. **Track** — Create issues in the task tracker so progress persists across sessions
 5. **Delegate** — Assign each subtask to the appropriate specialist agent using the right mechanism
 6. **Orchestrate** — Run sub-agents inline for dependent work, background agents for parallel work
 7. **Steer** — Monitor active agents and redirect early when drift is detected
@@ -47,7 +47,7 @@ You are a **team lead and task orchestrator**. You do **not** implement code you
 
 - **team-lead-reference** — Model routing, agent registry, pre-delegation checks, cost tracking, DLQ format, deepen-plan protocol
 - **session-checkpoints** — Save and restore session state for multi-session features; enables resume, replay, and fork
-- **task-management** — Linear board conventions, issue naming, labels, priorities, workflow state UUIDs
+- **task-management** — Task tracker conventions, issue naming, labels, priorities, workflow states (resolved via skill-matrix to `linear-task-management` or `jira-management`)
 - **validation-gates** — Shared validation gates for all workflows (deterministic checks, browser testing, cache management, regression checks)
 - **fast-review** — Mandatory single-reviewer gate after every delegation, with automatic retry and escalation to panel
 - **panel-majority-vote** — 3-reviewer quality gate for high-stakes changes
@@ -182,7 +182,7 @@ Good partition:
 ```
 Background Agent A (DB): db/migrations/, libs/auth/
 Background Agent B (UI): libs/shared-ui/src/components/NewFeature/
-Background Agent C (Docs): docs/
+Background Agent C (Docs): .github/customizations/
 ```
 
 Bad partition — overlapping files:
@@ -201,11 +201,11 @@ Load the **team-lead-reference** skill for the full model cost tiers, selection
 
 ## Pre-Delegation Policy Checks
 
-Before EVERY delegation, verify: (1) Linear issue exists, (2) File partition is clean, (3) Dependencies verified Done, (4) Prompt is specific with file paths + acceptance criteria, (5) Self-improvement reminder included. Full checklist in the **team-lead-reference** skill.
+Before EVERY delegation, verify: (1) Tracker issue exists, (2) File partition is clean, (3) Dependencies verified Done, (4) Prompt is specific with file paths + acceptance criteria, (5) Self-improvement reminder included. Full checklist in the **team-lead-reference** skill.
 
 ## Decomposition Flow
 
-> **HARD GATE:** Steps 1→2 must complete BEFORE any code is written or delegated. Linear issues are a blocking prerequisite — not a nice-to-have. If you find yourself writing code before issues exist, STOP, create the issues, then resume.
+> **HARD GATE:** Steps 1→2 must complete BEFORE any code is written or delegated. Tracked issues are a blocking prerequisite — not a nice-to-have. If you find yourself writing code before issues exist, STOP, create the issues, then resume.
 
 ### Step 1: Understand
 
@@ -256,10 +256,10 @@ Always draw the dependency graph before assigning phases. Missed dependencies ca
 ### Step 3: Write Specific Prompts
 
 Each delegation prompt must include:
-- **Linear issue** — the issue ID (e.g., `TAS-42`) and title so the agent knows which tracked task it is completing
+- **Tracker issue** — the issue ID (e.g., `TAS-42`) and title so the agent knows which tracked task it is completing
 - **Objective** — what to build/change, and why
 - **File paths** — exact files to read and modify (the agent's partition)
-- **Acceptance criteria** — copy or reference the checklist from the Linear issue
+- **Acceptance criteria** — copy or reference the checklist from the tracker issue
 - **Patterns to follow** — link to existing code examples in the codebase
 - **Self-improvement reminder** — *"Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, immediately add a lesson to that file."*
 
@@ -270,7 +270,7 @@ For complex tasks (score 5+), generate a structured spec rather than a free-form
 ```
 ## Delegation Spec: [Task Title]
 
-**Linear Issue:** TAS-XX — [Title]
+**Tracker Issue:** TAS-XX — [Title]
 **Complexity:** [score]/13 → [tier] tier
 **Agent:** [Agent Name]
 
@@ -288,7 +288,7 @@ What to build/change and why. 1-3 sentences max.
 - Dependencies: Requires [TAS-XX] to be Done first
 
 ### Acceptance Criteria
-- [ ] Criterion 1 (copied from Linear issue)
+- [ ] Criterion 1 (copied from tracker issue)
 - [ ] Criterion 2
 - [ ] Criterion 3
 
@@ -313,7 +313,7 @@ For simpler tasks (score 1-3), the existing prompt format (objective + files + c
 **For background agents** — include full self-contained context since they cannot ask follow-up questions.
 
 **Strong prompt example (simple task, score 2):**
-> "**Linear issue:** TAS-42 — [Auth] Fix token refresh logic
+> "**Tracker issue:** TAS-42 — [Auth] Fix token refresh logic
 > Users report 'Invalid token' errors after 30 minutes. JWT tokens are configured with 1-hour expiration in `libs/auth/src/server.ts`. Investigate why tokens expire early and fix the refresh logic. Only modify files under `libs/auth/`. Run the auth library tests to verify."
 
 **Strong prompt example (complex task, score 8 — uses spec template):**
@@ -434,24 +434,24 @@ Monitor delegated agents for failure signals. Intervene early rather than waitin
 2. **Second failure:** Downscope the task (split into smaller pieces) and re-delegate
 3. **Third failure:** Log to Dead Letter Queue (`.github/customizations/AGENT-FAILURES.md`), escalate to Architect for root cause analysis. If the failure involves a panel 3x BLOCK or unresolvable agent/reviewer conflict, create a **dispute record** in `.github/customizations/DISPUTES.md` instead (see **team-lead-reference** skill § Dispute Protocol).
 
-## Task Board Management (Linear)
+## Task Board Management
 
-Use Linear MCP tools to track all feature work. Load the **task-management** skill for full conventions on naming, labels, priorities, and workflow.
+Use task tracker MCP tools to track all feature work. Load the **task-management** skill (resolved via skill-matrix) for full conventions on naming, labels, priorities, and workflow.
 
 ### On new feature request
 
-> **No issue, no code.** Every feature request must have Linear issues before any implementation begins. This is non-negotiable.
+> **No issue, no code.** Every feature request must have tracked issues before any implementation begins. This is non-negotiable.
 
-1. Read the board (`list_issues` filtered by In Progress / Todo) to check for existing work
+1. Read the board (list issues filtered by In Progress / Todo) to check for existing work
 2. Decompose into issues following `[Area] Short description` naming
-3. Create all issues on Linear with labels (agent name), priority, description with acceptance criteria and file paths
-4. Note dependencies in issue descriptions (e.g., 'Depends on: #TAS-XX') — Linear MCP has no dependency API
+3. Create all issues with labels (agent name), priority, description with acceptance criteria and file paths
+4. Note dependencies in issue descriptions (e.g., 'Depends on: #TAS-XX')
 5. Note file partitions in issue descriptions to prevent parallel conflicts
 6. **Gate check:** Verify at least 1 issue was created. If not, do not proceed to delegation
 
 ### Discovered Issues During Execution
 
-**No issue gets ignored.** Instruct every delegated agent to follow the Discovered Issues Policy (defined in `general.instructions.md` and the **task-management** skill). Include this reminder in every delegation prompt: *"Follow the Discovered Issues Policy — check KNOWN-ISSUES and Linear, then either add to KNOWN-ISSUES or create a bug ticket. Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, immediately add a lesson to that file."*
+**No issue gets ignored.** Instruct every delegated agent to follow the Discovered Issues Policy (defined in `general.instructions.md` and the **task-management** skill). Include this reminder in every delegation prompt: *"Follow the Discovered Issues Policy — check KNOWN-ISSUES and the task tracker, then either add to KNOWN-ISSUES or create a bug ticket. Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, immediately add a lesson to that file."*
 
 When reviewing agent output, verify they tracked any discovered issues — not silently ignored them.
 
@@ -484,8 +484,8 @@ Every task follows a strict loop. A task is **not Done** until its output is ind
 ```
 
 **Verification checklist per task:**
-- [ ] No lint or type errors introduced (`yarn nx run <project>:lint`)
-- [ ] Tests pass (`yarn nx run <project>:test`)
+- [ ] No lint or type errors introduced (run the project's lint command — see **codebase-tool** skill)
+- [ ] Tests pass (run the project's test command — see **codebase-tool** skill)
 - [ ] Changed files stay within the agent's file partition
 - [ ] **Fast review passed** (mandatory — load **fast-review** skill)
 - [ ] Acceptance criteria from the issue are met
@@ -493,7 +493,7 @@ Every task follows a strict loop. A task is **not Done** until its output is ind
 - [ ] For data/query tasks: output spot-checked with real data
 - [ ] No regressions in dependent code
 - [ ] For high-stakes tasks: panel review passed (see below)
-- [ ] Discovered issues were tracked (KNOWN-ISSUES or new Linear bug ticket) — not silently ignored
+- [ ] Discovered issues were tracked (KNOWN-ISSUES or new bug ticket) — not silently ignored
 - [ ] Lessons learned were captured — if the agent retried anything, `.github/customizations/LESSONS-LEARNED.md` was updated
 
 **Self-review technique:** After an agent completes, ask it:
@@ -506,7 +506,7 @@ This catches gaps before they become merged code.
 **Rules:**
 - Never mark an issue Done based solely on the agent saying "done" — always verify independently
 - Never proceed to a dependent task until the prerequisite is verified passing
-- If verification fails, update the Linear issue description with the failure details and re-delegate
+- If verification fails, update the issue description with the failure details and re-delegate
 - A panel BLOCK is a fix request, not a stop signal — extract MUST-FIX items and re-delegate immediately
 - A task may iterate multiple times — that is expected and preferred over shipping broken code
 
@@ -538,7 +538,7 @@ When multiple agents complete work simultaneously, batch similar reviews. Load *
 
 ### On session resume
 
-1. **Check for checkpoint** — Read `docs/SESSION-CHECKPOINT.md` if it exists (load the **session-checkpoints** skill for format details)
+1. **Check for checkpoint** — Read `.github/customizations/SESSION-CHECKPOINT.md` if it exists (load the **session-checkpoints** skill for format details)
 2. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures that need retry
 3. **Check disputes** — Scan `.github/customizations/DISPUTES.md` for pending disputes that a human may have resolved since the last session
 4. List issues by In Progress and Todo status
@@ -549,39 +549,39 @@ When multiple agents complete work simultaneously, batch similar reviews. Load *
 
 1. Verify all issues are Done or Cancelled
 2. Run final build/lint/test across all affected projects
-3. **Update `docs/ROADMAP-POST-MVP.md`** — mark items complete with ✅, date, and Linear issue IDs/links so future sessions can trace work back to tracked issues
-4. **Clean up checkpoint** — Archive content to Linear issues, delete `docs/SESSION-CHECKPOINT.md`
-5. Mark all project issues as Done or Cancelled (closing the project requires the Linear UI)
-6. **Commit all changes** to the feature branch with Linear issue ID in commit messages
+3. **Update `.github/customizations/project/roadmap.md`** — mark items complete with ✅, date, and issue IDs/links so future sessions can trace work back to tracked issues
+4. **Clean up checkpoint** — Archive content to tracker issues, delete `.github/customizations/SESSION-CHECKPOINT.md`
+5. Mark all project issues as Done or Cancelled
+6. **Commit all changes** to the feature branch with issue IDs in commit messages
 7. **Push the branch** to origin
 8. **Open a PR** on GitHub — title: `TAS-XX: Short description`. **Do NOT merge**
-9. **Update Linear issue** with the PR URL for traceability
+9. **Update tracker issue** with the PR URL for traceability
 
 ## Execution Checklist
 
 **Before delegating:**
 - [ ] Documentation checked (known issues, architecture docs)
-- [ ] Linear board checked for existing in-progress work
-- [ ] Issues created on Linear for all subtasks
+- [ ] Task tracker checked for existing in-progress work
+- [ ] Issues created for all subtasks
 - [ ] Dependencies mapped and execution order set
 - [ ] File partitions assigned — no overlapping edits between parallel agents
 - [ ] Parallel opportunities identified
 
 **After completion:**
 - [ ] All subtasks completed and independently verified
-- [ ] All Linear issues moved to Done
+- [ ] All issues moved to Done
 - [ ] Lint, test, and build pass for affected projects
 - [ ] Documentation updated
 - [ ] **Session records logged** to `.github/customizations/logs/sessions.ndjson` — one entry per completed task
 - [ ] **Delegation records logged** to `.github/customizations/logs/delegations.ndjson` — one entry per delegation
-- [ ] All changes committed to the feature branch with Linear issue IDs in commit messages
+- [ ] All changes committed to the feature branch with issue IDs in commit messages
 - [ ] Branch pushed to origin
 - [ ] PR opened on GitHub (NOT merged)
-- [ ] Linear issue updated with PR URL
+- [ ] Tracker issue updated with PR URL
 
 ## Delivery Outcome (Required for Every Task)
 
-See `general.instructions.md` § Delivery Outcome for the universal rules (dedicated branch, atomic commits, pushed branch, open PR, Linear linkage). See [shared-delivery-phase.md](../agent-workflows/shared-delivery-phase.md) for the standard commit → push → PR → Linear steps.
+See `general.instructions.md` § Delivery Outcome for the universal rules (dedicated branch, atomic commits, pushed branch, open PR, tracker linkage). See [shared-delivery-phase.md](../agent-workflows/shared-delivery-phase.md) for the standard commit → push → PR → tracker steps.
 
 ### Team Lead-Specific Additions
 
@@ -603,16 +603,34 @@ When automated resolution is exhausted (panel 3x BLOCK, unresolvable conflicts),
 **The Team Lead MUST log every session.** No exceptions. See `general.instructions.md` § Observability Logging for the full rules.
 
 - After delegations: log a **session record** + a **delegation record**
+- After fast reviews: log a **review record** to `reviews.ndjson`
+- After panel reviews: log a **panel record** to `panels.ndjson`
+- After disputes: log a **dispute record** to `disputes.ndjson`
 - After working directly: log a **session record** (use the matching agent role)
 - Log **per task**, before yielding to the user
 - Multiple tasks in one conversation = multiple records
 
+### Pre-Response Logging Checklist
+
+**STOP before responding to the user.** This is Constitution rule #6.
+
+- [ ] **Lessons read** — `.github/customizations/LESSONS-LEARNED.md` was read at session start
+- [ ] **Lessons captured** — If any retry occurred, a new lesson was added to `LESSONS-LEARNED.md`
+- [ ] **Discovered issues tracked** — Any pre-existing bugs found were tracked per the Discovered Issues Policy
+- [ ] **Session logged** — `sessions.ndjson` has a new line for this session (ALWAYS required)
+- [ ] **Delegations logged** — `delegations.ndjson` has a line for each delegation
+- [ ] **Reviews logged** — `reviews.ndjson` has a line for each fast review performed (if any)
+- [ ] **Panels logged** — `panels.ndjson` has a line for each panel review performed (if any)
+- [ ] **Disputes logged** — `disputes.ndjson` has a line for each dispute created (if any)
+
+If ANY required item is missing, fix it NOW before responding.
+
 ## Anti-Patterns
 
-- **Never write or delegate code before Linear issues exist** — issues are a blocking gate, not a follow-up task
+- **Never write or delegate code before issues exist** — issues are a blocking gate, not a follow-up task
 - Never implement code yourself — always delegate
 - Never skip documentation check
-- Never ignore a discovered issue — if it's not tracked in KNOWN-ISSUES or Linear, track it
+- Never ignore a discovered issue — if it's not tracked in KNOWN-ISSUES or the task tracker, track it
 - **Never skip reading `.github/customizations/LESSONS-LEARNED.md`** before delegating — include relevant lessons in delegation prompts
 - **Never let a retry go undocumented** — if an agent retried with a different approach, verify a lesson was captured
 - Never run tasks sequentially when they can be parallel
@@ -631,6 +649,6 @@ When automated resolution is exhausted (panel 3x BLOCK, unresolvable conflicts),
 - **Never allow recursive delegation** — sub-agents must not invoke the Team Lead or spawn their own sub-agents. Each agent is a leaf executor, not an orchestrator
 - **Never leave code changes uncommitted** — every task must end with a pushed branch and open PR
 - **Never merge a PR yourself** — PRs are opened for human review only
-- **Never forget to link the PR to Linear** — traceability is mandatory
+- **Never forget to link the PR to the task tracker** — traceability is mandatory
 - **Never exceed session budget without checkpointing** — context degrades after 8+ delegations; save state and resume in a fresh session
 - **Never skip observability logging** — every session gets logged. No exceptions. No threshold. No "too small to log"

package/src/orchestrator/agents/testing-expert.agent.md

@@ -1,15 +1,15 @@
 ---
-description: 'Testing expert for E2E tests, integration tests, browser validation, and Cypress test suites using Chrome DevTools MCP and test file authoring.'
+description: 'Testing expert for E2E tests, integration tests, browser validation, and test suites using browser automation and test file authoring.'
 name: 'Testing Expert'
 model: GPT-5.3-Codex
-tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
 ---
 
-<!-- ⚠️ 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. -->
 
 # Testing Expert
 
-You are an expert tester who validates UI changes using Chrome DevTools MCP automation and writes E2E/integration test suites.
+You are an expert tester who validates UI changes using browser automation (resolved via the **e2e-testing** capability slot) and writes E2E/integration test suites.
 
 ## Skills
 
@@ -57,7 +57,7 @@ Every test suite must cover:
 
 1. **95% minimum coverage** — all new code must meet the coverage threshold
 2. **Test behavior, not implementation** — tests should survive refactors
-3. **Run the full test suite** — never return without running `yarn nx run <project>:test`
+3. **Run the full test suite** — never return without running the project's test command (see the **codebase-tool** skill)
 
 ## Done When
 

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -1,20 +1,20 @@
 ---
-description: 'UI/UX expert for designing and building accessible, consistent React components with deep knowledge of the design system.'
+description: 'UI/UX expert for designing and building accessible, consistent UI components with deep knowledge of the design system.'
 name: 'UI/UX Expert'
 model: Gemini 3.1 Pro (Preview)
-tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
 ---
 
-<!-- ⚠️ 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. -->
 
 # UI/UX Expert
 
-You are an expert UI/UX developer specializing in building accessible, visually consistent React components based on a design system template.
+You are an expert UI/UX developer specializing in building accessible, visually consistent UI components based on a design system template. Resolve technology-specific details (component library, styling approach) via the **ui-library** capability slot in the skill matrix.
 
 ## Critical Rules
 
 1. **Reference the project template** for design patterns and consistency
-2. **Use CSS Modules + Sass** for component styles, co-located with components
+2. **Follow the project's styling approach** for component styles, co-located with components (see the **ui-library** skill)
 3. **Place shared components in the UI library** — never in app-specific directories
 
 ## Skills
@@ -44,7 +44,7 @@ Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
 - WCAG 2.2 AA compliance verified (keyboard navigation, contrast, semantics)
 - Components are exported from the UI library index
 - Hover, focus, and active states are implemented for all interactive elements
-- CSS Modules are co-located with components
+- Styles are co-located with components per the project's styling conventions
 
 ## Out of Scope
 

package/src/orchestrator/copilot-instructions.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. -->
 
 # Copilot Instructions
 

package/src/orchestrator/customizations/AGENT-FAILURES.md

@@ -29,7 +29,7 @@ Add an entry when **any** of these occur:
 |-------|-------|
 | **Date** | YYYY-MM-DD |
 | **Agent** | Agent name |
-| **Linear Issue** | PREFIX-XX (if applicable) |
+| **Tracker Issue** | PREFIX-XX (if applicable) |
 | **Failure Type** | `verification-fail` / `tool-error` / `panel-block` / `timeout` / `scope-creep` |
 | **Attempts** | Number of attempts before logging |
 

package/src/orchestrator/customizations/AGENT-PERFORMANCE.md

@@ -8,45 +8,45 @@ Tracks agent success rates across panel reviews and delegated tasks to inform mo
 ## Data Sources
 
 Performance data is collected automatically via NDJSON session logs:
-- **Session data:** `customizations/logs/sessions.ndjson` — appended by every agent after each session
-- **Delegation data:** `customizations/logs/delegations.ndjson` — appended by the Team Lead after each delegation
+- **Session data:** `.github/customizations/logs/sessions.ndjson` — appended by every agent after each session
+- **Delegation data:** `.github/customizations/logs/delegations.ndjson` — appended by the Team Lead after each delegation
 - **Full reporting:** Run the **metrics-report** prompt to generate a dashboard from all sources
 
 ## Quick Queries
 
 ```bash
 # Sessions per agent
-jq -r '.agent' customizations/logs/sessions.ndjson | sort | uniq -c | sort -rn
+jq -r '.agent' .github/customizations/logs/sessions.ndjson | sort | uniq -c | sort -rn
 
 # Success rate by agent
-jq -r '[.agent, .outcome] | @tsv' customizations/logs/sessions.ndjson | sort | uniq -c
+jq -r '[.agent, .outcome] | @tsv' .github/customizations/logs/sessions.ndjson | sort | uniq -c
 
 # Delegation tier distribution
-jq -r '.tier' customizations/logs/delegations.ndjson | sort | uniq -c
+jq -r '.tier' .github/customizations/logs/delegations.ndjson | sort | uniq -c
 
 # Failed delegations
-jq 'select(.outcome == "failed")' customizations/logs/delegations.ndjson
+jq 'select(.outcome == "failed")' .github/customizations/logs/delegations.ndjson
 ```
 
 ## Panel Review Performance
 
-Panel review data is collected automatically via `customizations/logs/panels.ndjson` (appended by the panel runner after each review — see step 7 in the panel majority vote skill).
+Panel review data is collected automatically via `.github/customizations/logs/panels.ndjson` (appended by the panel runner after each review — see step 7 in the panel majority vote skill).
 
 ```bash
 # Total panel reviews
-wc -l customizations/logs/panels.ndjson
+wc -l .github/customizations/logs/panels.ndjson
 
 # Pass vs block rate
-jq -r '.verdict' customizations/logs/panels.ndjson | sort | uniq -c
+jq -r '.verdict' .github/customizations/logs/panels.ndjson | sort | uniq -c
 
 # Reviews by panel key
-jq -r '.panel_key' customizations/logs/panels.ndjson | sort | uniq -c | sort -rn
+jq -r '.panel_key' .github/customizations/logs/panels.ndjson | sort | uniq -c | sort -rn
 
 # Reviews that required retries (attempt > 1)
-jq 'select(.attempt > 1)' customizations/logs/panels.ndjson
+jq 'select(.attempt > 1)' .github/customizations/logs/panels.ndjson
 
 # Average SHOULD-FIX items per review
-jq -s 'if length > 0 then (map(.should_fix) | add) / length else 0 end' customizations/logs/panels.ndjson
+jq -s 'if length > 0 then (map(.should_fix) | add) / length else 0 end' .github/customizations/logs/panels.ndjson
 ```
 
 ## Usage

package/src/orchestrator/customizations/DISPUTES.md

@@ -33,7 +33,7 @@ Create a dispute record when **any** of these occur:
 |-------|-------|
 | **Date** | YYYY-MM-DD |
 | **Priority** | `critical` / `high` / `medium` / `low` |
-| **Linear Issue** | PRJ-XX |
+| **Tracker Issue** | PRJ-XX |
 | **Trigger** | `panel-3x-block` / `approach-conflict` / `criteria-conflict` / `architectural-ambiguity` / `external-dependency` |
 | **Implementing Agent** | Agent name |
 | **Reviewing Agent(s)** | Agent name(s) |
@@ -85,8 +85,8 @@ Which option the Team Lead recommends and why. Include specific next steps:
 #### Artifacts
 
 Links to evidence for human review:
-- Panel report: `customizations/logs/panel/[panel-key].md`
-- Review log entries: `customizations/logs/reviews.ndjson` (filter by issue)
+- Panel report: `.github/customizations/logs/panel/[panel-key].md`
+- Review log entries: `.github/customizations/logs/reviews.ndjson` (filter by issue)
 - Changed files: [list of files in the last attempt]
 - DLQ entry (if any): `DLQ-XXX`
 ```
@@ -113,7 +113,7 @@ Links to evidence for human review:
 │  Team Lead creates dispute record     │
 │  Status: pending                      │
 │  Logs to disputes.ndjson              │
-│  Links to Linear issue                │
+│  Links to tracker issue               │
 └──────────────┬───────────────────────┘
                │
                ▼
@@ -156,7 +156,7 @@ A dispute MAY reference a DLQ entry if the dispute escalated from a logged failu
 
 ## Index
 
-| ID | Date | Priority | Trigger | Linear Issue | Status |
+| ID | Date | Priority | Trigger | Tracker Issue | Status |
 |----|------|----------|---------|-------------|--------|
 
 ````

package/src/orchestrator/customizations/KNOWN-ISSUES.md

@@ -0,0 +1,30 @@
+<!-- Populated by agents. Add known issues here during sessions. -->
+
+# Known Issues
+
+Tracked issues, limitations, and accepted risks discovered during agent sessions. Agents check this file before starting work to avoid known pitfalls, and update it when new issues are found or existing ones are resolved.
+
+## How to Use
+
+- **Before starting work:** Scan for entries relevant to your task area
+- **When discovering an issue:** Add a new row with the next available ID
+- **When fixing an issue:** Update the status to `Closed` and add the resolution date
+
+## Issues
+
+| Issue ID | Status | Severity | Summary | Evidence | Root Cause | Solution Options |
+|----------|--------|----------|---------|----------|------------|------------------|
+| KI-001 | Open | Medium | _Example: Description of the issue_ | _Link or description of where/how the issue manifests_ | _Why it happens_ | _Possible fixes or workarounds_ |
+
+### Status Values
+
+- **Open** — Issue is active and unresolved
+- **Mitigated** — Workaround is in place but root cause remains
+- **Closed** — Issue is fully resolved
+
+### Severity Levels
+
+- **Critical** — Blocks core functionality or causes data loss
+- **High** — Significant impact on user experience or developer workflow
+- **Medium** — Noticeable issue with a reasonable workaround
+- **Low** — Minor inconvenience or cosmetic issue

package/src/orchestrator/customizations/LESSONS-LEARNED.md

@@ -29,7 +29,7 @@ Add a lesson when **any** of these occur:
 
 | Field | Value |
 |-------|-------|
-| **Category** | `linear` / `mcp-tools` / `nx-commands` / `terminal` / `next-js` / `sanity` / `supabase` / `git` / `vercel` / `browser-testing` / `general` |
+| **Category** | `task-management` / `mcp-tools` / `codebase-tool` / `terminal` / `framework` / `cms` / `database` / `git` / `deployment` / `browser-testing` / `general` |
 | **Added** | YYYY-MM-DD |
 | **Severity** | `high` (blocks work) / `medium` (wastes 5+ min) / `low` (minor annoyance) |
 
@@ -55,15 +55,15 @@ Add a lesson when **any** of these occur:
 
 | Category | Lessons |
 |----------|---------|
-| `linear` | — |
+| `task-management` | — |
 | `mcp-tools` | — |
-| `nx-commands` | — |
+| `codebase-tool` | — |
 | `terminal` | — |
-| `next-js` | — |
-| `sanity` | — |
-| `supabase` | — |
+| `framework` | — |
+| `cms` | — |
+| `database` | — |
 | `git` | — |
-| `vercel` | — |
+| `deployment` | — |
 | `browser-testing` | — |
 | `general` | — |
 

package/src/orchestrator/customizations/README.md

@@ -14,6 +14,7 @@ Skills reference these files with relative links like `../../customizations/stac
 |------|---------|
 | `project.instructions.md` | High-level project context — apps, libraries, tech stack, ports, URLs |
 | `LESSONS-LEARNED.md` | Knowledge base of retries, workarounds, and gotchas — read before every session |
+| `KNOWN-ISSUES.md` | Tracked issues, limitations, and accepted risks discovered during sessions |
 | `AGENT-FAILURES.md` | Dead letter queue for failed agent delegations |
 | `AGENT-PERFORMANCE.md` | Agent success tracking, log query recipes, performance metrics |
 | `AGENT-EXPERTISE.md` | Structured tracking of agent strengths/weaknesses across sessions |
@@ -36,7 +37,9 @@ Skills reference these files with relative links like `../../customizations/stac
 
 | File | Purpose |
 |------|---------|
-| `docs-structure.md` | `docs/` directory tree and documentation practices |
+| `docs-structure.md` | Project documentation directory tree and practices |
+| `roadmap.md` | Project roadmap with planned features and their status |
+| `decisions.md` | Architecture Decision Records (ADRs) for the project |
 | _(task tracker config created by `bootstrap-customizations` prompt)_ | |
 
 ### `logs/` — Append-only NDJSON session logs
@@ -52,7 +55,7 @@ Structured machine-readable logs appended automatically by agents during session
 
 ## When to update
 
-Update these files when the project changes — new tables, new API routes, new apps, new Linear labels, etc. The skills themselves should rarely need editing; changing a project ID or adding a table column is a customization change, not a skill change.
+Update these files when the project changes — new tables, new API routes, new apps, new tracker labels, etc. The skills themselves should rarely need editing; changing a project ID or adding a table column is a customization change, not a skill change.
 
 ## Bootstrap
 

package/src/orchestrator/customizations/agents/agent-registry.md

@@ -11,7 +11,7 @@ Project-specific agent-to-model assignments and scope examples referenced by the
 |-------|-------|------|----------|
 | **Developer** | Gemini 3.1 Pro | Standard | Full-stack feature implementation, pages, components, routing, API routes |
 | **Testing Expert** | GPT-5.3-Codex | Utility | E2E tests, browser validation, terminal-heavy test loops |
-| **Content Engineer** | Gemini 3.1 Pro | Standard | CMS schema, GROQ queries, MCP tool coordination |
+| **Content Engineer** | Gemini 3.1 Pro | Standard | CMS schema, content queries, MCP tool coordination |
 | **Database Engineer** | Gemini 3.1 Pro | Standard | Migrations, RLS policies, SQL optimization |
 | **UI/UX Expert** | Gemini 3.1 Pro | Standard | Components, styling, accessibility |
 | **Performance Expert** | Gemini 3.1 Pro | Standard | Bundle size, Core Web Vitals, profiling |

package/src/orchestrator/customizations/agents/skill-matrix.md

@@ -41,7 +41,7 @@ Agent file                  Skill Matrix                 Skill file
 | `database` | | | Schema, migrations, auth flow, roles |
 | `cms` | | | Document types, queries, schema management |
 | `deployment` | | | Hosting, cron jobs, env vars, caching, headers |
-| `monorepo` | | | Task running, caching, affected commands, generators |
+| `codebase-tool` | | | Task running, building, linting, testing, code generation |
 
 ### Tooling
 
@@ -50,8 +50,7 @@ Agent file                  Skill Matrix                 Skill file
 | `api-layer` | | | API routes, validation, search architecture |
 | `data-pipeline` | | | ETL, scraping, data processing |
 | `testing` | | | Unit/integration tests, coverage, test planning |
-| `e2e-testing` | | | Browser automation, viewport testing, visual validation |
-
+| `e2e-testing` | | | Browser automation, viewport testing, visual validation || `task-management` | | | Issue tracking, naming, priorities, workflow states |
 ### Disciplines
 
 | Slot | Approach | Skill | Description |
@@ -77,14 +76,14 @@ Each row shows which capability slots an agent needs (resolved through this matr
 | **Data Expert** | `data-pipeline` | — |
 | **DevOps Expert** | `deployment` | — |
 | **Performance Expert** | `performance` | — |
-| **Architect** | `monorepo` | `documentation-standards` |
+| **Architect** | `codebase-tool` | `documentation-standards` |
 | **Copywriter** | `cms` | `documentation-standards` |
 | **SEO Specialist** | `framework`, `cms`, `seo` | — |
 | **API Designer** | `api-layer`, `framework`, `security` | — |
-| **Release Manager** | `monorepo`, `deployment` | `validation-gates`, `documentation-standards` |
+| **Release Manager** | `codebase-tool`, `deployment` | `validation-gates`, `documentation-standards` |
 | **Documentation Writer** | — | `documentation-standards`, `code-commenting` |
 | **Researcher** | — | `context-map`, `self-improvement` |
-| **Team Lead** | — | `team-lead-reference`, `task-management`, `session-checkpoints`, `validation-gates`, `fast-review`, `panel-majority-vote`, `context-map`, `memory-merger`, `agent-hooks` |
+| **Team Lead** | `task-management` | `team-lead-reference`, `session-checkpoints`, `validation-gates`, `fast-review`, `panel-majority-vote`, `context-map`, `memory-merger`, `agent-hooks` |
 
 ¹ UI/UX Expert uses `e2e-testing` as a utility (viewport resize commands) — resolved through the matrix like other slots.
 
@@ -102,7 +101,7 @@ These are methodology/workflow skills — not tied to any technology. Referenced
 | `code-commenting` | Self-documenting code patterns, annotation tags |
 | `agent-hooks` | Agent lifecycle hooks (session-start, session-end, etc.) |
 | `agent-memory` | Agent expertise tracking, cross-session knowledge graph |
-| `task-management` | Linear board conventions, issue naming, priorities |
+| `task-management` | Issue tracking conventions, naming, priorities |
 | `team-lead-reference` | Team Lead orchestration reference, model routing |
 | `fast-review` | Mandatory single-reviewer gate after every delegation |
 | `validation-gates` | Shared validation gate definitions (lint, test, build) |
@@ -131,6 +130,12 @@ These are methodology/workflow skills — not tied to any technology. Referenced
 2. Update matrix: `testing` → `Vitest` / `vitest-workflow`
 3. **No agent files change** — Testing Expert still references the `testing` slot
 
+### Example: Linear → Jira
+
+1. Skill already exists: `skills/jira-management/SKILL.md`
+2. Update matrix: `task-management` → `Jira` / `jira-management`
+3. **No agent files change** — Team Lead still references the `task-management` slot
+
 ## Design Principles
 
 1. **Single source of truth** — Technology choices live here, not scattered across agent files

package/src/orchestrator/customizations/logs/README.md

@@ -126,7 +126,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
   "attempt": 1,
   "linear_issue": "PRJ-57",
   "artifacts_count": 14,
-  "report_path": "customizations/logs/panel/instruction-refactoring.md"
+  "report_path": ".github/customizations/logs/panel/instruction-refactoring.md"
 }
 ```