opencastle 0.1.0

package/src/orchestrator/agent-workflows/performance-optimization.md

@@ -0,0 +1,125 @@
+# Workflow: Performance Optimization
+
+Measure-first optimization workflow. Never optimize without profiling data.
+
+## Phases
+
+```
+Phase 1: Baseline Measurement    (sub-agent, inline)
+Phase 2: Analysis                (sub-agent, inline)
+Phase 3: Optimization            (background agents, parallel)
+Phase 4: Verification            (sub-agent, inline)
+Phase 5: Compound                (direct, Team Lead)
+```
+
+---
+
+## Branch & Delivery Strategy
+
+Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ownership** rules in `team-lead.agent.md`. Branch naming: `perf/<ticket-id>-<short-description>` or `feat/<ticket-id>-<short-description>`.
+
+---
+
+## Phase 1: Baseline Measurement
+
+**Agent:** Performance Expert (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Build the affected app(s) with production config
+2. Run Lighthouse audit on key pages
+3. Measure bundle size (`yarn nx run <app>:build` output)
+4. Record Core Web Vitals: LCP, FID/INP, CLS, TTFB
+5. Profile server-side rendering time
+6. Document baseline metrics
+
+### Key Pages to Measure
+
+> See `project.instructions.md` for the app inventory and key routes. Prioritize pages with the most traffic and the most complex rendering.
+
+### Exit Criteria
+
+- [ ] Baseline metrics recorded for all key pages
+- [ ] Bundle size documented
+- [ ] Lighthouse scores saved
+- [ ] Linear issue created with targets
+
+---
+
+## Phase 2: Analysis
+
+**Agent:** Performance Expert (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Identify the top 3 performance bottlenecks
+2. Analyze bundle composition (largest chunks)
+3. Check for unnecessary client-side JavaScript
+4. Review image optimization (WebP/AVIF, lazy loading, sizing)
+5. Check caching headers and ISR configuration
+6. Review database query performance (if applicable)
+7. Prioritize optimizations by impact/effort
+
+### Exit Criteria
+
+- [ ] Top 3 bottlenecks identified with evidence
+- [ ] Optimization plan created (ordered by impact)
+- [ ] Each optimization has expected improvement estimate
+- [ ] File partitions mapped for parallel work
+
+---
+
+## Phase 3: Optimization (Parallel)
+
+**Agents:** Varies by optimization type
+**Type:** Background agents (parallel where file partitions allow)
+
+### Typical Tracks
+
+| Track | Agent | Focus | Files |
+|-------|-------|-------|-------|
+| A: Bundle | Performance Expert | Code splitting, tree shaking, dynamic imports | `app/`, `libs/` |
+| B: Images | UI/UX Expert | Image optimization, lazy loading, srcset | `components/`, `public/` |
+| C: Queries | Developer | Query optimization, caching | Query library, framework config |
+| D: Database | Database Engineer | Index optimization, query planning | Database migrations |
+
+### Exit Criteria (per track)
+
+- [ ] Optimization implemented
+- [ ] Lint + test + build pass
+- [ ] Output contract with before/after metrics
+
+---
+
+## Phase 4: Verification
+
+**Agent:** Performance Expert (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Rebuild with production config
+2. Re-run Lighthouse on same pages as Phase 1
+3. Compare metrics: before vs. after
+4. Verify no visual regressions (browser test)
+5. Confirm no functional regressions (test suite)
+6. Document results
+
+### Exit Criteria
+
+- [ ] Metrics improved (or justified why not)
+- [ ] No visual regressions
+- [ ] No functional regressions
+- [ ] Results documented in Linear issue
+- [ ] Roadmap updated
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+
+---
+
+### Phase 5: Delivery (Compound)
+
+> **See [shared-delivery-phase.md](shared-delivery-phase.md) for the standard delivery steps.**
+>
+> Commit → Push → PR → Linear linkage. Team Lead owns delivery.

package/src/orchestrator/agent-workflows/refactoring.md

@@ -0,0 +1,142 @@
+# Workflow: Code Refactoring
+
+Structured workflow for safe code refactoring — improving code quality without changing behavior.
+
+## Phases
+
+```
+Phase 1: Scope & Baseline       (sub-agent, inline)
+Phase 2: Test Coverage Gap       (sub-agent or background)
+Phase 3: Refactor Implementation (sub-agent or background)
+Phase 4: Verification            (sub-agent, inline)
+Phase 5: Panel Review            (sub-agent, for large refactors)
+Phase 6: Compound                (direct, Team Lead)
+```
+
+---
+
+## Branch & Delivery Strategy
+
+Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ownership** rules in `team-lead.agent.md`. Branch naming: `refactor/<ticket-id>-<short-description>`.
+
+---
+
+## Phase 1: Scope & Baseline
+
+**Agent:** Team Lead (self)
+**Type:** Direct research
+
+### Steps
+
+1. Identify all files and modules in scope for refactoring
+2. Document current behavior (screenshots, test outputs, API responses)
+3. Run baseline tests: `yarn nx run <project>:test --coverage`
+4. Run baseline lint: `yarn nx run <project>:lint`
+5. Record baseline metrics (test count, coverage %, lint errors, bundle size)
+6. Create Linear issues for the refactoring scope
+
+### Exit Criteria
+
+- [ ] Scope documented with file list
+- [ ] Baseline metrics recorded
+- [ ] Linear issues created
+
+---
+
+## Phase 2: Test Coverage Gap
+
+**Agent:** Testing Expert
+**Type:** Sub-agent (inline) or background
+
+### Steps
+
+1. Analyze test coverage for all files in scope
+2. Write missing tests to cover existing behavior BEFORE refactoring
+3. Ensure every function/component being refactored has test coverage
+4. Run full test suite to confirm all new tests pass
+
+### Exit Criteria
+
+- [ ] All in-scope code has test coverage for existing behavior
+- [ ] No test failures
+- [ ] Coverage report saved
+
+---
+
+## Phase 3: Refactor Implementation
+
+**Agent:** Appropriate specialist (Developer, UI/UX Expert, etc.)
+**Type:** Sub-agent or background (depending on scope)
+
+### Steps
+
+1. Apply refactoring changes following project conventions
+2. Maintain all existing public APIs and behavior
+3. Run lint and type-check after each significant change
+4. Commit atomic changes (one concern per commit when possible)
+
+### File Partition
+
+The refactoring agent owns only the scoped files. No changes outside the partition.
+
+### Exit Criteria
+
+- [ ] Refactoring complete per scope
+- [ ] No lint or type errors
+- [ ] All tests still pass (same count, same behavior)
+
+---
+
+## Phase 4: Verification
+
+**Agent:** Team Lead (self) + Testing Expert
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Run full test suite: `yarn nx run <project>:test`
+2. Run lint: `yarn nx run <project>:lint`
+3. Run build: `yarn nx run <project>:build`
+4. Compare metrics against Phase 1 baseline (test count, coverage, bundle size)
+5. For UI refactors: start dev server and visually verify at all breakpoints
+6. Verify no regressions in dependent code
+
+### Exit Criteria
+
+- [ ] All tests pass (count >= baseline)
+- [ ] Coverage >= baseline
+- [ ] No new lint errors
+- [ ] Build succeeds
+- [ ] visual verification passed (for UI changes)
+
+---
+
+## Phase 5: Panel Review (Large Refactors)
+
+**Agent:** Panel (3 reviewers)
+**Type:** Sub-agent (inline)
+
+### When to use
+
+- Refactoring touches >10 files
+- Refactoring changes shared library interfaces
+- Refactoring affects authentication or security code
+
+### Steps
+
+1. Load **panel-majority-vote** skill
+2. Run panel with question: "Does this refactoring preserve all existing behavior while improving code quality?"
+3. On BLOCK: extract MUST-FIX items and re-delegate
+
+### Exit Criteria
+
+- [ ] Panel PASS (2/3 majority)
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+
+---
+
+### Phase 6: Delivery (Compound)
+
+> **See [shared-delivery-phase.md](shared-delivery-phase.md) for the standard delivery steps.**
+>
+> Commit → Push → PR → Linear linkage. Team Lead owns delivery.

package/src/orchestrator/agent-workflows/schema-changes.md

@@ -0,0 +1,164 @@
+# Workflow: Schema / CMS Changes
+
+Structured workflow for CMS schema modifications, query updates, and content model changes.
+
+> **Project config:** For CMS-specific paths, schema locations, and query library details, see the relevant CMS customization file (e.g., `sanity-config.md`).
+
+## Phases
+
+```
+Phase 1: Schema Analysis      (sub-agent, inline)
+Phase 2: Schema Implementation (sub-agent or background)
+Phase 3: Query Updates         (sub-agent, sequential)
+Phase 4: Page Integration      (sub-agent, sequential)
+Phase 5: Verification          (sub-agent, inline)
+Phase 6: Compound              (direct, Team Lead)
+```
+
+---
+
+## Branch & Delivery Strategy
+
+Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ownership** rules in `team-lead.agent.md`. Branch naming: `feat/<ticket-id>-<short-description>` or `chore/<ticket-id>-<short-description>`.
+
+---
+
+## Phase 1: Schema Analysis
+
+**Agent:** Content Engineer (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Read current CMS schema to understand existing types
+2. Check the data model documentation (see `docs-structure.md`) for field documentation
+3. Check the query library (see CMS customization) for queries that will be affected
+4. Verify schema changes don't conflict with existing content in the CMS
+5. Document field mapping (new vs existing fields)
+6. Create Linear issue with schema change details
+
+### Exit Criteria
+
+- [ ] Existing schema understood
+- [ ] Impact on data queries assessed
+- [ ] Impact on existing content assessed
+- [ ] Linear issue created
+- [ ] Approach decided (new type vs modify existing)
+
+---
+
+## Phase 2: Schema Implementation
+
+**Agent:** Content Engineer
+**Type:** Sub-agent (simple changes) or Background (complex schema additions)
+
+### File Partition
+
+> See the CMS customization file for project-specific paths.
+
+- CMS schema directory — schema type files
+- CMS config file — schema registry
+
+### Steps
+
+1. Create or modify schema type files using `defineType` / `defineField`
+2. Add validation rules where appropriate
+3. Update the schema index to register new types
+4. Deploy schema (see CMS customization for deploy command)
+5. Verify in CMS studio that the schema renders correctly
+6. Create any necessary content for new types
+
+### Exit Criteria
+
+- [ ] Schema files created/modified
+- [ ] Schema deployed successfully
+- [ ] Schema renders correctly in CMS Studio
+- [ ] Existing content not broken by changes
+- [ ] Output contract returned
+
+---
+
+## Phase 3: Query Updates
+
+**Agent:** Content Engineer or Developer (via sub-agent)
+**Type:** Sub-agent (sequential — depends on Phase 2)
+
+### File Partition
+
+> See the CMS customization file for project-specific query library paths.
+
+- Query library — data query files
+
+### Steps
+
+1. Update data queries to include new/modified fields
+2. Update TypeScript types for query results
+3. Test queries in the CMS query tool
+4. Run query library tests
+
+### Exit Criteria
+
+- [ ] Data queries updated
+- [ ] TypeScript types match schema
+- [ ] Queries tested in CMS query tool
+- [ ] Query tests pass
+- [ ] Output contract returned
+
+---
+
+## Phase 4: Page Integration
+
+**Agent:** Developer (via sub-agent)
+**Type:** Sub-agent (sequential — depends on Phase 3)
+
+### File Partition
+
+- Varies by feature — typically app page routes and shared UI components
+
+### Steps
+
+1. Update components to use new/modified fields
+2. Handle missing data gracefully (backwards compatibility)
+3. Run lint + test + build for affected projects
+4. Start dev server and verify in browser
+
+### Exit Criteria
+
+- [ ] Components updated
+- [ ] Missing data handled gracefully
+- [ ] Lint + test + build pass
+- [ ] Visual verification in browser
+- [ ] Output contract returned
+
+---
+
+## Phase 5: Verification
+
+**Agent:** Team Lead (self)
+**Type:** Direct verification
+
+### Steps
+
+1. Review all output contracts
+2. Verify in CMS that content can be created/edited
+3. Start dev server and verify pages render correctly
+4. Check both apps if shared schema/queries changed
+5. Verify data model documentation is updated
+6. Move Linear issue to Done
+
+### Exit Criteria
+
+- [ ] Schema works in CMS
+- [ ] Pages render correctly in browser
+- [ ] Both apps verified (if shared code changed)
+- [ ] Data model documentation updated (if applicable)
+- [ ] Linear issue moved to Done
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+
+---
+
+### Phase 6: Delivery (Compound)
+
+> **See [shared-delivery-phase.md](shared-delivery-phase.md) for the standard delivery steps.**
+>
+> Commit → Push → PR → Linear linkage. Team Lead owns delivery.

package/src/orchestrator/agent-workflows/security-audit.md

@@ -0,0 +1,148 @@
+# Workflow: Security Audit
+
+Comprehensive security review workflow for auth, RLS, headers, and API security.
+
+## Phases
+
+```
+Phase 1: Scope & Context      (sub-agent, inline)
+Phase 2: Automated Checks     (sub-agent, inline)
+Phase 3: Manual Review        (background agent)
+Phase 4: Panel Review         (sub-agent, inline)
+Phase 5: Remediation          (sub-agent or background)
+Phase 6: Compound             (direct, Team Lead)
+```
+
+---
+
+## Branch & Delivery Strategy
+
+Follow the **Delivery Outcome** in `general.instructions.md` and the **Branch Ownership** rules in `team-lead.agent.md`. Branch naming: `fix/<ticket-id>-<short-description>` for remediations.
+
+---
+
+## Phase 1: Scope & Context
+
+**Agent:** Team Lead (self)
+**Type:** Direct research
+
+### Steps
+
+1. Define audit scope (full audit vs. targeted area)
+2. Read `docs/PROJECT.md` security sections
+3. Read `docs/KNOWN-ISSUES.md` for existing security items
+4. Check current CSP configuration in `next.config.js`
+5. Review auth flow (see database/auth customization for library paths)
+6. Map all API routes and Server Actions
+7. Create Linear issue for the audit
+
+### Exit Criteria
+
+- [ ] Scope defined (which apps, libs, routes)
+- [ ] Existing security docs reviewed
+- [ ] Attack surface mapped
+- [ ] Linear issue created
+
+---
+
+## Phase 2: Automated Checks
+
+**Agent:** Security Expert (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Run lint with security rules
+2. Check for hardcoded secrets (`grep -r "password\|secret\|api_key"`)
+3. Validate CSP headers
+4. Check dependency vulnerabilities (`yarn audit`)
+5. Verify RLS is enabled on all database tables
+6. Check for `dangerouslySetInnerHTML` usage
+
+### Exit Criteria
+
+- [ ] No hardcoded secrets found
+- [ ] CSP headers valid
+- [ ] Dependency audit clean (or known issues documented)
+- [ ] RLS enabled on all tables
+- [ ] No unsafe HTML injection points
+- [ ] Findings documented
+
+---
+
+## Phase 3: Manual Review
+
+**Agent:** Security Expert
+**Type:** Background agent
+
+### Checklist
+
+- [ ] **Authentication:** Session handling, token refresh, logout flow
+- [ ] **Authorization:** Role checks, route protection, middleware
+- [ ] **RLS Policies:** Default-deny, explicit-allow, policy correctness
+- [ ] **Input Validation:** Zod schemas on all API routes and Server Actions
+- [ ] **CSRF Protection:** Server Actions use form tokens
+- [ ] **Rate Limiting:** Proxy layer, per-IP limits, fingerprinting
+- [ ] **Error Handling:** No sensitive data in error responses
+- [ ] **OAuth:** Callback URLs, state parameter, PKCE
+- [ ] **Headers:** HSTS, X-Content-Type-Options, X-Frame-Options
+- [ ] **Cookies:** HttpOnly, Secure, SameSite flags
+
+### Exit Criteria
+
+- [ ] All checklist items reviewed
+- [ ] Findings categorized by severity
+- [ ] Output contract returned with findings list
+
+---
+
+## Phase 4: Panel Review
+
+**Agent:** Team Lead (orchestrates panel)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Load **panel-majority-vote** skill
+2. Provide Phase 3 findings and affected files as in-scope artifacts
+3. Panel question: "Are there any unmitigated security vulnerabilities in the reviewed code?"
+4. Run 3 reviewer sub-agents
+5. Consolidate results
+
+### Exit Criteria
+
+- [ ] Panel completed (PASS or BLOCK)
+- [ ] Panel report linked to Linear issue
+- [ ] If BLOCK: MUST-FIX items extracted
+
+---
+
+## Phase 5: Remediation
+
+**Agent:** Security Expert or Developer (depends on finding)
+**Type:** Sub-agent (critical fixes) or Background (non-critical)
+
+### Steps
+
+1. Fix Critical and High severity findings first
+2. Create separate Linear issues for Medium/Low findings if not fixing now
+3. Run verification after each fix
+4. Re-run panel review if initial panel BLOCKed
+5. Update `docs/KNOWN-ISSUES.md` for any accepted risks
+
+### Exit Criteria
+
+- [ ] Critical/High findings remediated
+- [ ] Medium/Low findings tracked in Linear
+- [ ] Panel review passed (if applicable)
+- [ ] Known issues updated for accepted risks
+- [ ] All Linear issues updated
+- [ ] Delivery Outcome completed (see `general.instructions.md`) — branch pushed, PR opened (not merged), Linear linked
+
+---
+
+### Phase 6: Delivery (Compound)
+
+> **See [shared-delivery-phase.md](shared-delivery-phase.md) for the standard delivery steps.**
+>
+> Commit → Push → PR → Linear linkage. Team Lead owns delivery.

package/src/orchestrator/agent-workflows/shared-delivery-phase.md

@@ -0,0 +1,33 @@
+# Shared Delivery Phase
+
+This phase is referenced by all workflow templates. It covers the final delivery steps after all implementation and verification is complete.
+
+## Steps
+
+1. **Commit all changes** to the feature branch with Linear issue IDs in commit messages
+2. **Push the branch** to origin: `git push -u origin <branch-name>`
+3. **Open a PR** using `gh` CLI (always use `GH_PAGER=cat` to prevent pager issues):
+   ```bash
+   GH_PAGER=cat gh pr create --base main --title "TAS-XX: Short description" --body "Resolves TAS-XX"
+   ```
+4. **Do NOT merge** — PRs are opened for human review only
+5. **Update Linear issues** with the PR URL for traceability
+6. **Clean up session checkpoint** if one exists
+
+## Branch & Delivery Strategy
+
+The **Team Lead owns delivery**, not individual specialist agents:
+
+- **Team Lead creates the branch** in Phase 1 before any delegation
+- **Sub-agents** work directly on the Team Lead's branch (shared working tree)
+- **Background agents** work in isolated worktrees branched from the feature branch
+- **Team Lead merges worktrees back** during verification
+- **Only the Team Lead pushes** to the branch and opens the PR
+
+## Exit Criteria
+
+- [ ] All changes committed with Linear issue IDs in messages
+- [ ] Branch pushed to origin
+- [ ] PR opened on GitHub (NOT merged)
+- [ ] Linear issues updated with PR URL
+- [ ] All project issues marked Done or Cancelled

package/src/orchestrator/agents/api-designer.agent.md

@@ -0,0 +1,68 @@
+---
+description: 'API designer for route architecture, endpoint conventions, request/response schemas, versioning strategy, and API documentation.'
+name: 'API Designer'
+model: Gemini 3.1 Pro
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
+---
+
+# API Designer
+
+You are an API designer specializing in route architecture, endpoint conventions, request/response schemas, versioning, error handling patterns, and API documentation.
+
+## Critical Rules
+
+1. **Design before implementing** — define the contract (request/response shapes, status codes, errors) before writing handler code
+2. **Consistent conventions** — all endpoints follow the same naming, error format, and pagination pattern
+3. **Validate everything** — every endpoint has input validation schemas; never trust client input
+4. **Version from the start** — design for backward compatibility; breaking changes require a new version
+
+## Skills
+
+### Capability Slots
+
+Resolve via [skill-matrix.md](.github/customizations/agents/skill-matrix.md).
+
+- **api-layer** — Route handler patterns, server-side actions, validation libraries, search API architecture
+- **framework** — Framework routing conventions, middleware, request lifecycle
+- **security** — Input validation, authentication, authorization, rate limiting
+
+## API Design Principles
+
+Load the **api-patterns** skill for comprehensive API design guidelines covering route architecture, request/response schemas, error handling, pagination, versioning, and rate limiting.
+
+## Guidelines
+
+- Audit existing API routes before designing new ones — maintain consistency
+- Document every endpoint with method, path, request schema, response schema, and error cases
+- Consider the consumer's perspective — what makes this API easy to use?
+- Design for both internal (app) and potential external (public API) consumers
+- Coordinate with Database Engineer for query efficiency behind endpoints
+- Coordinate with Security Expert for authentication and authorization patterns
+
+## Done When
+
+- API contract is fully defined (routes, methods, request/response schemas, error cases)
+- Zod schemas are created for all inputs and outputs
+- Route handlers are implemented following the framework's conventions
+- Error handling is consistent across all endpoints
+- API documentation is generated or written
+- Existing endpoint conventions are maintained
+
+## Out of Scope
+
+- Database schema design or migrations (define data needs, not table structure)
+- Frontend integration (design the contract, not the consumer)
+- Load testing or performance benchmarking
+- Authentication provider setup (use existing auth patterns)
+
+## Output Contract
+
+When completing a task, return a structured summary:
+
+1. **Endpoints** — List each endpoint with method, path, and purpose
+2. **Schemas** — Request/response Zod schemas created or modified
+3. **Error Cases** — Error codes and status codes for each endpoint
+4. **Verification** — Lint, type-check, and test results
+5. **Documentation** — API docs produced or updated
+
+See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).