opencastle 0.5.1 → 0.7.0

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"
 }
 ```
 

package/src/orchestrator/customizations/project/decisions.md

@@ -0,0 +1,31 @@
+<!-- Populated by agents. Add ADRs here when architectural decisions are made. -->
+
+# Architecture Decision Records
+
+Log of architectural decisions made during the project. Each ADR captures the context, decision, and consequences so future sessions understand why things are the way they are.
+
+## How to Use
+
+- **Before making an architectural decision:** Check existing ADRs for prior decisions in the same area
+- **After making a decision:** Add a new ADR with the next available ID
+- **When revisiting a decision:** Update the status to `Superseded` and reference the new ADR
+
+## Decisions
+
+### ADR-001: _Template — Short Decision Title_
+
+| Field | Value |
+|-------|-------|
+| **ID** | ADR-001 |
+| **Date** | YYYY-MM-DD |
+| **Status** | Proposed / Accepted / Deprecated / Superseded |
+
+**Context:** _What is the issue that we're seeing that motivates this decision?_
+
+**Decision:** _What is the change that we're proposing and/or doing?_
+
+**Consequences:** _What becomes easier or more difficult to do because of this change?_
+
+---
+
+_Add new ADRs above this line, incrementing the ID._

package/src/orchestrator/customizations/project/docs-structure.md

@@ -4,20 +4,31 @@
 
 Project-specific documentation layout referenced by the `documentation-standards` skill.
 
+Documentation files live in the `.github/customizations/` directory alongside other project-specific configuration. Key documentation files:
+
+- `.github/customizations/KNOWN-ISSUES.md` — Tracked issues, limitations, and accepted risks
+- `.github/customizations/project/roadmap.md` — Project roadmap and feature status
+- `.github/customizations/project/decisions.md` — Architecture Decision Records
+- `.github/customizations/LESSONS-LEARNED.md` — Agent knowledge base of retries and workarounds
+
 ## Directory Tree
 
-<!-- Map your project's docs/ directory here -->
+<!-- Map your project's documentation directory here if one exists -->
 
 ```
-docs/
-├── README.md               — Documentation index
-└── ...                     — Add entries as docs are created
+.github/customizations/
+├── KNOWN-ISSUES.md            — Tracked issues and limitations
+├── LESSONS-LEARNED.md         — Agent knowledge base
+└── project/
+    ├── roadmap.md             — Feature roadmap
+    ├── decisions.md           — Architecture Decision Records
+    └── docs-structure.md      — This file
 ```
 
 ## Practices
 
 - **Check Known Issues** before starting any task
-- **Review Architecture** docs for context
+- **Review Architecture** decisions for context
 - **Update roadmap** after completing features
 - **Add new issues** with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
 - **Archive** outdated docs rather than deleting

package/src/orchestrator/customizations/project/roadmap.md

@@ -0,0 +1,24 @@
+<!-- Populated by the bootstrap-customizations prompt or manually. -->
+
+# Project Roadmap
+
+High-level roadmap of planned features and improvements. Updated by agents as tasks are completed.
+
+## How to Use
+
+- **Before implementing a feature:** Check the roadmap for scope, status, and acceptance criteria
+- **After completing a feature:** Mark the item with ✅, add the completion date and tracker issue IDs
+- **When planning:** Add new items with priority and description
+
+## Roadmap Items
+
+| Status | Priority | Description | Tracker Issues |
+|--------|----------|-------------|----------------|
+| Planned | High | _Example: Short description of the feature_ | — |
+
+### Status Values
+
+- **Planned** — Scoped but not yet started
+- **In Progress** — Actively being worked on
+- **Done** — Completed and verified
+- **Cancelled** — Removed from scope with documented reason

package/src/orchestrator/customizations/project/tracker-config.md

@@ -3,7 +3,7 @@
 <!-- Populated by the `bootstrap-customizations` prompt.
      Rename this file to match your tracker: linear-config.md, jira-config.md, etc. -->
 
-Project-specific task tracker details referenced by the `task-management` skill.
+Project-specific task tracker details referenced by task management workflows.
 
 ## Workspace
 

package/src/orchestrator/customizations/stack/cms-config.md

@@ -19,7 +19,7 @@ Project-specific CMS details referenced by the corresponding CMS skill (e.g., `s
 
 ## Query Examples
 
-<!-- Provide representative query examples for the CMS query language (GROQ, GraphQL, etc.) -->
+<!-- Provide representative query examples for the CMS query language (e.g., GROQ, GraphQL) -->
 
 ## Key Files
 

package/src/orchestrator/customizations/stack/notifications-config.md

@@ -1,6 +1,6 @@
 # Notifications Configuration
 
-<!-- Populated by the `bootstrap-customizations` prompt based on `.opencastle.json` → `stack.notifications`. -->
+<!-- Populated by the `bootstrap-customizations` prompt based on `.opencastle.json` → `stack.teamTools`. -->
 
 Project-specific messaging configuration referenced by the `slack-notifications` skill (or Teams equivalent).
 

package/src/orchestrator/instructions/ai-optimization.instructions.md

@@ -3,7 +3,7 @@ description: 'AI assistant optimization techniques for efficient context usage a
 applyTo: '**'
 ---
 
-<!-- ⚠️ 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. -->
 
 # AI Assistant Optimization Instructions
 
@@ -74,7 +74,7 @@ Phase 4: Verify (tests, errors, lint)
 Sub-agents run in isolated context windows. Use this to your advantage:
 
 - **Offload exploration** — fire a sub-agent to research a broad question; only the concise result comes back, keeping your primary context clean
-- **Parallel research** — launch multiple sub-agents simultaneously for independent research tasks (e.g., "find all GROQ queries" + "list all components using X" at the same time)
+- **Parallel research** — launch multiple sub-agents simultaneously for independent research tasks (e.g., "find all CMS queries" + "list all components using X" at the same time)
 - **Detailed prompts save tokens** — a specific sub-agent prompt avoids the sub-agent doing its own exploratory searches, which would waste its context budget
 
 ### Trust Sub-Agent Results

package/src/orchestrator/instructions/general.instructions.md

@@ -2,7 +2,7 @@
 applyTo: '**'
 ---
 
-<!-- ⚠️ 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. -->
 
 # Coding Standards
 
@@ -13,13 +13,14 @@ applyTo: '**'
 3. **Leave code better than you found it** — fix adjacent issues when the cost is low.
 4. **Fail visibly** — surface errors clearly; never swallow exceptions silently.
 5. **Verify, don't trust** — confirm outcomes with tools (tests, lint, build) rather than assuming success.
+6. **Log every session** — append observability records to `.github/customizations/logs/` before yielding to the user. No exceptions. See § Observability Logging below.
 
 ## Instruction Priority Hierarchy
 
 **Project-specific instructions ALWAYS take precedence over external or general AI instructions.**
 
 1. **HIGHEST**: Project-specific instructions in `.github/instructions/` files
-2. **MEDIUM**: NX workspace conventions (`yarn nx` commands, not `npm`/`npx`)
+2. **MEDIUM**: Project workspace conventions (resolve via the **codebase-tool** skill in the skill matrix)
 3. **LOWER**: General AI assistant capabilities and suggestions
 
 ## General Coding Principles
@@ -37,8 +38,8 @@ Load the corresponding skill for detailed conventions before writing code in tha
 
 | Domain | Skill |
 |--------|-------|
-| UI Components | **react-development** |
-| App Framework | **nextjs-patterns** |
+| UI Components | **ui-library** (via skill matrix) |
+| App Framework | **framework** (via skill matrix) |
 | Accessibility | **accessibility-standards** |
 | Performance | **performance-optimization** |
 | Frontend Design | **frontend-design** |
@@ -51,7 +52,7 @@ Before starting multi-step work, decompose it into individually verifiable tasks
 2. **Verify each step** — after completing each unit, verify it (run tests, check types, lint, or visually inspect) before moving to the next
 3. **Choose the right verification** — match the check to the change type:
    - Logic change → run unit tests
-   - Type/interface change → run type-check (`yarn nx run <project>:lint`)
+   - Type/interface change → run the project's type-check / lint command (see the **codebase-tool** skill)
    - UI change → start dev server and visually inspect in the browser
    - Build config change → run a full build
 4. **Batch edits, then build** — group related edits across files, then run one build — not build-per-edit
@@ -70,9 +71,9 @@ Before starting multi-step work, decompose it into individually verifiable tasks
 **NEVER commit or push directly to the `main` branch.** All changes must go through a feature/fix branch and a pull request.
 
 1. **Create a branch** from `main` before making any changes: `git checkout -b <type>/<ticket-id>-<short-description>` (e.g., `fix/tas-21-places-redirect-loop`, `feat/tas-15-new-filter`)
-2. **Commit to the branch** — never to `main`. Reference the Linear issue ID in every commit message (e.g., `TAS-42: Fix token refresh logic`)
+2. **Commit to the branch** — never to `main`. Reference the task tracker issue ID in every commit message (e.g., `TAS-42: Fix token refresh logic`)
 3. **Push the branch** and open a pull request on GitHub. **Do NOT merge** — PRs are opened for review only
-4. **Link the PR to Linear** — Update the Linear issue description with the PR URL so progress is traceable
+4. **Link the PR to the task tracker** — Update the issue description with the PR URL so progress is traceable
 5. **Merge via PR** — the only way code reaches `main`, and only after review/approval
 
 Branch naming convention: `<type>/<ticket-id>-<short-description>` where type is `fix`, `feat`, `chore`, `refactor`, `perf`, or `docs`.
@@ -91,31 +92,27 @@ Branch naming convention: `<type>/<ticket-id>-<short-description>` where type is
 Every task that produces code changes — whether a roadmap feature, bug fix, follow-up, data pipeline, or refactor — must deliver:
 
 1. **Dedicated branch** — `<type>/<ticket-id>-<short-description>` created from `main`
-2. **Atomic commits** — Each commit references the Linear issue ID (e.g., `TAS-42: Add filter component`)
+2. **Atomic commits** — Each commit references the issue ID (e.g., `TAS-42: Add filter component`)
 3. **Pushed branch** — Branch pushed to origin
 4. **Open PR** — Use `gh` CLI to create the PR. **Do NOT merge** — PRs are opened for review only:
    ```bash
    GH_PAGER=cat gh pr create --base main --title "TAS-XX: Short description" --body "Resolves TAS-XX"
    ```
-5. **Linear linkage** — The Linear issue is updated with the PR URL, and the PR description references the Linear issue ID
+5. **Task tracker linkage** — The issue is updated with the PR URL, and the PR description references the issue ID
 
-## NX Commands
+## Build & Task Commands
 
-**NEVER use `npm`/`npx`/`jest`/`eslint` directly. Always use `yarn nx` commands.**
+Use the project's configured task runner for all build, test, lint, and serve commands. **Never invoke test runners or linters directly** — always use the task runner wrapper.
 
-```bash
-yarn nx run <project-name>:test [--coverage] [-u]
-yarn nx run <project-name>:lint --fix
-yarn nx run <project-name>:lint-styles --fix
-yarn nx run <project-name>:build
-yarn nx run <project-name>:serve
-yarn nx generate <generator-name>
-yarn nx affected -t <target>
-```
+Resolve exact commands by loading the **codebase-tool** skill from the skill matrix. Common tasks:
 
-**Exception:** Tools without NX targets may be invoked directly — e.g., `npx sanity@latest schema deploy`, `npx supabase gen types`, `next start`. Check `project.json` targets first; only bypass NX when no target exists.
+- **Test** — run project tests (with optional coverage)
+- **Lint** — run linter with auto-fix
+- **Build** — production build
+- **Serve** — start dev server
+- **Affected** — run a target for all projects affected by current changes
 
-For comprehensive NX conventions, load the **nx-workspace** skill.
+**Exception:** Tools without task runner targets may be invoked directly (e.g., CMS CLI commands, database CLI commands). Check the project's task runner config first; only bypass it when no target exists.
 
 ## Documentation
 
@@ -127,25 +124,27 @@ Follow prompt caching and batch processing best practices. See [AI Optimization
 
 ## Discovered Issues Policy
 
-**No issue gets ignored.** When you encounter a bug, error, or unexpected behavior that is unrelated to the current task:
+> **⛔ No issue gets ignored.** Untracked bugs discovered during work are a quality gate failure.
+
+When you encounter a bug, error, or unexpected behavior that is unrelated to the current task:
 
 1. **Check if already tracked:**
-   - Search `docs/KNOWN-ISSUES.md` for a matching entry
-   - If you have Linear tools available, also search Linear for open bugs (use `search_issues` or `list_issues` with bug label)
+   - Search `.github/customizations/KNOWN-ISSUES.md` for a matching entry
+   - If you have task tracker tools available, also search for open bugs (use `search_issues` or `list_issues` with bug label)
 2. **If found tracked** — skip it, continue with your current work
 3. **If NOT tracked** — you must act:
-   - **Unfixable limitation** (third-party constraint, platform restriction, upstream dependency) → add it to `docs/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
-   - **Fixable bug** → if you have Linear tools, create a ticket with label `bug`, appropriate priority, and a clear description of the symptoms, reproduction steps, and affected files. If you do NOT have Linear tools, add a `**Discovered Issues**` section to your output listing the bug details so the Team Lead can track it.
+   - **Unfixable limitation** (third-party constraint, platform restriction, upstream dependency) → add it to `.github/customizations/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Fixable bug** → if you have task tracker tools, create a ticket with label `bug`, appropriate priority, and a clear description of the symptoms, reproduction steps, and affected files. If you do NOT have task tracker tools, add a `**Discovered Issues**` section to your output listing the bug details so the Team Lead can track it.
 
 Never assume a pre-existing issue is somebody else's problem. If it's not tracked, track it.
 
 ## Task Tracking
 
-Feature work is tracked on **Linear** (see `linear-config.md` for team and project details). The Team Lead agent creates and updates issues via MCP. For conventions, load the **task-management** skill.
+Feature work is tracked in the **task tracker** (see `tracker-config.md` for project details). The Team Lead agent creates and updates issues via MCP. For conventions, load the **task-management** skill.
 
-### When Linear MCP Tools Are Unavailable
+### When Task Tracker MCP Tools Are Unavailable
 
-If Linear MCP tools are not available in the current session, do NOT block on issue creation. Instead:
+If task tracker MCP tools are not available in the current session, do NOT block on issue creation. Instead:
 
 1. **Document planned issues** in your output with the title, description, and acceptance criteria you would have used
 2. **Proceed with implementation** — the work is still valuable without a ticket number
@@ -155,37 +154,79 @@ If Linear MCP tools are not available in the current session, do NOT block on is
 
 ## Observability Logging (Mandatory)
 
+> **⛔ HARD GATE — This is a blocking requirement, not a suggestion.**
+> Do NOT respond to the user until you have appended the required log records.
+> A session without log records is a failed session — regardless of code quality.
+
 **Every agent MUST log every session to the observability NDJSON files.** No exceptions. No threshold. No "too small to log." The dashboard depends on this data.
 
 ### What to log
 
-| File | Who appends | When |
-|------|------------|------|
-| `sessions.ndjson` | **All agents** | After every session — always |
-| `delegations.ndjson` | **Team Lead** | After each delegation to a specialist agent |
-| `panels.ndjson` | **Panel runner** | After each majority-vote review |
+| File | Who appends | When | Example command below |
+|------|------------|------|----------------------|
+| `sessions.ndjson` | **All agents** | After every session — always | ✅ |
+| `delegations.ndjson` | **Team Lead** | After each delegation to a specialist agent | ✅ |
+| `reviews.ndjson` | **Team Lead** (via fast-review skill) | After each fast review | ✅ |
+| `panels.ndjson` | **Panel runner** (via panel majority vote skill) | After each majority-vote review | ✅ |
+| `disputes.ndjson` | **Team Lead** (via dispute protocol) | After each dispute record | ✅ |
 
 See `.github/customizations/logs/README.md` for the full schema of each record.
 
 ### How to log
 
-Append one JSON line per task. When the Team Lead works directly, use the agent role that best describes the work (e.g., `"agent": "Developer"`, `"agent": "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
+Append one JSON line per task using `echo '...' >> <file>`. When the Team Lead works directly, use the agent role that best describes the work (e.g., `"agent": "Developer"`, `"agent": "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
 
+**Session record** (ALL agents, EVERY session):
 ```bash
 echo '{"timestamp":"2026-03-01T14:00:00Z","agent":"Developer","model":"claude-opus-4-6","task":"Fix login redirect bug","outcome":"success","duration_min":15,"files_changed":3,"retries":0,"lessons_added":[],"discoveries":[]}' >> .github/customizations/logs/sessions.ndjson
 ```
 
+**Delegation record** (Team Lead only, after each delegation):
+```bash
+echo '{"timestamp":"2026-03-01T14:00:00Z","session_id":"feat/prj-57","agent":"Developer","model":"gpt-5.3-codex","tier":"fast","mechanism":"sub-agent","linear_issue":"PRJ-57","outcome":"success","retries":0,"phase":2,"file_partition":["src/components/"]}' >> .github/customizations/logs/delegations.ndjson
+```
+
+**Fast review record** (Team Lead, after each fast review):
+```bash
+echo '{"timestamp":"2026-03-01T14:30:00Z","linear_issue":"PRJ-42","agent":"Developer","reviewer_model":"gpt-5-mini","verdict":"pass","attempt":1,"issues_critical":0,"issues_major":0,"issues_minor":2,"confidence":"high","escalated":false,"duration_sec":45}' >> .github/customizations/logs/reviews.ndjson
+```
+
+**Panel record** (after each panel majority vote):
+```bash
+echo '{"timestamp":"2026-03-01T15:00:00Z","panel_key":"auth-review","verdict":"pass","pass_count":2,"block_count":1,"must_fix":0,"should_fix":3,"reviewer_model":"claude-opus-4-6","weighted":false,"attempt":1,"linear_issue":"PRJ-42","artifacts_count":5}' >> .github/customizations/logs/panels.ndjson
+```
+
+**Dispute record** (Team Lead, after each dispute):
+```bash
+echo '{"timestamp":"2026-03-01T16:00:00Z","dispute_id":"DSP-001","linear_issue":"PRJ-42","priority":"high","trigger":"panel-3x-block","implementing_agent":"Developer","reviewing_agents":["Reviewer","Panel (3x)"],"total_attempts":6,"est_tokens_spent":120000,"status":"pending","resolution_option_chosen":null,"resolved_at":null}' >> .github/customizations/logs/disputes.ndjson
+```
+
+### Pre-Response Logging Checklist
+
+**STOP before responding to the user.** Verify each applicable item:
+
+- [ ] **Session logged** — `sessions.ndjson` has a new line for this session (ALWAYS required)
+- [ ] **Delegations logged** — `delegations.ndjson` has a line for each delegation (Team Lead only)
+- [ ] **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 log is missing, append it NOW before responding.
+
 ### Rules
 
-- **Log before yielding to the user** — logging is the last action before responding.
+- **Log before yielding to the user** — logging is the LAST action before responding. This is Constitution rule #6.
 - **Log per task**, not per conversation. Multiple tasks = multiple records.
 - **Never batch-log retrospectively** across sessions.
+- **Verify the append succeeded** — if unsure, `tail -1` the file to confirm.
 
 ## Self-Improvement Protocol
 
+> **⛔ HARD GATE — Lessons are the team's collective memory. Skipping them causes repeated failures.**
+
 **Every agent must learn from mistakes and share knowledge.** This prevents the same pitfalls from being repeated across sessions.
 
-1. **Before starting work:** Read `.github/customizations/LESSONS-LEARNED.md` — apply relevant lessons proactively
+1. **Before starting work:** Read `.github/customizations/LESSONS-LEARNED.md` — apply relevant lessons proactively. This is NOT optional.
 2. **During execution:** If you retry a command/tool with a different approach and it works, **immediately** add a lesson entry to `.github/customizations/LESSONS-LEARNED.md`
 3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too
 4. **Update instructions:** Proactively suggest updates to `.github/instructions/` or `.github/skills/` files when:
@@ -210,16 +251,37 @@ These rules apply to ALL specialist agents automatically. **Do not duplicate the
 1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents. If work requires another domain, document the need in your output contract.
 2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see § Discovered Issues Policy above).
 3. **Read and update lessons** — Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, add a lesson immediately.
-4. **Log every session** — Append to `.github/customizations/logs/sessions.ndjson` after every session. No exceptions. See § Observability Logging above.
+4. **Log every session** — Append to `.github/customizations/logs/sessions.ndjson` after every session. No exceptions. See § Observability Logging above. This is Constitution rule #6 — a blocking gate, not optional.
 
 ## Base Output Contract
 
 Every specialist agent's Output Contract MUST end with these standard items (in addition to domain-specific items above them):
 
-- **Session Logged** — Confirm that a session record was appended to `.github/customizations/logs/sessions.ndjson` (mandatory per § Observability Logging)
+- **Observability Logged** — Confirm ALL applicable log records were appended (Constitution rule #6):
+  - `sessions.ndjson` — ALWAYS (every agent, every session)
+  - `delegations.ndjson` — if delegations occurred (Team Lead only)
+  - `reviews.ndjson` — if fast reviews occurred
+  - `panels.ndjson` — if panel reviews occurred
+  - `disputes.ndjson` — if disputes were created
 - **Discovered Issues** — Pre-existing bugs or anomalies found during work, with tracking action taken per the Discovered Issues Policy
 - **Lessons Applied** — Lessons from `.github/customizations/LESSONS-LEARNED.md` that influenced this work, and any new lessons added
 
 Agents reference this contract with: `See **Base Output Contract** in general.instructions.md for the standard closing items.`
 
+## Pre-Response Quality Gate
+
+> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
+
+This is the single exit gate for every session. All items are mandatory unless marked conditional.
+
+- [ ] **Lessons read** — `.github/customizations/LESSONS-LEARNED.md` was read at session start (Self-Improvement Protocol)
+- [ ] **Lessons captured** — If any retry occurred, a new lesson was added to `LESSONS-LEARNED.md`
+- [ ] **Discovered issues tracked** — Any pre-existing bugs found were added to `KNOWN-ISSUES.md` or a tracker ticket was created (Discovered Issues Policy)
+- [ ] **Lint/type/test pass** — No new errors introduced; verification ran after code changes (Constitution rule #5)
+- [ ] **Session logged** — `sessions.ndjson` has a new line for this session (Constitution rule #6 — ALWAYS required)
+- [ ] **Delegations logged** — `delegations.ndjson` has a line for each delegation (Team Lead only)
+- [ ] **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)
+
 <!-- End of Coding Standards -->

package/src/orchestrator/{skills/browser-testing → plugins/chrome-devtools}/SKILL.md

@@ -3,7 +3,7 @@ name: browser-testing
 description: "Chrome DevTools MCP automation patterns for validating UI changes in real browsers. Use when performing E2E browser testing, validating visual changes, testing user interactions, or debugging UI issues with Chrome DevTools."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Browser Testing with Chrome DevTools MCP
 

package/src/orchestrator/plugins/chrome-devtools/config.ts

@@ -0,0 +1,29 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'chrome-devtools',
+  name: 'Chrome DevTools',
+  category: 'tech',
+  subCategory: 'testing',
+  label: 'Chrome DevTools',
+  hint: 'Browser testing, screenshots, DOM inspection',
+  skillName: 'browser-testing',
+  mcpServerKey: 'chrome-devtools',
+  mcpConfig: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', 'chrome-devtools-mcp@latest'],
+  },
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {
+    'performance-expert': ['chrome-devtools/*'],
+    'seo-specialist': ['chrome-devtools/*'],
+    'testing-expert': ['chrome-devtools/*'],
+    'ui-ux-expert': ['chrome-devtools/*'],
+  },
+  docsUrl: '/guides/plugins#chrome-devtools',
+  officialDocs: 'https://developer.chrome.com/docs/devtools',
+  mcpPackage: 'chrome-devtools-mcp',
+  preselected: true,
+};

package/src/orchestrator/{skills/contentful-cms → plugins/contentful}/SKILL.md

@@ -3,7 +3,7 @@ name: contentful-cms
 description: "Contentful CMS development patterns, GraphQL/REST API usage, content modeling, and migration best practices. Use when working with Contentful content types, entries, assets, or the Management API."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Contentful CMS
 

package/src/orchestrator/plugins/contentful/config.ts

@@ -0,0 +1,49 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'contentful',
+  name: 'Contentful',
+  category: 'tech',
+  subCategory: 'cms',
+  label: 'Contentful',
+  hint: 'GraphQL / REST API, structured content',
+  skillName: 'contentful-cms',
+  mcpServerKey: 'Contentful',
+  mcpConfig: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@contentful/mcp-server'],
+  },
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {
+    'content-engineer': [
+      'contentful/get_initial_context', 'contentful/list_content_types', 'contentful/get_content_type',
+      'contentful/create_content_type', 'contentful/update_content_type', 'contentful/publish_content_type',
+      'contentful/unpublish_content_type', 'contentful/delete_content_type', 'contentful/search_entries',
+      'contentful/get_entry', 'contentful/create_entry', 'contentful/update_entry',
+      'contentful/publish_entry', 'contentful/unpublish_entry', 'contentful/delete_entry',
+      'contentful/list_editor_interfaces', 'contentful/get_editor_interface', 'contentful/update_editor_interface',
+      'contentful/upload_asset', 'contentful/list_assets', 'contentful/get_asset',
+      'contentful/update_asset', 'contentful/publish_asset', 'contentful/unpublish_asset',
+      'contentful/delete_asset', 'contentful/list_spaces', 'contentful/get_space',
+      'contentful/list_environments', 'contentful/create_environment', 'contentful/delete_environment',
+      'contentful/list_locales', 'contentful/get_locale', 'contentful/create_locale',
+      'contentful/update_locale', 'contentful/delete_locale', 'contentful/list_tags',
+      'contentful/create_tag', 'contentful/list_orgs', 'contentful/get_org',
+    ],
+    'copywriter': [
+      'contentful/get_initial_context', 'contentful/list_content_types', 'contentful/get_content_type',
+      'contentful/search_entries', 'contentful/get_entry', 'contentful/update_entry',
+      'contentful/publish_entry', 'contentful/list_spaces', 'contentful/get_space',
+    ],
+    'data-expert': [
+      'contentful/get_initial_context', 'contentful/list_content_types', 'contentful/get_content_type',
+      'contentful/search_entries', 'contentful/get_entry', 'contentful/create_entry',
+      'contentful/update_entry', 'contentful/list_spaces', 'contentful/get_space',
+    ],
+  },
+  docsUrl: null,
+  officialDocs: 'https://www.contentful.com/developers/docs/',
+  mcpPackage: '@contentful/mcp-server',
+};

package/src/orchestrator/{skills/convex-database → plugins/convex}/SKILL.md

@@ -3,7 +3,7 @@ name: convex-database
 description: "Convex reactive database patterns, schema design, real-time queries, mutations, actions, and deployment best practices. Use when designing Convex schemas, writing queries/mutations, or managing the Convex backend."
 ---
 
-<!-- ⚠️ 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. -->
 
 # Convex Database