opencastle 0.32.11 → 0.32.13

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

@@ -1,13 +1,11 @@
 ---
 name: trello-task-management
-description: "Trello board conventions for tracking feature work — board/list/card workflow, checklist-driven task breakdown, due dates, and when to use comments vs checklist items. Use when decomposing features into cards or resuming interrupted sessions."
+description: "Create and manage Trello cards, checklists, and boards for kanban workflows. Use when the user says: 'create a kanban board', 'add a task card', 'move card to sprint', or 'track project board'."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Task Management with Trello
 
-Conventions for tracking feature work on Trello boards via MCP tools. For project-specific board IDs and list IDs, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
+For project-specific board IDs and list IDs, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
 
 ## MCP Server
 
@@ -17,43 +15,34 @@ Conventions for tracking feature work on Trello boards via MCP tools. For projec
 | **Type** | stdio (spawned via `npx -y @delorenj/mcp-server-trello`) |
 | **Auth** | API key + token via `TRELLO_API_KEY` and `TRELLO_TOKEN` env vars |
 
-### Authentication
+## Available MCP Tools (quick)
 
-1. Get your API key at [trello.com/app-key](https://trello.com/app-key) → **API Key**
-2. On the same page, click **"Generate a Token"** to get your token
-3. Add both to your `.env` file:
+- `get_boards`, `get_lists`, `get_cards_by_list_id`, `get_card_details` — read-only board/list/card tools
+- `create_card`, `update_card`, `add_checklist_to_card`, `add_comment_to_card` — create/update tools (ensure proper auth)
 
-```
-TRELLO_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-TRELLO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
+### Example Invocations
 
-## Available MCP Tools
+```json
+// trello/create_card
+{ "listId": "abc123", "name": "[Feature] Add search", "desc": "Acceptance: returns results within 200ms", "labels": ["feature"] }
+// → { "id": "card456", "url": "https://trello.com/c/card456", "name": "[Feature] Add search" }
 
-| Tool | Description |
-|------|-------------|
-| `get_boards` | List all boards accessible to the authenticated user |
-| `get_lists` | Get all lists on a board (by board ID) |
-| `get_cards_by_list_id` | Get all cards in a specific list |
-| `get_card_details` | Get full details of a single card |
-| `create_card` | Create a new card in a list |
-| `update_card` | Update card fields (name, description, due date, list) |
-| `add_checklist_to_card` | Add a checklist with items to a card |
-| `add_comment_to_card` | Post a comment on a card |
+// trello/update_card  — move card to In Progress
+{ "cardId": "card456", "listId": "inprogress789" }
+// → { "id": "card456", "idList": "inprogress789" }
 
-## Discovered Issues (Bug Tickets)
+// trello/add_comment_to_card
+{ "cardId": "card456", "text": "Blocked: waiting for API schema approval" }
+// → { "id": "comment999", "data": { "text": "Blocked: ..." } }
+```
 
-When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked:
+## Discovered Issues (Bug Tickets)
 
-1. **Check** existing cards on the board to see if it is already tracked
-2. **If tracked** — skip it, continue with current work
-3. **If NOT tracked:**
-   - **Unfixable limitation** — add to known issues with severity, evidence, and root cause
-   - **Fixable bug** — create a Trello card:
-     - **Name:** `[Bug] Short description of the symptom`
-     - **List:** `Backlog` (or the equivalent list in your project)
-     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages
-     - **Due date:** Set only if it is blocking current work
+- Check existing cards for the issue.
+- If tracked, skip and continue.
+- If not tracked:
+  - For unfixable limitations: add to known issues with severity, evidence, and root cause.
+  - For fixable bugs: create a Trello card with Name (`[Bug] Short description`), List (`Backlog`), Description (symptoms, repro steps, affected files), and optional Due date if blocking.
 
 ## Card Naming
 
@@ -68,22 +57,9 @@ Use `[Area] Short description` format:
 [Docs] Update data model documentation
 ```
 
-**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`, `[Bug]`
 
 ## Board and List Workflow
 
-### Typical List Structure
-
-```
-Backlog  →  To Do  →  In Progress  →  In Review  →  Done
-```
-
-- **Backlog** — Captured but not yet planned
-- **To Do** — Planned and ready to start
-- **In Progress** — Actively being worked on
-- **In Review** — PR open, awaiting review or merge
-- **Done** — Completed and verified
-
 ### Agent-Driven Card Transitions (via MCP)
 
 | From | To | When |
@@ -92,53 +68,7 @@ Backlog  →  To Do  →  In Progress  →  In Review  →  Done
 | In Progress | Done | Non-PR task is verified (docs, config) |
 | Any | Backlog | Task is deferred |
 
-## Checklist-Driven Task Breakdown
-
-Use checklists for **subtask decomposition within a single card**. This keeps related work together without cluttering the board with micro-cards.
-
-### When to Use a Checklist vs a Separate Card
-
-| Use a **checklist item** when… | Use a **separate card** when… |
-|-------------------------------|------------------------------|
-| Steps are sequential and tightly coupled | Work can be assigned independently |
-| Total effort fits in one session | Each step spans multiple sessions |
-| Steps share the same assignee | Steps need different labels/due dates |
-| Internal implementation details | Distinct deliverables that need review |
-
-### Checklist Pattern for Feature Decomposition
-
-```
-Card: [Feature] Add price range filter
-Checklist: Implementation Steps
-  ☐ Add priceRange field to schema
-  ☐ Create DB migration
-  ☐ Update GROQ/API query
-  ☐ Build UI component
-  ☐ Wire into page
-  ☐ Write unit tests
-  ☐ Update documentation
-```
-
-## Due and Start Dates
-
-Trello cards support both a **start date** and a **due date**.
-
-- **Due date** — The deadline for the card to move to Done. Set for tasks on the critical path.
-- **Start date** — When work is expected to begin. Useful for pipeline planning.
-- **Due time** — Be explicit with time only for time-sensitive deliverables (e.g., scheduled releases).
-- **Format:** Trello API uses ISO 8601: `2026-03-20T14:00:00.000Z`
-
-## Comments vs Checklist Items
-
-| Use **comments** for… | Use **checklist items** for… |
-|-----------------------|------------------------------|
-| Progress updates visible to the team | Actionable steps with completion state |
-| Blocking issues or decisions | Pre-defined subtask decomposition |
-| Links to PRs, builds, external docs | Typed acceptance criteria |
-| Questions or async approvals | Implementation sub-steps |
-| Post-implementation notes | QA verification steps |
-
-**Rule of thumb:** If it needs to be *checked off*, it's a checklist item. If it needs to be *read*, it's a comment.
+After each create/update, verify the returned card ID and URL before proceeding.
 
 ## Session Continuity
 
@@ -146,6 +76,4 @@ At the start of each work session:
 
 1. `get_boards` — confirm the right board is active
 2. `get_lists` — identify current list structure
-3. `get_cards_by_list_id` for **In Progress** — find cards already in flight
-4. Resume work on the relevant card, updating the checklist as steps complete
-5. Move the card to the next list when the current phase is done
+3. `get_cards_by_list_id` for **In Progress** — resume work on relevant cards, updating checklists and moving to next list when done

package/src/orchestrator/plugins/turborepo/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Turborepo advanced topics
+
+- CI snippets for `turbo run --remote` and remote cache configuration
+- `inputs`/`outputs` tuning examples for common monorepo layouts
+- Self-hosted remote cache options and troubleshooting cache misses

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

@@ -1,6 +1,6 @@
 ---
 name: turborepo-monorepo
-description: "Turborepo monorepo commands, pipeline configuration, caching strategies, and task orchestration. Use when running builds, tests, linting, or any development commands in a Turborepo monorepo."
+description: "Configure pipelines, set up local/remote caching, and run scoped tasks in a Turborepo monorepo. Use when you say: 'enable remote caching', 'optimize pipeline inputs/outputs', or 'filter builds to affected packages'."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -95,6 +95,16 @@ turbo run build --remote-only      # Force remote cache usage
 - Vercel Remote Cache or self-hosted (Ducktape, TurboCache)
 - Set `TURBO_TOKEN` and `TURBO_TEAM` in CI environment
 
+## Quick Workflow: Setup remote caching in CI
+1. Add `TURBO_TOKEN` and `TURBO_TEAM` to your CI secrets.  
+2. Locally run `turbo login` and `turbo link` to verify the project is linked.  
+3. Add `turbo run build --remote` to the CI pipeline and watch for cache hit/miss logs.  
+4. If cache misses persist: verify `inputs`/`outputs` in `turbo.json`, stable env vars, then re-run.  
+
+**Validation (recommended):** run `turbo run build --dry-run` locally or in CI to preview the task graph and catch misconfigured inputs/outputs before executing.
+
+See REFERENCE.md for CI snippets and advanced cache tuning.
+
 ## Package Workspace Structure
 
 ```
@@ -119,3 +129,5 @@ monorepo/
 - Use `--dry-run` to debug pipeline configuration
 - Add `TURBO_TOKEN` and `TURBO_TEAM` to CI for remote caching
 - Never commit `.turbo/` or `node_modules/.cache/turbo`
+
+Further reading: see REFERENCE.md in this directory for CI snippets and advanced cache tuning.

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

@@ -3,43 +3,35 @@ name: vercel-deployment
 description: "Vercel deployment workflows, environment management, domain configuration, and build troubleshooting. Use when deploying, checking deployment status, reviewing build logs, or managing environments."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Vercel Deployment
 
 Vercel-specific deployment patterns and MCP tool usage. For project-specific deployment architecture, environment variables, and key files, see [deployment-config.md](../../.opencastle/stack/deployment-config.md).
 
 ## Deployment Model
 
-Vercel uses Git-based deployments with automatic preview and production environments:
-
-```
-main branch    → Production deployment (auto)
-feature/*      → Preview deployment (auto)
-fix/*          → Preview deployment (auto)
-```
+Branch → Environment mapping:
 
-- Every push creates a deployment — no manual triggers needed
-- Preview deployments get unique URLs for testing
-- Production deploys only from the main branch
-- Rollback by redeploying a previous commit
+| Branch pattern | Environment |
+|----------------|-------------|
+| `main` | Production deployment (auto) |
+| `feature/*`, `fix/*` | Preview deployment (auto) |
 
 ## MCP Tools
 
 The Vercel MCP server provides these tools through `https://mcp.vercel.com`:
 
-| Tool | Purpose | Primary Agents |
-|------|---------|----------------|
-| `deploy_to_vercel` | Trigger a deployment | DevOps Expert |
-| `get_deployment` | Check deployment status and metadata | DevOps, Release Manager |
-| `get_deployment_build_logs` | Read build output for debugging | DevOps, Release Manager |
-| `get_runtime_logs` | Read runtime logs for debugging | DevOps, Release Manager |
-| `list_deployments` | List recent deployments | DevOps, Release Manager |
-| `get_project` | Get project configuration | DevOps Expert |
-| `list_projects` | List all projects in the team | DevOps Expert |
-| `list_teams` | List available teams | DevOps Expert |
-| `search_vercel_documentation` | Search Vercel docs | DevOps Expert |
-| `check_domain_availability_and_price` | Domain availability check | DevOps Expert |
+| Tool | Purpose |
+|------|---------|
+| `deploy_to_vercel` | Trigger a deployment |
+| `get_deployment` | Check deployment status and metadata |
+| `get_deployment_build_logs` | Read build output for debugging |
+| `get_runtime_logs` | Read runtime logs for debugging |
+| `list_deployments` | List recent deployments |
+| `get_project` | Get project configuration |
+| `list_projects` | List all projects in the team |
+| `list_teams` | List available teams |
+| `search_vercel_documentation` | Search Vercel docs |
+| `check_domain_availability_and_price` | Domain availability check |
 
 ## Environment Variables
 
@@ -55,10 +47,7 @@ Vercel supports three environment scopes — set variables for each appropriatel
 
 ### Best Practices
 
-- Set secrets via the Vercel dashboard or CLI — never commit them
-- Use `NEXT_PUBLIC_*` prefix only for variables safe to expose to the browser
-- Verify required env vars exist in all three scopes (production, preview, development)
-- Use `.env.local` for local development; never commit this file
+Verify required env vars exist in production and preview scopes; see REFERENCE.md for details.
 
 ## Build Troubleshooting
 
@@ -66,34 +55,38 @@ When builds fail, follow this workflow:
 
 1. **Read build logs** — use `get_deployment_build_logs` to get the full output
 2. **Check common causes:**
-   - Missing environment variables (works locally but not on Vercel)
+   - Missing environment variables
    - Node.js version mismatch (check `engines` in `package.json`)
    - Build command mismatch (verify in project settings)
    - Dependency resolution issues (lockfile out of sync)
-3. **Check runtime logs** — use `get_runtime_logs` for post-deploy errors
-4. **Verify deployment status** — use `get_deployment` to check state and error details
+  3. **Check runtime logs** — use `get_runtime_logs` for post-deploy errors
+  4. **Verify deployment status** — use `get_deployment` to check state and error details
+
+  ### Example troubleshooting commands (MCP payloads)
+
+  1) Get build logs:
+
+  ```json
+  // tool: vercel/get_deployment_build_logs
+  { "deployment_id": "dpl_abc123" }
+  ```
+
+  2) Get runtime logs:
+
+  ```json
+  // tool: vercel/get_runtime_logs
+  { "deployment_id": "dpl_abc123", "limit": 200 }
+  ```
+
+  3) Re-deploy a specific commit after fixing an issue:
 
-## Domain Configuration
+  ```json
+  // tool: vercel/deploy_to_vercel
+  { "project_id": "proj_xxx", "gitCommitSha": "abcd1234" }
+  ```
 
-- Use `check_domain_availability_and_price` before purchasing
-- Configure domains in the Vercel dashboard
-- Always set up both `www` and apex domain with proper redirects
-- Enable HTTPS (automatic with Vercel)
-- Set appropriate DNS records (CNAME for subdomains, A record for apex)
+  After re-deploying, re-check `get_deployment_build_logs` and `get_runtime_logs` to confirm the fix. Repeat until build succeeds.
 
 ## Cron Jobs (vercel.json)
 
-```json
-{
-  "crons": [
-    {
-      "path": "/api/cron/task-name",
-      "schedule": "0 */6 * * *"
-    }
-  ]
-}
-```
-
-- Protect cron endpoints with `CRON_SECRET` — Vercel sends it in the `Authorization` header
-- Maximum execution time depends on plan (10s hobby, 60s pro, 900s enterprise)
-- Use `vercel.json` to declare cron schedules — not external schedulers
+Configure cron jobs in `vercel.json` under `crons[]` with path and schedule.

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

@@ -1,13 +1,13 @@
 ---
 name: vitest-testing
-description: "Vitest unit and integration testing patterns, configuration, mocking, and coverage. Use when writing unit tests, configuring Vitest, or setting up test coverage."
+description: "Vitest unit and integration testing patterns, commands, mocking (vi.mock), and coverage. Use when writing .test.ts files, configuring the test runner, or adding coverage thresholds."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Vitest Testing
 
-Vitest-specific unit and integration testing patterns. For project-specific test configuration, see [testing-config.md](../../.opencastle/stack/testing-config.md).
+For project-specific test configuration, see [testing-config.md](../../.opencastle/stack/testing-config.md).
 
 ## Commands
 
@@ -152,15 +152,11 @@ export default defineConfig({
 });
 ```
 
-## Best Practices
-
-- Co-locate test files next to source files (`foo.test.ts` next to `foo.ts`)
-- Use `describe` blocks to group related tests
-- Each test should be independent — no shared mutable state between tests
-- Clean up mocks with `vi.restoreAllMocks()` in `afterEach`
-- Mock dependencies before imports — `vi.mock()` calls are hoisted automatically but declare them at the top for clarity
-- Prefer `toEqual` for objects, `toBe` for primitives
-- Use `test.each` for parameterized tests
-- Set coverage thresholds to prevent regression
-- Use `vi.useFakeTimers()` for time-dependent code — never `setTimeout` in tests
-- Aim for 3-5 focused tests per file for maintainability — split large test suites
+## Workflow
+
+1. Create `*.test.ts` adjacent to the source file.
+2. Write focused unit tests (happy path + edge cases). Use `vi.mock()` before imports; restore in `afterEach` with `vi.restoreAllMocks()`.
+3. Run `npx vitest run <file>` — fix failures.
+4. If tests fail: run `npx vitest run <file> --reporter=verbose` to inspect, fix, re-run.
+5. Coverage validation: run `npx vitest run --coverage --reporter=json` (CI) or `npx vitest run --coverage --reporter=text` (local) to generate coverage reports. Inspect `coverage`/`coverage-final.json` or the human-readable summary to find uncovered files/branches. If coverage is below thresholds, add targeted tests for uncovered branches, then re-run `npx vitest run --coverage` until thresholds pass.
+6. Commit tests alongside source changes.

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -55,37 +55,49 @@ Determine the type:
 Use this template:
 
 ```markdown
-````skill
 ---
 name: <skill-name>
-description: "<One-line description of what the skill covers. Include key topics and when to use it.>"
+description: "<Verb1> X, <verb2> Y, and <verb3> Z. Use when <scenario1>, <scenario2>, or <scenario3>."
 ---
 
 # <Display Name>
 
-<1-2 sentence overview of the skill's purpose and scope.>
-
-## Core Principles
+## Workflow
 
-1. **<Principle>** — <Explanation>
-2. **<Principle>** — <Explanation>
-3. **<Principle>** — <Explanation>
+1. **<Step>** — <Action>
+   - Checkpoint: <what to verify before proceeding>
+   - Recovery: <what to do on failure>
+2. **<Step>** — <Action>
+   - Checkpoint: <validation>
+3. **<Step>** — <Action>
+   - Fail → fix → re-run from step N.
 
-## <Domain Section 1>
+## <Domain Section>
 
 <Content organized by topic. Use tables, code blocks, and checklists.>
 
-## <Domain Section 2>
+## <Executable Example>
 
-<More domain content.>
+```<lang>
+// Concrete, copy-paste-ready code (5-15 lines)
+```
 
 ## Anti-Patterns
 
-- **<Bad pattern>** — <Why it's bad and what to do instead>
-- **<Bad pattern>** — <Why it's bad and what to do instead>
-````
+| Anti-pattern | Fix |
+|-------------|-----|
+| <Bad pattern> | <What to do instead> |
+
+## References
+
+| Resource | Purpose |
+|----------|--------|
+| [REFERENCE.md](./REFERENCE.md) | <Extended examples, schemas, large tables> |
+| **<related-skill>** skill | <What it contributes> |
 ```
 
+If the skill has large code examples (>30 lines), schema tables, or verbose reference material, create a companion `REFERENCE.md` in the same directory and link to it from SKILL.md. Keep SKILL.md as the lean operational overview. Companion files must start with a backlink: `> Parent: [SKILL.md](./SKILL.md)`.
+
 ### Step 4: Register the Skill
 
 Registration differs by type:
@@ -111,12 +123,42 @@ Registration differs by type:
 - [ ] Skill matrix updated (`directSkills` array or capability slot binding)
 - [ ] For process skills: at least one agent's `directSkills` array includes it in skill-matrix.json
 - [ ] For plugin skills: `config.ts` `skillName` matches the `name` in frontmatter
+- [ ] Run `npx tessl skill review <path>` — target 100% score (see Scoring Criteria below)
+
+## Scoring Criteria
+
+Skills are evaluated by `npx tessl skill review` across 8 criteria (3 pts each = 24 total). Target 100%.
+
+### Description (frontmatter `description` field)
+
+| Criterion | 3/3 Pattern | Common Pitfall |
+|-----------|------------|----------------|
+| **Specificity** | List 3+ concrete actions as verbs: "Creates X, validates Y, and manages Z" | Vague "covers" or "handles" without listing what |
+| **Trigger terms** | Natural phrases a user would say — broad synonyms and variations | Too specialized; missing common phrasings |
+| **Completeness** | Explicit `Use when...` clause with 3+ trigger scenarios | Missing when-to-use guidance |
+| **Distinctiveness** | Unique niche; terms unlikely to collide with other skills | Generic terms that overlap with adjacent skills |
+
+**Formula:** `"<Verb1> X, <verb2> Y, and <verb3> Z. Use when <scenario1>, <scenario2>, or <scenario3>."`
+
+### Content (SKILL.md body)
+
+| Criterion | 3/3 Pattern | Common Pitfall |
+|-----------|------------|----------------|
+| **Conciseness** | Every line earns its place. No info Claude already knows. Tables over prose. | Explaining obvious concepts, redundant sections, verbose anti-patterns with "Why" columns |
+| **Actionability** | ≥1 executable code example (copy-paste ready), concrete CLI commands, specific thresholds | Deferring to other skills without fallback, abstract guidance without examples |
+| **Workflow clarity** | Numbered steps with validation checkpoints, explicit error recovery, feedback loops (fail → fix → re-run) | Implied sequence without numbers, no checkpoints between steps, missing recovery path |
+| **Progressive disclosure** | SKILL.md = lean overview. Bulky content (>30-line examples, large tables, schemas) in REFERENCE.md. External refs organized in a References section. | Everything inline making the file too heavy, or too much deferred leaving SKILL.md hollow |
 
 ## Quality Guidelines
 
-- **Be prescriptive** — Skills should give clear instructions, not vague advice. "Use `fetchPlaces()` from `libs/queries`" beats "use the query library"
-- **Include examples** — Code snippets, file path examples, and table references
-- **Keep it scannable** — Use headings, tables, bullets, and code blocks. Agents need to find information fast
-- **Avoid duplication** — If a rule already exists in `.github/instructions/`, reference it instead of repeating it
-- **Stay stack-agnostic in process skills** — Never hardcode technology names; use capability slot references (e.g., "the **database** skill" not "Supabase")
-- **Size target** — 100-300 lines. Under 100 is probably too thin; over 300 should be split into multiple skills
+- **Be prescriptive** — "Use `fetchPlaces()` from `libs/queries`" beats "use the query library"
+- **Include executable examples** — At least one copy-paste-ready code block (5-15 lines). CLI commands with real flags, not placeholders
+- **Keep it scannable** — Tables over prose. Headings, bullets, code blocks. Agents parse structure, not paragraphs
+- **Number your workflows** — Every multi-step process needs numbered steps, checkpoints ("Gate: X passes"), and recovery ("Fail → fix → re-run step N")
+- **Don't explain what Claude knows** — Skip "what is X" explanations, obvious anti-pattern justifications, and concept definitions. Jump straight to the rules
+- **Avoid duplication** — If a rule exists in another skill or instruction file, reference it: "Load **security-hardening** skill for CSP configuration"
+- **Use REFERENCE.md for bulk** — Large code examples, schema tables, worked examples, and template libraries go in a companion `REFERENCE.md`. Link once from SKILL.md
+- **Stay stack-agnostic in process skills** — Use capability slot references ("the **database** skill" not "Supabase")
+- **Size target** — 80-200 lines in SKILL.md. Under 80 is too thin; over 200 should split content to REFERENCE.md. Over 300 should be split into multiple skills
+- **No standalone trigger-term sections** — Weave trigger terms naturally into the description's `Use when...` clause
+- **Third-person voice in descriptions** — "Creates X" not "Create X" or "This skill creates X"

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

@@ -0,0 +1,34 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Composite Widgets & Form Error Handling (Reference)
+
+### Roving tabindex pattern
+
+Use when a composite widget (menu, listbox, tabs) manages focus internally.
+
+1. Container receives `tabindex="0"` and keyboard handlers.
+2. Children are `tabindex="-1"` except one `tabindex="0"` representing active item.
+3. Arrow keys update `tabindex` values and call `.focus()` on the new active child.
+
+Example:
+
+```html
+<div role="listbox" tabindex="0" aria-activedescendant="item-1">
+  <div id="item-1" role="option">Item 1</div>
+  <div id="item-2" role="option">Item 2</div>
+</div>
+```
+
+### `aria-activedescendant` pattern
+
+When focus remains on a container but a child is visually active, use `aria-activedescendant` referencing the active child's `id`. Update the attribute on arrow navigation.
+
+### Form error handling
+
+- On validation error, add `aria-invalid="true"` and `aria-describedby="#error-id"` to the input.
+- Ensure the error element has role `alert` or is announced by screen readers when it appears.
+- Move focus to the first invalid control and programmatically announce error summary.
+
+### Skip links & focus management
+
+Provide a visible `skip to main` link as first focusable element. Ensure `main` has an `id` target.

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

@@ -21,11 +21,14 @@ Plain language; consistent landmarks and nav order across pages; minimal distrac
 - 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): tab stop on container; arrow keys navigate children via roving tabindex or `aria-activedescendant`; on focus restore last/first child.
+**Composite components** and detailed complex patterns have been moved to REFERENCE.md to keep this skill focused. See REFERENCE.md for roving tabindex, `aria-activedescendant`, and composite widget examples.
 
-**Roving tabindex:** First child `tabindex="0"`, rest `-1`; on arrow key set prev to `-1`, new to `0`, call `.focus()`.
+### Validation checkpoints (run-fix-repeat)
 
-**`aria-activedescendant`:** Container `tabindex="0"` + `aria-activedescendant="IDREF"`; CSS draws outline on referenced element; arrow keys update attribute.
+- Run an automated audit: `npx axe-core` or integrate `axe-core`/`axe-playwright` in CI — fix high/critical findings.
+- Verify keyboard tab order manually: `Tab` through the page, ensure logical order and visible focus.
+- Confirm contrast ratios (spot-check key pages): use `axe`, `pa11y`, or `contrast` tools and ensure ≥4.5:1 for body text.
+- Fix, re-run audits, and repeat until no high/critical a11y issues remain.
 
 **Skip link** (first focusable element):
 

package/src/orchestrator/skills/agent-hooks/HOOKS-REFERENCE.md

@@ -0,0 +1,48 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Agent Hooks — Detailed Reference
+
+## on-session-start (extended checks)
+
+| # | Action |
+|---|--------|
+| 1 | `rg -n "keyword" .opencastle/LESSONS-LEARNED.md` |
+| 2 | `cat .opencastle/SESSION-CHECKPOINT.md` |
+| 3 | `rg -n "Pending Approvals" .opencastle/SESSION-CHECKPOINT.md || true` |
+| 4 | `rg -n "ERROR\|FAIL" .opencastle/AGENT-FAILURES.md || true` |
+| 5 | `jq '.bindings' .opencastle/agents/skill-matrix.json` — verify bindings present |
+| 6 | Load domain skills before writing code |
+
+## on-pre-delegate (example commands)
+
+| # | Check | Example Command |
+|---|-------|-----------------|
+| 1 | Tracker issue | `gh issue view TAS-123 || gh issue create --title "TAS-123" --body "AC: ..."` |
+| 2 | File partition | `rg -n "path:" prompts/* | cut -d: -f2 | sort | uniq -d` |
+| 3 | Upstream deps | Verify upstream tasks are marked Done in tracker |
+| 4 | Paths + AC | Include exact file paths (not globs) and acceptance criteria in prompt |
+| 5 | Self-improvement | Add `Read .opencastle/LESSONS-LEARNED.md` to prompt text |
+| 6 | Context map | `opencastle context-map` — load **context-map** skill for 5+ files |
+
+Log delegation: `opencastle log --type=delegation --issue=TAS-123 --status=started --details "spawned subagent for feature X"`
+
+## on-post-delegate (detailed verification)
+
+| # | Action | Command |
+|---|--------|---------|
+| 1 | Log completion | `opencastle log --type=delegation --issue=TAS-XX --status=complete` |
+| 2 | Fast review | `opencastle log --type=review --issue=TAS-XX --verdict=PASS` |
+| 3 | CI checks | `pnpm lint && pnpm typecheck && pnpm test` |
+| 4 | Verify ACs | Check each acceptance criterion against tracker issue |
+| 5 | Track issues | `rg -n "Discovered issue" KNOWN-ISSUES.md || gh issue create` |
+| 6 | Lesson check | If agent retried, verify lesson added via **self-improvement** |
+| 7 | Close/retry | `gh issue edit TAS-XX --state done` or re-delegate; 3rd failure → `.opencastle/AGENT-FAILURES.md` |
+
+## on-session-end (detailed)
+
+| # | Action | Who |
+|---|--------|-----|
+| 1 | `opencastle doctor --fix` | Team Lead |
+| 2 | `opencastle log --type session ...` | All |
+| 3 | Write `.opencastle/SESSION-CHECKPOINT.md` if incomplete | Team Lead |
+| 4 | `rg -c "^Lesson:" .opencastle/LESSONS-LEARNED.md` — flag merge if ≥5 | All |