opencastle 0.1.0

package/src/dashboard/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "strictNullChecks": true
+  }
+}

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

@@ -0,0 +1,22 @@
+# Workflow Templates
+
+Declarative workflow templates for common orchestration patterns. Inspired by Sandcastle's YAML workflow engine, these templates provide reproducible execution plans that the Team Lead and prompts can reference.
+
+## How to Use
+
+1. **Reference in prompts** — When delegating, cite the relevant template and phase
+2. **Customize per task** — Templates define the structure; fill in specific files, agents, and criteria
+3. **Track progress** — Use the phase structure to update session checkpoints
+
+## Available Templates
+
+| Template | Use Case |
+|----------|----------|
+| [Feature Implementation](feature-implementation.md) | Multi-layer features spanning DB → Query → UI → Tests |
+| [Bug Fix](bug-fix.md) | Triage → RCA → Fix → Verify workflow |
+| [Data Pipeline](data-pipeline.md) | Scrape → Convert → Enrich → Validate → Import |
+| [Security Audit](security-audit.md) | Comprehensive security review workflow |
+| [Performance Optimization](performance-optimization.md) | Measure → Analyze → Optimize → Verify |
+| [Schema Changes](schema-changes.md) | CMS schema modifications, query updates, content model changes |
+| [Database Migration](database-migration.md) | Database migrations, RLS policies, type generation, rollback |
+| [Refactoring](refactoring.md) | Safe code refactoring with baseline metrics and behavior preservation |

package/src/orchestrator/agent-workflows/bug-fix.md

@@ -0,0 +1,128 @@
+# Workflow: Bug Fix
+
+Structured workflow for investigating and fixing reported bugs.
+
+## Phases
+
+```
+Phase 1: Triage & Reproduce    (sub-agent, inline)
+Phase 2: Root Cause Analysis    (sub-agent, inline)
+Phase 3: Fix Implementation     (sub-agent or background)
+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: `fix/<ticket-id>-<short-description>`.
+
+---
+
+## Phase 1: Triage & Reproduce
+
+**Agent:** Team Lead (self)
+**Type:** Direct research
+
+### Steps
+
+1. Check `docs/KNOWN-ISSUES.md` for existing entry
+2. Check Linear for existing bug ticket
+3. Read `.github/customizations/LESSONS-LEARNED.md` for related pitfalls
+4. **Reproduce the bug** — this is mandatory before any fix attempt:
+   a. Start the dev server: `yarn nx run <app>:serve`
+   b. Navigate to the affected page in Chrome
+   c. Follow the reproduction steps from the bug report
+   d. **Confirm the failure** — screenshot the broken state as evidence
+   e. If the bug **cannot be reproduced**, document what was tried and ask the reporter for more detail. Do NOT proceed to Phase 2 without reproduction
+5. Assess severity (Critical/High/Medium/Low)
+6. Create Linear issue with `[Bug]` prefix and `bug` label, including reproduction steps and screenshot
+
+### Exit Criteria
+
+- [ ] Bug **confirmed reproduced** with screenshot evidence (or documented as non-reproducible with investigation notes)
+- [ ] Severity assessed
+- [ ] Linear issue created with reproduction steps and screenshot
+- [ ] Affected apps identified (see `project.instructions.md` for inventory)
+
+---
+
+## Phase 2: Root Cause Analysis
+
+**Agent:** Specialist (based on bug domain — Developer, Security Expert, etc.)
+**Type:** Sub-agent (inline, result needed for Phase 3)
+
+### Steps
+
+1. Search codebase for components, queries, and logic involved
+2. Trace data flow from source → query → component → render
+3. Check `git log` on suspected files for recent changes
+4. Identify root cause category:
+   - Code bug (logic error, missing null check)
+   - Data issue (unexpected shape, missing field)
+   - Race condition (timing, hydration mismatch)
+   - CSS/Layout (specificity, overflow, responsive)
+   - Integration (API contract mismatch, schema drift)
+5. Update Linear issue with root cause and affected files
+
+### Exit Criteria
+
+- [ ] Root cause identified and documented
+- [ ] Affected files listed (defines the fix partition)
+- [ ] Fix approach decided
+
+---
+
+## Phase 3: Fix Implementation
+
+**Agent:** Specialist (same as Phase 2)
+**Type:** Sub-agent (simple fix) or Background (complex fix)
+
+### Steps
+
+1. Implement the fix within the identified file partition
+2. Add or update tests covering the bug scenario
+3. Run lint + test + build for affected projects
+4. Return output contract
+
+### Exit Criteria
+
+- [ ] Fix implemented
+- [ ] Test covering the bug added
+- [ ] Lint + test + build pass
+- [ ] Output contract returned
+
+---
+
+## Phase 4: Verification
+
+**Agent:** Team Lead (self)
+**Type:** Direct verification
+
+### Steps
+
+1. Review the output contract
+2. Start dev server with clean cache
+3. Verify the bug is fixed in Chrome (screenshot the working state)
+4. Test adjacent features for regressions
+5. If security-related: schedule panel review
+6. Move Linear issue to Done
+7. Update `docs/KNOWN-ISSUES.md` if the bug was listed there
+8. Commit and push
+
+### Exit Criteria
+
+- [ ] Bug confirmed fixed with screenshot
+- [ ] No regressions introduced
+- [ ] Linear issue moved to Done
+- [ ] Known issues updated (if applicable)
+- [ ] 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/data-pipeline.md

@@ -0,0 +1,145 @@
+# Workflow: Data Pipeline
+
+Standard execution plan for scraping, processing, and importing data.
+
+> **Project config:** For project-specific paths, data schema, CLI commands, and processing rules, see `data-pipeline-config.md`. For data model docs, see `docs-structure.md`.
+
+## Phases
+
+```
+Phase 1: Source Analysis    (sub-agent, inline)
+Phase 2: Scraping           (background agent)
+Phase 3: Processing         (sub-agent, sequential)
+Phase 4: Validation         (sub-agent, inline)
+Phase 5: Import             (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>`. Only code changes are committed — NDJSON data files in `tmp/` are NOT committed to Git.
+
+---
+
+## Phase 1: Source Analysis
+
+**Agent:** Data Expert (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Analyze the target data source (website, API, file)
+2. Identify data fields available and their mapping to the place schema
+3. Check the data model documentation (see `docs-structure.md`) for required fields
+4. Estimate record count
+5. Check for existing scraper patterns (see **data-engineering** skill)
+6. Create Linear issue with data source details
+
+### Exit Criteria
+
+- [ ] Source structure documented
+- [ ] Field mapping defined (source field → target field)
+- [ ] Estimated record count
+- [ ] Linear issue created
+- [ ] Scraper approach decided (Puppeteer, fetch, API)
+
+---
+
+## Phase 2: Scraping
+
+**Agent:** Data Expert
+**Type:** Background agent (may be long-running)
+
+### Steps
+
+1. Implement scraper following existing patterns (see `data-pipeline-config.md`)
+2. Output raw data as NDJSON
+3. Handle pagination, rate limiting, and error recovery
+4. Log scraping statistics (pages visited, records extracted, errors)
+
+### Exit Criteria
+
+- [ ] Raw NDJSON file produced
+- [ ] Scraping statistics logged
+- [ ] No duplicate records
+- [ ] Output contract returned
+
+---
+
+## Phase 3: Processing
+
+**Agent:** Data Expert (via sub-agent)
+**Type:** Sub-agent (sequential — depends on Phase 2 output)
+
+### Steps
+
+1. Convert raw data to the target schema format
+2. Enrich with geocoding, slug generation, image optimization
+3. Normalize text fields (see data-pipeline-config.md for rules)
+4. Validate against place schema
+5. Output processed NDJSON
+
+### Exit Criteria
+
+- [ ] Processed NDJSON matches place schema
+- [ ] All required fields present
+- [ ] Slugs are unique
+- [ ] Geocoding complete
+- [ ] Pipeline tests pass: `yarn nx run data-pipeline:test`
+- [ ] Output contract returned with quality metrics
+
+---
+
+## Phase 4: Validation
+
+**Agent:** Team Lead (self)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Spot-check 10-20 records manually
+2. Run validation script against full dataset
+3. Check for duplicates against existing data
+4. Verify image URLs are accessible
+5. Confirm field mapping accuracy
+
+### Exit Criteria
+
+- [ ] Spot check passed
+- [ ] Validation script reports <1% error rate
+- [ ] No duplicates with existing data
+- [ ] Images accessible
+
+---
+
+## Phase 5: Import
+
+**Agent:** Data Expert (via sub-agent)
+**Type:** Sub-agent (inline — need immediate feedback)
+
+### Steps
+
+1. Import small test batch (5-10 records) first
+2. Verify in CMS
+3. Import full dataset
+4. Log import statistics (created, updated, skipped, failed)
+5. Update Linear issue and roadmap
+
+### Exit Criteria
+
+- [ ] Test batch verified in CMS
+- [ ] Full import complete
+- [ ] Import statistics logged
+- [ ] <0.1% failure rate
+- [ ] Output contract returned
+- [ ] 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/database-migration.md

@@ -0,0 +1,159 @@
+# Workflow: Database Migration
+
+Structured workflow for database schema changes, RLS policies, and data migrations.
+
+> **Project config:** For database-specific paths, schema details, and migration conventions, see the relevant database customization file (e.g., `supabase-config.md`).
+
+## Phases
+
+```
+Phase 1: Migration Planning     (sub-agent, inline)
+Phase 2: Migration Implementation (sub-agent or background)
+Phase 3: Type Generation        (sub-agent, sequential)
+Phase 4: Code Integration       (sub-agent, sequential)
+Phase 5: Verification & Rollback Test (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 `fix/<ticket-id>-<short-description>`.
+
+---
+
+## Phase 1: Migration Planning
+
+**Agent:** Database Engineer (via sub-agent)
+**Type:** Sub-agent (inline)
+
+### Steps
+
+1. Read current schema in the migrations directory (see database customization) to understand existing tables
+2. Check existing RLS policies using the database query tool
+3. Read `docs/PROJECT.md` for database architecture
+4. Check `docs/KNOWN-ISSUES.md` for database-related limitations
+5. Document the migration plan: tables affected, columns added/removed, RLS changes
+6. Write rollback strategy (how to reverse the migration)
+7. Create Linear issue with migration details and rollback plan
+
+### Exit Criteria
+
+- [ ] Current schema understood
+- [ ] Migration plan documented
+- [ ] Rollback strategy defined
+- [ ] Impact on existing data assessed
+- [ ] Linear issue created with rollback plan
+
+---
+
+## Phase 2: Migration Implementation
+
+**Agent:** Database Engineer
+**Type:** Sub-agent (simple changes) or Background (complex migrations)
+
+### File Partition
+
+> See the database customization file for project-specific migration paths.
+
+- Migrations directory — migration SQL files
+
+### Steps
+
+1. Create migration file following naming convention: `YYYYMMDDHHMMSS_description.sql`
+2. Write idempotent SQL (can safely re-run)
+3. Include RLS policies for any new tables — default deny, explicit allow
+4. Add indexes for frequently queried columns
+5. Include SQL comments documenting the purpose
+6. Apply migration using the database MCP tool
+7. Verify migration applied successfully
+
+### Exit Criteria
+
+- [ ] Migration file created with idempotent SQL
+- [ ] RLS policies included for new tables
+- [ ] Indexes added for query columns
+- [ ] Migration applied successfully
+- [ ] Rollback SQL tested (or documented)
+- [ ] Output contract returned
+
+---
+
+## Phase 3: Type Generation
+
+**Agent:** Database Engineer (via sub-agent)
+**Type:** Sub-agent (sequential — depends on Phase 2)
+
+### Steps
+
+1. Generate updated TypeScript types using the database MCP tool
+2. Update any local type files that reference the changed tables
+3. Verify types compile correctly
+
+### Exit Criteria
+
+- [ ] TypeScript types regenerated
+- [ ] Types compile without errors
+- [ ] Output contract returned
+
+---
+
+## Phase 4: Code Integration
+
+**Agent:** Developer (via sub-agent)
+**Type:** Sub-agent (sequential — depends on Phase 3)
+
+### File Partition
+
+- Varies by feature — typically Server Actions, API routes, React components
+
+### Steps
+
+1. Update Server Actions / API routes to use new schema
+2. Update components to handle new data fields
+3. Run lint + test + build for affected projects
+4. Start dev server and test in browser
+
+### Exit Criteria
+
+- [ ] Server Actions updated
+- [ ] Components updated
+- [ ] Lint + test + build pass
+- [ ] Browser verification complete
+- [ ] Output contract returned
+
+---
+
+## Phase 5: Verification & Rollback Test
+
+**Agent:** Team Lead (self)
+**Type:** Direct verification
+
+### Steps
+
+1. Review all output contracts from Phases 2–4
+2. Verify RLS policies from different user roles (anon, authenticated, admin)
+3. Spot-check data using the database query tool
+4. Start dev server and verify end-to-end functionality
+5. **Security check:** If the migration touches auth or RLS, schedule panel review
+6. Document rollback procedure in Linear issue
+7. Move Linear issue to Done
+
+### Exit Criteria
+
+- [ ] RLS policies tested from multiple roles
+- [ ] Data integrity verified
+- [ ] End-to-end flow works in browser
+- [ ] Panel review passed (if auth/RLS changes)
+- [ ] Rollback procedure documented
+- [ ] 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/feature-implementation.md

@@ -0,0 +1,223 @@
+# Workflow: Feature Implementation
+
+Standard execution plan for multi-layer features. Customize file paths, agents, and criteria per task.
+
+## Phases
+
+```
+Phase 0: Brainstorm      (sub-agent or direct, optional)
+Phase 1: Research        (sub-agent, inline)
+Phase 2: Foundation      (background agents, parallel)
+Phase 3: Integration     (sub-agent, sequential)
+Phase 4: Validation      (background agents, parallel)
+Phase 5: QA Gate         (sub-agent, inline)
+Phase 6: Compound        (direct, Team Lead)
+```
+
+---
+
+## State Tracking
+
+Every Team Lead response during feature work **must** end with a state block. This enables context recovery after interruption and keeps the user informed:
+
+```
+📍 Phase 2/6 — Foundation | Progress: 3/7 issues | Budget: 2/7 delegations
+   Last: ✅ TAS-42 schema deployed (Content Engineer)
+   Next: Delegate TAS-43 migration (DB Engineer)
+   Cost: ~45K tokens (Standard×2)
+```
+
+Fields: current phase, issues completed/total, delegations used/budget, last completed action, next planned action, running estimated token cost.
+
+---
+
+## Branch Strategy
+
+1. **Team Lead creates the feature branch** in Phase 1 before any delegation: `git checkout -b feat/<ticket-id>-<short-description>`
+2. **Sub-agents** work directly on the feature branch (they share the Team Lead’s working tree)
+3. **Background agents** work in isolated worktrees branched from the feature branch
+4. **Team Lead merges worktrees back** in Phase 5 (QA Gate) after verifying each background agent’s output
+5. **Only the Team Lead pushes** to the feature branch and opens the PR
+
+---
+
+## Phase 0: Brainstorm (Optional)
+
+**Agent:** Team Lead (self)
+**Type:** Direct or sub-agent
+**Blocking:** No — skip when the approach is obvious
+
+Run the `brainstorm` prompt when the task has ambiguity, multiple valid approaches, or significant design decisions. Skip for well-defined tasks with obvious implementation paths.
+
+### Steps
+
+1. Clarify the problem — restate, surface assumptions
+2. Explore solution space — search existing code, check docs
+3. Generate 2-3 alternative approaches with trade-offs
+4. Recommend an approach with rationale
+5. Define scope boundaries (in/out/deferred)
+
+### Exit Criteria
+
+- [ ] Problem clearly understood
+- [ ] Alternatives explored
+- [ ] Approach chosen with rationale
+- [ ] Scope boundaries defined
+- [ ] Brainstorm report produced (feeds into Phase 1)
+
+---
+
+## Phase 1: Research & Planning
+
+**Agent:** Team Lead (self)
+**Type:** Sub-agent or direct
+**Blocking:** Yes — all other phases depend on this
+
+### Steps
+
+1. Read `docs/PROJECT.md`, `docs/KNOWN-ISSUES.md`, `.github/customizations/LESSONS-LEARNED.md`
+2. Search codebase for existing implementations
+3. Identify affected apps, libs, and layers
+4. **Spec flow analysis** — Trace the complete user flow end-to-end and identify:
+   - All user-visible states (loading, empty, populated, error, partial)
+   - State transitions and what triggers them
+   - Edge cases (network failure, invalid data, concurrent access, empty collections)
+   - Missing paths in the spec ("what happens when X?")
+   - Accessibility flows (keyboard navigation, screen reader announcements)
+   - Document findings as acceptance criteria on the Linear issues
+5. Decompose into Linear issues with file partitions
+6. **Surface Open Questions** — Collect ambiguities, design choices, and assumptions that need user input. Present as a structured list for approval before proceeding.
+7. Create session checkpoint
+
+### Open Questions Gate
+
+> **MANDATORY STOP.** Do not proceed to Phase 2 until the user has answered all open questions.
+
+After decomposition, present a structured list of open questions. Each question should:
+- State the decision needed clearly
+- Offer 2-3 concrete options with brief trade-offs
+- Flag a recommended option if one is obvious
+
+```markdown
+**Open Questions (answer before implementation begins):**
+1. [Question]? Option A (trade-off) / Option B (trade-off) / **Recommended: A**
+2. [Question]? Option A / Option B
+```
+
+If there are no open questions, explicitly state: "No open questions — plan is unambiguous."
+
+### Exit Criteria
+
+- [ ] All relevant docs read
+- [ ] **User flow traced** — all states, transitions, and edge cases documented
+- [ ] Linear issues created for every subtask (including edge case coverage)
+- [ ] File partitions mapped (no overlaps)
+- [ ] Dependencies identified
+- [ ] **Open questions answered** by user (or none identified)
+- [ ] Session checkpoint saved
+
+---
+
+## Phase 2: Foundation (Parallel)
+
+**Agents:** Varies by task (DB Engineer, Content Engineer, UI Expert)
+**Type:** Background agents (parallel)
+**Blocking:** Phase 3 depends on this
+
+### Typical Partitions
+
+> For project-specific paths, see `project.instructions.md` and the relevant `stack/` customization files.
+
+| Track | Agent | Files | Purpose |
+|-------|-------|-------|----------|
+| A: Schema | Content Engineer | CMS schema directory | CMS schema changes |
+| B: Database | Database Engineer | Database migrations directory | Migration + RLS policies |
+| C: Components | UI/UX Expert | Shared component library | New UI components |
+
+### Exit Criteria (per track)
+
+- [ ] Schema deployed or migration applied
+- [ ] Type definitions generated
+- [ ] Lint + test pass
+- [ ] Output contract returned
+
+---
+
+## Phase 3: Integration (Sequential)
+
+**Agent:** Developer
+**Type:** Sub-agent (needs Phase 2 results)
+**Blocking:** Phase 4 depends on this
+
+### Steps
+
+1. Wire new components to data queries
+2. Update data queries (see relevant skill for query library location)
+3. Integrate into page routes
+4. Add loading/error states
+5. Run lint + test + build
+
+### Exit Criteria
+
+- [ ] Feature works end-to-end (data → query → component → page)
+- [ ] Loading and error states implemented
+- [ ] All affected projects build
+- [ ] Output contract returned
+
+---
+
+## Phase 4: Validation (Parallel)
+
+**Agents:** Testing Expert, Security Expert, Documentation Writer
+**Type:** Background agents (parallel)
+
+### Tracks
+
+| Track | Agent | Focus |
+|-------|-------|-------|
+| A: Tests | Testing Expert | Unit tests, E2E browser tests |
+| B: Security | Security Expert | RLS audit, input validation, auth check |
+| C: Docs | Documentation Writer | Roadmap, ADRs, known issues |
+
+### Exit Criteria (per track)
+
+- [ ] 95% test coverage on new code
+- [ ] Browser screenshots at all breakpoints
+- [ ] Security audit passes (or panel review scheduled)
+- [ ] Documentation updated
+- [ ] Output contracts returned
+
+---
+
+## Phase 5: QA Gate
+
+**Agent:** Team Lead (self)
+**Type:** Sub-agent (inline)
+**Blocking:** Must pass before merge
+
+### Steps
+
+1. Review all output contracts from Phases 2-4
+2. Run full lint + test + build across all affected projects
+3. Verify no files outside partitions were modified
+4. Check all Linear issue acceptance criteria
+5. Run panel review if high-stakes (security, DB, architecture)
+6. Move all issues to Done
+7. Update session checkpoint → delete checkpoint
+8. Update `docs/ROADMAP-POST-MVP.md`
+
+### Exit Criteria
+
+- [ ] All phases verified
+- [ ] All Linear issues Done
+- [ ] Full build passes
+- [ ] Roadmap 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.