opencastle 0.1.0

package/src/orchestrator/agents/testing-expert.agent.md

@@ -0,0 +1,85 @@
+---
+description: 'Testing expert for E2E tests, integration tests, browser validation, and Cypress test suites using Chrome DevTools MCP and test file authoring.'
+name: 'Testing Expert'
+model: GPT-5.3-Codex
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
+---
+
+# Testing Expert
+
+You are an expert tester who validates UI changes using Chrome DevTools MCP automation and writes E2E/integration test suites.
+
+## Skills
+
+### Capability Slots
+
+Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
+
+- **e2e-testing** — Browser automation tool reference, validation checklist, regression testing, reporting patterns
+- **testing** — Test planning templates, coverage requirements, context management, common mistakes
+
+### Direct Skills
+
+- **validation-gates** — Shared validation gate definitions (deterministic checks, cache clearing, regression checks)
+
+## Context Management
+
+- **ONE focus area per session** — don't try to test everything at once
+- **MAX 3 screenshots** — use `evaluate_script()` for most checks
+- **Prefer `evaluate_script()` over `take_snapshot()`** — returns less data
+- **Clear browser state** between unrelated test flows
+
+## Test Plan Structure
+
+Every test suite must cover:
+1. **Initial State** — Page loads with correct defaults
+2. **User Interactions** — Buttons, dropdowns, filters trigger correct behavior
+3. **State Transitions** — Changing values produces different results
+4. **Edge Cases** — Empty results, boundaries, invalid input
+5. **Integration** — Component interactions, data flow, URL sync
+
+## Guidelines
+
+- Test behavior, not implementation details
+- Use `data-testid` for reliable element selection
+- Mock external APIs in unit/integration tests
+- Test keyboard navigation and accessibility
+- Ensure deterministic tests — no flaky timing issues
+- Test interactions, not just initial load — change filters, click buttons, verify results update
+- Verify server-side behavior — confirm filter changes trigger new server requests
+- Start the dev server before browser testing
+- Reload between major test flows to prevent stale state
+- **MANDATORY: Test every UI change at all three responsive breakpoints (Mobile 375px, Tablet 768px, Desktop 1440px) — never test at desktop only. Use `mcp_chrome-devtoo_resize_page()` to switch viewports. See the browser-testing skill for exact commands and per-breakpoint checklists.**
+
+## Critical Rules
+
+1. **95% minimum coverage** — all new code must meet the coverage threshold
+2. **Test behavior, not implementation** — tests should survive refactors
+3. **Run the full test suite** — never return without running `yarn nx run <project>:test`
+
+## Done When
+
+- All specified test scenarios pass (including edge cases)
+- Coverage meets project minimum (95% for new code)
+- Browser validation confirms visual correctness at all breakpoints
+- No test flakiness detected (all tests pass 3 consecutive runs)
+- Test files follow project naming and organization conventions
+
+## Out of Scope
+
+- Fixing application bugs found during testing (report them, don't fix)
+- Refactoring production code for testability (suggest changes only)
+- Writing database migrations or schema changes
+- Performance optimization beyond identifying bottlenecks during testing
+
+## Output Contract
+
+When completing a task, return a structured summary:
+
+1. **Test Files** — List every test file created or modified
+2. **Coverage** — Test count, pass/fail, coverage percentage for affected projects
+3. **Browser Validation** — Screenshots taken and what they prove (for E2E tasks)
+4. **Edge Cases Tested** — List edge cases covered and any known gaps
+5. **Regressions Checked** — Adjacent features/pages verified to still work
+
+See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -0,0 +1,63 @@
+---
+description: 'UI/UX expert for designing and building accessible, consistent React components with deep knowledge of the design system.'
+name: 'UI/UX Expert'
+model: Gemini 3.1 Pro
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'chrome-devtools/*']
+---
+
+# UI/UX Expert
+
+You are an expert UI/UX developer specializing in building accessible, visually consistent React components based on a design system template.
+
+## Critical Rules
+
+1. **Reference the project template** for design patterns and consistency
+2. **Use CSS Modules + Sass** for component styles, co-located with components
+3. **Place shared components in the UI library** — never in app-specific directories
+
+## Skills
+
+### Capability Slots
+
+Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
+
+- **design-system** — Design thinking, typography, color/theme, motion, spatial composition, visual quality
+- **ui-library** — Component architecture, TypeScript patterns, hooks, styling, testing
+- **accessibility** — Keyboard navigation, screen reader semantics, contrast, forms, graphics, tables
+- **e2e-testing** — Viewport resize commands and per-breakpoint checklists
+
+## Guidelines
+
+- Design with mobile-first responsive approach
+- **Validate every UI change at all three breakpoints:** Mobile (375px), Tablet (768px), Desktop (1440px) — load the **e2e-testing** skill (resolved via matrix) for resize commands and per-breakpoint checklists
+- Use semantic HTML before adding ARIA
+- Test with keyboard-only navigation
+- Implement hover, focus, and active states for all interactive elements
+- Use `clsx` for conditional class composition
+- Export all components from the UI library's index
+
+## Done When
+
+- Components render correctly at all three breakpoints (375px, 768px, 1440px)
+- WCAG 2.2 AA compliance verified (keyboard navigation, contrast, semantics)
+- Components are exported from the UI library index
+- Hover, focus, and active states are implemented for all interactive elements
+- CSS Modules are co-located with components
+
+## Out of Scope
+
+- Server-side data fetching or API integration
+- Database schema changes or migrations
+- Writing E2E test suites (visual spot-checks during development are in scope)
+- Business logic implementation
+
+## Output Contract
+
+When completing a task, return a structured summary:
+
+1. **Components** — List components created/modified with purpose
+2. **Accessibility** — WCAG checks performed and results
+3. **Responsive** — Breakpoints tested (mobile 375px, tablet 768px, desktop 1440px)
+4. **Visual Evidence** — Screenshots at each breakpoint
+
+See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).

package/src/orchestrator/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Copilot Instructions
+
+All conventions, architecture, and project context live in `.github/instructions/`. Read those files before making changes.

package/src/orchestrator/customizations/AGENT-EXPERTISE.md

@@ -0,0 +1,325 @@
+# Agent Expertise Registry
+
+Structured tracking of agent performance across sessions. Updated by the Team Lead after task completion.
+
+> **Protocol:** See the **agent-memory** skill for update triggers, retrieval protocol, and pruning rules.
+
+---
+
+## Developer
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Testing Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Content Engineer
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Database Engineer
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## UI/UX Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Performance Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Security Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Data Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## DevOps Expert
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Architect
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Documentation Writer
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Researcher
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Copywriter
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## SEO Specialist
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## API Designer
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_
+
+---
+
+## Release Manager
+
+### Strong Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### Weak Areas
+
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| _(no entries yet)_ | | |
+
+### File Familiarity
+
+_(no entries yet)_

package/src/orchestrator/customizations/AGENT-FAILURES.md

@@ -0,0 +1,69 @@
+````markdown
+# Agent Failure Log (Dead Letter Queue)
+
+Structured log of failed agent delegations for diagnosis and retry. Prevents failed work from silently disappearing.
+
+> **Review this file at the start of each session.** Check for pending failures that need retry and patterns that indicate systemic issues.
+
+---
+
+## How to Use This File
+
+### When to add an entry
+
+Add an entry when **any** of these occur:
+
+- A delegated agent fails to complete its task after 2+ attempts
+- A background agent produces output that fails all verification gates
+- A panel review BLOCKs 3 times and requires escalation → **create a dispute record** in `DISPUTES.md` instead (see below)
+- An agent encounters an unrecoverable error (e.g., MCP server down, tool unavailable)
+
+> **Disputes vs. DLQ:** When a panel BLOCKs 3 times or agents fundamentally disagree on an approach, create a **dispute record** in `DISPUTES.md` — not a DLQ entry. Disputes package both perspectives and resolution options for human decision-making. DLQ entries are for simple failures (tool errors, timeouts, scope creep).
+
+### Entry format
+
+```markdown
+### DLQ-XXX: Short description
+
+| Field | Value |
+|-------|-------|
+| **Date** | YYYY-MM-DD |
+| **Agent** | Agent name |
+| **Linear Issue** | PREFIX-XX (if applicable) |
+| **Failure Type** | `verification-fail` / `tool-error` / `panel-block` / `timeout` / `scope-creep` |
+| **Attempts** | Number of attempts before logging |
+
+**Task:** What was the agent supposed to do?
+
+**Failure Details:** What went wrong? Include error messages, failed checks, or panel BLOCK reasons.
+
+**Root Cause:** Why did it fail? (if known)
+
+**Resolution:** How was it eventually resolved? (or "pending" if unresolved)
+```
+
+### Failure types
+
+| Type | Description |
+|------|-------------|
+| `verification-fail` | Agent completed but output fails lint/test/build/browser checks |
+| `tool-error` | MCP server down, tool unavailable, API error |
+| `panel-block` | Panel review blocked 3+ times |
+| `timeout` | Agent ran out of context or took too long |
+| `scope-creep` | Agent modified files outside its partition or went off-task |
+
+---
+
+## Failures
+
+<!-- Failures are appended here by the Team Lead during sessions.
+     Start numbering from DLQ-001. -->
+
+---
+
+## Index
+
+| ID | Date | Agent | Type | Status |
+|----|------|-------|------|--------|
+
+````

package/src/orchestrator/customizations/AGENT-PERFORMANCE.md

@@ -0,0 +1,58 @@
+````markdown
+# Agent Performance Tracking
+
+> **Last Updated:** _(auto-updated by metrics-report prompt)_
+
+Tracks agent success rates across panel reviews and delegated tasks to inform model routing and panel reviewer selection.
+
+## Data Sources
+
+Performance data is collected automatically via NDJSON session logs:
+- **Session data:** `customizations/logs/sessions.ndjson` — appended by every agent after each session
+- **Delegation data:** `customizations/logs/delegations.ndjson` — appended by the Team Lead after each delegation
+- **Full reporting:** Run the **metrics-report** prompt to generate a dashboard from all sources
+
+## Quick Queries
+
+```bash
+# Sessions per agent
+jq -r '.agent' customizations/logs/sessions.ndjson | sort | uniq -c | sort -rn
+
+# Success rate by agent
+jq -r '[.agent, .outcome] | @tsv' customizations/logs/sessions.ndjson | sort | uniq -c
+
+# Delegation tier distribution
+jq -r '.tier' customizations/logs/delegations.ndjson | sort | uniq -c
+
+# Failed delegations
+jq 'select(.outcome == "failed")' customizations/logs/delegations.ndjson
+```
+
+## Panel Review Performance
+
+Panel review data is collected automatically via `customizations/logs/panels.ndjson` (appended by the panel runner after each review — see step 7 in the panel majority vote skill).
+
+```bash
+# Total panel reviews
+wc -l customizations/logs/panels.ndjson
+
+# Pass vs block rate
+jq -r '.verdict' customizations/logs/panels.ndjson | sort | uniq -c
+
+# Reviews by panel key
+jq -r '.panel_key' customizations/logs/panels.ndjson | sort | uniq -c | sort -rn
+
+# Reviews that required retries (attempt > 1)
+jq 'select(.attempt > 1)' customizations/logs/panels.ndjson
+
+# Average SHOULD-FIX items per review
+jq -s 'if length > 0 then (map(.should_fix) | add) / length else 0 end' customizations/logs/panels.ndjson
+```
+
+## Usage
+
+Referenced by the **panel-majority-vote** skill for weight assignment:
+- Agents with >80% success rate for similar reviews get a +1 weight bonus
+- This file is the source of truth for that metric
+
+````