opencastle 0.35.2 → 0.35.3

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: decomposition
-description: "Resolves task dependencies, generates machine-actionable delegation specs, and structures phased subtask plans for multi-agent work. Use when writing delegation specs, resolving task dependencies, building phased subtask plans for multi-agent work, assigning work to sub-agents, or partitioning a feature into parallelizable phases."
+description: "Resolves task dependencies, generates machine-actionable delegation specs, structures phased subtask plans for multi-agent work. Use when writing delegation specs, resolving task dependencies, building phased subtask plans for multi-agent work, assigning work to sub-agents, or partitioning a feature into parallelizable phases."
 ---
 
 # Task Decomposition
@@ -12,7 +12,7 @@ description: "Resolves task dependencies, generates machine-actionable delegatio
 
 **Topological sort:** No-dep tasks → Phase 1. Tasks depending only on Phase N → Phase N+1. Same-phase tasks with no mutual deps run in parallel.
 
-**Cycle detection:** If A → B → C → A, split one task into an independent part + a dependent part.
+**Cycle detection:** If A → B → C → A, split one task into independent part + dependent part.
 
 ```
 Graph:        Plan:
@@ -28,15 +28,42 @@ F → C, D     Phase 3: E, F (parallel)
 | Tracker | TAS-XX — Title |
 | Complexity | [score]/13 → [tier] |
 | Agent | Agent Name |
-| Objective | 1-3 sentences: what to build/change and why |
+| Objective | 1-3 sentences: what to build/change, why |
 | Context | Key files, related patterns, prior phase output, relevant lessons |
 | Constraints | File partition, explicit exclusions, phase dependencies |
 | Acceptance Criteria | `[ ]` checklist |
 | Expected Output | Files changed · Verification · AC status · Discovered issues |
 
-For score 1-3, objective + files + criteria is sufficient. See `REFERENCE.md` for the full delegation spec template.
+For score 1-3, objective + files + criteria is sufficient. Full template:
 
-Read `.opencastle/LESSONS-LEARNED.md` before starting. Add a lesson if you retry any approach.
+```markdown
+## Delegation Spec: [Task Title]
+**Tracker Issue:** TAS-XX — [Title]
+**Complexity:** [score]/13 → [tier] tier
+**Agent:** [Agent Name]
+
+### Objective
+1-3 sentences: what to build/change and why.
+
+### Context
+- Key files: [list]
+- Related patterns: [file:line references]
+- Prior phase output: [compacted summary if applicable]
+- Relevant lessons: [LES-XXX from LESSONS-LEARNED.md]
+
+### Constraints
+- File partition: Only modify files under [paths]
+- Do NOT modify: [explicit exclusions]
+- Dependencies: Requires [TAS-XX] Done first
+
+### Acceptance Criteria
+- [ ] Criterion 1
+
+### Expected Output
+Files changed · Verification (lint/test/build) · AC status (✅/❌) · Discovered issues · Lessons applied
+```
+
+Read `.opencastle/LESSONS-LEARNED.md` before starting. Add lesson if you retry any approach.
 
 ## Prompt Quality
 
@@ -90,6 +117,6 @@ Phase 2+: page tasks (parallel)
 
 **Common mistake:** Decomposing pages as independent Phase 1 tasks → each agent invents its own design.
 
-**Distinctive note (AI delegation):** This skill focuses on decomposition that produces machine-actionable delegation prompts: file partitions, explicit acceptance criteria, and machine-friendly constraints (exact paths, line ranges, forbidden files). The output should be ready to paste into a sub-agent prompt without additional human translation.
+**Distinctive note (AI delegation):** This skill focuses on decomposition producing machine-actionable delegation prompts: file partitions, explicit acceptance criteria, machine-friendly constraints (exact paths, line ranges, forbidden files). Output should be ready to paste into sub-agent prompt without additional human translation.
 
-> Load the **project-consistency** skill for the full Foundation Phase pattern, prompt templates, and anti-patterns.
+> Load **project-consistency** skill for full Foundation Phase pattern, prompt templates, anti-patterns.

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: deployment-infrastructure
-description: "Configures deployment pipelines, manages environment variables, schedules cron jobs, applies security headers, and implements caching strategies. Use when working with Docker, Vercel, AWS, Dockerfile, nginx.conf, or platform deployment configs."
+description: "Configures deployment pipelines, manages environment variables, schedules cron jobs, applies security headers, implements caching strategies. Use when working with Docker, Vercel, AWS, Dockerfile, nginx.conf, or platform deployment configs."
 ---
 
 # Deployment Infrastructure
 
-See [deployment-config.md](../../.opencastle/stack/deployment-config.md) for full architecture, env vars, cron jobs, and caching headers.
+See [deployment-config.md](../../.opencastle/stack/deployment-config.md) for full architecture, env vars, cron jobs, caching headers.
 
 ## Environment Variables
 
@@ -65,7 +65,7 @@ Apply via framework `headers()` config or CDN rules.
 
 ## Security Headers
 
-Load **security-hardening** skill for full CSP inventory and header configuration.
+Load **security-hardening** skill for full CSP inventory, header configuration.
 
 ## Release Process
 
@@ -79,7 +79,7 @@ Load **security-hardening** skill for full CSP inventory and header configuratio
 
 ## Rollback
 
-Prefer platform rollback (promote last good deploy). Fallback: `git revert -m 1 HEAD && git push`.
+Prefer platform rollback (promote last good deploy). Fallback: `git revert -m 1 HEAD Prefer platform rollback (promote last good deploy). Fallback: `git revert -m 1 HEAD && git push`.Prefer platform rollback (promote last good deploy). Fallback: `git revert -m 1 HEAD && git push`. git push`.
 
 1. Roll back → 2. Smoke-test (`curl -sI`) → 3. Confirm 200 + correct behavior → 4. If still broken, escalate
 5. Notify team; create post-mortem ticket

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

@@ -1,11 +1,11 @@
 ---
 name: documentation-standards
-description: "Scaffolds issue docs, ADRs, README outlines, changelog entries, roadmap updates, and Mermaid architecture diagrams using project templates. Use when drafting an ADR, writing a changelog, updating the roadmap after a feature ships, creating a README for a new library, or diagramming a system flow."
+description: "Scaffolds issue docs, ADRs, README outlines, changelog entries, roadmap updates, Mermaid architecture diagrams using project templates. Use when drafting ADR, writing changelog, updating roadmap after a feature ships, creating README for a new library, or diagramming a system flow."
 ---
 
 # Documentation Standards
 
-For project-specific directory structure and practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
+For project-specific directory structure, practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
 
 
 ## Issue Documentation Template
@@ -34,7 +34,7 @@ For project-specific directory structure and practices, see [docs-structure.md](
 
 ## Roadmap Update Template
 
-When a feature is completed: add `COMPLETE` row with date and owner, list files changed with rationale, add validation command + exit status, move to `Completed` section with one-line release note.
+When feature completed: add `COMPLETE` row with date, owner; list files changed with rationale; add validation command + exit status; move to `Completed` section with one-line release note.
 
 ```markdown
 - Feature: Add priceRange filter
@@ -63,7 +63,7 @@ One-sentence summary of what this does and why it exists.
 ## Quick Start
 Brief usage example or setup steps.
 ## Architecture
-High-level overview. Include a Mermaid diagram for non-trivial systems.
+High-level overview. Include Mermaid diagram for non-trivial systems.
 ## Key Files
 | File | Purpose |
 |------|---------|
@@ -87,7 +87,7 @@ flowchart TD
 
 ## Changelog Entry Template
 
-Group entries by Conventional Commits type under a version heading:
+Group entries by Conventional Commits type under version heading:
 
 ```markdown
 ## [1.2.0] — YYYY-MM-DD
@@ -99,7 +99,7 @@ Group entries by Conventional Commits type under a version heading:
 - refactor: Extract validation into shared module (#125)
 ```
 
-- One line per change; reference the PR or issue number
+- One line per change; reference PR or issue number
 - Imperative mood; most recent version first
 
 ## Documentation workflow
@@ -117,4 +117,4 @@ Group entries by Conventional Commits type under a version heading:
 
 ## Writing, Formatting & Anti-Patterns
 
-See [WRITING-GUIDE.md](WRITING-GUIDE.md) for writing guidelines, formatting rules, and anti-patterns.
+See [WRITING-GUIDE.md](WRITING-GUIDE.md) for writing guidelines, formatting rules, anti-patterns.

package/src/orchestrator/skills/documentation-standards/WRITING-GUIDE.md

@@ -13,7 +13,7 @@
 | Element | Convention |
 |---------|-----------|
 | Headings | Sentence case (`## Core principles`, not `## Core Principles`). Exception: proper nouns and acronyms. |
-| Lists | Parallel structure — all items start with the same part of speech |
+| Lists | Parallel structure — all items start with same part of speech |
 | Code | Inline backticks for symbols/commands; fenced blocks for multi-line |
 | Links | Descriptive text: `[migration guide](./migrate.md)` not `[click here](./migrate.md)` |
 | Tables | Use for structured comparisons; keep columns ≤5 |
@@ -21,7 +21,7 @@
 
 ## Markdown Standards
 
-- One blank line before and after headings, code blocks, and tables
+- One blank line before, after headings, code blocks, tables
 - No trailing whitespace
 - Files end with a single newline
 - Use `---` for horizontal rules (sparingly)
@@ -32,7 +32,7 @@
 | Anti-pattern | Fix |
 |-------------|-----|
 | Walls of prose without structure | Break into headings, bullets, or tables |
-| Duplicate content across docs | Link to the canonical source |
+| Duplicate content across docs | Link to canonical source |
 | Stale "Last Updated" dates | Remove or automate; manual dates drift |
 | TODO/FIXME placeholders in published docs | Resolve before merging |
 | Screenshots without alt text | Add descriptive alt text for accessibility |

package/src/orchestrator/skills/fast-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fast-review
-description: "Mandatory post-delegation gate that checks output completeness, verifies acceptance criteria compliance, flags regressions, and produces a PASS/FAIL verdict. Use when checking delegated work against acceptance criteria, running the post-delegation gate, validating agent output before acceptance, verifying a sub-agent completed its assignment, or running a post-delegation QA check."
+description: "Mandatory post-delegation gate: checks output completeness, verifies acceptance criteria compliance, flags regressions, produces PASS/FAIL verdict. Use when checking delegated work against acceptance criteria, running post-delegation gate, validating agent output before acceptance, verifying sub-agent completed its assignment, or running post-delegation QA check."
 ---
 
 # Skill: Fast Review
@@ -57,7 +57,7 @@ CONFIDENCE: low | medium | high
 
 ## Reviewer Prompt Template
 
-See [REFERENCE.md](REFERENCE.md) for the full reviewer prompt template.
+See [REFERENCE.md](REFERENCE.md) for full reviewer prompt template.
 
 ## Logging
 

package/src/orchestrator/skills/frontend-design/COMPONENTS.md

@@ -2,7 +2,7 @@
 
 # Frontend Design Components
 
-Extended component patterns, card variants, and hero animations for the **frontend-design** skill.
+Extended component patterns, card variants, hero animations for **frontend-design** skill.
 
 ## Design Tokens (starter)
 

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: "Defines a named visual aesthetic, selects typography pairings, builds CSS token systems, and adds entrance animations for high-design-quality pages. Use when the user asks to design a landing page, style a marketing site, create a distinctive UI theme, pick fonts, or add CSS animations — specifically when visual polish and brand identity matter rather than generic component scaffolding."
+description: "Defines named visual aesthetic, selects typography pairings, builds CSS token systems, adds entrance animations for high-design-quality pages. Use when user asks to design landing page, style marketing site, create distinctive UI theme, pick fonts, or add CSS animations — specifically when visual polish, brand identity matter rather than generic component scaffolding."
 license: Complete terms in LICENSE.txt
 ---
 
@@ -8,10 +8,10 @@ license: Complete terms in LICENSE.txt
 
 ## Design Workflow
 
-1. **Name the aesthetic** — declare a 2–3 word direction in a code comment at the top of the main CSS file
-2. **Set foundations** — define `:root` CSS custom properties for colors, spacing, and radii
+1. **Name the aesthetic** — declare 2–3 word direction in code comment at top of main CSS file
+2. **Set foundations** — define `:root` CSS custom properties for colors, spacing, radii
 3. **Build components** — implement layout, cards, heroes, forms using only tokens from step 2
-4. **Add motion** — add `@keyframes` entrance animations wrapped in a reduced-motion guard
+4. **Add motion** — add `@keyframes` entrance animations wrapped in reduced-motion guard
 5. **Validate** — run Quality Checklist below; fix any failing item before marking done
 
 ### Quick-start example
@@ -35,23 +35,23 @@ license: Complete terms in LICENSE.txt
 }
 ```
 
-Card patterns, hero animations, and extended token sets are in [COMPONENTS.md](./COMPONENTS.md).
+Card patterns, hero animations, extended token sets in [COMPONENTS.md](./COMPONENTS.md).
 
 ## Design Principles
 
-High-level design principles and the full set of example constraints live in [REFERENCE.md](./REFERENCE.md). Keep this checklist as a short reminder:
+High-level design principles, full example constraints live in [REFERENCE.md](./REFERENCE.md). Keep this checklist as short reminder:
 
-- Pick a named aesthetic (2–3 words) and commit to it.
-- Use tokenized colors/spacing, respect WCAG contrast, and prefer semantic HTML.
-- Respect `prefers-reduced-motion` and keep critical animations under 500ms.
+- Pick named aesthetic (2–3 words); commit to it.
+- Use tokenized colors/spacing; respect WCAG contrast; prefer semantic HTML.
+- Respect `prefers-reduced-motion`; keep critical animations under 500ms.
 
 **Every design must have one unforgettable detail.** No two designs should look alike.
 
 ## Typography Pairings
 
-Recommended typography pairings and an extended catalogue are in [REFERENCE.md](./REFERENCE.md). For production, always include a metric-preserving fallback chain (e.g., `'Fraunces', 'Georgia', serif`).
+Recommended typography pairings, extended catalogue in [REFERENCE.md](./REFERENCE.md). For production, always include metric-preserving fallback chain (e.g., `.Fraunces., .Georgia., serif`).
 
-> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.
+> Load **project-consistency** skill for full Foundation Phase pattern, prompt templates.
 
 ### Quality Checklist (quick)
 

package/src/orchestrator/skills/git-workflow/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: git-workflow
-description: "Defines branch naming conventions, PR template requirements, commit message format, discovered-issues escalation policy, and task tracking conventions. Load when committing, pushing, or opening PRs."
+description: "Defines branch naming conventions, PR template requirements, commit message format, discovered-issues escalation policy, task tracking conventions. Load when committing, pushing, or opening PRs."
 ---
 
 # Git Workflow & Delivery
 
-**NEVER push directly to `main`.** All changes go through a feature/fix branch → PR.
+**NEVER push directly to `main`.** All changes go through feature/fix branch → PR.
 
 ## Branch & Commit Rules
 
@@ -22,7 +22,7 @@ description: "Defines branch naming conventions, PR template requirements, commi
 1. Branch `<type>/<ticket-id>-<slug>` from `main`
 2. Atomic commits referencing issue ID
 3. Push branch to origin
-4. Open PR (do NOT merge) — write the body to a temp file first, then use `--body-file`:
+4. Open PR (do NOT merge) — write body to temp file first; use `--body-file`:
    ```sh
    # Write PR body to a temp file to avoid shell escaping issues
    cat > /tmp/pr-body.md << 'EOF'
@@ -33,7 +33,7 @@ description: "Defines branch naming conventions, PR template requirements, commi
    EOF
    GH_PAGER=cat gh pr create --base main --title "TAS-XX: Short description" --body-file /tmp/pr-body.md
    ```
-   **Never use inline `--body` with markdown/backticks/special chars** — it breaks in zsh heredocs and quoted strings.
+   **Never use inline `--body` with markdown/backticks/special chars** — breaks in zsh heredocs, quoted strings.
 5. Update issue with PR URL
 
 ## Discovered Issues Policy
@@ -44,4 +44,4 @@ description: "Defines branch naming conventions, PR template requirements, commi
 
 Tracked in the **task tracker** (`tracker-config.md`). Team Lead creates/updates issues via MCP. Load **task-management** skill for conventions.
 
-**If MCP tools unavailable:** Document planned issues (title + AC) in output, use `"N/A"` (no tracker) or `"TAS-PENDING"` (tracker configured), proceed with work, update IDs when available.
+**If MCP tools unavailable:** Document planned issues (title + AC) in output; use `"N/A"` (no tracker) or `"TAS-PENDING"` (tracker configured); proceed with work; update IDs when available.

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

@@ -1,6 +1,6 @@
 ---
 name: memory-merger
-description: "Reviews mature LESSONS-LEARNED.md entries, rewrites them as permanent rules in skill/instruction files, and archives graduated lessons. Use when graduating lessons into skills, promoting validated lessons, updating skills from past learnings, archiving mature lessons, codifying repeated patterns, or cleaning up a crowded LESSONS-LEARNED.md."
+description: "Reviews mature LESSONS-LEARNED.md entries, rewrites them as permanent rules in skill/instruction files, archives graduated lessons. Use when graduating lessons into skills, promoting validated lessons, updating skills from past learnings, archiving mature lessons, codifying repeated patterns, or cleaning up a crowded LESSONS-LEARNED.md."
 ---
 
 # Memory Merger
@@ -22,11 +22,11 @@ Combined signals to identify merge candidates.
 ## Workflow (numbered)
 
 1. Scan LESSONS-LEARNED.md for candidate entries (frequency, severity, age).
-2. Map each candidate to a target file and section.
-3. Draft the exact edit (concise rule or example).
-4. Apply the edit with an attribution comment.
-5. Archive the migrated lesson in LESSONS-LEARNED.md with a merge note.
-6. Update the index and run validation checks.
+2. Map each candidate to target file, section.
+3. Draft exact edit (concise rule or example).
+4. Apply edit with attribution comment.
+5. Archive migrated lesson in LESSONS-LEARNED.md with merge note.
+6. Update index; run validation checks.
 
 ## Merge Protocol
 
@@ -58,9 +58,33 @@ Move merged lessons to `## Archived (Merged)` at the bottom of `LESSONS-LEARNED.
 
 Update `## Index by Category` in `LESSONS-LEARNED.md` to mark archived lessons.
 
-### Worked Example
+### Worked Example: LES-042 — MCP Tool Timeout
 
-See [REFERENCE.md](./REFERENCE.md) for a full worked merge example (LES-042: MCP tool timeout).
+**Source lesson** (cited 4×, severity high, 90 days old):
+> LES-042: MCP tool timeout causes silent failures — set explicit timeout, check return value
+
+**Draft:**
+```
+Lesson: LES-042 — MCP tool timeout
+Target: src/orchestrator/skills/orchestration-protocols/SKILL.md
+Section: Error Recovery Playbook
+Edit: Add row: | **MCP timeout** | Tool returns null/undefined after delay | Set explicit timeout (30s); check return value; retry once; fall back to CLI; log to DLQ | <!-- Merged from LES-042 -->
+```
+
+**Archive in `LESSONS-LEARNED.md`:**
+```markdown
+### LES-042: MCP tool timeout → Merged to `src/orchestrator/skills/orchestration-protocols/SKILL.md` on 2026-05-18
+```
+
+### Automating the scan
+
+```sh
+# Find lessons cited 3+ times across sessions
+rg -c "LES-[0-9]+" .opencastle/logs/events.ndjson | awk -F: '$2 >= 3 {print $1}'
+
+# Find lessons referenced in recent retries
+rg "retry.*LES-[0-9]+" .opencastle/logs/events.ndjson | rg -o "LES-[0-9]+" | sort | uniq -c | sort -rn | head -20
+```
 
 ## Quality Gates (validation checkpoints)
 

package/src/orchestrator/skills/observability-logging/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: observability-logging
-description: "Writes session logs, records delegation decisions, and tracks review/dispute outcomes in NDJSON format. Use when logging session activity, recording audit trails, or running pre-response verification checklists."
+description: "Logs sessions, tracks activity, records delegation decisions, and stores review/dispute outcomes as NDJSON audit trails. Use when logging session activity, tracking work, recording decisions, building audit trails, capturing delegation history, or running pre-response verification checklists. Trigger terms: log, track activity, audit trail, session record, delegation log, NDJSON"
 ---
 
 # Observability Logging
 
-> **⛔ HARD GATE.** Every agent MUST log every session to `events.ndjson` before responding. No exceptions. A session without logs is a failed session.
+> **⛔ HARD GATE.** Every agent MUST log every session to `events.ndjson` before responding. No exceptions. Session without logs is a failed session.
 
 | File | Event types | Who | When |
 |------|------------|-----|------|
@@ -22,7 +22,7 @@ opencastle log --type session --agent Developer --model claude-opus-4-6 \
   --files_changed 3 --retries 0
 ```
 
-**Delegation** (Team Lead — immediately after each delegation, not at session end):
+**Delegation** (Team Lead, after each delegation — never batched):
 ```sh
 opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
   --model claude-sonnet-4-6 --tier quality --mechanism sub-agent \
@@ -32,7 +32,7 @@ opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
 
 > `model` and `tier` must reflect the delegated agent's assignment from the agent registry.
 
-**Review** (Team Lead — immediately after each fast review):
+**Review** (Team Lead, after each fast review):
 ```sh
 opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
   --reviewer_model gpt-5-mini --verdict pass --attempt 1 \
@@ -40,7 +40,7 @@ opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
   --confidence high --escalated false --duration_sec 45
 ```
 
-**Panel** (Panel runner — immediately after each panel vote):
+**Panel** (Panel runner, after each vote):
 ```sh
 opencastle log --type panel --panel_key auth-review --verdict pass \
   --pass_count 3 --block_count 0 --must_fix 0 --should_fix 3 \
@@ -48,7 +48,7 @@ opencastle log --type panel --panel_key auth-review --verdict pass \
   --tracker_issue PRJ-42 --artifacts_count 5
 ```
 
-**Dispute** (Team Lead — immediately after each dispute):
+**Dispute** (Team Lead, after each dispute):
 ```sh
 opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
   --priority high --trigger panel-3x-block --implementing_agent Developer \
@@ -66,11 +66,6 @@ Verify any append: `tail -1 .opencastle/logs/events.ndjson`
 - [ ] **Delegations logged** — `delegation` record per delegation (Team Lead) (if applicable)
 - [ ] **Reviews logged** — `review` record per fast review (if applicable)
 
-## Universal Agent Rules
-
-1. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting; add lessons after retries via **self-improvement** skill.
-2. **Log every session** — See [logging-mandatory](../../snippets/logging-mandatory.md).  
-
 ## Base Output Contract
 
 > Inherits: [base-output-contract](../../snippets/base-output-contract.md)

package/src/orchestrator/skills/orchestration-protocols/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: orchestration-protocols
-description: "Coordinates multiple agents with parallel task spawning, health monitoring, circuit breakers, and escalation paths. Use when managing parallel agents, handling agent timeouts, orchestrate agents, run tasks in parallel, concurrent agent execution, or fan-out tasks. Use when coordinating multi-agent task delegation."
+description: "Coordinate multiple agents: parallel spawning, health monitoring, circuit breakers, escalation. Use for parallel agents, agent timeouts, fan-out tasks, multi-agent delegation."
 ---
 
 # Orchestration Protocols
 
-Runtime patterns for managing delegated agents.
+Runtime patterns for delegated agents.
 
 ## Active Steering
 
-Intervene early when you spot:
+Intervene early on:
 
 | Signal | Action |
 |--------|--------|
@@ -19,11 +19,11 @@ Intervene early when you spot:
 | Circular behavior | Halt; switch approach |
 | Intent misunderstanding | Clarify prompt; re-delegate |
 
-When redirecting, explain *why* and *how*:
+When redirecting, explain *why* + *how*:
 
 > "Don't modify `libs/data/src/lib/product.ts` — shared across features. Add the new query in `libs/data/src/lib/reviews.ts`."
 
-**Sub-agents:** Catch problems early (5 min in can save an hour). **Background agents:** Steer post-hoc — invest in prompt specificity and partition constraints upfront.
+**Sub-agents:** Catch problems early (5 min in saves an hour). **Background agents:** Steer post-hoc — invest in prompt specificity, partition constraints upfront.
 
 ## Background Agents
 
@@ -31,18 +31,18 @@ Run autonomously in isolated Git worktrees. Reserve for well-scoped tasks >5 min
 
 - **Spawn:** Delegate Session → Background → Select agent → Enter prompt
 - **Auto-compaction:** At 95% token limit; use `--resume` to continue
-- **No real-time monitoring:** Invest in specific prompts, strict partition constraints, and acceptance criteria checklists upfront
+- **No real-time monitoring:** Invest in specific prompts, strict partition constraints, acceptance criteria checklists upfront
 
 ## Parallel Research Protocol
 
-Spawn multiple research sub-agents in parallel when 3+ independent questions must be answered before implementation. **Spawn if:** ≥3 independent questions AND answers span multiple codebase areas — otherwise handle sequentially.
+Spawn multiple research sub-agents in parallel when 3+ independent questions need answers before implementation. **Spawn if:** ≥3 independent questions AND answers span multiple codebase areas — else handle sequentially.
 
 ### Spawn Strategy
 
 | Rule | Detail |
 |------|--------|
 | Divide by topic/area | Each researcher owns a coherent domain |
-| Max 3–5 researchers | More creates diminishing returns and token waste |
+| Max 3–5 researchers | More: diminishing returns, token waste |
 | Focused scope per agent | Explicit dirs, file patterns, or questions |
 | Economy/Standard tier | Manage cost for research sub-agents |
 
@@ -56,21 +56,21 @@ Return: key findings, relevant file paths (with line numbers), patterns, unanswe
 ### Result Merge Protocol
 
 1. Collect all results into single context
-2. **Checkpoint:** verify every researcher returned a result (no timeout or error); re-run any that failed before proceeding.
+2. **Checkpoint:** verify every researcher returned a result (no timeout/error); re-run failures before proceeding.
 3. Deduplicate (same file/pattern counts once)
 4. Resolve conflicts — specific evidence beats general observations
 5. Synthesize into concise context block for implementation prompts
-6. **Checkpoint:** confirm synthesized block covers every original question; mark any unanswered questions as blockers.
+6. **Checkpoint:** confirm synthesized block covers every original question; mark unanswered as blockers.
 
 ## Batch Reviews
 
 - Group by domain (UI, data); run fast reviews in parallel for independent outputs
-- Review sequentially when outputs share the same partition boundary
-- Combine related artifacts into one panel question when they share acceptance criteria
+- Review sequentially when outputs share partition boundary
+- Combine related artifacts into one panel question when sharing acceptance criteria
 
 ## Context Compaction
 
-Summarize prior phase output before passing to the next agent. **Extract:** files changed, key decisions, verification (pass/fail), blockers. **Discard:** raw tool output, reasoning traces, failed attempts.
+Summarize prior phase output before passing to next agent. **Extract:** files changed, key decisions, verification (pass/fail), blockers. **Discard:** raw tool output, reasoning traces, failed attempts.
 
 **Template:**
 ```
@@ -94,12 +94,12 @@ Summarize prior phase output before passing to the next agent. **Extract:** file
 
 ## Health & Recovery Reference
 
-Detailed Agent Health Monitoring, Error Recovery Playbook, and Agent Circuit Breaker tables have been moved to REFERENCE.md to keep this skill concise. See REFERENCE.md in this directory for thresholds, recovery steps, and escalation flows.
+Agent Health Monitoring, Error Recovery Playbook, Circuit Breaker tables moved to REFERENCE.md. See REFERENCE.md for thresholds, recovery steps, escalation flows.
 
 
 ### CLI examples (spawn & monitor)
 
-These use the OpenCastle CLI (`npx opencastle` or `bin/cli.mjs`):
+Use OpenCastle CLI (`npx opencastle` or `bin/cli.mjs`):
 
 ```bash
 opencastle run --file convoy.yml --dry-run

package/src/orchestrator/skills/panel-majority-vote/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: panel-majority-vote
-description: "Runs 3 isolated reviewer sub-agents and consolidates a PASS/BLOCK verdict by majority. Use when the user requests an independent review of code changes, pull requests, design documents, or release notes."
+description: "Runs 3 isolated reviewer sub-agents; consolidates PASS/BLOCK verdict by majority. Use when user requests independent review of code changes, pull requests, design documents, or release notes."
 ---
 
 # Skill: Panel majority vote
@@ -18,7 +18,7 @@ description: "Runs 3 isolated reviewer sub-agents and consolidates a PASS/BLOCK
 
 ## Procedure
 
-1. **Validate scope** — every artifact path is under `<runRoot>` and the list is sufficient to answer the question.
+1. **Validate scope** — every artifact path under `<runRoot>`; list sufficient to answer question.
 
 2. **Spawn 3 reviewers in parallel** — start three isolated subagents with identical prompts. Spawn 3 reviewers using `runSubagent` with identical prompts; each reviewer receives the same question, artifact list, and constraints but runs in isolation. Required reviewer output sections (no others): `VERDICT: PASS | BLOCK`, `MUST-FIX:`, `SHOULD-FIX:`, `QUESTIONS:`, `TEST IDEAS:`, `CONFIDENCE: low | med | high`.
 
@@ -48,9 +48,9 @@ jq -n --arg panel_key "run123-panel" --arg verdict "$verdict" --argjson pass_cou
 
 ## Notes
 
-- On BLOCK: change the underlying work and re-run; do not re-word the question.
+- On BLOCK: change underlying work; re-run; do not re-word question.
 - After 3 consecutive BLOCKs on the same panel key: create a dispute record per **team-lead-reference** § Dispute Protocol.
-- Model selection: use the same model for all 3 reviewers. See **team-lead-reference** for model routing.
+- Model selection: use same model for all 3 reviewers. See **team-lead-reference** for model routing.
 
 ## Related Resources
 

package/src/orchestrator/skills/performance-optimization/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: performance-optimization
-description: "Profiles and reduces frontend/backend costs: split bundles, optimize assets, apply caching, and fix Core Web Vitals regressions. Use when profiling Lighthouse/CI regressions, reducing bundle size, or fixing high CLS/LCP/TTI metrics."
+description: "Profiles, reduces frontend/backend costs: split bundles, optimize assets, apply caching, fix Core Web Vitals regressions. Use when profiling Lighthouse/CI regressions, reducing bundle size, or fixing high CLS/LCP/TTI metrics."
 ---
 
 # Performance Optimization
 
 **Rule:** Measure first (`Chrome DevTools`, `Lighthouse`, `Datadog`), optimize second. Set budgets (load time, memory, API latency). Automate in CI/CD.
 
-Domain-specific patterns (rendering, JS, Node optimizations) are referenced in REFERENCE.md to keep this skill concise.
+Domain-specific patterns (rendering, JS, Node optimizations) referenced in REFERENCE.md to keep this skill concise.
 
 ## Patterns by Domain
 
@@ -55,15 +55,15 @@ export default function List({items}){
 
 ## Profiling Workflow (step-by-step)
 
-1. Run Lighthouse (or CI perf job) and record baseline.
+1. Run Lighthouse (or CI perf job); record baseline.
 	 - Checkpoint: failing metric(s) identified (LCP/CLS/FID/TTI).
 	 - Recovery: if noisy, reproduce locally with `--emulated-form-factor=mobile`.
 2. Profile with DevTools Profiler / React profiler or Node `clinic` for backend.
 	 - Checkpoint: hotspot call stacks / long tasks located.
 3. Apply minimal fix (code-split, memoize, reduce payloads, defer non-critical work).
 	 - Checkpoint: targeted change reduces measured hotspot time in profiler.
-4. Re-run Lighthouse/CI perf job and compare; set threshold (e.g., 10% improvement or within budget).
-5. If regression persists, iterate and create a rollback plan; note fixes in changelog.
+4. Re-run Lighthouse/CI perf job; compare; set threshold (e.g., 10% improvement or within budget).
+5. If regression persists, iterate; create rollback plan; note fixes in changelog.
 
 ## Review Checklist
 

package/src/orchestrator/skills/project-consistency/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: project-consistency
-description: "Generates shared CSS variables, validates component naming conventions, and creates layout pattern templates. Use when coordinating a design system, theme, consistent styling, CSS variables, or a component library across parallel agents."
+description: "Generates shared CSS variables, validates component naming conventions, creates layout pattern templates. Use when coordinating design system, theme, consistent styling, CSS variables, or component library across parallel agents."
 ---
 
 # Project Consistency
 
-Ensure consistency by producing shared artifacts and automated checks before parallel work begins.
+Ensure consistency by producing shared artifacts, automated checks before parallel work begins.
 
 ## Foundation-First Principle
 
@@ -22,13 +22,13 @@ Phase 1 (sequential): create shared artifacts (tokens, Layout, UI components). P
 
 **Validation checkpoints:**
 1. Foundation complete: `tokens.css` has all palette/type/spacing vars, Layout renders, UI components compile.
-2. Per-page: `grep -r 'style={{' src/pages/` returns 0 hits (no inline styles). All imports resolve.
+2. Per-page: `grep -r .style={{. src/pages/` returns 0 hits (no inline styles). All imports resolve.
 
 ---
 
 ## Convoy Integration
 
-Phase 1 (sequential): foundation-setup creates tokens, Layout, UI library, and style guide brief. Phase 2 (parallel): every page task imports from Phase 1. Include these 5 references in every page prompt:
+Phase 1 (sequential): foundation-setup creates tokens, Layout, UI library, style guide brief. Phase 2 (parallel): every page task imports from Phase 1. Include these 5 references in every page prompt:
 
 ```
 1. Design tokens path   2. Layout path   3. UI components path