opencastle 0.1.0

package/src/orchestrator/skills/nextjs-patterns/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: nextjs-patterns
+description: "Next.js App Router best practices for server/client components, routing, API routes, and project structure. Use when creating or modifying Next.js pages, layouts, route handlers, or Server Actions."
+---
+
+# Next.js Patterns (2025)
+
+## Project Structure
+
+- **Use `app/` directory** (App Router) for all routes.
+- Top-level: `app/`, `public/`, `lib/`, `components/`, `contexts/`, `styles/`, `hooks/`, `types/`.
+- Colocate files near where they're used.
+- **Route Groups**: parentheses `(admin)` — group without affecting URL.
+- **Private Folders**: underscore `_internal` — opt out of routing.
+- Feature folders for large apps: `app/dashboard/`, `app/auth/`.
+
+## Server and Client Components
+
+**Default: Server Components** — data fetching, heavy logic, non-interactive UI.
+
+**Client Components** — add `'use client'` at top. Use for interactivity, state, browser APIs.
+
+### Critical Rule
+
+**Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** This causes build/runtime errors.
+
+**Correct approach:**
+1. Move all client-only logic into a dedicated Client Component (`'use client'`).
+2. Import and use that Client Component directly in the Server Component.
+
+```tsx
+// Server Component
+import DashboardNavbar from '@/components/DashboardNavbar';
+
+export default async function DashboardPage() {
+  return (
+    <>
+      <DashboardNavbar /> {/* Client Component */}
+    </>
+  );
+}
+```
+
+## Component Practices
+
+- PascalCase for files/exports. camelCase for hooks.
+- Shared components in `components/`. Route-specific in route folder.
+- TypeScript interfaces for props. Explicit types and defaults.
+- Co-locate tests with components.
+
+## Naming Conventions
+
+- Folders: `kebab-case`.
+- Components: `PascalCase`. Hooks: `camelCase`. Assets: `kebab-case`.
+- Types/Interfaces: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
+
+## API Routes (Route Handlers)
+
+- Location: `app/api/` (e.g., `app/api/users/route.ts`).
+- Export async functions named after HTTP verbs (`GET`, `POST`, etc.).
+- Use Web `Request`/`Response` APIs. `NextRequest`/`NextResponse` for advanced features.
+- Dynamic segments: `[param]`.
+- Validate with Zod/Yup. Return appropriate status codes.
+- Protect sensitive routes with middleware or server-side session checks.
+
+## General Best Practices
+
+- TypeScript with `strict` mode.
+- ESLint with official Next.js config.
+- Secrets in `.env.local` — never committed.
+- Built-in Image and Font optimization.
+- Suspense and loading states for async data.
+- Avoid large client bundles — keep logic in Server Components.
+- Semantic HTML and ARIA attributes.
+- Do NOT create example/demo files unless explicitly requested.

package/src/orchestrator/skills/nx-workspace/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: nx-workspace
+description: "NX monorepo commands, conventions, code generation, and task running patterns. Use when running builds, tests, linting, code generation, or any development commands."
+---
+
+# NX Workspace
+
+## Commands
+
+### Testing
+
+```bash
+yarn nx run <project-name>:test
+yarn nx run <project-name>:test --coverage
+yarn nx run <project-name>:test -u              # Update snapshots
+yarn nx affected -t test                         # Affected tests only
+```
+
+### Linting
+
+```bash
+yarn nx run <project-name>:lint --fix
+yarn nx run <project-name>:lint-styles --fix     # CSS/SCSS
+yarn nx affected -t lint
+```
+
+### Building
+
+```bash
+yarn nx run <project-name>:build
+yarn nx affected -t build
+```
+
+### Serving
+
+```bash
+yarn nx run <project-name>:serve
+yarn nx run <project-name>:dev
+```
+
+### Code Generation
+
+```bash
+yarn nx generate <generator-name> --no-interactive
+yarn nx g <generator-name> --no-interactive
+```
+
+### Formatting
+
+```bash
+yarn nx format --fix
+```
+
+### Forbidden Commands
+
+```bash
+# NEVER use these:
+npm test | npm run test | npm run lint | npm run build
+npm run dev | npm start | npx jest | npx eslint
+jest --coverage | eslint --fix
+```
+
+## Requirements
+
+- **Minimum Coverage**: 95% for new components/functions.
+- **Coverage Reports**: `reports/coverage/jest/`.
+- **Code Linting**: Always use `--fix` flag.
+- **Style Linting**: `yarn nx run <project>:lint-styles --fix` for CSS/SCSS.
+
+## Best Practices
+
+1. Always use `yarn nx run <project-name>:<target>` format.
+2. Use `yarn nx affected -t <target>` for multi-project changes.
+3. Use exact project names from `project.json` files.
+4. NX automatically handles task caching and parallel execution.
+
+## NX MCP Server
+
+The NX MCP server provides tools for understanding and working with the workspace. Use these tools instead of guessing about workspace structure:
+
+| Tool | When to Use |
+|------|-------------|
+| `nx_workspace` | First — understand workspace architecture, get errors |
+| `nx_docs` | Configuration questions, best practices (always check before assuming) |
+| `nx_project_details` | Inspect a specific project's targets, config, and dependencies |
+| `nx_visualize_graph` | Visualize project/task dependency graphs |
+| `nx_generators` | List available generators (plugin + local) |
+| `nx_generator_schema` | Get schema details for a specific generator |
+| `nx_available_plugins` | Discover installable plugins when no existing generator fits |
+| `nx_current_running_tasks_details` | Monitor running/completed/failed tasks |
+| `nx_current_running_task_output` | Get terminal output for a specific task |
+
+---
+
+## Code Generation Workflow
+
+Use this workflow whenever scaffolding new code (libraries, applications, features) or running automated code transformations. **Always prefer generators over manual file creation** when a generator exists for the task.
+
+### Phase 1: Discover
+
+1. **List available generators** using `nx_generators` MCP tool
+   - This includes plugin generators (e.g., `@nx/react:library`) and local workspace generators
+2. **Match generator to request** — identify which generator(s) could fulfill the need
+3. **Prefer local generators** — when both local and plugin generators could work, **always prefer local** (they're customized for this repo's patterns)
+4. **If no generator fits** — check `nx_available_plugins` for installable plugins. Only fall back to manual creation after exhausting all generator options
+
+### Phase 2: Understand
+
+Before running any generator, complete these steps:
+
+1. **Fetch generator schema** using `nx_generator_schema` MCP tool
+   - Identify required vs optional options
+   - Note default values that may need overriding
+   - Pay attention to options that affect file structure or naming
+
+2. **Read generator source code** (for unfamiliar generators)
+   - Find source: `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"`
+   - If that fails: read from `node_modules/<plugin>/generators.json`
+   - Local generators: check `tools/generators/` or local plugin directories
+   - Understanding the source reveals side effects (config updates, dep installs) and files created/modified
+
+3. **Reevaluate generator choice** — after understanding what the generator does, confirm it's the right one. If not, go back to Phase 1 and select a different generator.
+
+4. **Examine repo context** — study existing similar artifacts in the codebase:
+   - Look at how similar projects are structured (naming, test runner, build tool, linter)
+   - Match conventions when configuring the generator
+   - Note directory structures, file patterns, and config styles
+
+5. **Validate required options** — map the user's request to generator options:
+   - Infer values from context where possible
+   - Ask for critical missing information if it cannot be inferred
+
+### Phase 3: Execute
+
+1. **Consider dry-run first** (recommended for complex/unfamiliar generators):
+   ```bash
+   yarn nx generate <generator-name> <options> --dry-run --no-interactive
+   ```
+   - Shows files that would be created/deleted/modified (but not content)
+   - Some generators don't support dry-run (e.g., if they install packages) — skip and run for real
+   - For simple, well-understood generators, you may skip dry-run
+
+2. **Run the generator**:
+   ```bash
+   yarn nx generate <generator-name> <options> --no-interactive
+   ```
+   **CRITICAL**: Always include `--no-interactive` to prevent prompts that hang execution.
+
+   **CRITICAL**: Generators may behave differently based on the current working directory (e.g., library generators use cwd to determine placement). Verify cwd before running.
+
+3. **Handle failures** — if the generator fails:
+   - Read the error message carefully
+   - Common causes: missing required options, invalid values, conflicting files, missing dependencies
+   - Adjust options and retry
+   - Add a lesson to `.github/customizations/LESSONS-LEARNED.md` if the fix was non-obvious
+
+### Phase 4: Post-Generation
+
+1. **Modify generated code** if needed — generators provide a starting point:
+   - Adjust functionality to match specific requirements
+   - Update imports, exports, configurations
+   - Integrate with existing code patterns
+
+2. **Format code**:
+   ```bash
+   yarn nx format --fix
+   ```
+
+3. **Run verification** on generated/affected projects:
+   ```bash
+   yarn nx run <new-project>:lint --fix
+   yarn nx run <new-project>:test
+   yarn nx run <new-project>:build
+   ```
+
+4. **Handle verification failures**:
+   - **Small scope** (few lint errors, minor type issues) — fix directly, re-verify
+   - **Large scope** (many errors, complex problems) — fix obvious issues first, escalate remaining with description of what was generated, what's failing, and what was attempted
+
+## Running Tasks Workflow
+
+When helping with build, test, lint, or serve tasks:
+
+1. Use `nx_current_running_tasks_details` to check for active/completed/failed tasks
+2. For a specific task, use `nx_current_running_task_output` to get its terminal output
+3. Diagnose issues from the output and apply fixes
+4. To rerun a task, always use `yarn nx run <taskId>` to preserve the NX context
+5. **Continuous tasks** (like `serve`) are already running — don't offer to rerun, just check output
+
+## Project Names
+
+See `project.instructions.md` for the full project name → location mapping.

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

@@ -0,0 +1,184 @@
+---
+name: panel-majority-vote
+description: "Run 3 isolated reviewer sub-agents against the same question and decide PASS/BLOCK by majority vote (2/3 wins). Use when deterministic verification is insufficient."
+---
+
+# Skill: Panel majority vote (3 reviewers)
+
+Use this skill when deterministic verification is unavailable and you need a panel to decide PASS/BLOCK for a single question against a declared artifact scope.
+
+## Contract
+- Scope is exactly one run root and one panel key.
+- Reviewers must only use the declared in-scope artifacts.
+- Exactly 3 isolated reviewer runs.
+- Majority vote decides overall verdict (2/3 wins).
+- Consolidated panel report must include a short retry summary when BLOCK.
+
+## Inputs
+- Run root: `<runRoot>`
+- Panel key: `<panelKey>` (a filesystem-safe identifier used to name output files)
+- Exact question text (single question)
+- Explicit in-scope artifact list (all under the same run root)
+
+Optional (defaults shown):
+- Panel output directory: `<panelDir>` (default: `<runRoot>/panel/`)
+
+## Outputs (files)
+- (Optional) Prompt payload: `<panelDir>/<panelKey>-panel-prompt.md`
+- Raw reviewer outputs: `<panelDir>/<panelKey>-reviewer-outputs.md`
+- Consolidated report: `<panelDir>/<panelKey>.md`
+
+## Procedure (required: run in isolation)
+Run this skill in an isolated subagent (using `runSubagent`) so the panel cannot accidentally consult unrelated workspace context.
+
+The isolated runner subagent must:
+1. Validate scope
+  - Ensure every in-scope artifact path is under `<runRoot>`.
+  - Ensure the in-scope list is sufficient to answer the question.
+
+2. Spawn exactly 3 reviewers (in parallel)
+  - Launch 3 isolated reviewer subagents (using `runSubagent`) with the exact same prompt payload.
+  - The prompt payload may be passed directly to the reviewer subagents (no file required).
+  - If you want an explicit artifact of the prompt payload, optionally write it to `<panelDir>/<panelKey>-panel-prompt.md`.
+  - Reviewer prompt must require this strict output format:
+    1) VERDICT: PASS | BLOCK
+    2) MUST-FIX:
+    - ...
+    3) SHOULD-FIX:
+    - ...
+    4) QUESTIONS:
+    - ...
+    5) TEST IDEAS:
+    - ...
+    6) CONFIDENCE: low | med | high
+  - Reviewers must not include any other sections.
+
+3. Persist reviewer outputs (required audit trail)
+  - Create/overwrite `<panelDir>/<panelKey>-reviewer-outputs.md`.
+  - Include at the top:
+    - Run root
+    - Panel key
+    - Question text
+    - In-scope artifact list
+    - (Optional) The exact prompt payload text provided to reviewers
+  - Then include each reviewer output verbatim, clearly separated.
+
+4. Consolidate by majority vote (2/3 wins)
+  - Compute:
+    - PASS count
+    - BLOCK count
+    - Overall = PASS if PASS >= 2 else BLOCK
+  - Deduplicate MUST-FIX and SHOULD-FIX items; annotate how many reviewers flagged each.
+  - Record disagreements (items flagged by only 1 reviewer; or materially conflicting assessments).
+  - Include determinize-next recommendations.
+  - If Overall = BLOCK, include a short Retry summary:
+    - top changes required before retrying
+
+5. Write the consolidated panel report
+ - Create `<panelDir>/<panelKey>.md` using the template in `panel-report.template.md` (in this directory).
+
+6. Print a concise summary to chat
+  - Overall verdict + vote tally + path to `<panelDir>/<panelKey>.md`.
+
+7. Log the panel result
+  - Append a JSON line to `.github/customizations/logs/panels.ndjson` with the panel record schema (see `.github/customizations/logs/README.md`).
+  - Include: `timestamp`, `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `linear_issue`, `artifacts_count`, `report_path`.
+  - Example:
+    ```bash
+    echo '{"timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","panel_key":"instruction-refactoring","verdict":"pass","pass_count":3,"block_count":0,"must_fix":0,"should_fix":5,"reviewer_model":"claude-opus-4-6","weighted":false,"attempt":1,"artifacts_count":14,"report_path":".github/customizations/logs/panel/instruction-refactoring.md"}' >> .github/customizations/logs/panels.ndjson
+    ```
+
+Finally: ensure whatever produced the claim being verified links the consolidated panel report as verification evidence.
+
+## Notes
+- If the panel output is BLOCK, prefer to change the underlying work and re-run the same panel question over re-wording the question.
+- After 3 consecutive BLOCKs on the same panel key, create a **dispute record** in `.github/customizations/DISPUTES.md` instead of retrying further. The dispute packages the agent's position, all reviewer feedback, attempt history, and resolution options for human decision-making. See the **team-lead-reference** skill § Dispute Protocol for the full procedure.
+
+## Model Selection for Reviewers
+
+Choose reviewer models based on the domain being reviewed:
+- **Security, architecture, complex logic** → Premium (Claude Opus 4.6) for all 3 reviewers
+- **Feature implementation, UI, queries** → Standard (Gemini 3.1 Pro) for all 3 reviewers
+- **Mixed-domain review** → Use Premium for at least 1 reviewer, Standard for the other 2
+
+All 3 reviewers should use the same model to ensure comparable verdicts. Mixing models can lead to inconsistent review depth and confusing disagreements.
+
+## Weighted Consensus Variant
+
+Extends the panel system for subjective decisions where domain expertise should weight more heavily than a simple head-count.
+
+### When to Use Weighted Consensus
+
+| Decision Type | Use Simple Majority | Use Weighted Consensus |
+|--------------|--------------------|-----------------------|
+| Security vulnerability present? | ✅ | — |
+| Code correctness | ✅ | — |
+| Best UI approach for user experience | — | ✅ |
+| Architecture tradeoff (performance vs maintainability) | — | ✅ |
+| Data model design choices | — | ✅ |
+| Naming conventions / code style disputes | — | ✅ |
+
+### Weight Assignment Rules
+
+Each reviewer gets a weight based on 3 factors:
+
+| Factor | Weight Bonus | Example |
+|--------|-------------|---------|
+| **Domain expertise** | +2 | Security Expert reviewing auth code |
+| **Confidence level** | +1 (high) / 0 (med) / -1 (low) | Self-reported by reviewer |
+| **Prior success** | +1 | Agent has >80% success rate for similar reviews (from AGENT-PERFORMANCE.md) |
+
+**Base weight:** 1 for all reviewers. Add bonuses to get final weight.
+
+**Example:**
+
+```text
+Reviewer 1 (Security Expert, reviewing auth): base 1 + domain 2 + confidence 1 = weight 4
+Reviewer 2 (Next.js Dev, reviewing auth):     base 1 + domain 0 + confidence 1 = weight 2
+Reviewer 3 (Architect, reviewing auth):        base 1 + domain 1 + confidence 0 = weight 2
+```
+
+### Weighted Voting Protocol
+
+1. **Assign weights** to each reviewer before spawning them (based on their role relative to the review domain)
+2. **Spawn reviewers** with the same prompt as simple majority (use the existing procedure)
+3. **Collect verdicts** — each reviewer submits PASS/BLOCK with confidence level
+4. **Calculate weighted score:**
+   - Sum weights of PASS reviewers → PASS score
+   - Sum weights of BLOCK reviewers → BLOCK score
+   - Overall = PASS if PASS score > BLOCK score, else BLOCK
+5. **Tie-breaking:** If scores are equal, the reviewer with the highest individual weight breaks the tie. If weights are also equal, default to BLOCK (conservative).
+
+### Conflict Resolution
+
+- If a low-weight reviewer BLOCKs but high-weight reviewers PASS: note the BLOCK concerns in the report but overall PASS. Include the low-weight MUST-FIX items as SHOULD-FIX instead.
+- If the domain expert BLOCKs but generalists PASS: overall BLOCK. Domain expertise overrides general opinion.
+- If all reviewers have equal weight: falls back to simple majority vote (2/3 wins).
+
+### Weighted Panel Report Extension
+
+Add these fields to the consolidated panel report template when using weighted consensus:
+
+```markdown
+### Weighting
+| Reviewer | Role | Domain | Confidence | Prior Success | Final Weight |
+|----------|------|--------|------------|---------------|-------------|
+| 1 | [Agent] | +X | +X | +X | X |
+| 2 | [Agent] | +X | +X | +X | X |
+| 3 | [Agent] | +X | +X | +X | X |
+
+### Weighted Score
+- PASS: X (reviewers: 1, 3)
+- BLOCK: X (reviewer: 2)
+- **Overall: PASS/BLOCK** (weighted)
+```
+
+### Integration with Existing Panel Workflow
+
+The weighted consensus variant follows the SAME procedure steps (1-6) from the main panel protocol. The only differences are:
+1. Weight assignment happens in step 2 (before spawning reviewers)
+2. Step 4 uses weighted calculation instead of simple count
+3. The consolidated report includes the weighting table
+
+The Team Lead decides whether to use simple majority or weighted consensus when scheduling the panel review. Include the decision rationale in the delegation prompt.
+

package/src/orchestrator/skills/panel-majority-vote/panel-report.template.md

@@ -0,0 +1,38 @@
+# Panel Report
+
+## Context
+- Run root (must be a single run):
+ - `<runRoot>/`
+- Panel key:
+- Question asked (exact text):
+- Artifacts in scope (must all be under the same run root):
+ - `<runRoot>/...`
+- Reviewer runs:
+ - N = 3
+- Reviewer outputs source:
+ - `<panelDir>/<panelKey>-reviewer-outputs.md`
+
+## Panel verdict
+- Overall: PASS | BLOCK
+
+## Vote tally
+- PASS: 0
+- BLOCK: 0
+
+## Must-fix
+List must-fix issues, and annotate how many panelists flagged each.
+
+## Should-fix
+-
+
+## Questions / Ambiguities
+-
+
+## Disagreements
+-
+
+## Determinize next
+Top actions to convert concerns into deterministic verification (tests/checks).
+
+## Retry summary (only if Overall = BLOCK)
+What should change before re-verifying.

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

@@ -0,0 +1,101 @@
+---
+name: performance-optimization
+description: "Frontend and backend performance optimization patterns including rendering, asset optimization, JavaScript performance, caching, profiling, and code review checklist. Use when optimizing components, reviewing code for performance, or analyzing bundle size and Core Web Vitals."
+---
+
+# Performance Optimization
+
+## General Principles
+
+- **Measure first, optimize second** — profile before optimizing. Use Chrome DevTools, Lighthouse, Datadog.
+- **Optimize for the common case** — focus on frequently executed code paths.
+- **Avoid premature optimization** — write clear code first, optimize when necessary.
+- **Minimize resource usage** — CPU, memory, network, disk.
+- **Prefer simplicity** — simple algorithms are often faster and easier to optimize.
+- **Document performance assumptions** — comment performance-critical code.
+- **Automate performance testing** — integrate into CI/CD.
+- **Set performance budgets** — define limits for load time, memory, API latency.
+
+## Rendering and DOM
+
+- **Memoization**: Use `React.memo`, `useMemo`, `useCallback` judiciously — only when profiling shows unnecessary re-renders. Don't pre-optimize.
+- Stable `key` props in lists (avoid array indices unless static).
+- Avoid inline styles (can trigger layout thrashing). Prefer CSS classes.
+- CSS transitions/animations over JavaScript for GPU-accelerated effects.
+- `requestIdleCallback` for deferring non-critical rendering.
+
+## Asset Optimization
+
+- Modern image formats (WebP, AVIF). Tools: ImageOptim, Squoosh.
+- SVGs for icons.
+- Bundle and minify JS/CSS (Webpack, Rollup, esbuild). Tree-shaking.
+- Long-lived cache headers for static assets. Cache busting for updates.
+- `loading="lazy"` for images. Dynamic imports for JS.
+- Font subsetting. `font-display: swap`.
+
+## JavaScript Performance
+
+- Offload heavy computation to Web Workers.
+- Debounce/throttle scroll, resize, input events.
+- Clean up event listeners, intervals, DOM references (prevent memory leaks).
+- Maps/Sets for lookups. TypedArrays for numeric data.
+- Avoid global variables.
+- Avoid deep object cloning unless necessary.
+
+## Node.js
+
+- Async APIs only — never `fs.readFileSync` in production.
+- Clustering or worker threads for CPU-bound tasks.
+- Streams for large file/network processing.
+- Profile with `clinic.js`, `node --inspect`.
+
+## Code Review Checklist
+
+- [ ] No obvious algorithmic inefficiencies (O(n²) or worse)?
+- [ ] Appropriate data structures?
+- [ ] No unnecessary computations or repeated work?
+- [ ] Caching used where appropriate with correct invalidation?
+- [ ] Database queries optimized, indexed, no N+1?
+- [ ] Large payloads paginated, streamed, or chunked?
+- [ ] No memory leaks or unbounded resource usage?
+- [ ] Network requests minimized, batched, retried on failure?
+- [ ] Assets optimized, compressed, served efficiently?
+- [ ] No blocking operations in hot paths?
+- [ ] Logging in hot paths minimized and structured?
+- [ ] Performance-critical paths documented and tested?
+- [ ] Automated benchmarks for performance-sensitive code?
+- [ ] Alerts for performance regressions?
+- [ ] No anti-patterns (SELECT *, blocking I/O, globals)?
+- [ ] Memoization used judiciously — only where profiling shows benefit?
+
+## Practical Examples
+
+### Debouncing User Input
+
+```javascript
+// BAD: API call on every keystroke
+input.addEventListener('input', (e) => fetch(`/search?q=${e.target.value}`));
+
+// GOOD: Debounced
+let timeout;
+input.addEventListener('input', (e) => {
+  clearTimeout(timeout);
+  timeout = setTimeout(() => fetch(`/search?q=${e.target.value}`), 300);
+});
+```
+
+### Lazy Loading Images
+
+```html
+<!-- BAD -->
+<img src="large-image.jpg" />
+
+<!-- GOOD -->
+<img src="large-image.jpg" loading="lazy" />
+```
+
+## References
+
+- [Google Web Fundamentals: Performance](https://web.dev/performance/)
+- [MDN: Performance](https://developer.mozilla.org/en-US/docs/Web/Performance)
+- [Lighthouse](https://developers.google.com/web/tools/lighthouse)