opencastle 0.1.0

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -0,0 +1,137 @@
+---
+description: 'Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, and adjustments that are too small for Linear tracking.'
+agent: Team Lead
+---
+
+# Follow-Up Refinement
+
+You are the Team Lead. Handle the follow-up refinement described below. This is a **post-task adjustment** — a bug fix, UI tweak, or polish item that came up after reviewing a completed roadmap task. It does NOT require Linear tracking.
+
+## Request
+
+{{followUpRequest}}
+
+---
+
+## How Follow-Ups Differ from Roadmap Tasks
+
+| Aspect | Roadmap Task | Follow-Up |
+|--------|-------------|-----------|
+| Linear issues | Required (hard gate) | Depends on scope (see triage) |
+| Panel review | For high-stakes changes | Only if security/data-related |
+| Documentation updates | Roadmap + known issues + ADRs | Only if behavior changes significantly |
+| Scope | Multi-step feature | Focused fix or adjustment |
+| Branch strategy | Dedicated feature branch | Current branch (already in progress) |
+
+**Despite being lighter-weight, follow-ups still require the same code quality and verification standards.** Never skip linting, testing, or browser checks just because the change is "small."
+
+## Workflow
+
+### 1. Triage: Decide Tracking Level
+
+Before doing anything, decide whether this follow-up needs Linear tracking:
+
+**Create a Linear issue if ANY of these are true:**
+- The change affects user-visible behavior (not just cosmetic)
+- It touches more than 2–3 files
+- It modifies shared library code (`libs/`)
+- It changes data queries, API routes, or Server Actions
+- It could introduce regressions in other features
+- You want a record for future reference (e.g., "why was this changed?")
+
+**Skip Linear if ALL of these are true:**
+- Pure cosmetic/spacing/copy tweak
+- Isolated to a single component or page
+- No behavioral change
+- Trivial to verify visually
+
+If creating a Linear issue, use:
+- **Title**: `[Follow-up] Short description`
+- **Label**: agent name + `follow-up`
+- **Priority**: Low or Medium
+- **Description**: What changed, why, and which files
+
+### 2. Understand the Request
+
+Before touching any code:
+
+1. **Clarify scope** — Identify exactly which pages, components, or behaviors need to change
+2. **Find affected files** — Search the codebase for the relevant components, styles, queries, and tests
+3. **Check known issues** — Scan `docs/KNOWN-ISSUES.md` in case this is a documented limitation
+4. **Read lessons learned** — Check `.github/customizations/LESSONS-LEARNED.md` for relevant pitfalls before starting
+5. **Assess complexity** — If the request turns out to be larger than expected (touches >5 files, needs a migration, or affects auth/security), escalate it:
+   - Inform the user that this should be a tracked task
+   - Create a Linear issue (if not already created in triage) and switch to the `implement-feature` workflow
+
+### 3. Plan the Fix
+
+Think before you act:
+
+1. **Identify root cause** — For bugs, find why it happens, not just where. For UI tweaks, understand the current styling/layout chain
+2. **Check for shared impact** — Will the fix affect other pages or apps? Check component usage across the codebase
+3. **Determine the minimal change** — Follow the principle of least surprise. Change only what's necessary
+4. **Reuse existing patterns** — Use components, utilities, and styles that already exist in the codebase. Never introduce a new pattern for a one-off fix
+
+### 4. Implement
+
+Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and focused, prefer **sub-agents** (inline) over background agents.
+
+#### Delegation Prompt Must Include
+
+- **What to fix** — clear description of the problem and desired outcome
+- **Where** — exact file paths to read and modify
+- **How to verify** — what the result should look like or how to test it
+- **Boundaries** — "Only modify files listed above. Do not refactor unrelated code."
+- **Self-improvement reminder** — include per `general.instructions.md` § Self-Improvement Protocol
+
+#### Implementation Rules
+
+- **No scope creep** — Fix what was asked. If you notice other issues, note them but don't fix them in this pass
+- **DRY** — Search before creating. Reuse existing components and utilities
+- **Visual consistency** — Match the existing design system (spacing, colors, typography)
+- **Cross-app check** — If the change is in shared code (`libs/`), verify it works for both apps
+- **Accessibility** — Don't regress keyboard navigation, screen reader support, or contrast ratios
+
+### 5. Validate
+
+> Load the **validation-gates** skill for detailed steps on each gate.
+
+Every follow-up, no matter how small, must pass these checks:
+
+1. **Deterministic Checks** — `yarn nx run <project>:lint --fix`, `:test`, `:build` — all zero errors
+2. **Browser Testing** (MANDATORY for any visual change) — clear cache, start server, verify scenario + responsive + screenshot evidence
+3. **Regression Check** — if shared component/library modified, run tests for all consuming projects and browser-test at least one page per affected app
+
+### 6. Delivery
+
+If triage determined this follow-up needs Linear tracking, follow the **Delivery Outcome** defined in `general.instructions.md` — commit, push, open PR (not merged), and link to Linear.
+
+If triage determined no Linear tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
+
+### 7. Escalation Triggers
+
+Stop the follow-up workflow and switch to a full roadmap task if:
+
+- The fix requires a **database migration**
+- The fix involves **authentication or authorization** changes
+- The fix touches **more than 5 files** across multiple libraries
+- The fix introduces a **new dependency** or **new API endpoint**
+- The fix changes **data models** (CMS schemas, database tables)
+- You discover the "small fix" is actually a **systemic issue** requiring architectural changes
+
+When escalating, explain to the user what you found and why it needs proper tracking.
+
+### 8. Completion
+
+The follow-up is complete when:
+
+- [ ] The specific request is resolved
+- [ ] Linear issue created and moved to Done (if triage determined tracking was needed)
+- [ ] Lint, test, and build pass for all affected projects
+- [ ] **Dev server started with CLEAN cache** (`rm -rf .next && yarn nx reset` before serving)
+- [ ] **Visual changes verified in Chrome with screenshot taken as proof**
+- [ ] No regressions in adjacent functionality
+- [ ] Shared component changes tested across all consuming apps
+- [ ] Delivery Outcome completed if tracked (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+- [ ] Lessons learned captured if any retries occurred
+- [ ] Known issues updated if a new limitation was discovered

package/src/orchestrator/prompts/resolve-pr-comments.prompt.md

@@ -0,0 +1,100 @@
+---
+description: 'Resolve GitHub PR review comments by reading them, grouping by file, and applying fixes systematically.'
+agent: Team Lead
+---
+
+# Resolve PR Comments
+
+You are the Team Lead. A pull request has review comments that need to be resolved. Read the comments, group them by file, and delegate fixes efficiently.
+
+## PR Reference
+
+{{prReference}}
+
+---
+
+## Workflow
+
+### Phase 1: Gather Comments
+
+1. **Read the PR** — Use `gh pr view <number> --comments` and `gh pr diff <number>` to understand the full context
+2. **List review comments** — Use `gh api repos/{owner}/{repo}/pulls/{number}/comments` to get all inline review comments
+3. **Group by file** — Organize comments by file path. Comments on the same file should be resolved together
+4. **Classify each comment:**
+   - **Must-fix** — Correctness issues, security concerns, logic errors, test gaps
+   - **Should-fix** — Style issues, naming improvements, missing edge cases
+   - **Discussion** — Questions, alternative suggestions, design debates (flag for human)
+
+### Phase 2: Plan Fixes
+
+1. **Map file ownership** — Ensure no two parallel agents touch the same file
+2. **Check dependencies** — Some comments may depend on others (e.g., "rename this type" affects all files using it)
+3. **Order by dependency** — Resolve foundational changes first (types, shared utilities) before downstream files
+4. **Estimate scope** — If >10 must-fix comments, consider splitting into multiple delegation rounds
+
+### Phase 3: Apply Fixes
+
+For each file group, delegate to the appropriate specialist agent:
+
+```
+Fix the following PR review comments in [file path]:
+
+1. [Comment 1]: [reviewer's feedback] (Line X)
+2. [Comment 2]: [reviewer's feedback] (Line Y)
+
+Context: This file is part of [feature/area]. The PR is [brief PR description].
+
+Acceptance criteria:
+- [ ] Each comment is addressed (fixed or documented why not)
+- [ ] No new lint/type errors introduced
+- [ ] Existing tests still pass
+- [ ] New tests added if the comment identified a gap
+```
+
+**Discussion comments** — Do not fix these. Instead, compile them into a summary for the human reviewer with your recommendation.
+
+### Phase 4: Verify & Report
+
+1. **Run verification** — `yarn nx affected -t lint,test,build` on all affected projects
+2. **Commit fixes** — Use descriptive commit messages referencing the PR: `TAS-XX: Address PR review — [summary]`
+3. **Push to the same branch** — The PR updates automatically
+4. **Report back** — Provide a structured summary of what was resolved
+
+## Output Format
+
+After resolving comments, report:
+
+```markdown
+## PR Comment Resolution: #<number>
+
+### Resolved (Must-Fix)
+| File | Comment | Resolution |
+|------|---------|------------|
+| path/to/file.ts | [feedback summary] | [what was changed] |
+
+### Resolved (Should-Fix)
+| File | Comment | Resolution |
+|------|---------|------------|
+| path/to/file.ts | [feedback summary] | [what was changed] |
+
+### Flagged for Discussion
+| File | Comment | Recommendation |
+|------|---------|---------------|
+| path/to/file.ts | [question/debate] | [your take + options] |
+
+### Verification
+- Lint: PASS/FAIL
+- Tests: PASS/FAIL
+- Build: PASS/FAIL
+
+### Commits
+- `abc1234` TAS-XX: Address PR review — [summary]
+```
+
+## Rules
+
+- **Never dismiss a must-fix comment** — if you disagree, flag it for discussion instead
+- **Preserve the reviewer's intent** — don't just technically satisfy the comment, address the underlying concern
+- **Don't over-fix** — resolve only what was commented on. Save unrelated improvements for a separate PR
+- **Respond to every comment** — nothing should be silently ignored
+- **Self-improvement** — Follow `general.instructions.md` § Self-Improvement Protocol

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

@@ -0,0 +1,164 @@
+---
+name: accessibility-standards
+description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, and inclusive language."
+---
+
+# Accessibility Standards
+
+Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/). Go beyond minimal conformance wherever possible.
+
+## Workflow
+
+1. Before generating code, plan how to implement it accessibly.
+2. After generating code, review against WCAG 2.2 and these patterns. Iterate until compliant.
+3. Inform the user the code was built with accessibility in mind but may still have issues. Suggest [Accessibility Insights](https://accessibilityinsights.io/) for testing.
+
+## Inclusive Language
+
+- Use people-first language ("person using a screen reader," not "blind user").
+- Avoid stereotypes or assumptions about ability.
+- Flag uncertain implementations — include reasoning or references to standards.
+
+## Cognitive
+
+- Prefer plain language.
+- Use consistent page structure (landmarks) across the application.
+- Keep navigation items in the same order across pages.
+- Keep the interface clean — reduce unnecessary distractions.
+
+## Keyboard
+
+- All interactive elements must be keyboard navigable with predictable focus order (reading order).
+- Focus must be clearly visible at all times.
+- All interactive elements must be operable (buttons, links, dropdowns, etc.).
+- Static (non-interactive) elements should NOT have `tabindex`. Exception: elements receiving programmatic focus (e.g., headings) get `tabindex="-1"`.
+- Hidden elements must not be keyboard focusable.
+
+### Composite Components (grids, listboxes, menus, tabs, toolbars)
+
+- Tab stop on the container with appropriate interactive role.
+- Arrow keys navigate children (roving tabindex or `aria-activedescendant`).
+- On focus: show selected child, or previously focused child, or first interactive child.
+
+### Bypass Blocks
+
+Provide "Skip to main" link as first focusable element:
+
+```html
+<header>
+  <a href="#maincontent" class="sr-only">Skip to main</a>
+</header>
+<main id="maincontent"></main>
+```
+
+```css
+.sr-only:not(:focus):not(:active) {
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  height: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+```
+
+### Common Keys
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Next interactive element |
+| `Arrow` | Navigate within composite component |
+| `Enter` | Activate focused control |
+| `Escape` | Close open surfaces (dialogs, menus) |
+
+### Roving Tabindex Pattern
+
+1. Initial: `tabindex="0"` on first focusable child, `tabindex="-1"` on rest.
+2. On arrow key: set previous to `-1`, new target to `0`, call `element.focus()`.
+
+### `aria-activedescendant` Pattern
+
+- Container has `tabindex="0"` and `aria-activedescendant="IDREF"`.
+- CSS draws focus outline on referenced element.
+- Arrow keys update `aria-activedescendant`.
+
+## Low Vision
+
+- Dark text on light backgrounds (or vice versa).
+- Text contrast ≥4.5:1 (≥3:1 for large text: 18.5px bold or 24px).
+- Graphics/controls contrast ≥3:1 with adjacent colors.
+- Control state indicators (pressed, focus, checked) ≥3:1 contrast.
+- Color must NOT be the only way to convey information — use text/shapes in addition.
+
+## Screen Reader
+
+- All elements must convey correct semantics (name, role, value, states/properties). Prefer native HTML; use ARIA when necessary.
+- Use landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`.
+- Use headings (`<h1>`–`<h6>`) to introduce sections. One `<h1>` per page. Avoid skipping levels.
+
+## Voice Access
+
+- Accessible name of interactive elements must contain the visual label (so voice users can say "Click [label]").
+- `aria-label` must contain the visual label text.
+
+## Forms
+
+- Labels must accurately describe control purpose.
+- Required fields: asterisk in label + `aria-required="true"`.
+- Errors: `aria-invalid="true"` on invalid fields. Error messages via `aria-describedby`.
+- Inline errors next to fields (common) or form-level errors at top identifying specific fields.
+- Submit buttons should NOT be disabled — trigger error messages instead.
+- On submit with invalid input, focus the first invalid field.
+
+## Graphics and Images
+
+- All graphics must have correct role (`<img>` implicit, `<svg>` needs `role="img"`, icon fonts/emojis need `role="img"` on `<span>`).
+- **Informative**: `alt` text conveying meaning/purpose (concise, meaningful). Avoid `title` attribute.
+- **Decorative**: `alt=""` for `<img>`, `aria-hidden="true"` for `role="img"`.
+
+## Input Labels
+
+- All interactive elements need visual labels.
+- `<label for="id">` for form inputs.
+- Multiple controls with same label (e.g., "Remove"): use `aria-label` for disambiguation.
+- Help text: associate via `aria-describedby`.
+
+## Navigation
+
+```html
+<nav>
+  <ul>
+    <li>
+      <button aria-expanded="false" tabindex="0">Section 1</button>
+      <ul hidden>
+        <li><a href="..." tabindex="-1">Link 1</a></li>
+      </ul>
+    </li>
+    <li>
+      <button aria-expanded="false" tabindex="-1">Section 2</button>
+      <ul hidden>
+        <li><a href="..." tabindex="-1">Link 1</a></li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+```
+
+- Navigation menus use `<nav>` with `<ul>`, NOT `menu`/`menubar` roles.
+- Toggle `aria-expanded` on expand/collapse.
+- Roving tabindex for main items (arrow across), arrow down into sub-menus.
+- `Escape` closes expanded menus.
+
+## Page Title
+
+- Defined in `<title>` in `<head>`.
+- Describes page purpose, unique per page.
+- Front-load unique information: `"[Page] - [Section] - [Site]"`.
+
+## Tables and Grids
+
+- Column headers via `<th>` in first `<tr>`. Row headers via `<th>` in each row.
+- `role="gridcell"` must be nested within `role="row"`.
+- Prefer simple tables (one set of headers, no spanning cells).
+- Use `<table>` for static data, `role="grid"` for interactive data (date pickers, calendars).

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: agent-hooks
+description: "Lifecycle hooks for AI agent sessions — reusable actions that run at specific points (session start, session end, pre-delegation, post-delegation). Defines what to do at each lifecycle event so agents behave consistently."
+---
+
+# Agent Lifecycle Hooks
+
+Hooks are **standardized actions** that agents execute at specific points during their lifecycle. They enforce consistency across sessions and prevent common oversights (missing lessons, forgotten checkpoints, untracked issues).
+
+## Hook Execution Model
+
+Hooks are **conventions, not automated triggers**. Agents must explicitly follow them. The Team Lead includes hook reminders in delegation prompts; specialist agents include them in their own workflow.
+
+```
+Session Lifecycle:
+  on-session-start  →  [work loop]  →  on-session-end
+                          ↓   ↑
+                    on-pre-delegate → on-post-delegate
+```
+
+---
+
+## Hook: on-session-start
+
+**When:** First action in any agent session (Team Lead or specialist).
+
+### Actions
+
+1. **Read lessons learned** — Scan `.github/customizations/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
+2. **Check for checkpoint** — If `docs/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
+3. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures related to the current scope.
+4. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
+
+### Template for Delegation Prompts
+
+Include this reminder in every delegation:
+
+```
+**Session Start:** Read `.github/customizations/LESSONS-LEARNED.md` before starting.
+Check `docs/SESSION-CHECKPOINT.md` for prior state. Load relevant skills
+before writing code.
+```
+
+---
+
+## Hook: on-session-end
+
+**When:** Before the agent yields control back to the user or completes its task.
+
+### Actions
+
+1. **Log the session** — Append a JSON line to `.github/customizations/logs/sessions.ndjson` with: agent name, task summary, files changed, duration estimate, outcome (success/partial/failed), and lessons count.
+2. **Save checkpoint** (Team Lead only) — If work is incomplete, write `docs/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
+3. **Verify lessons captured** — If any retries occurred during the session, confirm that each retry resulted in a lesson entry in `LESSONS-LEARNED.md`.
+4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
+5. **Clean up** — Remove any temporary files created during the session (e.g., test fixtures, debug outputs).
+
+### Template for Delegation Prompts
+
+```
+**Session End:** Log your session to `.github/customizations/logs/sessions.ndjson`.
+If you retried anything with a different approach that worked, add a lesson
+to `.github/customizations/LESSONS-LEARNED.md`. Clean up temp files.
+```
+
+---
+
+## Hook: on-pre-delegate
+
+**When:** Team Lead only — before every delegation (sub-agent or background agent).
+
+### Actions
+
+1. **Linear issue exists** — Verify the task has a Linear issue. If not, create one first.
+2. **File partition clean** — Confirm no overlap with other active agents' file ownership.
+3. **Dependencies verified** — All prerequisite tasks are marked Done with independent verification.
+4. **Prompt is specific** — Includes: objective, file paths, acceptance criteria, patterns to follow, self-improvement reminder.
+5. **Context map** (optional, for complex tasks) — If modifying 5+ files, generate a context map first (load **context-map** skill).
+6. **Cost check** — Estimate token usage based on task complexity and model tier. Check against session budget.
+
+### Quick Checklist
+
+```
+Pre-Delegate:
+☐ Linear issue ID included
+☐ File partition specified
+☐ Dependencies are Done
+☐ Prompt has file paths + acceptance criteria
+☐ Self-improvement reminder included
+☐ Budget check passes
+```
+
+---
+
+## Hook: on-post-delegate
+
+**When:** Team Lead only — after receiving results from a delegated agent.
+
+### Actions
+
+0. **Fast review (mandatory)** — Run the `fast-review` skill against the agent's output. This is a **non-skippable gate**. See the fast-review skill for the full procedure (single reviewer sub-agent, automatic retry, escalation). Only after the fast review passes do you proceed to the remaining post-delegate actions below.
+1. **Verify output** — Read changed files. Check that changes stay within the agent's file partition.
+2. **Run verification** — Execute appropriate checks: lint, type-check, tests, or visual inspection.
+3. **Check acceptance criteria** — Compare output against the Linear issue's acceptance criteria. Each criterion must be independently verified.
+4. **Discovered issues tracked** — Verify the agent followed the Discovered Issues Policy. If they found issues, check that they're in KNOWN-ISSUES.md or a new Linear ticket.
+5. **Lessons captured** — If the agent retried anything, verify a lesson was added to LESSONS-LEARNED.md.
+6. **Update Linear** — Move the issue to Done (if passing) or add failure notes and re-delegate (if failing).
+
+### Quick Checklist
+
+```
+Post-Delegate:
+☐ Changed files reviewed
+☐ Files within partition
+☐ Lint/test/build passes
+☐ Fast review PASS (mandatory — load fast-review skill)
+☐ Acceptance criteria met
+☐ Discovered issues tracked (not ignored)
+☐ Lessons captured (if retries occurred)
+☐ Issue updated
+```
+
+---
+
+## Hook Integration
+
+### For Team Lead
+
+The on-pre-delegate and on-post-delegate hooks are already encoded in the Team Lead's orchestration workflow. Reference this skill to ensure consistency.
+
+### For Specialist Agents
+
+Include on-session-start and on-session-end actions in every delegation prompt. Use the templates above.
+
+### For Workflow Templates
+
+Each workflow's **Compound phase** naturally serves as the on-session-end hook for that workflow type. The Compound phase steps should include session logging, lesson verification, and memory merge checks.
+
+---
+
+## Anti-Patterns
+
+- **Skipping on-session-start** — Leads to repeated mistakes already documented in lessons learned
+- **Forgetting session logging** — Makes performance tracking and agent improvement impossible
+- **Partial post-delegate checks** — "It compiled, ship it" without checking acceptance criteria
+- **No cleanup** — Temp files accumulate and confuse future sessions
+- **Hooks as blockers** — Hooks should add ~2 minutes overhead, not 20. If a hook takes too long, skip the optional parts