opencastle 0.32.11 → 0.32.13

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

@@ -0,0 +1,113 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Frontend Design Components
+
+Extended component patterns, card variants, and hero animations for the **frontend-design** skill.
+
+## Design Tokens (starter)
+
+```css
+:root {
+	--color-bg: #0f1724;
+	--color-ink: #e6eef8;
+	--color-accent: #ff7a59;
+	--space-1: 4px;
+	--space-2: 8px;
+	--space-3: 16px;
+	--radius-1: 6px;
+}
+```
+
+## Entrance Animation (starter)
+
+```css
+@keyframes fadeUp {
+	from { opacity: 0; transform: translateY(8px); }
+	to   { opacity: 1; transform: translateY(0); }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.fade-in-up { animation: fadeUp 420ms cubic-bezier(.2,.9,.2,1) both; }
+}
+```
+
+## Card Patterns
+
+### Glass Card
+
+```css
+.card-glass {
+	background: rgba(255, 255, 255, 0.05);
+	backdrop-filter: blur(12px);
+	border: 1px solid rgba(255, 255, 255, 0.1);
+	border-radius: var(--radius-1);
+	padding: var(--space-3);
+}
+```
+
+### Elevated Card
+
+```css
+.card-elevated {
+	background: var(--color-bg);
+	border-radius: var(--radius-1);
+	padding: var(--space-3);
+	box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12);
+	transition: transform 200ms ease, box-shadow 200ms ease;
+}
+.card-elevated:hover {
+	transform: translateY(-2px);
+	box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
+}
+```
+
+## Hero Animations
+
+### Staggered Fade-In
+
+```css
+.hero-stagger > * {
+	opacity: 0;
+	transform: translateY(12px);
+	animation: fadeUp 500ms cubic-bezier(.2,.9,.2,1) forwards;
+}
+.hero-stagger > *:nth-child(1) { animation-delay: 0ms; }
+.hero-stagger > *:nth-child(2) { animation-delay: 80ms; }
+.hero-stagger > *:nth-child(3) { animation-delay: 160ms; }
+```
+
+### Gradient Shift
+
+```css
+.hero-gradient {
+	background: linear-gradient(135deg, var(--color-accent), var(--color-bg));
+	background-size: 200% 200%;
+	animation: gradientShift 6s ease infinite;
+}
+@keyframes gradientShift {
+	0%, 100% { background-position: 0% 50%; }
+	50% { background-position: 100% 50%; }
+}
+```
+
+## Button Variants
+
+```css
+.btn-primary {
+	background: var(--color-accent);
+	color: #fff;
+	padding: var(--space-2) var(--space-3);
+	border-radius: var(--radius-1);
+	font-weight: 600;
+	transition: opacity 150ms ease;
+}
+.btn-primary:hover { opacity: 0.9; }
+
+.btn-ghost {
+	background: transparent;
+	color: var(--color-ink);
+	border: 1px solid currentColor;
+	padding: var(--space-2) var(--space-3);
+	border-radius: var(--radius-1);
+}
+```

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

@@ -0,0 +1,36 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Frontend Design REFERENCE: detailed principles, typography catalogue, tokens, and component patterns.
+
+Last Updated: 2026-03-31
+
+## Design Principles (extended)
+
+| Dimension | Rule |
+|-----------|------|
+| Direction | Pick an extreme aesthetic (brutally minimal, maximalist, retro-futuristic, luxury, brutalist, art deco, editorial…) and commit fully. Name it in 2–3 words. |
+| Typography | Characterful display+body pair. No Inter/Roboto/Arial. `clamp()` fluid scale; heading lh ~1.1–1.2, body lh ~1.5–1.7; letter-spacing on uppercase/small. |
+| Color | CSS vars only; dominant + sharp accent hierarchy; WCAG AA (4.5:1 body, 3:1 large); dark/light both intentional. |
+| Motion | CSS-only for HTML; Motion library for React; staggered page entrance; custom easing; `prefers-reduced-motion` fallback. |
+| Layout | Asymmetry, overlap, diagonal flow, grid-breaking. Consistent spacing tokens — no ad-hoc values. Holds at mobile/tablet/desktop. |
+| Atmosphere | Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows. No purple-on-white defaults. |
+
+## Typography Pairings (catalogue)
+
+| Aesthetic | Display | Body | Mood |
+|-----------|---------|------|------|
+| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich |
+| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp grotesque |
+| Warm humanist | Fraunces | Nunito Sans | Friendly, approachable |
+| Brutalist edge | Monument Extended | JetBrains Mono | Raw technical power |
+| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic |
+| Retro-futuristic | Syne | Outfit | Geometric boldness |
+
+## Tokens & Patterns
+
+See `COMPONENTS.md` for tokens and component code snippets. This reference holds the rationale and extended examples used across projects.
+
+## Usage
+
+- Use these tables to choose a type system and enforce token fallbacks.
+- Link lessons and PRs that change foundational tokens to the `project-consistency` skill guidance.

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

@@ -1,111 +1,62 @@
 ---
 name: frontend-design
-description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics."
+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."
 license: Complete terms in LICENSE.txt
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
-## Design Principles
-
-| Dimension | Rule |
-|-----------|------|
-| Direction | Pick an extreme aesthetic (brutally minimal, maximalist, retro-futuristic, luxury, brutalist, art deco, editorial…) and commit fully. Name it in 2–3 words. |
-| Typography | Characterful display+body pair. No Inter/Roboto/Arial. `clamp()` fluid scale; heading lh ~1.1–1.2, body lh ~1.5–1.7; letter-spacing on uppercase/small. |
-| Color | CSS vars only; dominant + sharp accent hierarchy; WCAG AA (4.5:1 body, 3:1 large); dark/light both intentional. |
-| Motion | CSS-only for HTML; Motion library for React; staggered page entrance; custom easing; `prefers-reduced-motion` fallback. |
-| Layout | Asymmetry, overlap, diagonal flow, grid-breaking. Consistent spacing tokens — no ad-hoc values. Holds at mobile/tablet/desktop. |
-| Atmosphere | Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows. No purple-on-white defaults. |
+## Design Workflow
 
-**Every design must have one unforgettable detail.** No two designs should look alike.
+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
+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
+5. **Validate** — run Quality Checklist below; fix any failing item before marking done
 
-## Design System Foundations
+### Quick-start example
 
 ```css
+/* Aesthetic: minimal neon */
 :root {
-  --color-ink:     #1a1614;  --color-paper:   #f5f0e8;
-  --color-accent:  #c8e630;  --color-muted:   #9b9083;
-  --color-surface: #eae3d8;  --color-border:  rgba(26, 22, 20, 0.08);
-
-  --text-sm:   clamp(0.875rem, 0.83rem + 0.22vw, 1rem);
-  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
-  --text-xl:   clamp(1.563rem, 1.35rem + 1.06vw, 2rem);
-  --text-2xl:  clamp(1.953rem, 1.6rem + 1.77vw, 2.75rem);
-  --text-hero: clamp(2.441rem, 1.8rem + 3.2vw, 4.5rem);
-
-  --space-2: 0.5rem; --space-4: 1rem;  --space-6: 1.5rem;
-  --space-8: 2rem;   --space-16: 4rem; --space-32: 8rem;
-
-  --ease-out-expo:    cubic-bezier(0.16, 1, 0.3, 1);
-  --ease-in-out-back: cubic-bezier(0.68, -0.6, 0.32, 1.6);
-  --duration-fast: 150ms; --duration-normal: 300ms; --duration-slow: 600ms;
-
-  --shadow-md: 0 4px 16px rgba(26, 22, 20, 0.08);
-  --shadow-lg: 0 12px 48px rgba(26, 22, 20, 0.12);
-}
-```
-
-## Component Patterns
-
-**Card:**
-```css
-.card {
-  position: relative;
-  background: var(--color-paper);
-  border: 1px solid var(--color-border);
-  border-left: 4px solid var(--color-accent);
-  padding: var(--space-8) var(--space-6);
-  transition: transform var(--duration-normal) var(--ease-out-expo),
-              box-shadow var(--duration-normal) var(--ease-out-expo);
-}
-.card:hover { transform: translateY(-3px); box-shadow: var(--shadow-lg); }
-.card__label {
-  position: absolute; top: calc(-1 * var(--space-3)); left: var(--space-4);
-  background: var(--color-accent); color: var(--color-ink);
-  font-size: var(--text-xs); font-weight: 700;
-  letter-spacing: 0.08em; text-transform: uppercase;
-  padding: var(--space-1) var(--space-3);
+  --color-bg: #0a0a0f; --color-surface: #141420;
+  --color-text: #e8e6e3; --color-accent: #6366f1;
+  --space-sm: 8px; --space-md: 16px; --space-lg: 32px;
+  --radius-md: 8px;
+  --font-heading: 'Fraunces', 'Georgia', serif;
+  --font-body: 'Inter', system-ui, sans-serif;
 }
-```
-
-**Hero staggered reveal:**
-```css
-@keyframes rise {
-  from { opacity: 0; transform: translateY(24px); }
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(12px); }
   to   { opacity: 1; transform: translateY(0); }
 }
-.hero           { overflow: hidden; padding: var(--space-32) var(--space-8); }
-.hero__eyebrow  { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 100ms; }
-.hero__headline { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 250ms; }
-.hero__body     { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 400ms; }
-.hero__cta      { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 550ms; }
+@media (prefers-reduced-motion: no-preference) {
+  .hero__title { animation: fade-up 0.4s ease-out both; }
+}
 ```
 
-## Typography Pairings
-
-| Aesthetic | Display | Body | Mood |
-|-----------|---------|------|------|
-| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich |
-| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp grotesque |
-| Warm humanist | Fraunces | Nunito Sans | Friendly, approachable |
-| Brutalist edge | Monument Extended | JetBrains Mono | Raw technical power |
-| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic |
-| Retro-futuristic | Syne | Outfit | Geometric boldness |
+Card patterns, hero animations, and extended token sets are in [COMPONENTS.md](./COMPONENTS.md).
 
-Include a metric-preserving fallback chain (e.g., `'Fraunces', 'Georgia', serif`).
+## Design Principles
 
-## Quality Checklist
+High-level design principles and the full set of example constraints live in [REFERENCE.md](./REFERENCE.md). Keep this checklist as a short reminder:
 
-**Identity:** aesthetic named in 2–3 words · color/type/space/motion tell one story · one memorable detail
+- 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.
 
-**Typography:** display+body pair distinct · `clamp()` fluid scale · heading lh ~1.1–1.2 / body lh ~1.5–1.7 · letter-spacing on uppercase/small
+**Every design must have one unforgettable detail.** No two designs should look alike.
 
-**Color:** CSS vars only · dominant+accent hierarchy · WCAG AA (4.5:1 body, 3:1 large) · dark/light both intentional
+## Typography Pairings
 
-**Layout:** spacing tokens throughout · one grid-breaking element · responsive at mobile/tablet/desktop
+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`).
 
-**Motion:** coordinated entrance sequence · hover/focus on all interactives · custom easing curves · `prefers-reduced-motion` fallback
+> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.
 
-**Production:** no hardcoded widths · `alt`/`aria-hidden` on images · visible focus indicators · no scroll-animation layout thrashing
+### Quality Checklist (quick)
 
-> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.
+- **Contrast:** Text ≥4.5:1 body, ≥3:1 large.
+- **Tokens:** All spacing/colors in `:root` tokens; avoid ad-hoc values.
+- **Responsiveness:** Layouts break at defined tokens; no overflow at mobile sizes.
+- **Motion:** `prefers-reduced-motion` respected; key animations <500ms.
+- **Accessibility:** Keyboard focus states visible; semantic HTML used.

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

@@ -1,6 +1,6 @@
 ---
 name: git-workflow
-description: "Git branching, PR workflow, delivery requirements, discovered issues 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, and task tracking conventions. Load when committing, pushing, or opening PRs."
 ---
 
 # Git Workflow & Delivery

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

@@ -0,0 +1,20 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Memory Merger Reference
+
+### Worked Example: LES-042 — MCP Tool Timeout
+
+**Lesson:** `LES-042: MCP tool timeout causes silent failures — always set explicit timeout and check return value` (cited 4×, severity high, 90 days old)
+
+**Draft:**
+```
+Lesson: LES-042 — MCP tool timeout
+Target: .github/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 -->
+```
+
+**After merge in target file**, archive in LESSONS-LEARNED.md:
+```markdown
+### LES-042: MCP tool timeout → Merged to `.github/skills/orchestration-protocols/SKILL.md` on 2026-03-15
+```

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

@@ -1,49 +1,34 @@
 ---
 name: memory-merger
-description: "Protocol for graduating mature lessons from LESSONS-LEARNED.md into permanent instruction and skill files. Closes the self-improvement loop by codifying validated knowledge at the source level."
+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."
 ---
 
 # Memory Merger
 
-Promotes validated lessons from `.opencastle/LESSONS-LEARNED.md` into instruction/skill files where they have permanent impact.
 
-## When to Run
+## Run Criteria
 
-| Trigger | Threshold |
-|---------|-----------|
-| File size | >50 entries |
-| Citation count | Cited 3+ times |
-| Age | >60 days old |
+Combined signals to identify merge candidates.
+
+| Criterion | Signal / Threshold |
+|-----------|--------------------|
+| File size | LESSONS-LEARNED.md > 50 entries |
+| Citation count | Cited 3+ times across sessions |
+| Age | >60 days and still relevant |
 | Category cluster | 5+ lessons in same category |
-| Discretionary | Lessons file feels stale |
+| Severity | Marked `high` or blocking |
+| Discretionary | Curator / maintainer judgement (stale file) |
 
-## Merge Protocol
+## 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.
 
-### 1 — Scan Candidates
-
-| Criterion | Signal |
-|-----------|--------|
-| Frequency | Cited/re-discovered 3+ times |
-| Severity | Marked `high` |
-| Age | >60 days, still relevant |
-| Concentration | 5+ in same category → extract pattern |
-| Tool-specific | MCP tool, codebase-tool command, or framework pattern |
-
-### 2 — Map to Target File
-
-| Category | Target |
-|----------|--------|
-| `task-management` | skill-matrix `task-management` slot |
-| `mcp-tools` | agent/skill that uses the tool |
-| `codebase-tool` | skill-matrix `codebase-tool` slot |
-| `cms` / `database` | respective skill-matrix slots |
-| `browser-testing` | skill-matrix `e2e-testing` slot |
-| `git-workflow` | `.github/skills/git-workflow/SKILL.md` |
-| `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
-| `delegation` | `.github/agents/team-lead.agent.md` or `team-lead-reference` skill |
-| `testing` | `.github/skills/testing-workflow/SKILL.md` |
-| `ui` / `framework` | `framework` slot or `react-development` skill |
-| Cross-cutting | `.github/instructions/general.instructions.md` |
+## Merge Protocol
 
 ### 3 — Draft Edit
 
@@ -73,12 +58,18 @@ Move merged lessons to `## Archived (Merged)` at the bottom of `LESSONS-LEARNED.
 
 Update `## Index by Category` in `LESSONS-LEARNED.md` to mark archived lessons.
 
-## Quality Gates
+### Worked Example
+
+See [REFERENCE.md](./REFERENCE.md) for a full worked merge example (LES-042: MCP tool timeout).
+
+## Quality Gates (validation checkpoints)
 
 - [ ] Merged content reads naturally (not copy-pasted)
-- [ ] No duplicate rules created
-- [ ] Archived lesson references target file
+- [ ] No duplicate rules created in target files or other skills
+- [ ] Archived lesson references target file and date
 - [ ] Core insight preserved — no loss of nuance
+- [ ] Target file still passes lint/markdown checks (if applicable)
+- [ ] A quick smoke verification (search for relevant keyword) confirms merge applied
 
 ## Anti-Patterns
 

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

@@ -1,6 +1,6 @@
 ---
 name: observability-logging
-description: "Session logging, delegation records, review/panel/dispute NDJSON logging, pre-response checklists. Load before responding to verify all logs are written."
+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."
 ---
 
 # Observability Logging
@@ -62,21 +62,14 @@ Verify any append: `tail -1 .opencastle/logs/events.ndjson`
 **⛔ STOP.** Verify before responding — fix any missing log NOW.
 
 - [ ] **Lessons read** — `.opencastle/LESSONS-LEARNED.md` read at session start
-- [ ] **Lessons captured** — new lesson added via **self-improvement** if any retry occurred
-- [ ] **Discovered issues tracked** — pre-existing bugs added to `KNOWN-ISSUES.md` or tracker
-- [ ] **Lint/type/test pass** — no new errors after code changes
 - [ ] **Session logged** — `events.ndjson` has a `session` record (ALWAYS)
-- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead)
-- [ ] **Reviews logged** — `review` record per fast review (if any)
-- [ ] **Panels logged** — `panel` record per panel vote (if any)
-- [ ] **Disputes logged** — `dispute` record per dispute (if any)
+- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead) (if applicable)
+- [ ] **Reviews logged** — `review` record per fast review (if applicable)
 
 ## Universal Agent Rules
 
-1. **Never delegate** — complete own work; document cross-domain needs in output contract.
-2. **Follow Discovered Issues Policy** — See [discovered-issues-policy](../../snippets/discovered-issues-policy.md).
-3. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting; add lessons after retries via **self-improvement** skill.
-4. **Log every session** — See [logging-mandatory](../../snippets/logging-mandatory.md).
+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
 

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

@@ -0,0 +1,42 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Agent Health Monitoring
+
+### Health Signals
+
+| Signal | Threshold | Recovery |
+|--------|-----------|----------|
+| **Stuck** — no output/changes | Sub: 5 min / BG: 15 min | Nudge; if frozen, abort + re-delegate with simpler scope |
+| **Looping** — same error repeated | 3 consecutive failures | Abort; add context; re-delegate with explicit fix path |
+| **Scope creep** — files outside partition | Any | Redirect: "Only modify files in [partition]. Revert [file]." |
+| **Context exhaustion** — confused/repetitive | Visible instruction amnesia | Checkpoint, end session, resume in fresh context |
+| **Permission loop** — waiting for input | 2+ prompts without progress | Auto-approve if safe; abort + re-delegate |
+
+**Cadence:** Sub-agents — continuous (real-time). Background agents — check at 10 min, then every 10 min. Always review full diff before accepting.
+
+### Escalation Path
+
+1. **Failure 1:** Re-delegate with more specific prompt + error context
+2. **Failure 2:** Downscope (split into smaller pieces), re-delegate
+3. **Failure 3:** Log to `.opencastle/AGENT-FAILURES.md`; if 3× panel BLOCK or conflict, create dispute in `.opencastle/DISPUTES.md` (see **team-lead-reference** § Dispute Protocol)
+
+## Error Recovery Playbook
+
+| Failure | Symptom | Recovery |
+|---------|---------|----------|
+| **Retry loop** | Same command fails 3+ times | Abort; identify root cause; re-delegate with explicit fix; log lesson |
+| **MCP unavailable** | Tool connection/timeout errors | Check server; retry once; fall back to CLI; log to DLQ if critical |
+| **Broken BG output** | Lint/type/test errors on return | Fix inline if small; discard + re-delegate if fundamental; DLQ after 2 fails |
+| **Parallel merge conflict** | Two agents modified overlapping files | Accept complex side first; re-delegate simple side to adapt; log lesson |
+| **Context exhausted** | Confused/repetitive responses | Checkpoint; end session; resume with checkpoint; reduce parallel work |
+| **Post-merge test failure** | Tests pass alone but fail merged | Run affected tests; check import/state conflicts; delegate fix to likely cause |
+
+## Agent Circuit Breaker
+
+| Threshold | Action |
+|-----------|--------|
+| **2 failures** | Investigate: same error class? Model healthy? Prompt pattern? |
+| **3 failures** | Open circuit — stop delegating; reassign or escalate to user |
+| **Next session** | Half-open — resets; re-open + add lesson if fails again |
+
+Judgment-based, not a hard gate. 3 similar failures with the same error is more concerning than 3 unrelated failures.

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

@@ -1,11 +1,11 @@
 ---
 name: orchestration-protocols
-description: "Runtime orchestration patterns for the Team Lead: parallel research spawning, agent health monitoring, active steering, background agent management, Context Compaction, Agent Circuit Breaker, and escalation paths."
+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."
 ---
 
 # Orchestration Protocols
 
-Runtime patterns for managing delegated agents. **Load at:** Execution phase (Step 4+), when monitoring active agents or spawning parallel work.
+Runtime patterns for managing delegated agents.
 
 ## Active Steering
 
@@ -13,11 +13,11 @@ Intervene early when you spot:
 
 | Signal | Action |
 |--------|--------|
-| Failing tests/builds | Can't resolve dependency or breaks existing code |
-| Unexpected file changes | Files outside partition in diff |
-| Scope creep | Refactors code not in scope |
-| Circular behavior | Same failing approach retried without change |
-| Intent misunderstanding | Session log shows wrong prompt interpretation |
+| Failing tests/builds | Check dependency resolution; revert if builds break |
+| Unexpected file changes | Revert; enforce partition |
+| Scope creep | Redirect to scoped files only |
+| Circular behavior | Halt; switch approach |
+| Intent misunderstanding | Clarify prompt; re-delegate |
 
 When redirecting, explain *why* and *how*:
 
@@ -35,7 +35,7 @@ Run autonomously in isolated Git worktrees. Reserve for well-scoped tasks >5 min
 
 ## Parallel Research Protocol
 
-Spawn multiple research sub-agents in parallel when 3+ independent questions must be answered before implementation. **Use when:** 3+ independent research questions, broad codebase exploration, or multi-area analysis (frontend/backend/CMS). **Skip when:** single-file investigation, answer in one known location, sequential results, or fewer than 3 questions.
+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 Strategy
 
@@ -56,9 +56,11 @@ Return: key findings, relevant file paths (with line numbers), patterns, unanswe
 ### Result Merge Protocol
 
 1. Collect all results into single context
-2. Deduplicate (same file/pattern counts once)
-3. Resolve conflicts — specific evidence beats general observations
-4. Synthesize into concise context block for implementation prompts
+2. **Checkpoint:** verify every researcher returned a result (no timeout or error); re-run any that failed 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.
 
 ## Batch Reviews
 
@@ -80,43 +82,54 @@ Summarize prior phase output before passing to the next agent. **Extract:** file
 - Blockers: [none | list]
 ```
 
-## Agent Health Monitoring
+**Concrete example:**
+```
+### Prior Phase Output
+**Phase 2 — Researcher A — Find usages of `calculateTotal()`**
+- Files changed: none (read-only research)
+- Decisions: `calculateTotal` lives in `libs/cart/src/lib/total.ts`; new logic should live in `libs/cart/src/lib/discounts.ts`
+- Verification: lint ✅ | types ✅ | unit smoke test (cart total) ✅
+- Blockers: design question on rounding behavior (see `docs/rounding.md`)
+```
+
+## Health & Recovery Reference
 
-### Health Signals
+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.
 
-| Signal | Threshold | Recovery |
-|--------|-----------|----------|
-| **Stuck** — no output/changes | Sub: 5 min / BG: 15 min | Nudge; if frozen, abort + re-delegate with simpler scope |
-| **Looping** — same error repeated | 3 consecutive failures | Abort; add context; re-delegate with explicit fix path |
-| **Scope creep** — files outside partition | Any | Redirect: "Only modify files in [partition]. Revert [file]." |
-| **Context exhaustion** — confused/repetitive | Visible instruction amnesia | Checkpoint, end session, resume in fresh context |
-| **Permission loop** — waiting for input | 2+ prompts without progress | Auto-approve if safe; abort + re-delegate |
 
-**Cadence:** Sub-agents — continuous (real-time). Background agents — check at 10 min, then every 10 min. Always review full diff before accepting.
+### CLI examples (spawn & monitor)
 
-### Escalation Path
+These use the OpenCastle CLI (`npx opencastle` or `bin/cli.mjs`):
 
-1. **Failure 1:** Re-delegate with more specific prompt + error context
-2. **Failure 2:** Downscope (split into smaller pieces), re-delegate
-3. **Failure 3:** Log to `.opencastle/AGENT-FAILURES.md`; if 3× panel BLOCK or conflict, create dispute in `.opencastle/DISPUTES.md` (see **team-lead-reference** § Dispute Protocol)
+```bash
+opencastle run --file convoy.yml --dry-run
+opencastle run --file convoy.yml --verbose
+opencastle run --resume
+opencastle run --status
+opencastle run --retry-failed
+```
+
+**Post-run verification (copy-paste checks):**
 
-## Error Recovery Playbook
+```bash
+if [ $? -ne 0 ]; then
+  echo "opencastle run failed — inspect .opencastle/convoy.log" \
+	 && tail -n 200 .opencastle/convoy.log && exit 1
+fi
 
-| Failure | Symptom | Recovery |
-|---------|---------|----------|
-| **Retry loop** | Same command fails 3+ times | Abort; identify root cause; re-delegate with explicit fix; log lesson |
-| **MCP unavailable** | Tool connection/timeout errors | Check server; retry once; fall back to CLI; log to DLQ if critical |
-| **Broken BG output** | Lint/type/test errors on return | Fix inline if small; discard + re-delegate if fundamental; DLQ after 2 fails |
-| **Parallel merge conflict** | Two agents modified overlapping files | Accept complex side first; re-delegate simple side to adapt; log lesson |
-| **Context exhausted** | Confused/repetitive responses | Checkpoint; end session; resume with checkpoint; reduce parallel work |
-| **Post-merge test failure** | Tests pass alone but fail merged | Run affected tests; check import/state conflicts; delegate fix to likely cause |
+npx opencastle run --status
+
+grep -i "error\|failed" .opencastle/convoy.log || echo "no obvious errors in logs"
+```
 
-## Agent Circuit Breaker
+## Validation & Verification Checkpoints
 
-| Threshold | Action |
-|-----------|--------|
-| **2 failures** | Investigate: same error class? Model healthy? Prompt pattern? |
-| **3 failures** | Open circuit — stop delegating; reassign or escalate to user |
-| **Next session** | Half-open — resets; re-open + add lesson if fails again |
+| Phase | Check | Command / Action |
+|-------|-------|-----------------|
+| Pre-spawn | Inputs present (task, scope, ACs) | `test -s convoy.yml \|\| exit 1` |
+| During-run | Tail for fatal errors | `tail -F .opencastle/convoy.log \| grep -i "fatal\|error"` |
+| Pre-merge | All agents exited 0 | `jq -e '.agents[] \| .exit_code == 0' .opencastle/results.json` |
+| Output schema | Required fields present | `jq -e '.agents[] \| (.findings and .file_paths)' .opencastle/results.json` |
+| Post-merge | Lint + smoke tests pass | `npm run lint && npm test -- -t "smoke"` |
+| Blocker | Any failure | Block merge; reopen to original researcher(s) |
 
-Judgment-based, not a hard gate. 3 similar failures with the same error is more concerning than 3 unrelated failures.