opencastle 0.32.5 → 0.32.6

package/src/orchestrator/instructions/general.instructions.md

@@ -25,133 +25,73 @@ applyTo: '**'
 
 ## General Coding Principles
 
-- **Clean Code**: Prioritize readability, maintainability, reusability
-- **Self-documenting Code**: Comment WHY, not WHAT — for detailed patterns, load the **code-commenting** skill
-- **TypeScript First**: All code in TypeScript with proper types — never `as any`
-- **DRY**: Extract reusable logic into functions, custom hooks, or components
-- **Feature Grouping**: Co-locate code that changes together; avoid barrel files
-- **Shared Code**: Place reusable UI components and data queries in shared libraries
+Clean code, readability, maintainability. TypeScript with proper types (never `as any`). DRY. Co-locate code that changes together; avoid barrel files. Shared code in shared libraries. Comment WHY, not WHAT (load **code-commenting** skill for patterns).
 
 ## Technology Standards
 
-Load the corresponding skill for detailed conventions before writing code in that domain. These are **not optional**. See `.opencastle/agents/skill-matrix.json` for the full domain-to-skill mapping.
+Load the corresponding skill before writing code in that domain. See `.opencastle/agents/skill-matrix.json` for domain-to-skill mapping. Key domains: UI Components (**ui-library**), App Framework (**framework**), Accessibility (**accessibility-standards**), Performance (**performance-optimization**), Frontend Design (**frontend-design**).
 
-| Domain | Skill |
-|--------|-------|
-| UI Components | **ui-library** (via skill matrix) |
-| App Framework | **framework** (via skill matrix) |
-| Accessibility | **accessibility-standards** |
-| Performance | **performance-optimization** |
-| Frontend Design | **frontend-design** |
+## Task Decomposition
 
-## Task Decomposition Protocol
-
-Before starting multi-step work, decompose it into individually verifiable tasks:
-
-1. **Decompose first** — split the work into the smallest meaningful units before writing any code
-2. **Verify each step** — after completing each unit, verify it (run tests, check types, lint, or visually inspect) before moving to the next
-3. **Choose the right verification** — match the check to the change type:
-   - Logic change → run unit tests
-   - Type/interface change → run the project's type-check / lint command (see the **codebase-tool** skill)
-   - UI change → start dev server and visually inspect in the browser
-   - Build config change → run a full build
-4. **Batch edits, then build** — group related edits across files, then run one build — not build-per-edit
-5. **Stop and re-plan** — if execution diverges from the plan (unexpected errors, wrong assumptions, scope growth), stop immediately, reassess, and revise the plan before continuing
-6. **When unsure how to verify** — ask the user rather than skipping verification
+Decompose → verify each step → batch edits → build once. Re-plan when execution diverges. Match verification to change type. Load **decomposition** skill for templates.
 
 ## Testing
 
-- **95% minimum** unit test coverage for all new code
-- **Test plan before implementation**: initial state, user interactions, state transitions, edge cases, integration
-- **Browser testing mandatory** for any UI change — verified at responsive breakpoints defined in `testing-config.md`
-- Load the **testing-workflow** skill for test patterns and the **browser-testing** skill for E2E automation
+95% minimum unit test coverage. Test plan before implementation. Browser testing mandatory for UI changes. Load **testing-workflow** and **browser-testing** skills.
 
 ## Build & Task Commands
 
-Use the project's configured task runner for all build, test, lint, and serve commands. **Never invoke test runners or linters directly** — always use the task runner wrapper.
-
-Resolve exact commands by loading the **codebase-tool** skill from the skill matrix. Common tasks:
-
-- **Test** — run project tests (with optional coverage)
-- **Lint** — run linter with auto-fix
-- **Build** — production build
-- **Serve** — start dev server
-- **Affected** — run a target for all projects affected by current changes
-
-**Exception:** Tools without task runner targets may be invoked directly (e.g., CMS CLI commands, database CLI commands). Check the project's task runner config first; only bypass it when no target exists.
+Always use the project's configured task runner. Load **codebase-tool** skill for exact commands. Direct CLI only for tools without task runner targets.
 
 ## Documentation
 
-Follow markdown formatting and documentation standards when writing docs. For templates, structure, and detailed patterns, load the **documentation-standards** skill.
+Follow markdown formatting standards. Load **documentation-standards** skill for templates.
 
 ## AI Optimization
 
-See [ai-optimization.instructions.md](ai-optimization.instructions.md) for batch processing, tool efficiency, and anti-patterns.
+See [ai-optimization.instructions.md](ai-optimization.instructions.md).
 
 ## Project Context
 
-For project-specific context (apps, libraries, tech stack, ports, URLs), see [project.instructions.md](../.opencastle/project.instructions.md).
+See [project.instructions.md](../.opencastle/project.instructions.md).
 
 ## Git Workflow
 
-**NEVER commit or push directly to the `main` branch.** All changes go through a feature/fix branch and a pull request. Load the **git-workflow** skill for branch naming, PR rules, and the Delivery Outcome checklist.
+**NEVER push to `main`.** All changes via feature/fix branch → PR. Load **git-workflow** skill for branch naming and PR rules.
 
 ## Discovered Issues Policy
 
-> **⛔ No issue gets ignored.** Untracked bugs discovered during work are a quality gate failure.
+> Inherits: [discovered-issues-policy](../snippets/discovered-issues-policy.md)
 
-When you encounter a bug unrelated to the current task: check if already tracked in `KNOWN-ISSUES.md` or the task tracker. If NOT tracked, track it (known issue entry or bug ticket). Never assume a pre-existing issue is somebody else's problem. See the **git-workflow** skill for the full procedure.
+See **git-workflow** skill for full tracking procedure.
 
 ## Observability Logging
 
-> **⛔ HARD GATE — This is a blocking requirement, not a suggestion.**
-> Do NOT respond to the user until you have appended the required log records.
-> A session without log records is a failed session — regardless of code quality.
+> Inherits: [logging-mandatory](../snippets/logging-mandatory.md)
 
-**Every agent MUST log every session** to `.opencastle/logs/events.ndjson`. No exceptions. No threshold. No "too small to log." Load the **observability-logging** skill for CLI commands, record schemas, and the full logging checklist.
+Load **observability-logging** skill for CLI commands and schemas.
 
 ## Self-Improvement Protocol
 
-> **⛔ HARD GATE — Lessons are the team's collective memory. Skipping them causes repeated failures.**
-
-1. **Before starting work:** Read `.opencastle/LESSONS-LEARNED.md` — apply relevant lessons proactively. This is NOT optional.
-2. **During execution:** If you retry with a different approach and it works, use the **self-improvement** skill to add a lesson immediately.
-3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too.
+> **⛔ HARD GATE** — Read `.opencastle/LESSONS-LEARNED.md` before starting work. Add lessons via **self-improvement** skill when retries succeed.
 
 ## Universal Agent Rules
 
-These rules apply to ALL specialist agents automatically. **Do not duplicate them in individual agent files.**
-
-1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents.
-2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see above).
-3. **Read and update lessons** — See Self-Improvement Protocol above.
-4. **Log every session** — See Observability Logging above. This is Constitution rule #6 — a blocking gate, not optional.
+1. Never delegate (specialists complete their own work)
+2. Follow Discovered Issues Policy
+3. Read and update lessons
+4. Log every session (Constitution rule #6)
 
 ## Pre-Response Quality Gate
 
-> **⛔ STOP before responding to the user.** Run through this checklist. If ANY required item is missing, fix it NOW.
-
-- [ ] **Lessons read** — `LESSONS-LEARNED.md` was read at session start
-- [ ] **Lessons captured** — If any retry occurred, a new lesson was added via the **self-improvement** skill
-- [ ] **Discovered issues tracked** — Any pre-existing bugs found were tracked (Discovered Issues Policy)
-- [ ] **Lint/type/test pass** — No new errors introduced; verification ran after code changes (Constitution rule #5)
-- [ ] **Session logged** — `events.ndjson` has a new `session` record (Constitution rule #6 — ALWAYS required)
-- [ ] **Delegations logged** — `events.ndjson` has a `delegation` record for each delegation (Team Lead only)
-- [ ] **Reviews logged** — `events.ndjson` has a `review` record for each fast review (if any)
-- [ ] **Panels logged** — `events.ndjson` has a `panel` record for each panel review (if any)
-- [ ] **Agent expertise updated** — `AGENT-EXPERTISE.md` updated for each delegation (strong/weak areas + file familiarity) (Team Lead only)
-- [ ] **Knowledge graph appended** — `KNOWLEDGE-GRAPH.md` has new rows for file relationships discovered (Team Lead only)
-
-Load the **observability-logging** skill for CLI commands, Base Output Contract, and detailed schemas.
-
-## Workflow & Governance Skills
+> **⛔ STOP before responding.** Load **observability-logging** skill and run its pre-response checklist.
 
-These skills provide detailed procedures. Load when their phase is reached.
+## Governance Skills
 
 | Concern | Skill |
 |---------|-------|
-| Branch naming, PR rules, delivery outcome, task tracking | **git-workflow** |
-| Log CLI commands, record schemas, output contracts | **observability-logging** |
-| Lesson writing CLI, categories, quality standards | **self-improvement** |
+| Branching, PR rules, delivery, tracking | **git-workflow** |
+| Log commands, schemas, output contracts | **observability-logging** |
+| Lesson writing, categories, quality | **self-improvement** |
 
 <!-- End of Coding Standards -->

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

@@ -9,64 +9,37 @@ description: "Astro framework best practices for content-driven sites, islands a
 
 ## Project Structure
 
-- **Use `src/pages/` directory** for file-based routing. Each `.astro`, `.md`, or `.mdx` file becomes a route.
-- Top-level: `src/`, `public/`, `astro.config.mjs`.
-- Inside `src/`: `pages/`, `layouts/`, `components/`, `content/`, `styles/`, `assets/`.
-- **`public/`** — static assets served as-is (favicons, robots.txt, fonts).
-- **`src/assets/`** — images and assets processed by Astro's build pipeline.
+Top-level: `src/`, `public/`, `astro.config.mjs`. Inside `src/`: `pages/`, `layouts/`, `components/`, `content/`, `styles/`, `assets/`. `public/` serves static assets as-is; `src/assets/` goes through Astro's build pipeline.
 
 ```
 src/
-├── pages/
-│   ├── index.astro          # → /
-│   ├── about.astro           # → /about
-│   └── blog/
-│       ├── index.astro       # → /blog
-│       └── [slug].astro      # → /blog/:slug
-├── layouts/
-│   └── BaseLayout.astro
-├── components/
-│   ├── Header.astro
-│   └── Counter.tsx           # React island
-├── content/
-│   └── blog/                 # Content collection
-│       ├── first-post.md
-│       └── second-post.md
-└── styles/
-    └── global.css
+├── pages/       # file-based routing (.astro, .md, .mdx)
+├── layouts/     # BaseLayout.astro, etc.
+├── components/  # .astro + framework components (React islands)
+├── content/     # Content collections (blog/, docs/, etc.)
+├── styles/      # global.css
+└── assets/      # processed images
 ```
 
 ## Component Model
 
-**Default: Zero JS** — Astro components (`.astro`) render to HTML with no client-side JavaScript.
+**Default: Zero JS** — `.astro` components render to HTML with no client-side JavaScript.
 
 **Islands Architecture** — Interactive components use `client:*` directives to hydrate only where needed.
 
-### Astro Components
+### Astro Component Example
 
 ```astro
 ---
-// Component script (runs at build time / server)
-interface Props {
-  title: string;
-  description?: string;
-}
+interface Props { title: string; description?: string; }
 const { title, description = 'Default description' } = Astro.props;
 const data = await fetch('https://api.example.com/data').then(r => r.json());
 ---
-
 <section>
   <h2>{title}</h2>
-  <p>{description}</p>
-  <ul>
-    {data.items.map((item: { id: string; name: string }) => (
-      <li>{item.name}</li>
-    ))}
-  </ul>
+  {data.items.map((item: { name: string }) => <li>{item.name}</li>)}
 </section>
-
 <style>
-  /* Scoped by default */
   section { max-width: 800px; margin: 0 auto; }
 </style>
 ```
@@ -81,22 +54,9 @@ const data = await fetch('https://api.example.com/data').then(r => r.json());
 | `client:media="(max-width: 768px)"` | When media query matches | Mobile-only interactivity |
 | `client:only="react"` | Client-only, no SSR | Components that can't server-render |
 
-```astro
----
-import Counter from '../components/Counter.tsx';
-import HeavyChart from '../components/HeavyChart.tsx';
----
-
-<!-- Hydrates immediately -->
-<Counter client:load />
-
-<!-- Hydrates when visible -->
-<HeavyChart client:visible />
-```
-
 ## Content Collections
 
-Define collections in `src/content.config.ts` (Astro v5+) using the Content Layer API:
+Define in `src/content.config.ts` (Astro v5+) using the Content Layer API:
 
 ```ts
 import { defineCollection, z } from 'astro:content';
@@ -106,173 +66,56 @@ const blog = defineCollection({
   loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
   schema: z.object({
     title: z.string(),
-    description: z.string(),
     pubDate: z.coerce.date(),
-    updatedDate: z.coerce.date().optional(),
-    heroImage: z.string().optional(),
     draft: z.boolean().default(false),
     tags: z.array(z.string()).default([]),
   }),
 });
-
 export const collections = { blog };
 ```
 
-### Querying Collections
+Query collections:
 
 ```astro
 ---
-import { getCollection, getEntry } from 'astro:content';
-
-// All published posts, sorted by date
+import { getCollection } from 'astro:content';
 const posts = (await getCollection('blog', ({ data }) => !data.draft))
   .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
-
-// Single entry
-const entry = await getEntry('blog', 'first-post');
 ---
 ```
 
 ## Routing
 
-### Static Routes
-
-Every `.astro` or `.md` file in `src/pages/` becomes a route.
-
-### Dynamic Routes
+Every `.astro` or `.md` file in `src/pages/` becomes a route. For dynamic routes:
 
 ```astro
 ---
 // src/pages/blog/[slug].astro
 import { getCollection } from 'astro:content';
-
 export async function getStaticPaths() {
   const posts = await getCollection('blog');
-  return posts.map(post => ({
-    params: { slug: post.id },
-    props: { post },
-  }));
+  return posts.map(post => ({ params: { slug: post.id }, props: { post } }));
 }
-
 const { post } = Astro.props;
 const { Content } = await post.render();
 ---
-
 <Content />
 ```
 
-### Server-Side Rendering (On-Demand)
-
-Enable SSR with an adapter in `astro.config.mjs`:
-
-```js
-import { defineConfig } from 'astro/config';
-import node from '@astrojs/node';
-
-export default defineConfig({
-  output: 'server', // or 'hybrid' for mixed static + server
-  adapter: node({ mode: 'standalone' }),
-});
-```
+**SSR**: Set `output: 'server'` (or `'hybrid'`) and add an adapter (`node`, `vercel`, `netlify`, `cloudflare`) in `astro.config.mjs`.
 
 ## Layouts
 
-```astro
----
-// src/layouts/BaseLayout.astro
-interface Props {
-  title: string;
-  description?: string;
-}
-const { title, description = 'My Astro Site' } = Astro.props;
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content={description} />
-    <title>{title}</title>
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
+Define in `src/layouts/BaseLayout.astro` — a full HTML shell with `<slot />` for page content. Pass `title` and `description` as props.
 
 ## Integrations
 
-Use `astro add` for official integrations:
-
-```bash
-npx astro add react        # Add React support
-npx astro add tailwind     # Add Tailwind CSS v4
-npx astro add mdx          # Add MDX support
-npx astro add sitemap      # Add sitemap generation
-npx astro add node         # Add Node.js SSR adapter
-npx astro add vercel       # Add Vercel adapter
-npx astro add netlify      # Add Netlify adapter
-npx astro add cloudflare   # Add Cloudflare adapter
-```
-
-## API Routes (Endpoints)
-
-```ts
-// src/pages/api/search.ts
-import type { APIRoute } from 'astro';
-
-export const GET: APIRoute = async ({ url }) => {
-  const query = url.searchParams.get('q');
-  const results = await searchDatabase(query);
-  return new Response(JSON.stringify(results), {
-    headers: { 'Content-Type': 'application/json' },
-  });
-};
-
-export const POST: APIRoute = async ({ request }) => {
-  const body = await request.json();
-  // handle mutation
-  return new Response(JSON.stringify({ ok: true }), { status: 200 });
-};
-```
-
-## Actions (Server Mutations)
+Use `astro add` for react, tailwind, mdx, sitemap, node, vercel, netlify, cloudflare.
 
-Define type-safe server actions in `src/actions/index.ts`:
+## API Routes & Actions
 
-```ts
-import { defineAction } from 'astro:actions';
-import { z } from 'astro:schema';
-
-export const server = {
-  subscribe: defineAction({
-    accept: 'form',
-    input: z.object({ email: z.string().email() }),
-    handler: async ({ email }) => {
-      await addToNewsletter(email);
-      return { success: true };
-    },
-  }),
-};
-```
-
-## Performance Patterns
-
-- **Zero JS by default** — only ship JavaScript for interactive islands.
-- **Image optimization** — use `astro:assets` for automatic image optimization.
-- **View Transitions** — use `<ViewTransitions />` for smooth page navigation.
-- **Prefetching** — enabled by default for visible links.
-- **CSS scoping** — styles in `.astro` files are scoped automatically.
-
-```astro
----
-import { Image } from 'astro:assets';
-import heroImage from '../assets/hero.jpg';
----
-
-<Image src={heroImage} alt="Hero" width={800} />
-```
+- **API routes**: Export `GET`/`POST` handlers from `src/pages/api/*.ts` returning `new Response(...)`.
+- **Actions**: Use `defineAction` in `src/actions/index.ts` for type-safe server mutations with Zod validation.
 
 ## Anti-Patterns
 
@@ -286,3 +129,4 @@ import heroImage from '../assets/hero.jpg';
 | Giant monolithic pages | Hard to maintain and test | Split into layouts + reusable components |
 | Ignoring `astro add` for integrations | Manual config is error-prone | Use `astro add` for official integrations |
 | Missing `alt` on images | Accessibility violation | Always provide descriptive `alt` text |
+| Not using `astro:assets` for images | Missing optimization | Use `<Image>` from `astro:assets` |

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

@@ -11,16 +11,36 @@ Generic Convex development methodology. For project-specific schema, functions,
 
 ## 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
+**Function Registration**
+- Public: `query`/`mutation`/`action`; Private: `internalQuery`/`internalMutation`/`internalAction` (import from `./_generated/server`)
+- Always include `returns` validator; use `returns: v.null()` when the function returns nothing (JS implicitly returns `null`)
+
+**Function References**
+- Use `api.filename.functionName` for public and `internal.filename.functionName` for internal functions (from `./_generated/api`)
+- Never pass functions directly to `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` — always use function references
+
+**Queries**
+- Do NOT use `.filter()` — define an index in the schema and use `.withIndex()` instead
+- Use `.unique()` for single document queries
+- No `.delete()` on queries — collect results, then call `ctx.db.delete(row._id)` on each
+
+**Actions**
+- Add `"use node";` at the top of files containing actions that use Node.js built-in modules
+- Never use `ctx.db` inside actions — actions don't have database access; use `ctx.runQuery`/`ctx.runMutation` instead
+
+**Schema**
+- Index name must include all fields: `["field1", "field2"]` → `"by_field1_and_field2"`
+- Index fields must be queried in definition order
+- Do NOT define `_id` or `_creationTime` — they are automatic system fields
+
+**General**
+- Schema-first design: define in `convex/schema.ts` using `defineSchema`/`defineTable`
+- Mutations are ACID transactional; use actions for external API calls or side effects
+- Never await queries in mutations — they run in separate contexts
+- Use `.paginate()` for large result sets
+- Use `Id<'tableName'>` for document ID types (from `./_generated/dataModel`)
+- Use `v.null()` not `v.undefined()` — `undefined` is not a valid Convex value
+- Environment variables: set via Convex dashboard; access with `process.env` in actions only
 
 ## Schema Patterns
 
@@ -34,7 +54,9 @@ export default defineSchema({
     name: v.string(),
     email: v.string(),
     role: v.union(v.literal("admin"), v.literal("user")),
-  }).index("by_email", ["email"]),
+  })
+    .index("by_email", ["email"])
+    .index("by_role", ["role"]),
 });
 ```
 
@@ -45,9 +67,12 @@ import { v } from "convex/values";
 
 export const list = query({
   args: { role: v.optional(v.string()) },
+  returns: v.array(v.any()),
   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")
+        .withIndex("by_role", q => q.eq("role", args.role!))
+        .collect();
     }
     return await ctx.db.query("users").collect();
   },
@@ -61,6 +86,7 @@ import { v } from "convex/values";
 
 export const create = mutation({
   args: { name: v.string(), email: v.string() },
+  returns: v.id("users"),
   handler: async (ctx, args) => {
     return await ctx.db.insert("users", { ...args, role: "user" });
   },

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

@@ -54,17 +54,21 @@ Place functions in `netlify/functions/`:
 
 ```typescript
 // netlify/functions/hello.ts
-import type { Handler } from '@netlify/functions';
+import type { Context, Config } from "@netlify/functions";
 
-export const handler: Handler = async (event) => {
-  return {
-    statusCode: 200,
-    body: JSON.stringify({ message: 'Hello 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",
 };
 ```
 
-- Functions are available at `/.netlify/functions/<name>`
+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)
@@ -110,15 +114,15 @@ export const config = { path: '/geo' };
 
 ```typescript
 // netlify/functions/daily-task.ts
-import type { Handler } from '@netlify/functions';
+import type { Config } from "@netlify/functions";
 
-export const handler: Handler = async () => {
-  // Run daily task
-  return { statusCode: 200, body: 'OK' };
+export default async (req: Request) => {
+  const { next_run } = await req.json();
+  console.log("Next invocation at:", next_run);
 };
 
-export const config = {
-  schedule: '0 0 * * *', // Daily at midnight UTC
+export const config: Config = {
+  schedule: "0 0 * * *", // Daily at midnight UTC
 };
 ```