opencastle 0.32.12 → 0.33.0

package/src/orchestrator/plugins/linear/SKILL.md

@@ -1,53 +1,52 @@
 ---
 name: linear-task-management
-description: "Linear board conventions for tracking feature work — issue naming, labels, priorities, status workflow, and session continuity. Use when decomposing features into tasks or resuming interrupted sessions."
+description: "Creates and names Linear issues, assigns labels and priorities, manages status transitions, and links issues to PRs. Use when decomposing features into tasks or resuming interrupted sessions. Trigger terms: tickets, backlog, task breakdown, project board, sprint planning"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Task Management with Linear
 
-Conventions for tracking feature work on the Linear board via MCP tools. For project-specific team ID, workflow state UUIDs, and label UUIDs, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
+For project-specific team ID, workflow state UUIDs, and label UUIDs, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
 
-## Discovered Issues (Bug Tickets)
+## MCP Tool Examples
 
-When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked. Follow this flow:
+```json
+// Create issue
+{ "teamId": "TEAM_UUID", "title": "[UI] Build PriceRangeFilter", "description": "Objective: ...\nFiles: ...\nAC: ...", "labelIds": ["LABEL_UUID"], "priority": 2 }
+// → { "id": "TAS-42", "url": "https://linear.app/team/TAS-42" }
 
-1. **Check** known issues docs and Linear (search for open bugs) to see if it's already tracked
-2. **If tracked** — skip it, continue with current work
-3. **If NOT tracked:**
-   - **Unfixable limitation** — add to known issues with Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
-   - **Fixable bug** — create a Linear ticket:
-     - **Name:** `[Bug] Short description of the symptom`
-     - **Label:** `bug` (plus the relevant domain label, e.g., `ui`, `nextjs`)
-     - **Priority:** P2 if it affects users, P3 if cosmetic or non-blocking
-     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages or screenshots
-     - **Status:** Backlog (unless it's blocking current work, then Todo)
+// Update issue status
+{ "issueId": "TAS-42", "stateId": "IN_PROGRESS_UUID" }
+
+// Search issues
+{ "query": "is:open assignee:me", "teamId": "TEAM_UUID" }
+```
+
+## Discovered Issues
+
+- Search Linear for existing tickets; if found, link and add evidence.
+- If not found, create: Title `[Bug] <symptom>`, Labels `bug` + domain, Priority P1–P4 with rationale, Acceptance steps.
 
 ## Issue Naming
 
-Use `[Area] Short description` format:
+Name issues using a verb-first, actionable format that maps to operator intent:
 
 ```
-[Schema] Add priceRange field to place type
-[DB] Add price_range column and migration
-[Query] Update GROQ query with priceRange filter
-[UI] Build PriceRangeFilter component
-[Page] Integrate price filter into /places
-[Test] E2E test price range filtering
-[Docs] Update data model documentation
+Add priceRange field to place type  -> Action: `Add schema: priceRange to place`
+Run DB migration to add price_range column -> Action: `Migrate DB: add price_range`
+Update GROQ query to include priceRange filter -> Action: `Update query: include priceRange`
+Build PriceRangeFilter component -> Action: `Implement UI: PriceRangeFilter`
 ```
 
-**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`
-
 ## Priority
 
-| Level | Meaning | When to use |
-|-------|---------|-------------|
-| P1 (Urgent) | Blocker | Blocks other tasks, critical path |
-| P2 (High) | Important | Core feature work, on critical path |
-| P3 (Medium) | Normal | Supporting tasks, can be parallelized |
-| P4 (Low) | Nice-to-have | Docs, cleanup, polish |
+| Level | When to use |
+|-------|-------------|
+| P1 (Urgent) | Blocks other tasks, critical path |
+| P2 (High) | Core feature work, on critical path |
+| P3 (Medium) | Supporting tasks, can be parallelized |
+| P4 (Low) | Docs, cleanup, polish |
 
 ## Status Workflow
 
@@ -55,91 +54,25 @@ Use `[Area] Short description` format:
 Backlog -> Todo -> In Progress -> In Review -> Done -> Cancelled
 ```
 
-- **Backlog** — Captured but not yet planned
-- **Todo** — Planned for current feature, ready to start
-- **In Progress** — Actively being worked on by an agent
-- **In Review** — PR opened, awaiting review/merge
-- **Done** — Completed and verified
-- **Cancelled** — Dropped or no longer relevant
-
-### Status Drivers
-
-Issue status is driven by **two sources** — the Team Lead agent (via MCP) and the GitHub integration (automatically). Both can move issues through the workflow.
-
-**Agent-driven transitions (via MCP):**
-- **Todo -> In Progress** — when the agent starts working on a task
-- **In Progress -> Done** — when non-PR tasks are verified (e.g., docs, config changes)
-- **Any -> Cancelled** — when a task is dropped
-
-**GitHub-driven transitions (automatic):**
-
-The Linear-GitHub integration auto-updates issue status based on PR lifecycle events. This is configured in Linear under *Settings -> Team -> Issue statuses & automations -> Pull request and commit automation*.
-
-| PR Event | Linear Status Change |
-|----------|---------------------|
-| Branch pushed / PR drafted | -> **In Progress** |
-| PR opened | -> **In Progress** |
-| Review requested | -> **In Review** |
-| PR ready for merge (all checks pass) | -> **In Review** |
-| PR merged to `main` | -> **Done** |
-
-**Linking issues to PRs:** Include the Linear issue ID (e.g., `TAS-123`) in the branch name or PR title. Linear auto-detects the link and begins status automation. Use the branch name format from Linear: copy with `Cmd+Shift+.` on any issue.
-
-**Multiple PRs per issue:** When multiple PRs are linked to one issue, the status only advances to Done when the *last* linked PR is merged.
+### Transition Rules
 
-**Important:** When GitHub automation handles status transitions, the agent does not need to update status manually — avoid conflicting updates. Only use MCP to move status when there is no linked PR (e.g., documentation-only tasks, config changes, schema deploys).
+- Agent (via MCP): `Todo → In Progress` on start; `In Progress → Done` on verified completion; `Any → Cancelled` to drop.
+- GitHub integration: auto-updates status on PR events (push → In Progress, review → In Review, merge → Done). Configure in Linear *Settings → Team → Pull request automation*.
+- Link via issue ID in branch/PR title (e.g., `TAS-123`).
 
 ## Issue Descriptions
 
-Every issue must include:
+Every issue must include: **Objective** (one sentence), **Files (partition)** (paths this agent may modify), **Acceptance Criteria** (verifiable checklist), **Dependencies** (`#TAS-XX`).
 
-```markdown
-**Objective:** One sentence describing the deliverable
-
-**Files (partition):**
-- `path/to/relevant/file.ts`
-- `path/to/another/file.ts`
-
-**Acceptance Criteria:**
-- [ ] Specific, verifiable outcome 1
-- [ ] Specific, verifiable outcome 2
-
-**Dependencies:** #TAS-XX (if any)
-```
-
-The **Files (partition)** section defines which files this agent is allowed to modify. This prevents merge conflicts when multiple agents work in parallel — no two issues in the same phase should list overlapping files.
-
-## Feature Grouping
-
-- Use a **Linear project** for each major feature
-- Create projects via the Linear UI — no create_project API is available via MCP
-- All related issues belong to that project
-- Issues track individual subtasks within the feature
+Group related issues under a Linear project; issues track individual subtasks.
 
 ## Session Workflow
 
-### Starting a new feature
-
-1. Read the board to check for existing in-progress work
-2. Decompose the feature into issues following the conventions above
-3. Create all issues on Linear with correct naming, labels, priority, and descriptions
-4. Note dependencies in issue descriptions — Linear MCP has no dependency API
-5. Begin delegation
-
-### During execution
-
-- Move issue to **In Progress** before delegating to an agent
-- Move issue to **Done** immediately after the agent completes and output is verified
-- If a task is blocked, update the issue description explaining the blocker (Linear MCP has no comment API)
-
-### Resuming an interrupted session
-
-1. List issues filtered by **In Progress** and **Todo** status
-2. Read issue descriptions to restore context
-3. Pick up where work left off — no need to re-analyze from scratch
-
-### Completing a feature
+1. Check board for existing in-progress work.
+2. Decompose feature into issues; create all on Linear — verify each returns a valid issue ID.
+3. Delegate: move to **In Progress** before starting; **Done** after verified.
+4. If blocked, update the issue description (Linear MCP has no comment API).
+5. On resume: filter by In Progress/Todo, read descriptions, continue.
+6. On completion: verify all issues Done/Cancelled, run build/lint/test.
 
-1. Verify all issues are **Done** or **Cancelled**
-2. Run final build/lint/test checks
-3. Mark all project issues as Done or Cancelled (closing the project requires the Linear UI)
+If creation fails: check team ID and state UUIDs in [tracker-config.md](../../.opencastle/project/tracker-config.md); retry once. If board state is inconsistent on resume: re-read all issue statuses before proceeding.

package/src/orchestrator/plugins/netlify/REFERENCE.md

@@ -0,0 +1,33 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Netlify REFERENCE: extended CI build examples, function/edge function snippets, and verification scripts.
+
+Put long-form troubleshooting steps and environment-specific snippets here; `SKILL.md` contains the concise checklist.
+Last Updated: 2026-03-31
+
+Reference: Netlify verification & scripts
+
+- Post-deploy verification scripts (curl checks, env validation) and Lighthouse commands
+- Netlify CLI examples for local `netlify build` and `netlify env:set`
+- Common deploy log patterns and error snippets with remediation steps
+
+## Environment Variable Scoping
+
+| Scope | When Applied | Use For |
+|-------|-------------|----------|
+| **Production** | `main` deploys | Live secrets, production API keys |
+| **Deploy previews** | All PR/branch builds | Staging/test API keys |
+| **Branch deploy** | Specific branch deploys | Branch-specific overrides |
+| **Local** | `netlify dev` | Local development |
+
+## Security Headers (netlify.toml)
+
+```toml
+[[headers]]
+  for = "/*"
+  [headers.values]
+    X-Frame-Options = "DENY"
+    X-Content-Type-Options = "nosniff"
+    Referrer-Policy = "strict-origin-when-cross-origin"
+```
+

package/src/orchestrator/plugins/netlify/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: netlify-deployment
-description: "Netlify deployment workflows, serverless functions, edge functions, environment management, and build configuration. Use when deploying to Netlify, writing serverless/edge functions, or troubleshooting builds."
+description: "Deploy sites, configure serverless and edge functions, and verify builds on Netlify. Use when the user mentions: 'deploy preview', 'configure netlify.toml', or 'debug a failed deploy'. Trigger terms: build error, Netlify Functions, deploy logs, deploy preview"
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Netlify Deployment
 
 Netlify-specific deployment patterns and conventions. For project-specific deployment architecture, environment variables, and key files, see [deployment-config.md](../../.opencastle/stack/deployment-config.md).
 
 ## Deployment Model
 
-Netlify uses Git-based continuous deployment:
+| Branch | Environment |
+|--------|-------------|
+| `main` | Production (auto) |
+| `feature/*`, `fix/*` | Deploy preview (auto, unique URL) |
 
-```
-main branch    → Production deployment (auto)
-feature/*      → Deploy preview (auto, unique URL)
-fix/*          → Deploy preview (auto, unique URL)
-```
+## Deployment Workflow
 
-- Every push triggers a build — no manual deploys needed
-- Deploy previews get unique URLs for PR-based testing
-- Instant rollback to any previous deploy from the dashboard
-- Branch deploys can be configured for specific branches beyond `main`
+1. Configure `netlify.toml` (build command, publish dir, env vars).
+2. Build locally: `netlify build --debug` — fix any errors before pushing.
+3. Push branch — Netlify auto-deploys a preview.
+4. Verify preview: `curl -fsS -o /dev/null -w '%{http_code}' https://<DEPLOY_URL>/` — expect 200.
+5. Merge to `main` — production auto-deploys.
 
 ## Build Configuration (netlify.toml)
 
@@ -39,39 +37,17 @@ fix/*          → Deploy preview (auto, unique URL)
   to = "/index.html"
   status = 200
   conditions = {Role = ["admin"]}
-
-[[headers]]
-  for = "/*"
-  [headers.values]
-    X-Frame-Options = "DENY"
-    X-Content-Type-Options = "nosniff"
-    Referrer-Policy = "strict-origin-when-cross-origin"
 ```
 
-## Serverless Functions
-
-Place functions in `netlify/functions/`:
+For security headers config, see [REFERENCE.md](REFERENCE.md).
 
-```typescript
-// netlify/functions/hello.ts
-import type { Context, Config } from "@netlify/functions";
-
-export default async (req: Request, context: Context) => {
-  return new Response(JSON.stringify({ message: "Hello from Netlify Functions" }), {
-    headers: { "Content-Type": "application/json" },
-  });
-};
-
-export const config: Config = {
-  path: "/hello",
-};
-```
+## Serverless Functions
 
-Functions use web standard Request/Response. The `Config` export defines routing (path) instead of the default `/.netlify/functions/<name>` path.
+Place functions in `netlify/functions/`. For full examples and CI-ready function patterns see [REFERENCE.md](REFERENCE.md).
 
-- Supports TypeScript out of the box
-- Default timeout: 10s (extendable to 26s on Pro)
-- Use background functions for long-running tasks (up to 15 min)
+- Functions use web standard Request/Response. The `Config` export defines routing (path) instead of the default `/.netlify/functions/<name>` path.
+- Supports TypeScript out of the box; default timeout: 10s (extendable to 26s on Pro).
+- Use background functions for long-running tasks (up to 15 min).
 
 ## Edge Functions
 
@@ -89,26 +65,12 @@ export default async (request: Request, context: Context) => {
 export const config = { path: '/geo' };
 ```
 
-- Run at the CDN edge, sub-millisecond cold starts
 - Use for personalization, A/B testing, geo-routing
 - Deno runtime (not Node.js)
 
 ## Environment Variables
 
-### Scoping
-
-| Scope | When Applied | Use For |
-|-------|-------------|---------|
-| **Production** | `main` deploys | Live secrets, production API keys |
-| **Deploy previews** | All PR/branch builds | Staging/test API keys |
-| **Branch deploy** | Specific branch deploys | Branch-specific overrides |
-| **Local** | `netlify dev` | Local development |
-
-### Best Practices
-
-- Set secrets via Netlify UI or CLI (`netlify env:set`) — never commit them
-- Use `netlify dev` to run locally with injected env vars
-- Validate required vars at build time in `netlify.toml`
+See [REFERENCE.md](REFERENCE.md) for environment variable scoping and security header examples.
 
 ## Scheduled Functions (Cron)
 
@@ -128,11 +90,19 @@ export const config: Config = {
 
 ## Build Troubleshooting
 
-1. **Check build logs** — Netlify UI → Deploys → click failed deploy
-2. **Common causes:**
-   - Missing environment variables
-   - Node.js version mismatch (set in `netlify.toml` or `.node-version`)
-   - Build command or publish directory mismatch
-   - Dependency install failures (check lockfile)
-3. **Local debugging** — run `netlify build` locally to reproduce
-4. **Clear cache** — Netlify UI → Deploys → Trigger deploy → Clear cache and deploy
+```bash
+netlify build --debug          # reproduce locally with verbose output
+netlify env:list               # verify env vars are set
+netlify status                 # check linked site and deploy state
+```
+
+Common fixes: set `NODE_VERSION` in `netlify.toml`, sync lockfile, verify `publish` directory matches build output.
+
+## Post-Deploy Verification
+
+```bash
+curl -fsS -o /dev/null -w '%{http_code}' https://<DEPLOY_URL>/          # expect 200
+curl -fsS -o /dev/null -w '%{http_code}' https://<DEPLOY_URL>/api/health # expect 200
+```
+
+If any route fails: inspect deploy logs in Netlify UI, fix, and re-deploy. See [REFERENCE.md](REFERENCE.md) for extended verification scripts.

package/src/orchestrator/plugins/nextjs/REFERENCE.md

@@ -0,0 +1,73 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Next.js REFERENCE: deep-dive topics for revalidation, middleware, and advanced caching.
+
+Place detailed config snippets and long tables here; the `SKILL.md` keeps only the quick workflow and validation commands.
+Last Updated: 2026-03-31
+
+Reference: deeper Next.js topics
+
+- Routing edge cases: middleware vs route-level server checks
+- Revalidation patterns: `revalidatePath`, `tags`, on-demand revalidation examples
+- App Router auth patterns and middleware examples
+- Performance tuning: RSC payload sizing and bundle splitting
+
+See `next.config.ts`, `app/` examples in the repo for applied patterns.
+
+## Caching Details
+
+| Mechanism | Scope | How to Use |
+|-----------|-------|------------|
+| **Request Memoization** | Per-request | Automatic deduplication of identical `fetch` calls |
+| **Data Cache** | Cross-request | Cached by default; opt out with `cache: 'no-store'` |
+| **Full Route Cache** | Build time | Static routes cached as HTML + RSC payload |
+| **Router Cache** | Client-side | Prefetched and visited routes cached in browser |
+
+On-demand revalidation: `revalidatePath('/blog')` or `revalidateTag('posts')`. Tag a fetch: `fetch(url, { next: { tags: ['posts'] } })`.
+
+## Routing — File Conventions & Dynamic Routes
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Route UI |
+| `layout.tsx` | Shared layout (persists across navigation) |
+| `template.tsx` | Like layout but re-mounts on navigation |
+| `loading.tsx` | Loading UI (automatic Suspense boundary) |
+| `error.tsx` | Error UI (Client Component) |
+| `not-found.tsx` | 404 UI |
+| `route.ts` | API endpoint |
+| `default.tsx` | Fallback for parallel routes |
+
+Dynamic route patterns:
+- `app/blog/[slug]/page.tsx` → `/blog/:slug`
+- `app/shop/[...slug]/page.tsx` → `/shop/:slug+` (catch-all)
+- `app/shop/[[...slug]]/page.tsx` → `/shop` or `/shop/:slug+` (optional)
+
+### Middleware examples
+
+```ts
+import { NextResponse, type NextRequest } from 'next/server';
+export function middleware(req: NextRequest) {
+	if (!req.cookies.get('session') && req.nextUrl.pathname.startsWith('/dashboard'))
+		return NextResponse.redirect(new URL('/login', req.url));
+	return NextResponse.next();
+}
+export const config = { matcher: ['/dashboard/:path*'] };
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Do This Instead |
+|-------------|---------------|-----------------|
+| `'use client'` on every component | Bloats JS bundle, defeats RSC benefits | Default to Server Components |
+| Sequential `await` for independent data | Waterfall, slows page load | Use `Promise.all()` |
+| `next/dynamic` with `ssr: false` in Server Components | Build/runtime crash | Extract to Client Component |
+| Fetching in `useEffect` when server fetch works | Extra roundtrip, loading flash | Fetch in Server Component or Server Actions |
+| Giant `layout.tsx` with all providers | Hard to test, couples concerns | Split into a `Providers` Client Component |
+| No `error.tsx` per segment | Unhandled errors crash the page | Add `error.tsx` per route segment |
+| Hardcoding secrets in source | Security risk, version control leak | Use `.env.local` and `process.env` |
+| Skipping `loading.tsx` / `<Suspense>` | Blank screen while data loads | Add `loading.tsx` or wrap in `<Suspense>` |
+| `getServerSideProps` / `getStaticProps` | Legacy Pages Router | Use App Router with async Server Components |
+| Missing `metadata` exports | Poor SEO, no social previews | Export `metadata` or `generateMetadata` per page |
+
+Last Updated: 2026-03-31