opencastle 0.32.5 → 0.32.6

package/src/orchestrator/skills/accessibility-standards/SKILL.md

@@ -3,164 +3,109 @@ name: accessibility-standards
 description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, and inclusive language."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Accessibility Standards
 
-Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/). Go beyond minimal conformance wherever possible.
-
-## Workflow
+Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
 
-1. Before generating code, plan how to implement it accessibly.
-2. After generating code, review against WCAG 2.2 and these patterns. Iterate until compliant.
-3. Inform the user the code was built with accessibility in mind but may still have issues. Suggest [Accessibility Insights](https://accessibilityinsights.io/) for testing.
+**Workflow:** Plan accessible implementation → generate → review against WCAG 2.2 → iterate. Suggest [Accessibility Insights](https://accessibilityinsights.io/) for testing.
 
-## Inclusive Language
-
-- Use people-first language ("person using a screen reader," not "blind user").
-- Avoid stereotypes or assumptions about ability.
-- Flag uncertain implementations — include reasoning or references to standards.
+**Language:** People-first ("person using a screen reader," not "blind user"). No ability stereotypes. Flag uncertain implementations with reasoning.
 
 ## Cognitive
 
-- Prefer plain language.
-- Use consistent page structure (landmarks) across the application.
-- Keep navigation items in the same order across pages.
-- Keep the interface clean — reduce unnecessary distractions.
+Plain language; consistent landmarks and nav order across pages; minimal distractions.
 
 ## Keyboard
 
-- All interactive elements must be keyboard navigable with predictable focus order (reading order).
-- Focus must be clearly visible at all times.
-- All interactive elements must be operable (buttons, links, dropdowns, etc.).
-- Static (non-interactive) elements should NOT have `tabindex`. Exception: elements receiving programmatic focus (e.g., headings) get `tabindex="-1"`.
-- Hidden elements must not be keyboard focusable.
+- All interactive elements keyboard-navigable with visible focus in reading order.
+- No `tabindex` on static elements; `tabindex="-1"` only for elements receiving programmatic focus.
+- Hidden elements must not be focusable.
 
-### Composite Components (grids, listboxes, menus, tabs, toolbars)
+**Composite components** (grids, listboxes, menus, tabs, toolbars): tab stop on container; arrow keys navigate children via roving tabindex or `aria-activedescendant`; on focus restore last/first child.
 
-- Tab stop on the container with appropriate interactive role.
-- Arrow keys navigate children (roving tabindex or `aria-activedescendant`).
-- On focus: show selected child, or previously focused child, or first interactive child.
+**Roving tabindex:** First child `tabindex="0"`, rest `-1`; on arrow key set prev to `-1`, new to `0`, call `.focus()`.
 
-### Bypass Blocks
+**`aria-activedescendant`:** Container `tabindex="0"` + `aria-activedescendant="IDREF"`; CSS draws outline on referenced element; arrow keys update attribute.
 
-Provide "Skip to main" link as first focusable element:
+**Skip link** (first focusable element):
 
 ```html
-<header>
-  <a href="#maincontent" class="sr-only">Skip to main</a>
-</header>
+<a href="#maincontent" class="sr-only">Skip to main</a>
 <main id="maincontent"></main>
 ```
 
 ```css
-.sr-only:not(:focus):not(:active) {
-  clip: rect(0 0 0 0);
-  clip-path: inset(50%);
-  height: 1px;
-  overflow: hidden;
-  position: absolute;
-  white-space: nowrap;
-  width: 1px;
-}
+.sr-only:not(:focus):not(:active) { clip: rect(0 0 0 0); clip-path: inset(50%); height: 1px; overflow: hidden; position: absolute; white-space: nowrap; width: 1px; }
 ```
 
-### Common Keys
-
 | Key | Action |
 |-----|--------|
 | `Tab` | Next interactive element |
 | `Arrow` | Navigate within composite component |
 | `Enter` | Activate focused control |
-| `Escape` | Close open surfaces (dialogs, menus) |
-
-### Roving Tabindex Pattern
-
-1. Initial: `tabindex="0"` on first focusable child, `tabindex="-1"` on rest.
-2. On arrow key: set previous to `-1`, new target to `0`, call `element.focus()`.
-
-### `aria-activedescendant` Pattern
-
-- Container has `tabindex="0"` and `aria-activedescendant="IDREF"`.
-- CSS draws focus outline on referenced element.
-- Arrow keys update `aria-activedescendant`.
+| `Escape` | Close dialogs/menus |
 
 ## Low Vision
 
-- Dark text on light backgrounds (or vice versa).
-- Text contrast ≥4.5:1 (≥3:1 for large text: 18.5px bold or 24px).
-- Graphics/controls contrast ≥3:1 with adjacent colors.
-- Control state indicators (pressed, focus, checked) ≥3:1 contrast.
-- Color must NOT be the only way to convey information — use text/shapes in addition.
+| Rule | Requirement |
+|------|-------------|
+| Text contrast | ≥4.5:1 (≥3:1 for large text: 18.5px bold / 24px) |
+| Graphics/controls | ≥3:1 with adjacent colors |
+| State indicators (pressed, focus, checked) | ≥3:1 |
+| Color | Never the sole conveyor of information |
 
 ## Screen Reader
 
-- All elements must convey correct semantics (name, role, value, states/properties). Prefer native HTML; use ARIA when necessary.
-- Use landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`.
-- Use headings (`<h1>`–`<h6>`) to introduce sections. One `<h1>` per page. Avoid skipping levels.
+- Correct semantics (name, role, value, states). Prefer native HTML; ARIA only when necessary.
+- Landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`.
+- One `<h1>` per page; `<h1>`–`<h6>` introduce sections; no skipping levels.
 
 ## Voice Access
 
-- Accessible name of interactive elements must contain the visual label (so voice users can say "Click [label]").
-- `aria-label` must contain the visual label text.
+- Interactive element accessible name must contain its visible label text.
+- `aria-label` must include the visible label.
 
 ## Forms
 
-- Labels must accurately describe control purpose.
+- Labels accurately describe control purpose.
 - Required fields: asterisk in label + `aria-required="true"`.
-- Errors: `aria-invalid="true"` on invalid fields. Error messages via `aria-describedby`.
-- Inline errors next to fields (common) or form-level errors at top identifying specific fields.
-- Submit buttons should NOT be disabled — trigger error messages instead.
-- On submit with invalid input, focus the first invalid field.
+- Errors: `aria-invalid="true"` + `aria-describedby` pointing to error message.
+- Don't disable submit — show errors instead; focus first invalid field on submit.
 
-## Graphics and Images
+## Images
 
-- All graphics must have correct role (`<img>` implicit, `<svg>` needs `role="img"`, icon fonts/emojis need `role="img"` on `<span>`).
-- **Informative**: `alt` text conveying meaning/purpose (concise, meaningful). Avoid `title` attribute.
-- **Decorative**: `alt=""` for `<img>`, `aria-hidden="true"` for `role="img"`.
+| Type | Pattern |
+|------|---------|
+| Informative | `alt="[meaning]"` on `<img>`; `role="img"` + `aria-label` on `<svg>` / icon fonts |
+| Decorative | `alt=""` on `<img>`; `aria-hidden="true"` on `role="img"` |
 
 ## Input Labels
 
-- All interactive elements need visual labels.
-- `<label for="id">` for form inputs.
-- Multiple controls with same label (e.g., "Remove"): use `aria-label` for disambiguation.
-- Help text: associate via `aria-describedby`.
+- `<label for="id">` for form inputs; all interactive elements need visible labels.
+- Disambiguate repeated labels (e.g., "Remove") with `aria-label`.
+- Help text via `aria-describedby`.
 
 ## Navigation
 
 ```html
-<nav>
-  <ul>
-    <li>
-      <button aria-expanded="false" tabindex="0">Section 1</button>
-      <ul hidden>
-        <li><a href="..." tabindex="-1">Link 1</a></li>
-      </ul>
-    </li>
-    <li>
-      <button aria-expanded="false" tabindex="-1">Section 2</button>
-      <ul hidden>
-        <li><a href="..." tabindex="-1">Link 1</a></li>
-      </ul>
-    </li>
-  </ul>
-</nav>
+<nav><ul>
+  <li><button aria-expanded="false" tabindex="0">Section 1</button>
+    <ul hidden><li><a href="..." tabindex="-1">Link 1</a></li></ul>
+  </li>
+</ul></nav>
 ```
 
-- Navigation menus use `<nav>` with `<ul>`, NOT `menu`/`menubar` roles.
-- Toggle `aria-expanded` on expand/collapse.
-- Roving tabindex for main items (arrow across), arrow down into sub-menus.
-- `Escape` closes expanded menus.
+- Use `<nav>` + `<ul>`, NOT `menu`/`menubar` roles.
+- Toggle `aria-expanded` on expand/collapse; `Escape` closes menus.
+- Roving tabindex across main items; arrow down into sub-menus.
 
 ## Page Title
 
-- Defined in `<title>` in `<head>`.
-- Describes page purpose, unique per page.
-- Front-load unique information: `"[Page] - [Section] - [Site]"`.
+- `<title>` describes page purpose, unique per page.
+- Front-load unique info: `"[Page] - [Section] - [Site]"`.
 
-## Tables and Grids
+## Tables & Grids
 
-- Column headers via `<th>` in first `<tr>`. Row headers via `<th>` in each row.
-- `role="gridcell"` must be nested within `role="row"`.
-- Prefer simple tables (one set of headers, no spanning cells).
-- Use `<table>` for static data, `role="grid"` for interactive data (date pickers, calendars).
+- Column headers: `<th>` in first `<tr>`; row headers: `<th>` in each row.
+- `role="gridcell"` nested within `role="row"`.
+- `<table>` for static data; `role="grid"` for interactive (date pickers, calendars).

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -3,150 +3,100 @@ name: agent-hooks
 description: "Lifecycle hooks for AI agent sessions — reusable actions that run at specific points (session start, session end, pre-delegation, post-delegation). Defines what to do at each lifecycle event so agents behave consistently."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Agent Lifecycle Hooks
 
-Hooks are **standardized actions** that agents execute at specific points during their lifecycle. They enforce consistency across sessions and prevent common oversights (missing lessons, forgotten checkpoints, untracked issues).
-
-## Hook Execution Model
-
-Hooks are **conventions, not automated triggers**. Agents must explicitly follow them. The Team Lead includes hook reminders in delegation prompts; specialist agents include them in their own workflow.
+Conventions (not auto-triggers) agents execute at specific lifecycle points. Team Lead includes hook reminders in delegation prompts; specialists follow them in their own workflow.
 
 ```
-Session Lifecycle:
-  on-session-start  →  [work loop]  →  on-session-end
-                          ↓   ↑
-                    on-pre-delegate → on-post-delegate
+on-session-start → [work loop] → on-session-end
+                        ↓   ↑
+               on-pre-delegate → on-post-delegate
 ```
 
 ---
 
-## Hook: on-session-start
-
-**When:** First action in any agent session (Team Lead or specialist).
-
-### Actions
-
-1. **Read lessons learned** — Scan `.opencastle/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
-2. **Check for checkpoint** — If `.opencastle/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
-3. **Check pending approvals** — If the checkpoint has a `## Pending Approvals` section, check for replies using the configured messaging provider's MCP tools (e.g., `conversations_replies` for Slack). Read `.opencastle.json` → `stack.teamTools` to determine the provider. If no messaging is configured, skip this step.
-4. **Check dead letter queue** — Scan `.opencastle/AGENT-FAILURES.md` for pending failures related to the current scope.
-5. **Validate skill-matrix bindings** — Open `.opencastle/agents/skill-matrix.json` and check whether the `bindings` object has any slots with non-empty `entries` arrays. If all entries are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
-6. **Check project context** — If `.opencastle/project.instructions.md` has only empty template rows (`| | | |`), warn the user that bootstrap hasn't populated project context.
-7. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
-
-### Template for Delegation Prompts
+## on-session-start — First action in any session
 
-Include this reminder in every delegation:
+| # | Action | Detail |
+|---|--------|--------|
+| 1 | Read lessons | Scan `.opencastle/LESSONS-LEARNED.md` for task-relevant entries. |
+| 2 | Check checkpoint | If `.opencastle/SESSION-CHECKPOINT.md` exists, resume from it. |
+| 3 | Check pending approvals | If checkpoint has `## Pending Approvals`, check replies via messaging provider (`stack.teamTools` in `.opencastle.json`). Skip if no messaging configured. |
+| 4 | Check DLQ | Scan `.opencastle/AGENT-FAILURES.md` for failures in current scope. |
+| 5 | Validate skill-matrix | Open `.opencastle/agents/skill-matrix.json` — if all `bindings` entries are empty, **warn** user to run *"Bootstrap Customizations"* prompt first. |
+| 6 | Check project context | If `.opencastle/project.instructions.md` has only empty template rows, warn bootstrap hasn't run. |
+| 7 | Load domain skills | Load appropriate skills before writing code. |
 
+**Delegation reminder:**
 ```
-**Session Start:** Read `.opencastle/LESSONS-LEARNED.md` before starting.
-Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals.
-If pending approvals exist, check for replies via the messaging provider.
-Validate `.opencastle/agents/skill-matrix.json` — warn if skill bindings are empty (bootstrap not run).
-Load relevant skills before writing code.
+Session Start: Read `.opencastle/LESSONS-LEARNED.md`. Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals. Validate `.opencastle/agents/skill-matrix.json` — warn if bindings empty. Load relevant skills before coding.
 ```
 
 ---
 
-## Hook: on-session-end
+## on-session-end — Before yielding control, every time unconditionally
 
-**When:** Before the agent yields control back to the user — every time, unconditionally.
+> **⛔ HARD GATE** — See [logging-mandatory](../../snippets/logging-mandatory.md). Run the Pre-Response Quality Gate from the **observability-logging** skill.
 
-> **⛔ HARD GATE — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill before responding.**
-> A session without log records is a failed session. A session without lessons captured after retries is a failed session.
-
-### Actions
-
-1. **Call Session Guard** (Team Lead only) — Delegate to the **Session Guard** agent with a session summary (delegations, retries, discoveries, files changed). Execute any fix commands it returns. This replaces the manual Pre-Response Quality Gate checklist — the guard runs it automatically with a fresh context window.
-2. **For specialist agents** (not Team Lead) — Run the Pre-Response Quality Gate checklist from the **observability-logging** skill manually. Specialist agents don't have access to the Session Guard.
-3. **Save checkpoint** (Team Lead only) — If work is incomplete, write `.opencastle/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
-4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
-5. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
-
-### Template for Delegation Prompts
+| # | Action | Who |
+|---|--------|-----|
+| 1 | Call Session Guard with session summary; execute fix commands it returns | Team Lead only |
+| 2 | Run Pre-Response Quality Gate checklist from **observability-logging** skill | Specialists only |
+| 3 | Write `.opencastle/SESSION-CHECKPOINT.md` if work is incomplete (load **session-checkpoints** skill) | Team Lead only |
+| 4 | Flag for memory merge if 5+ new lessons this session | All |
+| 5 | Remove temp files created during session | All |
 
+**Delegation reminder (specialists):**
 ```
-**Session End:** Run the Pre-Response Quality Gate from the **observability-logging** skill:
-- Log your session using the observability-logging skill's session record command (Constitution rule #6)
-- If you retried anything with a different approach that worked, use the **self-improvement** skill to add a lesson
-- Track any discovered issues in KNOWN-ISSUES.md or a tracker ticket
-- Clean up temp files
+Session End: Log session via observability-logging skill (Constitution rule #6). Add lesson via self-improvement if retried. Track discovered issues in KNOWN-ISSUES.md or tracker. Clean up temp files.
 ```
 
-> **Note for Team Lead:** You do NOT use this template yourself. Instead, call the **Session Guard** agent (step 10 in your role). This template is only for specialist agents you delegate to.
-
----
-
-## Hook: on-pre-delegate
-
-**When:** Team Lead only — before every delegation (sub-agent or background agent).
-
-Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker issue exists, (2) File partition clean, (3) Dependencies verified Done, (4) Prompt has file paths + acceptance criteria, (5) Self-improvement reminder included. For complex tasks (5+ files), also generate a context map.
-
 ---
 
-## Hook: on-post-delegate
-
-**When:** Team Lead only — after receiving results from a delegated agent.
+## on-pre-delegate — Team Lead only, before every delegation
 
-### Actions
+Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker issue exists, (2) File partition clean, (3) Dependencies verified Done, (4) Prompt has file paths + acceptance criteria, (5) Self-improvement reminder included. For 5+ files, generate a context map.
 
-0. **Log the delegation (⛔ hard gate)** — Use the **observability-logging** skill's delegation record command. Do NOT proceed to review or any other action until the delegation is logged and verified.
-1. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). **Log the review (⛔ hard gate)** using the **observability-logging** skill's review record command immediately after — do NOT proceed until logged. Only after both the fast review passes and the review is logged do you proceed to the remaining post-delegate actions below.
-2. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
-2. **Run verification** — Execute appropriate checks: lint, type-check, tests, or visual inspection.
-3. **Check acceptance criteria** — Compare output against the tracker issue's acceptance criteria. Each criterion must be independently verified.
-4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new tracker ticket.
-5. **Lessons captured** — If the agent retried anything, verify a lesson was added via the **self-improvement** skill.
-6. **Update tracker** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing). On 3rd failure → log to `.opencastle/AGENT-FAILURES.md` (DLQ format in file header).
-7. **Update agent expertise** — In `.opencastle/AGENT-EXPERTISE.md`: first-attempt success → add strong area; 2+ retries → add weak area. Update file familiarity with touched files.
-8. **Append knowledge graph** — Add file-to-file relationships the agent touched to `.opencastle/KNOWLEDGE-GRAPH.md` (one row per dependency discovered).
+## on-post-delegate — Team Lead only, after receiving delegation results
 
-### Quick Checklist
+| # | Action |
+|---|--------|
+| 0 | **⛔ Log delegation** via observability-logging skill — BLOCKING |
+| 1 | **Fast review (mandatory)** — run `fast-review` skill; **⛔ log review** — BLOCKING. Escalate to panel if needed; **⛔ log panel** — BLOCKING |
+| 2 | Read changed files; verify within file partition |
+| 3 | Run lint, type-check, tests |
+| 4 | Verify each acceptance criterion against tracker issue |
+| 5 | Confirm Discovered Issues Policy followed (KNOWN-ISSUES.md or tracker ticket) |
+| 6 | If agent retried, verify lesson added via **self-improvement** skill |
+| 7 | Move issue to Done or re-delegate; on 3rd failure → log to `.opencastle/AGENT-FAILURES.md` |
+| 8 | Update `.opencastle/AGENT-EXPERTISE.md` (strong/weak area + file familiarity) |
+| 9 | Append file relationships to `.opencastle/KNOWLEDGE-GRAPH.md` |
 
+**Quick checklist:**
 ```
-Post-Delegate:
-☐ ⛔ Delegation logged (observability-logging skill — verify with tail -1) — BLOCKING
-☐ Changed files reviewed
-☐ Files within partition
+☐ ⛔ Delegation logged (verify: tail -1 events.ndjson) — BLOCKING
+☐ Changed files reviewed; within partition
 ☐ Lint/test/build passes
-☐ Fast review PASS (mandatory — load fast-review skill)
-☐ ⛔ Review logged (observability-logging skill — verify with tail -1) — BLOCKING
-☐ ⛔ Panel logged if escalated (observability-logging skill — verify with tail -1) — BLOCKING
+☐ Fast review PASS; ⛔ Review logged — BLOCKING
+☐ ⛔ Panel logged if escalated — BLOCKING
 ☐ Acceptance criteria met
-☐ Discovered issues tracked (not ignored)
-☐ Lessons captured (if retries occurred)
+☐ Discovered issues tracked
+☐ Lessons captured (if retries)
 ☐ Issue updated
-☐ Agent expertise updated (AGENT-EXPERTISE.md — strong/weak area + file familiarity)
-☐ Knowledge graph appended (KNOWLEDGE-GRAPH.md — file relationships)
+☐ AGENT-EXPERTISE.md updated
+☐ KNOWLEDGE-GRAPH.md appended
 ```
 
 ---
 
-## Hook Integration
-
-### For Team Lead
-
-The on-pre-delegate and on-post-delegate hooks are already encoded in the Team Lead's orchestration workflow. Reference this skill to ensure consistency.
-
-### For Specialist Agents
-
-Include on-session-start and on-session-end actions in every delegation prompt. Use the templates above.
-
-### For Workflow Templates
-
-Each workflow's **Delivery phase** naturally serves as the on-session-end hook for that workflow type. The Delivery phase steps should include session logging, lesson verification, and memory merge checks.
-
----
-
 ## Anti-Patterns
 
-- **Skipping on-session-start** — Leads to repeated mistakes already documented in lessons learned
-- **Forgetting session logging** — Makes the observability dashboard empty and performance tracking impossible. This is the #1 most common failure.
-- **Treating logging as optional** — Every session gets logged. No threshold, no exceptions.
-- **Batch-logging retrospectively** — Log each task as it completes, not all at once at the end of a long conversation.
-- **Partial post-delegate checks** — "It compiled, ship it" without checking acceptance criteria
-- **No cleanup** — Temp files accumulate and confuse future sessions
-- **Hooks as blockers** — Hooks should add ~2 minutes overhead, not 20. If a hook takes too long, skip the optional parts
+| Anti-pattern | Why it matters |
+|---|---|
+| Skipping on-session-start | Repeated mistakes already in lessons learned |
+| Forgetting session logging | Observability dashboard empty; #1 most common failure |
+| Treating logging as optional | Every session logged — no threshold, no exceptions |
+| Batch-logging retrospectively | Log each task as it completes, not all at end |
+| Partial post-delegate checks | Must verify acceptance criteria, not just "it compiled" |
+| No cleanup | Temp files accumulate and confuse future sessions |
+| Hooks as blockers | Hooks add ~2 min overhead — skip optional parts if needed |

package/src/orchestrator/skills/agent-memory/SKILL.md

@@ -3,19 +3,11 @@ name: agent-memory
 description: "Agent expertise tracking and cross-session knowledge graph. Use when delegating tasks to track agent strengths/weaknesses, or when building context about file relationships and patterns."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Agent Memory Protocol
 
-## Purpose
-
-Track which agents have expertise with which files, patterns, and tools across sessions. This information helps the Team Lead make better delegation decisions by matching tasks to agents with proven track records.
-
 ## Expertise File
 
-Location: `.opencastle/AGENT-EXPERTISE.md` — a structured record of agent performance per domain.
-
-Template structure:
+**Location:** `.opencastle/AGENT-EXPERTISE.md`
 
 ```markdown
 # Agent Expertise Registry
@@ -24,123 +16,82 @@ Template structure:
 ### Strong Areas
 | Area | Evidence | Last Updated |
 |------|----------|-------------|
-| Feature implementation | Successfully built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
-| Server-side logic | Fixed auth flow (TAS-ZZ) | YYYY-MM-DD |
+| Feature implementation | Built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
 
 ### Weak Areas
 | Area | Evidence | Last Updated |
 |------|----------|-------------|
-| Styling approach | Required 2 retries on styling task (TAS-AA) | YYYY-MM-DD |
+| Styling | 2 retries on TAS-AA | YYYY-MM-DD |
 
 ### File Familiarity
-- `apps/web-app/places/` — 3 tasks completed
-- `libs/queries/src/lib/` — 2 tasks completed
+- `apps/web-app/places/` — 3 tasks
 ```
 
-## Memory Update Triggers
+## Update Triggers
 
 | Trigger | Action |
 |---------|--------|
-| Agent completes task successfully on first attempt | Add/update Strong Area entry |
-| Agent requires 2+ retries | Add/update Weak Area entry |
-| Agent modifies a file | Update File Familiarity count |
-| Agent fails a task entirely (DLQ) | Add Weak Area with failure reference |
-| >3 months since last update in an area | Mark as "stale" — needs re-evaluation |
-
-## Memory Retrieval Protocol
-
-1. Before delegating, check `.opencastle/AGENT-EXPERTISE.md` for the candidate agent
-2. If the task matches a Strong Area, include in the prompt: *"You have prior experience with [area] from [TAS-XX]. Apply the same patterns."*
-3. If the task matches a Weak Area, either: (a) add extra context to the prompt to compensate, or (b) consider a different agent
-4. If the file has high familiarity, mention it: *"You've worked on [file] before in [TAS-XX]."*
-
-## Memory Pruning Rules
-
-- Remove entries older than 6 months without recent updates
-- Consolidate similar entries (e.g., 5 "App Router pages" entries → 1 entry with count)
-- Remove File Familiarity entries for files that no longer exist
-- The Team Lead should prune at the start of major feature work (not every session)
+| First-attempt success | Add/update Strong Area |
+| 2+ retries | Add/update Weak Area |
+| File modified | Increment File Familiarity |
+| DLQ failure | Add Weak Area with ref |
+| >3 months stale | Mark as "stale" |
 
-## Integration with Delegation
+## Retrieval & Delegation
 
-Add relevant expertise context to delegation prompts. Example addition:
+Check `.opencastle/AGENT-EXPERTISE.md` before delegating. Add to prompt:
 
 ```
-### Agent Context (from expertise registry)
-- Strong: Server Components, CMS queries (3 successful tasks)
-- Weak: Component styling (1 retry on TAS-AA)
-- Familiar files: libs/queries/src/lib/search/ (2 tasks)
+### Agent Context
+- Strong: Server Components, CMS queries (3 tasks)  → "Prior experience from TAS-XX."
+- Weak: Component styling (retry TAS-AA)            → add context or reassign
+- Familiar: libs/queries/src/lib/search/ (2 tasks)  → "You've worked on [file] in TAS-XX."
 ```
 
-## Cross-Session Knowledge Graph
+## Pruning
 
-### Purpose
+- Remove entries >6 months old; consolidate repetitive entries; remove familiarity for deleted files
+- Prune at start of major feature work
 
-Capture structured relationships between concepts, files, agents, and decisions. Goes beyond flat lesson lists to show how pieces of the system connect.
+## Knowledge Graph
 
-### Entity Types
+**Location:** `.opencastle/KNOWLEDGE-GRAPH.md` (append-only)
 
-| Entity Type | Examples | Notation |
-|-------------|----------|----------|
-| `File` | `libs/queries/src/lib/search/searchModule.ts` | `F:path` |
-| `Agent` | Developer, Security Expert | `A:name` |
-| `Pattern` | Server Component data fetching, RLS policy structure | `P:name` |
-| `Decision` | "Use Jotai over Redux" (from DECISIONS.md) | `D:name` |
-| `Bug` | Known issue KI-XXX | `B:id` |
-| `Lesson` | LES-XXX from LESSONS-LEARNED.md | `L:id` |
+### Entities & Relationships
 
-### Relationship Types
+| Entity | Notation | Relationships |
+|--------|----------|--------------|
+| File | `F:path` | `depends-on`, `blocks` |
+| Agent | `A:name` | `expert-in` |
+| Pattern/Decision | `P:name` / `D:name` | `related-to`, `obsoletes` |
+| Bug/Lesson | `B:id` / `L:id` | `caused-by`, `related-to` |
 
-| Relationship | Meaning | Example |
-|-------------|---------|---------|
-| `depends-on` | X requires Y to function | `F:places/page.tsx depends-on F:searchModule.ts` |
-| `caused-by` | X was caused by Y | `B:KI-042 caused-by D:use-server-components` |
-| `expert-in` | Agent X has expertise in Y | `A:Content Engineer expert-in P:CMS-queries` |
-| `related-to` | Loose conceptual connection | `L:LES-15 related-to P:RLS-policies` |
-| `obsoletes` | X replaces/supersedes Y | `D:use-app-router obsoletes D:use-pages-router` |
-| `blocks` | X prevents Y from working | `B:KI-099 blocks F:auth/middleware.ts` |
-
-### Knowledge Graph File
-
-Location: `.opencastle/KNOWLEDGE-GRAPH.md` — an append-only relationship log.
-
-Template structure:
+### Graph Template
 
 ```markdown
 # Knowledge Graph
-
 ## Relationships
-
 | Source | Relationship | Target | Added | Context |
 |--------|-------------|--------|-------|---------|
-| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | Completed 3 CMS query tasks |
-| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | Search uses CMS client |
-| L:LES-15 | related-to | P:cookie-sessions | 2026-02-23 | Lesson about auth token format |
+| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | 3 tasks |
+| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | |
 ```
 
-### When to Add Relationships
-
-| Trigger | What to Record |
-|---------|---------------|
-| Agent completes a task touching multiple files | `depends-on` between the files |
-| A lesson is added that relates to a pattern | `related-to` between lesson and pattern |
-| An agent demonstrates expertise | `expert-in` between agent and domain |
-| A decision causes a known issue | `caused-by` between bug and decision |
-| A new pattern supersedes an old approach | `obsoletes` between decisions/patterns |
+### Add Relationships When
 
-### Query Patterns
+| Trigger | Record |
+|---------|--------|
+| Task touches multiple files | `depends-on` |
+| Lesson relates to a pattern | `related-to` |
+| Agent demonstrates expertise | `expert-in` |
+| Decision causes known issue | `caused-by` |
+| Pattern supersedes old approach | `obsoletes` |
 
-When gathering context for a delegation:
+### Pre-Delegation Queries
 
-1. Find the target file(s) in the graph
-2. Follow `depends-on` edges to identify related files the agent might need to read
-3. Follow `expert-in` edges to confirm the right agent is assigned
-4. Follow `related-to` edges from relevant lessons to discover applicable patterns
-5. Check for `blocks` edges that might indicate known issues affecting the task
+Follow `depends-on` for related reads, `expert-in` to confirm agent, `related-to` for patterns, `blocks` for known issues.
 
-### Maintenance Rules
+### Maintenance
 
-- Add relationships as you discover them — don't batch
-- Review and prune at the start of major features (remove obsolete relationships)
-- Keep the graph focused — max ~100 active relationships. Archive old ones quarterly
-- Relationships are append-only during a session; pruning happens between sessions
+- Add as discovered; prune between sessions
+- Max ~100 active relationships; archive quarterly