opencastle 0.1.0

package/src/orchestrator/skills/context-map/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: context-map
+description: "Generate a structured file impact map before making changes. Identifies all files that will be affected, their relationships, and cascade effects — improving file partitioning for parallel work and reducing unexpected side effects."
+---
+
+# Skill: Context Map
+
+Generate a structured **file impact map** before any code changes begin. This map identifies all files that will be touched, their relationships, and cascade effects — directly improving the Team Lead's file partitioning for parallel agents.
+
+## When to Use
+
+- Before **every feature implementation** (Phase 1: Research)
+- Before **refactoring** (Phase 1: Scope & Baseline)
+- Before **schema changes** that cascade through queries and components
+- Before **any task touching shared libraries** (`libs/`)
+- Optional for isolated bug fixes affecting 1-2 files
+
+## How to Generate a Context Map
+
+### Step 1: Identify the Entry Points
+
+Start from the task description and identify the primary files that MUST change:
+
+```
+Entry Points:
+- [file path] — [why it must change]
+- [file path] — [why it must change]
+```
+
+### Step 2: Trace Dependencies (Outward)
+
+For each entry point, trace what depends on it:
+
+1. **Imports** — what files import this module? (`grep_search` or `list_code_usages`)
+2. **Type consumers** — what files use types/interfaces defined here?
+3. **Route references** — what pages render this component?
+4. **Query consumers** — what components or pages call this query?
+5. **Test files** — what test files cover this code?
+
+### Step 3: Trace Sources (Inward)
+
+For each entry point, trace what it depends on:
+
+1. **Data sources** — which Sanity schemas, GROQ queries, or Supabase tables feed this code?
+2. **Shared utilities** — which `libs/` modules does it use?
+3. **Configuration** — which config files affect its behavior?
+
+### Step 4: Build the Map
+
+Produce a structured map in this format:
+
+```markdown
+## Context Map: [Task Name]
+
+### Entry Points (MUST change)
+| File | Reason | Owner |
+|------|--------|-------|
+| `libs/queries/src/lib/places.ts` | Add new query field | Content Engineer |
+| `libs/ui-kit/src/lib/components/PlaceCard/` | Display new field | UI/UX Expert |
+
+### Cascade Effects (WILL change)
+| File | Triggered By | Reason | Owner |
+|------|-------------|--------|-------|
+| `apps/tastebeer.eu/app/places/page.tsx` | PlaceCard change | Update props | Frontend Dev |
+| `apps/tastecoffee.eu/app/places/page.tsx` | PlaceCard change | Update props | Frontend Dev |
+| `libs/queries/src/lib/__tests__/places.test.ts` | Query change | Update test | Testing Expert |
+
+### Shared Boundaries (WATCH for conflicts)
+| File | Risk | Mitigation |
+|------|------|------------|
+| `libs/ui-kit/src/lib/index.ts` | Barrel export — may conflict | Merge sequentially |
+
+### Unaffected (explicitly safe)
+| Area | Why |
+|------|-----|
+| `supabase/migrations/` | No DB changes |
+| `libs/supabase-auth/` | No auth changes |
+| `apps/cms-studio/` | No schema changes |
+```
+
+### Step 5: Derive File Partitions
+
+From the context map, assign file ownership to agents:
+
+```
+Agent A (Content Engineer):    libs/queries/src/lib/places.ts
+Agent B (UI/UX Expert):     libs/ui-kit/src/lib/components/PlaceCard/
+Agent C (Frontend Dev):      apps/tastebeer.eu/app/places/, apps/tastecoffee.eu/app/places/
+Agent D (Testing Expert):   **/*test*, **/*spec*
+```
+
+**Rules:**
+- No file appears in two partitions
+- Shared boundaries are assigned to ONE agent and merged first
+- Test files belong to the Testing Expert unless tightly coupled to a specific change
+
+## Context Map Depth Levels
+
+Scale the depth to the task complexity:
+
+| Task Complexity | Depth | What to Trace |
+|----------------|-------|---------------|
+| **Small** (1-3 files) | Entry points only | Direct imports/exports |
+| **Medium** (4-8 files) | Entry + cascade | 1 hop of dependencies |
+| **Large** (9+ files) | Full map | Complete dependency graph |
+
+## Integration with Team Lead Workflow
+
+The context map is produced in **Phase 1 (Research)** and consumed by:
+
+1. **Decomposition (Step 2)** — the map directly informs file partitions
+2. **Delegation prompts** — include the relevant section of the map so agents know their boundaries
+3. **Verification (QA Gate)** — compare actual changed files against the map to detect scope creep
+
+### Including in Delegation Prompts
+
+```markdown
+## Your File Partition (from Context Map)
+
+You own these files — modify only these:
+- `libs/queries/src/lib/places.ts`
+- `libs/queries/src/lib/__tests__/places.test.ts`
+
+Do NOT modify:
+- `libs/ui-kit/` (owned by UI/UX Expert)
+- `apps/` (owned by Developer)
+```
+
+## Anti-Patterns
+
+- **Skipping the map for "obvious" tasks** — even small tasks can have unexpected cascades in shared libraries
+- **Mapping without searching** — don't guess dependencies; use `grep_search`, `list_code_usages`, and import tracing
+- **Over-mapping** — for a 2-file bug fix, don't trace the entire dependency graph. Match depth to complexity
+- **Stale maps** — if the plan changes during execution, update the map. A stale map is worse than no map
+- **Mapping files you won't change** — the "Unaffected" section is for explicitly noting what's safe, not for cataloging the entire codebase

package/src/orchestrator/skills/convex-database/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: convex-database
+description: "Convex reactive database patterns, schema design, real-time queries, mutations, actions, and deployment best practices. Use when designing Convex schemas, writing queries/mutations, or managing the Convex backend."
+---
+
+# Convex Database
+
+Generic Convex development methodology. For project-specific schema, functions, and deployment details, see [database-config.md](../../customizations/stack/database-config.md).
+
+## Critical Development Rules
+
+1. **Schema-first design** — define schema in `convex/schema.ts` using `defineSchema` and `defineTable`
+2. **Queries are reactive** — Convex queries automatically re-run when underlying data changes
+3. **Mutations are transactional** — mutations run as ACID transactions; leverage this for consistency
+4. **Actions for side effects** — use actions (not mutations) for external API calls, file uploads, etc.
+5. **Never await queries in mutations** — queries and mutations run in separate contexts
+6. **Use validators** — validate all function arguments with `v` (Convex's validator library)
+7. **Index design** — create indexes for frequently filtered/sorted fields in the schema
+8. **Paginated queries** — use `.paginate()` for large result sets
+9. **File storage** — use Convex's built-in file storage API, not external services
+10. **Environment variables** — set via Convex dashboard, access with `process.env` in actions only
+
+## Schema Patterns
+
+### Defining Tables
+```typescript
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  users: defineTable({
+    name: v.string(),
+    email: v.string(),
+    role: v.union(v.literal("admin"), v.literal("user")),
+  }).index("by_email", ["email"]),
+});
+```
+
+### Query Functions
+```typescript
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+export const list = query({
+  args: { role: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    if (args.role) {
+      return await ctx.db.query("users").filter(q => q.eq(q.field("role"), args.role)).collect();
+    }
+    return await ctx.db.query("users").collect();
+  },
+});
+```
+
+### Mutations
+```typescript
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const create = mutation({
+  args: { name: v.string(), email: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("users", { ...args, role: "user" });
+  },
+});
+```
+
+## Real-Time Patterns
+
+- Use `useQuery` hook for automatic real-time subscriptions
+- Queries re-run when any referenced table data changes
+- Use `useMutation` for optimistic updates
+- Paginated queries support real-time updates with `.paginate()`
+
+## Deployment
+
+- Deploy with `npx convex deploy`
+- Use `npx convex dev` for local development with hot reload
+- Schema changes are automatically migrated
+- Use `npx convex import` / `npx convex export` for data management

package/src/orchestrator/skills/data-engineering/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: data-engineering
+description: "Data pipeline ETL workflows, web scraping with Puppeteer, NDJSON processing, and CMS data import. Use when building scrapers, processing data, running CLI tools, or importing to a CMS."
+---
+
+# Data Engineering
+
+Generic data pipeline patterns and scraping methodology. For project-specific pipeline architecture, sources, CLI commands, and data status, see [data-pipeline-config.md](../../customizations/stack/data-pipeline-config.md).
+
+## Scraper Architecture
+
+### Base Scraper Pattern
+
+```typescript
+interface ScraperConfig {
+  source: string;
+  query: string;
+  maxPages: number;
+  concurrency: number;
+  delay: { min: number; max: number };
+  outputPath: string;
+  headless: boolean;
+}
+
+abstract class BaseScraper {
+  abstract scrape(config: ScraperConfig): Promise<void>;
+  abstract extractVenue(page: Page): Promise<RawVenue>;
+  abstract getNextPage(page: Page): Promise<string | null>;
+}
+```
+
+### Puppeteer Cluster Setup
+
+```typescript
+const cluster = await Cluster.launch({
+  concurrency: Cluster.CONCURRENCY_CONTEXT,
+  maxConcurrency: config.concurrency,
+  puppeteerOptions: {
+    headless: config.headless,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  },
+  retryLimit: 3,
+  retryDelay: 5000,
+  timeout: 30000,
+});
+```
+
+### Anti-Detection Measures
+
+- Rotate user agents from a curated list
+- Random delays between requests (2-5 seconds default)
+- Randomize viewport sizes
+- Block unnecessary resources (images, fonts, CSS) for speed
+- Use stealth plugin for Puppeteer
+- Request interception for resource optimization
+
+### Error Recovery
+
+- Retry failed pages with exponential backoff (3 retries default)
+- Log failed URLs for manual review
+- Save partial results on crash/interruption
+- Checkpoint/resume for long-running scrapes
+
+## NDJSON Output Format
+
+Each scraper produces one record per line:
+
+```json
+{"name":"Example Venue","lat":50.0755,"lng":14.4378,"source":"google-maps","sourceId":"ChIJ...","category":"bar","address":"Street 30, City","rating":4.5,"reviewCount":120}
+```
+
+### Required Fields
+
+| Field | Priority | Notes |
+|-------|----------|-------|
+| `name` | Required | Preserve original encoding |
+| `lat`/`lng` | Required | GPS coordinates |
+| `address` | Required | Full text address |
+| `source` | Required | Source identifier (e.g., `google-maps`) |
+| `sourceId` | Required | Source-specific unique ID |
+| `category` | Required | Domain-specific category |
+
+### Optional Fields
+
+`rating`, `reviewCount`, `phone`, `website`, `openingHours`, `photos`, `priceLevel`
+
+## Design Principles
+
+- Pipelines as composable, single-responsibility stages
+- Use streams for large file processing to minimize memory
+- Idempotent imports with `createOrReplace` and deterministic `_id` generation
+- Dry-run mode for all destructive operations
+- Generate normalized names by stripping diacritics for search
+- Structured addresses: `{ street, city, postalCode, country, countryCode }`
+- Track data lineage — record source and transformation history
+- Handle errors gracefully — skip bad records, don't halt pipeline
+- Backup before bulk operations
+- Respect `robots.txt` and rate limit all scraping requests
+- Only scrape publicly available data with source attribution

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: deployment-infrastructure
+description: "Deployment architecture, environment variables, cron jobs, security headers, and caching patterns. Use when configuring deployments, managing environment variables, setting up cron jobs, or troubleshooting build/deployment issues."
+---
+
+# Deployment Infrastructure
+
+All deployment configuration is project-specific. See [deployment-config.md](../../customizations/stack/deployment-config.md) for the full architecture, environment variables, cron jobs, caching headers, and key files.
+
+## Generic Deployment Principles
+
+- Use platform-native Git integration for CI/CD (push to main = production, push to branch = preview)
+- Store all secrets as environment variables — never in code, commits, or logs
+- Use `Bearer` token auth for cron job endpoints
+- Apply security headers via framework config (HSTS, CSP, X-Frame-Options, Permissions-Policy)
+- Set immutable cache headers for static assets (`max-age=31536000, immutable`)
+- Use short cache durations for frequently changing assets (e.g., favicon: `max-age=86400`)
+- Load the **security-hardening** skill for full header inventory and CSP configuration
+
+## Release Process
+
+### 1. Pre-Release Audit
+- Run `yarn nx affected -t lint,test,build` to verify all affected projects
+- Review all changed files since last release (`git diff` against last tag/release)
+- Check for uncommitted work or unmerged branches
+- Verify no draft PRs are accidentally included
+
+### 2. Regression Check
+- Identify features adjacent to changes and spot-check them
+- Run full test suites for all affected projects (not just changed files)
+- Check deployment preview builds for visual regressions
+- Verify critical user flows still work (homepage, search, venue detail)
+
+### 3. Changelog & Release Notes
+- Generate changelog from commit messages and PR titles since last release
+- Categorize changes: Features, Bug Fixes, Performance, Breaking Changes, Internal
+- Write human-readable release notes summarizing impact
+- Include migration notes for any breaking changes
+
+### 4. Version Management
+- Follow semver: MAJOR (breaking), MINOR (features), PATCH (fixes)
+- Tag releases in git with the version number
+- Update version references in relevant files
+
+### 5. Release Verification
+- Confirm deployment succeeded on production
+- Smoke-test production URLs for critical pages
+- Monitor error rates and performance metrics post-release
+- Document rollback steps if issues arise

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

@@ -0,0 +1,85 @@
+---
+name: documentation-standards
+description: "Documentation templates, structure, and standards for project docs, roadmaps, ADRs, and known issues. Use when writing or updating documentation files."
+---
+
+# Documentation Standards
+
+Generic documentation templates and writing standards. For project-specific directory structure and practices, see [docs-structure.md](../../customizations/project/docs-structure.md).
+
+## Issue Documentation Template
+
+```markdown
+### ISSUE-ID: Brief Description
+
+**Issue ID:** ISSUE-ID
+**Status:** Known Limitation | Fixed | Workaround Available
+**Severity:** Critical | High | Medium | Low
+**Impact:** [What user/developer experience is affected]
+
+#### Problem
+[Clear description of the issue]
+
+#### Root Cause
+[Technical explanation]
+
+#### Solution Options
+1. **Option A** — [Description]
+   - Pros: ...
+   - Cons: ...
+2. **Option B** — [Description]
+
+#### Related Files
+- `path/to/file.ts` — [What it does]
+```
+
+## Roadmap Update Template
+
+When a feature is completed:
+1. Change status to `COMPLETE`
+2. Add completion date
+3. List modified files
+4. Update the summary table at the top
+5. Move to completed section if applicable
+
+## Architecture Decision Record Template
+
+```markdown
+## ADR-NNN: Decision Title
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted | Superseded | Deprecated
+**Context:** [Why this decision was needed]
+**Decision:** [What was decided]
+**Consequences:** [Impact of the decision]
+**Alternatives Considered:** [What else was evaluated]
+```
+
+## Writing Guidelines
+
+- Write clear, concise prose — avoid jargon unless necessary
+- Include diagrams (Mermaid or ASCII) for architecture
+- Link to related files and docs using relative paths
+- Keep line length under 400 characters; break at 80 for readability
+- Use tables for structured data
+- Include "Last Updated" dates on all documents
+- Archive outdated docs rather than deleting
+- Cross-reference between documents when relevant
+
+### Formatting Rules
+
+- **Headings**: Use H2 for sections, H3 for subsections. Do not use H1 — generated from title. Avoid H4+
+- **Lists**: Use `-` for bullet points and `1.` for numbered lists; indent nested lists with two spaces
+- **Code Blocks**: Use fenced code blocks with language specified for syntax highlighting
+- **Links**: Use `[link text](URL)` with descriptive text and valid URLs
+- **Images**: Use `![alt text](image URL)` with brief descriptive alt text
+- **Tables**: Use `|` tables with properly aligned columns and headers
+- **Whitespace**: Use blank lines to separate sections; avoid excessive whitespace
+
+### Front Matter
+
+Include YAML front matter at the beginning of instruction/skill files:
+
+- `title` / `name`: The title of the document
+- `description`: A brief description of the document content
+- `applyTo`: (for instruction files) Glob pattern for which files the instructions apply to