opencastle 0.1.0

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

@@ -0,0 +1,134 @@
+---
+name: testing-workflow
+description: "Comprehensive testing workflow including test planning, unit/integration/E2E testing patterns, coverage requirements, and common testing mistakes. Use when writing tests, planning test strategies, or validating feature completeness."
+---
+
+# Testing Workflow
+
+## Core Principles
+
+- Test implementations thoroughly before claiming completion.
+- Every feature must be validated through comprehensive testing covering happy paths, edge cases, error conditions, and user interactions.
+- **Mandatory**: Every feature implementation must be tested in the browser using Chrome DevTools MCP automation before marking as complete.
+
+## E2E Testing Context Management
+
+**Problem:** Comprehensive E2E tests with Chrome MCP accumulate context that can exceed AI context limits (413 errors).
+
+**Rules:**
+1. **ONE suite per session** — never run all suites in one conversation.
+2. **MAX 3 screenshots** per session.
+3. **Use `evaluate_script()` over `take_snapshot()`** — returns less data.
+4. **Reload between major test flows** to clear state.
+5. **Log results separately** — append to `docs/testing/E2E-RESULTS.md`.
+
+### Suite Files
+
+See `project.instructions.md` for the full list of E2E test suite files.
+
+## Pre-Implementation Test Plan
+
+Before implementing any feature, create a plan covering:
+
+### 1. Initial State Tests
+- Page loads with default values.
+- Components render in expected initial state.
+
+### 2. User Interaction Tests
+- Buttons trigger expected actions.
+- Dropdowns respond to selection.
+- Filters update URL params and trigger data refetch.
+- Forms accept and validate input.
+
+### 3. State Transition Tests
+- Changing filter values produces different results.
+- Data updates on user interaction.
+- UI reflects backend state changes.
+- Loading states appear during async operations.
+
+### 4. Edge Case Tests
+- Empty results.
+- Maximum/minimum boundaries.
+- Invalid input handling.
+- Network errors and timeouts.
+
+### 5. Integration Tests
+- Component interactions work correctly.
+- Data flows from server to UI properly.
+- URL parameters sync with component state.
+- Server-side vs client-side filtering works.
+
+### 6. Responsive Breakpoint Tests (MANDATORY for UI changes)
+
+**Every UI feature must be tested at all three breakpoints** (Mobile 375px, Tablet 768px, Desktop 1440px). Most layout bugs only surface at mobile or tablet widths.
+
+> **Detailed breakpoint definitions, resize commands, and per-breakpoint checklists:** See the **browser-testing** skill. The **validation-gates** skill (Gate 3) defines the mandatory testing protocol.
+
+**Anti-pattern:** Testing only at desktop (or only at the default browser width) and assuming responsive classes work. Tailwind classes can be incorrect — always verify visually at every breakpoint.
+
+## Coverage Requirements
+
+### Unit Tests (Jest)
+- **Minimum 95% coverage** for all new code.
+- All exported functions, React components, custom hooks.
+- Edge cases and error conditions. Input validation.
+
+### Integration Tests
+- Component integration, data flow, state updates across boundaries.
+- URL synchronization.
+
+### E2E Tests (Browser Automation)
+- Complete user journeys. All interactive elements.
+- State transitions. Error handling. Performance.
+
+## Testing Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Testing only initial page load | Test filter changes, interactions, different results |
+| Assuming filters work because they render | Verify each filter option changes results |
+| Client-side only testing | Verify server requests triggered correctly |
+| Single scenario testing | Test urban, rural, edge of coverage, out of range |
+| Visual inspection only | Verify data values, counts, distances programmatically |
+
+## Comprehensive Testing Example
+
+```markdown
+### ✅ Correct Approach
+1. ✅ Load page with Prague coords (50.0755, 14.4378) → 3 places at 10km
+2. ✅ Change distance 10km → 100km → 5 places (added 2 at 44km, 83km)
+3. ✅ Change distance 100km → 25km → 3 places (removed beyond 25km)
+4. ✅ Rural coordinates (49.2, 15.5) → 0 places, auto-expanded to 100km
+5. ✅ Verified filter changes trigger new server requests
+```
+
+## Post-Implementation Browser Testing
+
+After completing any feature:
+
+1. Start dev server (see `project.instructions.md` for app/port details).
+2. Open browser to the dev URL.
+3. Test all critical user flows with Chrome DevTools MCP.
+4. Test edge cases (empty results, max/min values, errors).
+5. Document results with screenshots.
+
+### Verify Before Completion
+
+- [ ] Opened app in browser
+- [ ] Tested all interactive elements
+- [ ] Verified data changes match expectations
+- [ ] Checked edge cases
+- [ ] Confirmed empty states display correctly
+- [ ] **Tested at Mobile (375px), Tablet (768px), and Desktop (1440px) breakpoints**
+- [ ] **No horizontal overflow or layout breakage at any breakpoint**
+- [ ] Taken screenshots of key scenarios
+- [ ] Verified URL parameters are correct
+
+## Commands
+
+```bash
+yarn nx run <project>:test                 # Run tests
+yarn nx run <project>:test --coverage      # With coverage
+yarn nx run <project>:test -u              # Update snapshots
+yarn nx affected -t test                   # Affected tests
+```

package/src/orchestrator/skills/validation-gates/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: validation-gates
+description: "Shared validation gates for all orchestration workflows — deterministic checks, browser testing, cache management, regression checks. Referenced by prompt templates to maintain single source of truth."
+---
+
+# Validation Gates
+
+Canonical reference for validation gates shared across all orchestration workflows. Prompt templates reference this skill to avoid duplication.
+
+## Gate 1: Deterministic Checks
+
+Run for every affected NX project:
+
+```bash
+yarn nx run <project>:lint --fix
+yarn nx run <project>:test
+yarn nx run <project>:build
+```
+
+All must pass with zero errors. Run for **every** project that consumed modified files, not just the primary project.
+
+## Gate 1.5: Fast Review (MANDATORY)
+
+> **HARD GATE:** Every agent delegation output must pass fast review before acceptance. This is non-negotiable — even for overnight/unattended runs. Load the **fast-review** skill for the full procedure.
+
+After deterministic checks (Gate 1) pass:
+
+1. **Spawn a single reviewer sub-agent** with the review prompt from the fast-review skill
+2. **On PASS** — proceed to remaining gates
+3. **On FAIL** — re-delegate to the same agent with reviewer feedback (up to 2 retries)
+4. **On 3x FAIL** — escalate to panel review (Gate 5)
+
+The reviewer validates: acceptance criteria met, file partition respected, no regressions, type safety, error handling, security basics, and edge cases.
+
+**Auto-PASS conditions** (skip the reviewer sub-agent):
+- Pure research/exploration with no code changes
+- Only `.md` files were modified
+- All deterministic gates passed AND the change is ≤10 lines across ≤2 files
+
+## Gate 2: Cache Clearing (BEFORE Browser Testing)
+
+**Always clear before testing.** Testing stale code wastes time and produces false results.
+
+```bash
+rm -rf apps/<app>/.next
+yarn nx reset
+```
+
+Run these commands before starting the dev server for browser testing.
+
+## Gate 3: Browser Testing (MANDATORY for UI Changes)
+
+> **HARD GATE:** A task with UI changes is NOT done until you have screenshots in Chrome proving the feature works. "The code looks correct" is not proof. "Tests pass" is not proof. Only a screenshot of the working UI in Chrome is proof.
+
+1. **Start the dev server** — `yarn nx run <app>:serve` — wait for it to be ready
+2. **Navigate to affected pages** — Verify the new feature renders correctly
+3. **Verify SPECIFIC features** — Check every feature listed in the acceptance criteria. If the criteria say "icons, groups, and AND/OR toggle", you must see all three in the browser
+4. **Test interactions** — Click buttons, fill forms, toggle filters, submit data
+5. **Test responsive** — Resize to mobile (375px), tablet (768px), desktop (1440px)
+6. **Test edge cases** — Empty states, error states, loading states, long content
+7. **Screenshot evidence (REQUIRED)** — Take screenshots of key states. These are mandatory proof
+
+> **Anti-pattern:** Testing only at desktop width and assuming Tailwind classes work. They can be wrong — always verify at all three breakpoints.
+
+Load the **browser-testing** skill for Chrome MCP commands, breakpoint details, and reporting format.
+
+## Gate 4: Regression Testing
+
+New features must not break existing functionality:
+
+1. **Run full test suite** for affected projects — not just the new tests
+2. **Browser-test adjacent pages** — If you changed a shared component, test pages that use it
+3. **Verify navigation** — Ensure routing, links, and back-button behavior still work
+4. **Check shared components** — If a component from a shared library was modified, test it in all apps that consume it
+
+## Gate 5: Panel Review (High-Stakes Only)
+
+Use the **panel-majority-vote** skill for:
+
+- Security-sensitive changes (auth flows, RLS policies, API endpoints)
+- Database migrations that alter production data or schema
+- Architecture decisions or large refactors affecting multiple libraries
+- Complex business logic without comprehensive test coverage
+
+If the panel returns BLOCK, extract MUST-FIX items, re-delegate to the same agent, and re-run the panel. Never skip, never halt. Max 3 attempts, then escalate to Architect.
+
+## Universal Completion Checklist
+
+Use this checklist for any orchestration workflow:
+
+- [ ] Lint, test, and build pass for all affected projects
+- [ ] **Fast review passed** (mandatory — load **fast-review** skill)
+- [ ] Dev server started with **clean cache** (`rm -rf .next && yarn nx reset`)
+- [ ] UI changes verified in Chrome with screenshots at all breakpoints
+- [ ] Every acceptance criteria item visually confirmed — not just "page loads"
+- [ ] No regressions in adjacent functionality
+- [ ] Shared code changes tested across all consuming apps
+- [ ] No duplicated code — shared logic extracted to libraries
+- [ ] Lessons learned captured if any retries occurred
+- [ ] Known issues updated if new limitations were discovered