opencastle 0.1.0

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

@@ -0,0 +1,144 @@
+---
+name: agent-memory
+description: "Agent expertise tracking and cross-session knowledge graph. Use when delegating tasks to track agent strengths/weaknesses, or when building context about file relationships and patterns."
+---
+
+# Agent Memory Protocol
+
+## Purpose
+
+Track which agents have expertise with which files, patterns, and tools across sessions. This information helps the Team Lead make better delegation decisions by matching tasks to agents with proven track records.
+
+## Expertise File
+
+Location: `.github/customizations/AGENT-EXPERTISE.md` — a structured record of agent performance per domain.
+
+Template structure:
+
+```markdown
+# Agent Expertise Registry
+
+## Developer
+### Strong Areas
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| Feature implementation | Successfully built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
+| Server-side logic | Fixed auth flow (TAS-ZZ) | YYYY-MM-DD |
+
+### Weak Areas
+| Area | Evidence | Last Updated |
+|------|----------|-------------|
+| CSS Modules | Required 2 retries on styling task (TAS-AA) | YYYY-MM-DD |
+
+### File Familiarity
+- `apps/tastebeer.eu/app/places/` — 3 tasks completed
+- `libs/queries/src/lib/` — 2 tasks completed
+```
+
+## Memory Update Triggers
+
+| Trigger | Action |
+|---------|--------|
+| Agent completes task successfully on first attempt | Add/update Strong Area entry |
+| Agent requires 2+ retries | Add/update Weak Area entry |
+| Agent modifies a file | Update File Familiarity count |
+| Agent fails a task entirely (DLQ) | Add Weak Area with failure reference |
+| >3 months since last update in an area | Mark as "stale" — needs re-evaluation |
+
+## Memory Retrieval Protocol
+
+1. Before delegating, check `.github/customizations/AGENT-EXPERTISE.md` for the candidate agent
+2. If the task matches a Strong Area, include in the prompt: *"You have prior experience with [area] from [TAS-XX]. Apply the same patterns."*
+3. If the task matches a Weak Area, either: (a) add extra context to the prompt to compensate, or (b) consider a different agent
+4. If the file has high familiarity, mention it: *"You've worked on [file] before in [TAS-XX]."*
+
+## Memory Pruning Rules
+
+- Remove entries older than 6 months without recent updates
+- Consolidate similar entries (e.g., 5 "App Router pages" entries → 1 entry with count)
+- Remove File Familiarity entries for files that no longer exist
+- The Team Lead should prune at the start of major feature work (not every session)
+
+## Integration with Delegation
+
+Add relevant expertise context to delegation prompts. Example addition:
+
+```
+### Agent Context (from expertise registry)
+- Strong: Server Components, GROQ queries (3 successful tasks)
+- Weak: CSS Modules (1 retry on TAS-AA)
+- Familiar files: libs/queries/src/lib/search/ (2 tasks)
+```
+
+## Cross-Session Knowledge Graph
+
+### Purpose
+
+Capture structured relationships between concepts, files, agents, and decisions. Goes beyond flat lesson lists to show how pieces of the system connect.
+
+### Entity Types
+
+| Entity Type | Examples | Notation |
+|-------------|----------|----------|
+| `File` | `libs/queries/src/lib/search/searchModule.ts` | `F:path` |
+| `Agent` | Developer, Security Expert | `A:name` |
+| `Pattern` | Server Component data fetching, RLS policy structure | `P:name` |
+| `Decision` | "Use Jotai over Redux" (from DECISIONS.md) | `D:name` |
+| `Bug` | Known issue KI-XXX | `B:id` |
+| `Lesson` | LES-XXX from LESSONS-LEARNED.md | `L:id` |
+
+### Relationship Types
+
+| Relationship | Meaning | Example |
+|-------------|---------|---------|
+| `depends-on` | X requires Y to function | `F:places/page.tsx depends-on F:searchModule.ts` |
+| `caused-by` | X was caused by Y | `B:KI-042 caused-by D:use-server-components` |
+| `expert-in` | Agent X has expertise in Y | `A:Content Engineer expert-in P:GROQ-queries` |
+| `related-to` | Loose conceptual connection | `L:LES-15 related-to P:RLS-policies` |
+| `obsoletes` | X replaces/supersedes Y | `D:use-app-router obsoletes D:use-pages-router` |
+| `blocks` | X prevents Y from working | `B:KI-099 blocks F:auth/middleware.ts` |
+
+### Knowledge Graph File
+
+Location: `.github/customizations/KNOWLEDGE-GRAPH.md` — an append-only relationship log.
+
+Template structure:
+
+```markdown
+# Knowledge Graph
+
+## Relationships
+
+| Source | Relationship | Target | Added | Context |
+|--------|-------------|--------|-------|---------|
+| A:Security Expert | expert-in | P:RLS-policies | 2026-02-23 | Completed 3 RLS audits |
+| F:searchModule.ts | depends-on | F:sanity-client.ts | 2026-02-23 | Search uses Sanity client |
+| L:LES-15 | related-to | P:cookie-sessions | 2026-02-23 | Lesson about auth token format |
+```
+
+### When to Add Relationships
+
+| Trigger | What to Record |
+|---------|---------------|
+| Agent completes a task touching multiple files | `depends-on` between the files |
+| A lesson is added that relates to a pattern | `related-to` between lesson and pattern |
+| An agent demonstrates expertise | `expert-in` between agent and domain |
+| A decision causes a known issue | `caused-by` between bug and decision |
+| A new pattern supersedes an old approach | `obsoletes` between decisions/patterns |
+
+### Query Patterns
+
+When gathering context for a delegation:
+
+1. Find the target file(s) in the graph
+2. Follow `depends-on` edges to identify related files the agent might need to read
+3. Follow `expert-in` edges to confirm the right agent is assigned
+4. Follow `related-to` edges from relevant lessons to discover applicable patterns
+5. Check for `blocks` edges that might indicate known issues affecting the task
+
+### Maintenance Rules
+
+- Add relationships as you discover them — don't batch
+- Review and prune at the start of major features (remove obsolete relationships)
+- Keep the graph focused — max ~100 active relationships. Archive old ones quarterly
+- Relationships are append-only during a session; pruning happens between sessions

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

@@ -0,0 +1,106 @@
+---
+name: api-patterns
+description: "API design patterns for route handlers, Server Actions, Zod validation, and external API integration. Use when creating API routes, Server Actions, or integrating external services."
+---
+
+# API Patterns
+
+Generic API design patterns for Next.js App Router projects. For project-specific endpoints, actions, and external API inventory, see [api-config.md](../../customizations/stack/api-config.md).
+
+## Architecture
+
+This project uses **Next.js App Router** API patterns:
+
+- **Server Actions** (preferred for mutations) — form submissions, data writes, auth operations
+- **Route Handlers** (`route.ts`) — analytics endpoints, autocomplete, external integrations
+- **Proxy layer** — IP rate limiting, fingerprinting, bot detection
+
+## Code Patterns
+
+### Route Handler
+
+```typescript
+// app/api/example/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const schema = z.object({ query: z.string().min(1).max(200) });
+
+export async function GET(request: NextRequest) {
+  const params = Object.fromEntries(request.nextUrl.searchParams);
+  const result = schema.safeParse(params);
+  if (!result.success) {
+    return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
+  }
+  // ... process
+  return NextResponse.json(data);
+}
+```
+
+### Server Action
+
+```typescript
+'use server';
+import { createServerClient } from '@libs/supabase-auth';
+import { revalidatePath } from 'next/cache';
+
+export async function submitAction(formData: FormData) {
+  const supabase = await createServerClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return { error: 'Unauthorized' };
+  // ... validate and process
+  revalidatePath('/places');
+  return { success: true };
+}
+```
+
+## Design Principles
+
+- Prefer Server Actions for mutations over API routes
+- Always validate input with Zod schemas on the server side
+- Return appropriate HTTP status codes and error messages
+- Protect sensitive routes with middleware or role checks
+- Rate limit public endpoints to prevent abuse
+- Use Web `Request`/`Response` APIs with `NextRequest`/`NextResponse`
+- Use CDN caching headers for public, cacheable responses
+- Document new API endpoints in project documentation
+
+## API Design Principles
+
+### Route Architecture
+- RESTful resource naming: `/api/v1/places`, `/api/v1/places/:slug`
+- Use HTTP methods correctly: `GET` (read), `POST` (create), `PATCH` (partial update), `DELETE` (remove)
+- Group related endpoints under a common prefix
+- Keep URLs noun-based, not verb-based (`/api/places` not `/api/getPlaces`)
+
+### Request/Response Schemas
+- Define Zod schemas for all request bodies, query params, and responses
+- Use consistent envelope format for responses:
+  ```json
+  { "data": ..., "meta": { "total": 42, "page": 1 } }
+  ```
+- Error responses follow a standard shape:
+  ```json
+  { "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
+  ```
+
+### Error Handling
+- Use appropriate HTTP status codes (400, 401, 403, 404, 422, 429, 500)
+- Return machine-readable error codes alongside human-readable messages
+- Never leak internal errors — sanitize stack traces in production
+- Provide actionable error messages when possible
+
+### Pagination & Filtering
+- Cursor-based pagination for large datasets (offset-based as fallback)
+- Consistent query parameter names: `limit`, `cursor`, `sort`, `order`
+- Filter parameters match field names: `?type=brewery&city=prague`
+
+### Versioning
+- URL-based versioning: `/api/v1/...`
+- Never break existing contracts — add fields, never remove or rename
+- Deprecation notices in response headers before removal
+
+### Rate Limiting & Caching
+- Define rate limits per endpoint sensitivity
+- Set `Cache-Control` headers appropriate to content freshness
+- Use `ETag` / `If-None-Match` for conditional requests where applicable

package/src/orchestrator/skills/browser-testing/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: browser-testing
+description: "Chrome DevTools MCP automation patterns for validating UI changes in real browsers. Use when performing E2E browser testing, validating visual changes, testing user interactions, or debugging UI issues with Chrome DevTools."
+---
+
+# Browser Testing with Chrome DevTools MCP
+
+Generic browser testing methodology using Chrome DevTools MCP. For project-specific test app, selectors, suites, and breakpoint config, see [testing-config.md](../../customizations/stack/testing-config.md).
+
+## Purpose
+
+After any UI change, validate in a real browser:
+1. Start dev server if not running.
+2. Navigate to affected pages.
+3. Interact with UI elements (click, fill, filter).
+4. Validate behavior and appearance.
+5. Test edge cases (empty states, errors, boundaries).
+6. Document findings with screenshots and pass/fail.
+
+## Pre-Test Build Verification
+
+**CRITICAL: Always build before browser testing.** Testing stale code wastes time. See [testing-config.md](../../customizations/stack/testing-config.md) for the specific build and serve commands.
+
+## Chrome MCP Tools Reference
+
+### Navigation
+
+```javascript
+// Navigate to page
+mcp_chrome-devtoo_navigate_page({ type: 'url', url: 'http://localhost:<port>/places' })
+// Reload
+mcp_chrome-devtoo_navigate_page({ type: 'reload' })
+```
+
+### Interaction
+
+```javascript
+mcp_chrome-devtoo_click({ uid: 'element_uid' })
+mcp_chrome-devtoo_type({ uid: 'input_uid', text: 'search query' })
+mcp_chrome-devtoo_wait_for({ text: 'Expected text' })
+```
+
+### Validation (preferred — lightweight)
+
+```javascript
+// Count elements
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => document.querySelectorAll(".place-card").length'
+})
+// Check URL
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => window.location.href'
+})
+// Verify element exists
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => !!document.querySelector("[data-testid=filter-topbar]")'
+})
+// Get text content
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => document.querySelector("h1")?.textContent'
+})
+// Check URL params
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => new URL(window.location.href).searchParams.toString()'
+})
+```
+
+### Screenshots (use sparingly — MAX 3 per session)
+
+```javascript
+mcp_chrome-devtoo_take_screenshot({ format: 'png' })
+mcp_chrome-devtoo_take_snapshot()  // DOM snapshot, lighter than screenshot
+```
+
+### Performance
+
+```javascript
+mcp_chrome-devtoo_performance_start_trace({ reload: true, autoStop: true })
+mcp_chrome-devtoo_performance_analyze_insight({ insightSetId: 'set_id', insightName: 'LCPBreakdown' })
+```
+
+## Testing Workflow
+
+### 1. Setup
+
+Start the dev server (see [testing-config.md](../../customizations/stack/testing-config.md) for app and port).
+
+### 2. Initial State
+
+```javascript
+mcp_chrome-devtoo_navigate_page({ type: 'url', url: 'http://localhost:<port>/places' })
+mcp_chrome-devtoo_wait_for({ text: 'places' })
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => ({ url: window.location.href, title: document.title })'
+})
+```
+
+### 3. Test Interactions
+
+```javascript
+mcp_chrome-devtoo_click({ uid: 'filter_uid' })
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => document.querySelectorAll(".place-card").length'
+})
+```
+
+### 4. Test Edge Cases
+
+```javascript
+mcp_chrome-devtoo_navigate_page({
+  type: 'url', url: 'http://localhost:<port>/places?q=nonexistent-venue-xyz'
+})
+mcp_chrome-devtoo_evaluate_script({
+  function: '() => !!document.querySelector("[data-testid=empty-state]")'
+})
+```
+
+### 5. Console Error Check
+
+```javascript
+mcp_chrome-devtoo_list_console_messages()
+```
+
+### 6. Responsive Breakpoint Testing (MANDATORY)
+
+**Every UI change MUST be tested at all three breakpoints.** Do not test at desktop only — most layout bugs surface at mobile or tablet widths. See [testing-config.md](../../customizations/stack/testing-config.md) for project-specific breakpoint values.
+
+#### How to Resize
+
+```javascript
+// Mobile (iPhone-like)
+mcp_chrome-devtoo_resize_page({ width: 375, height: 812 })
+
+// Tablet (iPad-like)
+mcp_chrome-devtoo_resize_page({ width: 768, height: 1024 })
+
+// Desktop (standard)
+mcp_chrome-devtoo_resize_page({ width: 1440, height: 900 })
+```
+
+#### Per-Breakpoint Verification
+
+At **each** viewport size, verify:
+
+**Mobile (375 x 812):**
+- [ ] Sidebar/filter panel hidden — accessible via drawer/hamburger
+- [ ] Cards stack vertically, no horizontal overflow
+- [ ] Text truncates or wraps cleanly — no overflow or overlap
+- [ ] Touch targets >= 44px
+- [ ] Badges, tags, and pills wrap without horizontal scroll
+- [ ] Map/list toggle works
+
+**Tablet (768 x 1024):**
+- [ ] Layout adapts — may show 2-column grid or collapsed sidebar
+- [ ] Interactive elements have adequate spacing
+- [ ] Images and cards resize proportionally
+
+**Desktop (1440 x 900):**
+- [ ] Full layout visible — sidebar + content columns
+- [ ] Filter sidebar, content area, and any panels properly aligned
+- [ ] No excessive whitespace or stretched elements
+
+#### Responsive Testing Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Testing only at desktop width | Test at all 3 breakpoints (Mobile -> Tablet -> Desktop) |
+| Skipping resize because "it uses Tailwind" | Tailwind classes can be wrong — always verify visually |
+| Only checking layout, not interactions | Test filter drawers, dropdowns, and modals at each size |
+| Taking 3 screenshots (one per breakpoint) | Use `evaluate_script()` to check layout; save screenshots for failures |
+
+## Regression Re-Test Workflow
+
+When re-testing after a fix:
+1. Read previous `result.json` for failing tests.
+2. Run build + lint to verify fix compiles.
+3. Start dev server.
+4. Re-run ALL tests from previous suite (fixes can regress other tests).
+5. Compare results — every test must PASS.
+6. Write updated `result.json`.
+
+If any test still fails: analyze, fix, repeat. Do NOT stop.
+
+## Validation Checklist
+
+- [ ] Page loads without errors (check console)
+- [ ] Changed component renders correctly
+- [ ] Interactive elements respond to clicks/input
+- [ ] Filters/sorting produce correct results
+- [ ] URL parameters sync with UI state
+- [ ] Empty states display when appropriate
+- [ ] Error states handle gracefully
+- [ ] Loading states appear during async operations
+- [ ] Keyboard navigation works, focus is visible
+- [ ] **Responsive: Tested at Mobile, Tablet, and Desktop breakpoints**
+- [ ] **Responsive: No horizontal overflow at any breakpoint**
+- [ ] **Responsive: Interactions work at every breakpoint (drawers, dropdowns, modals)**
+
+## Context Management
+
+- ONE focus area per session.
+- MAX 3 screenshots — use `evaluate_script()` for most checks.
+- Clear browser state between unrelated test flows.

package/src/orchestrator/skills/code-commenting/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: code-commenting
+description: "Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. Use when writing or reviewing code comments."
+---
+
+# Self-explanatory Code Commenting
+
+## Core Principle
+
+**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
+We do not need comments most of the time.
+
+## Decision Framework
+
+Before writing a comment, ask:
+
+1. **Is the code self-explanatory?** → No comment needed
+2. **Would a better variable/function name eliminate the need?** → Refactor instead
+3. **Does this explain WHY, not WHAT?** → Good comment
+4. **Will this help future maintainers?** → Good comment
+
+## Comments to AVOID
+
+**Obvious Comments**
+
+```javascript
+let counter = 0; // Initialize counter to zero
+counter++; // Increment counter by one
+```
+
+**Redundant Comments**
+
+```javascript
+function getUserName() {
+  return user.name; // Return the user's name
+}
+```
+
+**Outdated Comments**
+
+```javascript
+// Calculate tax at 5% rate
+const tax = price * 0.08; // Actually 8%
+```
+
+## Comments to WRITE
+
+**Complex Business Logic**
+
+```javascript
+// Apply progressive tax brackets: 10% up to 10k, 20% above
+const tax = calculateProgressiveTax(income, [0.1, 0.2], [10000]);
+```
+
+**Non-obvious Algorithms**
+
+```javascript
+// Using Floyd-Warshall for all-pairs shortest paths
+// because we need distances between all nodes
+for (let k = 0; k < vertices; k++) { /* ... */ }
+```
+
+**Regex Patterns**
+
+```javascript
+// Match email format: username@domain.extension
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+```
+
+**API Constraints or Gotchas**
+
+```javascript
+// GitHub API rate limit: 5000 requests/hour for authenticated users
+await rateLimiter.wait();
+```
+
+## Public APIs
+
+```javascript
+/**
+ * Calculate compound interest using the standard formula.
+ *
+ * @param {number} principal - Initial amount invested
+ * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param {number} time - Time period in years
+ * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
+ * @returns {number} Final amount after compound interest
+ */
+function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
+  // ... implementation
+}
+```
+
+## Configuration and Constants
+
+```javascript
+const MAX_RETRIES = 3; // Based on network reliability studies
+const API_TIMEOUT = 5000; // AWS Lambda timeout is 15s, leaving buffer
+```
+
+## Annotation Tags
+
+```javascript
+// TODO: Replace with proper user authentication after security review
+// FIXME: Memory leak in production - investigate connection pooling
+// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
+// NOTE: This implementation assumes UTC timezone for all calculations
+// WARNING: This function modifies the original array instead of creating a copy
+// PERF: Consider caching this result if called frequently in hot path
+// SECURITY: Validate input to prevent SQL injection before using in query
+// BUG: Edge case failure when array is empty - needs investigation
+// REFACTOR: Extract this logic into separate utility function for reusability
+// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
+```
+
+## Anti-Patterns
+
+- **Dead code comments** — Don't comment out code; delete it (git has history)
+- **Changelog comments** — Don't maintain change history in comments; use git
+- **Divider comments** — Don't use decorative separators; use proper file structure
+
+## Quality Checklist
+
+Before committing, ensure your comments:
+
+- [ ] Explain WHY, not WHAT
+- [ ] Are grammatically correct and clear
+- [ ] Will remain accurate as code evolves
+- [ ] Add genuine value to code understanding
+- [ ] Are placed appropriately (above the code they describe)
+- [ ] Use proper spelling and professional language
+
+**The best comment is the one you don't need to write because the code is self-documenting.**

package/src/orchestrator/skills/contentful-cms/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: contentful-cms
+description: "Contentful CMS development patterns, GraphQL/REST API usage, content modeling, and migration best practices. Use when working with Contentful content types, entries, assets, or the Management API."
+---
+
+# Contentful CMS
+
+Generic Contentful CMS development methodology. For project-specific configuration, content types, and API keys, see [cms-config.md](../../customizations/stack/cms-config.md).
+
+## Critical Development Rules
+
+1. **Always use Content Types** — define structured content types before creating entries
+2. **Prefer GraphQL API** — use the GraphQL Content API for typed, efficient queries
+3. **Handle localization** — Contentful fields can be localized; always specify locale in queries
+4. **Use environments** — develop in sandbox environments, promote to master via migrations
+5. **Migration scripts** — use the Contentful CLI migration tool for schema changes, never modify content types manually in production
+6. **Rich Text rendering** — use `@contentful/rich-text-react-renderer` for React apps
+7. **Asset handling** — use Contentful's Image API for responsive images with transformations
+8. **Webhook-driven** — use webhooks for cache invalidation and rebuild triggers
+9. **Rate limiting** — respect API rate limits (Content Delivery: 78 req/s, Management: 10 req/s)
+10. **Keep queries in shared library** — queries belong in a shared queries library, never inline in components
+
+## Query Patterns
+
+### GraphQL Content API
+- Use typed GraphQL queries with code generation
+- Leverage `sys.publishedAt` for cache invalidation
+- Use `include` parameter to control link resolution depth
+- Filter with `where` clauses for efficient data fetching
+
+### REST Content Delivery API
+- Use `content_type` parameter to filter by type
+- Use `select` to limit returned fields
+- Use `links_to_entry` for reverse lookups
+- Handle pagination with `skip` and `limit`
+
+## Content Modeling
+
+- Use **references** for relationships between content types
+- Prefer **short text** over **long text** for searchable fields
+- Use **JSON fields** sparingly — prefer structured content types
+- Design for **reusability** — create component content types for shared UI patterns
+- Use **validation rules** on fields to enforce data quality