opencastle 0.10.7 → 0.11.0

package/src/orchestrator/customizations/README.md

@@ -50,9 +50,7 @@ Structured machine-readable logs appended automatically by agents during session
 | File | Purpose |
 |------|---------|
 | `README.md` | Schema documentation for the NDJSON log files |
-| `sessions.ndjson` | Structured session log entries |
-| `delegations.ndjson` | Structured delegation log entries |
-| `panels.ndjson` | Structured panel review log entries |
+| `events.ndjson` | All structured event log entries (sessions, delegations, reviews, panels, disputes) |
 
 ## When to update
 

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

@@ -1,21 +1,64 @@
 # Agent Session Logs
 
-Append-only NDJSON logs for agent activity tracking. Each file stores one JSON object per line.
+Append-only NDJSON log for agent activity tracking. All events are stored in a single file with a `type` discriminator — one JSON object per line.
 
-## Files
+## File
 
-| File | Appended by | Schema |
-|------|------------|--------|
-| `sessions.ndjson` | All agents (via self-improvement protocol) | Session record |
-| `delegations.ndjson` | Team Lead agent | Delegation record |
-| `reviews.ndjson` | Team Lead (via fast-review skill) | Fast review record |
-| `panels.ndjson` | Panel runner (via panel majority vote skill) | Panel record |
-| `disputes.ndjson` | Team Lead (via dispute protocol) | Dispute record |
+| File | Description |
+|------|-------------|
+| `events.ndjson` | All agent events, sorted by timestamp |
 
-## Session Record Schema
+## Type Discriminator
+
+Each record includes a `type` field that identifies the event kind:
+
+| `type` value | Appended by | Description |
+|-------------|-------------|-------------|
+| `session` | All agents (via self-improvement protocol) | Session record |
+| `delegation` | Team Lead agent | Delegation record |
+| `review` | Team Lead (via fast-review skill) | Fast review record |
+| `panel` | Panel runner (via panel majority vote skill) | Panel record |
+| `dispute` | Team Lead (via dispute protocol) | Dispute record |
+
+## CLI Usage
+
+Use `opencastle log` to append events. Agents should call this instead of raw `echo` commands.
+
+```sh
+# Session
+opencastle log --type session --agent Developer --model claude-sonnet-4-6 \
+  --task "PRJ-57: Fix header component" --outcome success --duration_min 12 \
+  --files_changed 5 --retries 0
+
+# Delegation
+opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
+  --model claude-opus-4-6 --tier fast --mechanism sub-agent \
+  --outcome success --phase 2 --file_partition "src/components/,src/pages/"
+
+# Review
+opencastle log --type review --tracker_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
+
+# Panel
+opencastle log --type panel --panel_key auth-review --verdict pass \
+  --pass_count 3 --block_count 0 --must_fix 0 --should_fix 5 \
+  --reviewer_model claude-opus-4-6 --weighted false --attempt 1
+
+# Dispute
+opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
+  --priority high --trigger panel-3x-block --implementing_agent Developer \
+  --reviewing_agents "Reviewer,Panel (3x)" --total_attempts 6 --status pending
+```
+
+Run `opencastle log --help` for full options.
+
+## Session Record (`type: "session"`)
 
 ```json
 {
+  "type": "session",
   "timestamp": "2026-02-25T14:30:00Z",
   "agent": "Developer",
   "model": "gpt-5.3-codex",
@@ -32,6 +75,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"session"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `agent` | `string` | Yes | Agent name from the registry |
 | `model` | `string` | Yes | Model used (e.g., `claude-opus-4-6`, `gpt-5.3-codex`) |
@@ -44,10 +88,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `lessons_added` | `string[]` | No | Lesson IDs added (e.g., `["LES-015"]`) |
 | `discoveries` | `string[]` | No | Issues discovered (issue IDs or KNOWN-ISSUES IDs) |
 
-## Delegation Record Schema
+## Delegation Record (`type: "delegation"`)
 
 ```json
 {
+  "type": "delegation",
   "timestamp": "2026-02-25T14:30:00Z",
   "session_id": "feat/prj-57",
   "agent": "Developer",
@@ -64,6 +109,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"delegation"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `session_id` | `string` | Yes | Branch name or feature identifier |
 | `agent` | `string` | Yes | Agent name delegated to |
@@ -76,10 +122,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `phase` | `number` | No | Execution phase number |
 | `file_partition` | `string[]` | No | Directories/files assigned |
 
-## Fast Review Record Schema
+## Fast Review Record (`type: "review"`)
 
 ```json
 {
+  "type": "review",
   "timestamp": "2026-02-28T14:30:00Z",
   "tracker_issue": "PRJ-42",
   "agent": "Developer",
@@ -97,6 +144,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"review"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `tracker_issue` | `string` | No | Issue ID if applicable |
 | `agent` | `string` | Yes | Agent whose output was reviewed |
@@ -110,10 +158,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `escalated` | `boolean` | Yes | Whether this review triggered escalation to panel |
 | `duration_sec` | `number` | No | Review duration in seconds |
 
-## Panel Record Schema
+## Panel Record (`type: "panel"`)
 
 ```json
 {
+  "type": "panel",
   "timestamp": "2026-02-25T14:30:00Z",
   "panel_key": "instruction-refactoring",
   "verdict": "pass",
@@ -132,6 +181,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"panel"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `panel_key` | `string` | Yes | Filesystem-safe panel identifier |
 | `verdict` | `string` | Yes | `pass` or `block` |
@@ -146,10 +196,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `artifacts_count` | `number` | No | Number of artifacts reviewed |
 | `report_path` | `string` | No | Path to the full panel report |
 
-## Dispute Record Schema
+## Dispute Record (`type: "dispute"`)
 
 ```json
 {
+  "type": "dispute",
   "timestamp": "2026-02-28T16:00:00Z",
   "dispute_id": "DSP-001",
   "tracker_issue": "PRJ-42",
@@ -167,6 +218,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"dispute"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime when dispute was created |
 | `dispute_id` | `string` | Yes | Dispute ID (e.g., `DSP-001`) |
 | `tracker_issue` | `string` | No | Issue ID if applicable |

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

@@ -1,145 +1,34 @@
 ---
-description: 'AI assistant optimization techniques for efficient context usage and faster responses'
+description: 'AI assistant optimization patterns for efficient context usage and tool calls'
 applyTo: '**'
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
-# AI Assistant Optimization Instructions
+# AI Optimization
 
-## Batch Processing
+Batch independent operations, gather context before acting, and avoid redundant tool calls.
 
-### DO: Batch Independent Operations
+## Key Rules
 
-When gathering context, batch all read operations together in a single parallel call:
+- **Batch independent reads** — parallelize file reads, searches, and error checks in a single call instead of sequentially
+- **Don't batch dependent ops** — if step B needs step A's output, run them sequentially
+- **Gather context first** — read and search before editing; don't act on assumptions
+- **Read strategically** — prefer large ranges (500–2000 lines) over many micro-reads; use `grep_search` to locate, then read targeted ranges
+- **Combine searches** — use regex alternation (`word1|word2|word3`) instead of separate searches
+- **Don't re-read** — if a file or sub-agent result is already in context, use it directly
+- **Verify once per phase** — run tests/lint/errors after a batch of edits, not after each individual change
+- **Scale planning to complexity** — trivial (1–2 files) → act directly; large (10+ files) → full decomposition
+- **Trust sub-agent results** — don't re-search or re-read what a sub-agent already returned
+- **Include file paths in delegation prompts** — saves the sub-agent from wasting context on discovery
 
-```
-Good: Read 3 files + search in parallel → 1 cache-friendly turn
-Bad: Read file 1 → Read file 2 → Read file 3 → 3 separate turns
-```
+## Anti-Patterns
 
-When modifying multiple independent files, batch the edits:
-
-```
-Good: Update 5 config files in parallel
-Bad: Update config 1 → wait → Update config 2 → wait...
-```
-
-### DON'T: Batch Dependent Operations
-
-Don't batch operations where one depends on the output of another:
-
-```
-Bad: Read file + Edit file (need to read first)
-Good: Read file → Analyze → Edit file
-```
-
-## Context Gathering Workflow
-
-Gather all necessary context upfront before analysis/implementation:
-
-```
-Phase 1 (parallel): Read files + search for patterns + check errors
-Phase 2: Analyze and plan
-Phase 3 (parallel if independent): Create/modify files
-Phase 4: Verify (tests, errors, lint)
-```
-
-## Token Reduction Techniques
-
-### Strategic Tool Selection
-
-- Use `grep_search` with `includePattern` to scope searches to specific directories
-- Use `file_search` to find files by pattern before reading
-- Use `semantic_search` for exploring unfamiliar code instead of multiple grep searches
-- Read targeted line ranges when you know approximately where code is
-
-### Avoid Redundant Operations
-
-- Don't re-read files already in context from the same conversation turn
-- Check errors once per phase, not after every single change
-- Don't search for what's already mentioned in context
-- Use regex with alternation (e.g., `word1|word2|word3`) to combine searches
-
-### Read Strategically
-
-- Read larger sections (500-2000 lines) instead of many small reads
-- Use `grep_search` to locate code, then read targeted ranges around it
-- Deduplicate file paths before batching read operations
-
-## Multi-Agent Optimization
-
-### Sub-Agent Context Isolation
-
-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 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
-
-- Don't re-read files a sub-agent just analyzed — trust the returned summary
-- Don't re-search for patterns a sub-agent already identified
-- If a sub-agent returns file paths or code snippets, use them directly
-
-### Background Agents for Long Work
-
-- Delegate tasks expected to take >5 minutes to background agents — they run in parallel without blocking
-- Include **all necessary context** in the delegation prompt (background agents can't ask follow-up questions)
-- Batch independent background delegations together (e.g., launch DB migration + UI components + docs simultaneously)
-
-### Delegation Prompt Efficiency
-
-- Include exact file paths so the delegated agent doesn't waste time searching
-- Reference existing patterns ("follow the structure in `libs/ui-kit/src/lib/Button/`") instead of describing patterns from scratch
-- Set clear scope boundaries ("only modify files under `libs/queries/`") to prevent unnecessary exploration
-
-## Response Optimization
-
-- Provide brief progress updates after batched operations
-- Describe changes concisely instead of repeating large code blocks
-- Plan what context is needed before making tool calls
-- Combine multiple related edits in planning before executing
-
-## Planning Thresholds
-
-Scale planning effort to task complexity — don't over-plan simple work:
-
-| Complexity | Planning | Approach |
-|-----------|----------|----------|
-| Trivial (1-2 files, clear fix) | None | Act directly |
-| Small (3-5 files, single concern) | Mental plan | Brief reasoning, then act |
-| Medium (5-10 files, multiple concerns) | Todo list | Track steps, batch reads |
-| Large (10+ files, cross-cutting) | Full decomposition | Dependency graph, phased execution |
-
-**Stop-and-re-plan trigger:** See the Task Decomposition Protocol in `general.instructions.md` (step 5).
-
-## Test & Build Output Efficiency
-
-- Capture full test/build output **once** per verification phase, not after each micro-change
-- Pipe verbose output through `tail -n 30` or `grep -E 'FAIL|ERROR|PASS'` to reduce noise
-- When tests fail, read the **relevant failure block** — don't re-run the entire suite repeatedly
-
-## README Cascade Reading
-
-When entering an unfamiliar directory, check for a `README.md` before exploring files. READMEs provide architecture context that prevents wasted searches. Priority order:
-1. Project root `README.md` (already covered by instruction files)
-2. Library/app-level `README.md` (e.g., `libs/queries/README.md`)
-3. Feature-level `README.md` (e.g., `libs/data-pipeline/src/lib/scrapers/README.md`)
-
-## Anti-Patterns to Avoid
-
-1. **Micro-reads** — Reading tiny file sections repeatedly
-2. **Sequential searches** — Running searches one at a time when they're independent
-3. **Premature actions** — Acting before gathering sufficient context
-4. **Silent processing** — Batching without progress updates
-5. **Exploratory tool calls** — Making tool calls without a clear plan
-6. **Over-checking** — Validating after every tiny change instead of batching
-7. **Re-gathering delegated context** — Re-reading files or re-searching after a sub-agent already returned the information
-8. **Vague delegation prompts** — Forcing sub-agents to waste their context budget on discovery you already completed
-9. **Sequential delegation** — Running independent sub-agents one-by-one when they could run in parallel
-10. **Leaking secrets** — Printing tokens, keys, or passwords in terminal output or logs (violates Constitution #1)
-11. **Over-planning** — Writing a full decomposition for a 2-file fix (see Planning Thresholds)
+1. **Micro-reads** — reading tiny file sections repeatedly
+2. **Sequential searches** — running independent searches one at a time
+3. **Premature actions** — editing before gathering sufficient context
+4. **Over-checking** — validating after every tiny change instead of batching
+5. **Re-gathering delegated context** — re-reading files a sub-agent already analyzed
+6. **Over-planning** — full decomposition for a 2-file fix
 
 <!-- End of AI Optimization Instructions -->

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

@@ -13,7 +13,7 @@ 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.
+6. **Log every session** — append observability records to `.github/customizations/logs/` before yielding to the user. No exceptions. Load the **observability-logging** skill for details.
 
 ## Instruction Priority Hierarchy
 
@@ -66,40 +66,6 @@ Before starting multi-step work, decompose it into individually verifiable tasks
 - **Browser testing mandatory** for any UI change — verified at responsive breakpoints defined in `testing-config.md`
 - Load the **testing-workflow** skill for test patterns and the **browser-testing** skill for E2E automation
 
-## Git Workflow
-
-**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 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 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`.
-
-**This rule has NO exceptions.** Not for "small fixes", not for "just config changes", not for urgent hotfixes. Every change goes through a PR.
-
-### PR Safety Rules
-
-- **Never** use `git push --force` or `git commit --amend` on shared branches
-- **Never** expose secrets in commits, PR descriptions, or terminal output (per Constitution #1)
-- Use `git push --force-with-lease` only when explicitly asked and on personal branches
-- If a secret is accidentally committed, immediately rotate it — git history is permanent
-
-### Delivery Outcome (Required for Every Task)
-
-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 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. **Task tracker linkage** — The issue is updated with the PR URL, and the PR description references the issue ID
-
 ## Build & Task 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.
@@ -120,182 +86,70 @@ Follow markdown formatting and documentation standards when writing docs. For te
 
 ## AI Optimization
 
-Follow prompt caching and batch processing best practices. See [AI Optimization Guide](ai-optimization.instructions.md) for details.
-
-## Discovered Issues Policy
+See [ai-optimization.instructions.md](ai-optimization.instructions.md) for batch processing, tool efficiency, and anti-patterns.
 
-> **⛔ 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 `.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 `.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.
+## Project Context
 
-Never assume a pre-existing issue is somebody else's problem. If it's not tracked, track it.
+For project-specific context (apps, libraries, tech stack, ports, URLs), see [project.instructions.md](../customizations/project.instructions.md).
 
-## Task Tracking
+## Git Workflow
 
-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.
+**NEVER commit or push directly to the `main` branch.** All changes go through a feature/fix branch and a pull request. Load the **git-workflow** skill for branch naming, PR rules, and the Delivery Outcome checklist.
 
-### When Task Tracker MCP Tools Are Unavailable
+## Discovered Issues Policy
 
-If task tracker MCP tools are not available in the current session, do NOT block on issue creation. Instead:
+> **⛔ No issue gets ignored.** Untracked bugs discovered during work are a quality gate failure.
 
-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
-3. **Placeholder value for `tracker_issue`:**
-   - **No tracker configured** (no `task-management` slot bound in `skill-matrix.json`) → use `"N/A"`
-   - **Tracker configured but tools unavailable** → use the project prefix + `PENDING` (e.g., `"TAS-PENDING"`)
-4. **Ask the user** to create the issues manually if tracking is critical for the task
-5. After implementation, update commit messages and PR descriptions when issue IDs become available
+When you encounter a bug unrelated to the current task: check if already tracked in `KNOWN-ISSUES.md` or the task tracker. If NOT tracked, track it (known issue entry or bug ticket). Never assume a pre-existing issue is somebody else's problem. See the **git-workflow** skill for the full procedure.
 
-## Observability Logging (Mandatory)
+## Observability Logging
 
 > **⛔ 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 | 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 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, **immediately after each delegation — not at session end**):
-```bash
-echo '{"timestamp":"2026-03-01T14:00:00Z","session_id":"feat/prj-57","agent":"Developer","model":"gemini-3.1-pro","tier":"standard","mechanism":"sub-agent","tracker_issue":"PRJ-57","outcome":"success","retries":0,"phase":2,"file_partition":["src/components/"]}' >> .github/customizations/logs/delegations.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/delegations.ndjson`
-
-> **`model` and `tier` must reflect the delegated agent's assignment from the agent registry** — not the Team Lead's own model.
-
-**Fast review record** (Team Lead, **immediately after each fast review**):
-```bash
-echo '{"timestamp":"2026-03-01T14:30:00Z","tracker_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
-```
-Verify: `tail -1 .github/customizations/logs/reviews.ndjson`
-
-**Panel record** (Panel runner, **immediately 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,"tracker_issue":"PRJ-42","artifacts_count":5}' >> .github/customizations/logs/panels.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/panels.ndjson`
-
-**Dispute record** (Team Lead, **immediately after each dispute**):
-```bash
-echo '{"timestamp":"2026-03-01T16:00:00Z","dispute_id":"DSP-001","tracker_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
-```
-Verify: `tail -1 .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). Count delegations → count records → must match
-- [ ] **Reviews logged** — `reviews.ndjson` has a line for **each** fast review performed. Count reviews → count records → must match
-- [ ] **Panels logged** — `panels.ndjson` has a line for **each** panel review performed. Count panels → count records → must match
-- [ ] **Disputes logged** — `disputes.ndjson` has a line for **each** dispute created. Count disputes → count records → must match
-
-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. 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.
+**Every agent MUST log every session** to `.github/customizations/logs/events.ndjson`. No exceptions. No threshold. No "too small to log." Load the **observability-logging** skill for CLI commands, record schemas, and the full logging checklist.
 
 ## 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. This is NOT optional.
-2. **During execution:** If any of these triggers occur, **immediately** add a lesson entry to `.github/customizations/LESSONS-LEARNED.md`:
-   - Retry with different approach that works
-   - Tool call fails unexpectedly (discover correct parameter format)
-   - Workaround needed for platform limitation
-   - Docs are misleading (reality differs from documentation)
-   - Configuration surprise (default behavior differs from expectation)
-   - Error message is unhelpful (real cause was something else)
-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:
-   - The user had to intervene or correct the agent's approach
-   - Multiple back-and-forth attempts were needed to get something right
-   - A change touched files you wouldn't have guessed from the task description
-   - Something worked differently than expected (API quirk, tool behavior, config side-effect)
-   - A recurring pattern should be codified (workaround, convention, tool quirk)
-
-   **When NOT to update:** Don't add obvious patterns, standard practices, or things easily discoverable by reading a few files. Instruction files capture *tribal knowledge* — what isn't obvious from the code.
-
-For the full protocol, load the **self-improvement** skill.
-
-## Project Context
-
-For project-specific context (apps, libraries, tech stack, ports, URLs), see [project.instructions.md](../customizations/project.instructions.md).
+2. **During execution:** If you retry with a different approach and it works, use the **self-improvement** skill to add a lesson immediately.
+3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too.
 
 ## Universal Agent Rules
 
 These rules apply to ALL specialist agents automatically. **Do not duplicate them in individual agent files.**
 
-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. This is Constitution rule #6 — a blocking gate, not optional.
-
-## Base Output Contract
+1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents.
+2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see above).
+3. **Read and update lessons** — See Self-Improvement Protocol above.
+4. **Log every session** — See Observability Logging above. This is Constitution rule #6 — a blocking gate, not optional.
 
-Every specialist agent's Output Contract MUST end with these standard items (in addition to domain-specific items above them):
+## Pre-Response Quality Gate
 
-- **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
+> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
 
-Agents reference this contract with: `See **Base Output Contract** in general.instructions.md for the standard closing items.`
+- [ ] **Lessons read** — `LESSONS-LEARNED.md` was read at session start
+- [ ] **Lessons captured** — If any retry occurred, a new lesson was added via the **self-improvement** skill
+- [ ] **Discovered issues tracked** — Any pre-existing bugs found were tracked (Discovered Issues Policy)
+- [ ] **Lint/type/test pass** — No new errors introduced; verification ran after code changes (Constitution rule #5)
+- [ ] **Session logged** — `events.ndjson` has a new `session` record (Constitution rule #6 — ALWAYS required)
+- [ ] **Delegations logged** — `events.ndjson` has a `delegation` record for each delegation (Team Lead only)
+- [ ] **Reviews logged** — `events.ndjson` has a `review` record for each fast review (if any)
+- [ ] **Panels logged** — `events.ndjson` has a `panel` record for each panel review (if any)
 
-## Pre-Response Quality Gate
+Load the **observability-logging** skill for CLI commands, Base Output Contract, and detailed schemas.
 
-> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
+## Workflow & Governance Skills
 
-This is the single exit gate for every session. All items are mandatory unless marked conditional.
+These skills provide detailed procedures. Load when their phase is reached.
 
-- [ ] **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)
+| Concern | Skill |
+|---------|-------|
+| Branch naming, PR rules, delivery outcome, task tracking | **git-workflow** |
+| Log CLI commands, record schemas, output contracts | **observability-logging** |
+| Lesson writing CLI, categories, quality standards | **self-improvement** |
 
 <!-- End of Coding Standards -->

package/src/orchestrator/plugins/nx/SKILL.md

@@ -154,7 +154,7 @@ Before running any generator, complete these steps:
    - Read the error message carefully
    - Common causes: missing required options, invalid values, conflicting files, missing dependencies
    - Adjust options and retry
-   - Add a lesson to `.github/customizations/LESSONS-LEARNED.md` if the fix was non-obvious
+   - Use the **self-improvement** skill to add a lesson if the fix was non-obvious
 
 ### Phase 4: Post-Generation