The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(skills): align documentation-lookup with CONTRIBUTING template; add cross-harness (Codex/Cursor) skill copies
Carson Rodriguesf03db8278c3e
diff --git a/.agents/skills/bun-runtime/SKILL.md b/.agents/skills/bun-runtime/SKILL.mdnew file mode 100644index 000000000..05bac8dca--- /dev/null+++ b/.agents/skills/bun-runtime/SKILL.md@@ -0,0 +1,106 @@+---+name: bun-runtime+description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.+origin: ECC+---++# Bun Runtime++Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner. Use this skill when working in or migrating to Bun.++## Core Concepts++- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).+- **Package manager**: `bun install` is significantly faster than npm/yarn; lockfile is `bun.lockb`.+- **Bundler**: Built-in bundler and transpiler for apps and libraries.+- **Test runner**: Built-in `bun test` with Jest-like API.++## When to Use Bun vs Node++- **Prefer Bun** for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).+- **Prefer Node** for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.++## Quick Reference++### Run and install++```bash+# Install dependencies (creates/updates bun.lockb)+bun install++# Run a script (package.json "scripts" or direct file)+bun run dev+bun run src/index.ts++# Run a file directly+bun src/index.ts+```++### Scripts and env++```bash+# Load .env and run+bun run --env-file=.env dev++# Inline env+FOO=bar bun run script.ts+```++### Testing++```bash+# Run tests (Jest-like API)+bun test++# Watch mode+bun test --watch+```++```typescript+// test/example.test.ts+import { expect, test } from "bun:test";++test("add", () => {+ expect(1 + 2).toBe(3);+});+```++### API (runtime)++```typescript+// File I/O (Bun-native, fast)+const file = Bun.file("package.json");+const json = await file.json();++// HTTP server+Bun.serve({+ port: 3000,+ fetch(req) {+ return new Response("Hello");+ },+});+```++## Migration from Node++- Replace `node script.js` with `bun run script.js` or `bun script.js`.+- Run `bun install` in place of `npm install`; most packages work. If something fails, try `bun install --backend=hardlink` or report upstream.+- Use `bun run` for npm scripts; `bun x` for npx-style one-off runs (e.g. `bun x prisma generate`).+- Node built-ins (`fs`, `path`, `http`, etc.) are supported; prefer Bun APIs where they exist for better performance.++## Vercel and deployment++- Vercel supports the Bun runtime. Set runtime to Bun in project settings or use the Bun build preset where available.+- Build command: often `bun run build` or `bun build ./src/index.ts --outdir=dist`.+- Install command: `bun install --frozen-lockfile` for reproducible deploys.++## Best Practices++- Use `bun.lockb` and commit it for reproducible installs.+- Prefer `bun run` for scripts so env and lifecycle are consistent.+- For TypeScript, Bun runs `.ts` natively; no separate `ts-node` needed.+- Keep dependencies up to date; Bun and the ecosystem evolve quickly.++## When to Use This Skill++Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.diff --git a/.agents/skills/documentation-lookup/SKILL.md b/.agents/skills/documentation-lookup/SKILL.mdnew file mode 100644index 000000000..56c6ad9bc--- /dev/null+++ b/.agents/skills/documentation-lookup/SKILL.md@@ -0,0 +1,79 @@+---+name: documentation-lookup+description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).+origin: ECC+---++# Documentation Lookup (Context7)++When the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools `resolve-library-id` and `query-docs`) instead of relying on training data.++## Core Concepts++- **Context7**: MCP server that exposes live documentation; use it instead of training data for libraries and APIs.+- **resolve-library-id**: Returns Context7-compatible library IDs (e.g. `/vercel/next.js`) from a library name and query.+- **query-docs**: Fetches documentation and code snippets for a given library ID and question. Always call resolve-library-id first to get a valid library ID.++## When to Use This Skill++Activate when the user:++- Asks setup or configuration questions (e.g. "How do I configure Next.js middleware?")+- Requests code that depends on a library ("Write a Prisma query for...")+- Needs API or reference information ("What are the Supabase auth methods?")+- Mentions specific frameworks or libraries (React, Vue, Svelte, Express, Tailwind, Prisma, Supabase, etc.)++## How to Fetch Documentation++### Step 1: Resolve the Library ID++Call the **resolve-library-id** MCP tool with:++- **libraryName**: The library or product name taken from the user's question (e.g. `Next.js`, `Prisma`, `Supabase`).+- **query**: The user's full question. This improves relevance ranking of results.++You must obtain a Context7-compatible library ID (format `/org/project` or `/org/project/version`) before querying docs. Do not call query-docs without a valid library ID from this step.++### Step 2: Select the Best Match++From the resolution results, choose one result using:++- **Name match**: Prefer exact or closest match to what the user asked for.+- **Benchmark score**: Higher scores indicate better documentation quality (100 is highest).+- **Source reputation**: Prefer High or Medium reputation when available.+- **Version**: If the user specified a version (e.g. "React 19", "Next.js 15"), prefer a version-specific library ID if listed (e.g. `/org/project/v1.2.0`).++### Step 3: Fetch the Documentation++Call the **query-docs** MCP tool with:++- **libraryId**: The selected Context7 library ID from Step 2 (e.g. `/vercel/next.js`).+- **query**: The user's specific question or task. Be specific to get relevant snippets.++Limit: do not call query-docs (or resolve-library-id) more than 3 times per question. If the answer is unclear after 3 calls, use the best information you have.++### Step 4: Use the Documentation++- Answer the user's question using the fetched, current information.+- Include relevant code examples from the docs when helpful.+- Cite the library or version when it matters (e.g. "In Next.js 15...").++## Code Examples++Example flow for "How do I set up Next.js middleware?":++1. Call **resolve-library-id** with `libraryName: "Next.js"`, `query: "How do I set up Next.js middleware?"`.+2. From results, pick the best match (e.g. `/vercel/next.js`) by name and benchmark score.+3. Call **query-docs** with `libraryId: "/vercel/next.js"`, `query: "How do I set up Next.js middleware?"`.+4. Use the returned snippets and text to answer; include a minimal `middleware.ts` example from the docs if relevant.++## Best Practices++- **Be specific**: Use the user's full question as the query where possible for better relevance.+- **Version awareness**: When users mention versions, use version-specific library IDs from the resolve step when available.+- **Prefer official sources**: When multiple matches exist, prefer official or primary packages over community forks.+- **No sensitive data**: Do not include API keys, passwords, or other secrets in any query sent to Context7.++## When to Use++Use this skill whenever the user's request depends on accurate, up-to-date behavior of a library, framework, or API. It applies across harnesses that have the Context7 MCP configured (e.g. Claude Code, Cursor, Codex with Context7).diff --git a/.agents/skills/nextjs-turbopack/SKILL.md b/.agents/skills/nextjs-turbopack/SKILL.mdnew file mode 100644index 000000000..be57a03b3--- /dev/null+++ b/.agents/skills/nextjs-turbopack/SKILL.md@@ -0,0 +1,60 @@+---+name: nextjs-turbopack+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.+origin: ECC+---++# Next.js and Turbopack++Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates. Use this skill when working with Next.js 16+ or tuning build performance.++## Core Concepts++- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.+- **Production**: Next.js production builds still use the existing production bundler (webpack-based); Turbopack is focused on dev today.++## When to Use Turbopack vs Webpack++- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with env or flag (e.g. `--no-turbopack` if your version supports it).+- **Production**: No change; production build pipeline is unchanged.++## Commands++```bash+# Dev with Turbopack (Next.js 16+ default)+next dev++# Build (unchanged; not Turbopack)+next build++# Start production server+next start+```++## File-System Caching++Turbopack caches work on disk so that:++- Restarts reuse previous work; second run is much faster.+- Large projects see 5–14x faster compile times on restart in practice.+- Cache is typically under `.next` or a similar project-local directory; no extra config needed for basic use.++## Bundle Analyzer (Next.js 16.1+)++Next.js 16.1 introduced an experimental Bundle Analyzer to inspect output and find heavy dependencies:++- Enable via config or experimental flag (see Next.js docs for your version).+- Use to optimize code-splitting and trim large dependencies.++## Best Practices++- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.+- For production bundle size issues, use the Bundle Analyzer and `next/bundle-analysis` or equivalent tooling.+- Prefer App Router and server components where possible; they align with current Next.js and Turbopack optimizations.++## When to Use This Skill++Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles with Next.js tooling.diff --git a/.cursor/skills/bun-runtime/SKILL.md b/.cursor/skills/bun-runtime/SKILL.mdnew file mode 100644index 000000000..05bac8dca--- /dev/null+++ b/.cursor/skills/bun-runtime/SKILL.md@@ -0,0 +1,106 @@+---+name: bun-runtime+description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.+origin: ECC+---++# Bun Runtime++Bun is a fast all-in-one JavaScript runtime and toolkit: runtime, package manager, bundler, and test runner. Use this skill when working in or migrating to Bun.++## Core Concepts++- **Runtime**: Drop-in Node-compatible runtime (built on JavaScriptCore, implemented in Zig).+- **Package manager**: `bun install` is significantly faster than npm/yarn; lockfile is `bun.lockb`.+- **Bundler**: Built-in bundler and transpiler for apps and libraries.+- **Test runner**: Built-in `bun test` with Jest-like API.++## When to Use Bun vs Node++- **Prefer Bun** for: new JS/TS projects, scripts where install/run speed matters, Vercel deployments with Bun runtime, and when you want a single toolchain (run + install + test + build).+- **Prefer Node** for: maximum ecosystem compatibility, legacy tooling that assumes Node, or when a dependency has known Bun issues.++## Quick Reference++### Run and install++```bash+# Install dependencies (creates/updates bun.lockb)+bun install++# Run a script (package.json "scripts" or direct file)+bun run dev+bun run src/index.ts++# Run a file directly+bun src/index.ts+```++### Scripts and env++```bash+# Load .env and run+bun run --env-file=.env dev++# Inline env+FOO=bar bun run script.ts+```++### Testing++```bash+# Run tests (Jest-like API)+bun test++# Watch mode+bun test --watch+```++```typescript+// test/example.test.ts+import { expect, test } from "bun:test";++test("add", () => {+ expect(1 + 2).toBe(3);+});+```++### API (runtime)++```typescript+// File I/O (Bun-native, fast)+const file = Bun.file("package.json");+const json = await file.json();++// HTTP server+Bun.serve({+ port: 3000,+ fetch(req) {+ return new Response("Hello");+ },+});+```++## Migration from Node++- Replace `node script.js` with `bun run script.js` or `bun script.js`.+- Run `bun install` in place of `npm install`; most packages work. If something fails, try `bun install --backend=hardlink` or report upstream.+- Use `bun run` for npm scripts; `bun x` for npx-style one-off runs (e.g. `bun x prisma generate`).+- Node built-ins (`fs`, `path`, `http`, etc.) are supported; prefer Bun APIs where they exist for better performance.++## Vercel and deployment++- Vercel supports the Bun runtime. Set runtime to Bun in project settings or use the Bun build preset where available.+- Build command: often `bun run build` or `bun build ./src/index.ts --outdir=dist`.+- Install command: `bun install --frozen-lockfile` for reproducible deploys.++## Best Practices++- Use `bun.lockb` and commit it for reproducible installs.+- Prefer `bun run` for scripts so env and lifecycle are consistent.+- For TypeScript, Bun runs `.ts` natively; no separate `ts-node` needed.+- Keep dependencies up to date; Bun and the ecosystem evolve quickly.++## When to Use This Skill++Use when: adopting Bun, migrating from Node, writing or debugging Bun scripts/tests, or configuring Bun on Vercel or other platforms.diff --git a/.cursor/skills/documentation-lookup/SKILL.md b/.cursor/skills/documentation-lookup/SKILL.mdnew file mode 100644index 000000000..56c6ad9bc--- /dev/null+++ b/.cursor/skills/documentation-lookup/SKILL.md@@ -0,0 +1,79 @@+---+name: documentation-lookup+description: Use up-to-date library and framework docs via Context7 MCP instead of training data. Activates for setup questions, API references, code examples, or when the user names a framework (e.g. React, Next.js, Prisma).+origin: ECC+---++# Documentation Lookup (Context7)++When the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools `resolve-library-id` and `query-docs`) instead of relying on training data.++## Core Concepts++- **Context7**: MCP server that exposes live documentation; use it instead of training data for libraries and APIs.+- **resolve-library-id**: Returns Context7-compatible library IDs (e.g. `/vercel/next.js`) from a library name and query.+- **query-docs**: Fetches documentation and code snippets for a given library ID and question. Always call resolve-library-id first to get a valid library ID.++## When to Use This Skill++Activate when the user:++- Asks setup or configuration questions (e.g. "How do I configure Next.js middleware?")+- Requests code that depends on a library ("Write a Prisma query for...")+- Needs API or reference information ("What are the Supabase auth methods?")+- Mentions specific frameworks or libraries (React, Vue, Svelte, Express, Tailwind, Prisma, Supabase, etc.)++## How to Fetch Documentation++### Step 1: Resolve the Library ID++Call the **resolve-library-id** MCP tool with:++- **libraryName**: The library or product name taken from the user's question (e.g. `Next.js`, `Prisma`, `Supabase`).+- **query**: The user's full question. This improves relevance ranking of results.++You must obtain a Context7-compatible library ID (format `/org/project` or `/org/project/version`) before querying docs. Do not call query-docs without a valid library ID from this step.++### Step 2: Select the Best Match++From the resolution results, choose one result using:++- **Name match**: Prefer exact or closest match to what the user asked for.+- **Benchmark score**: Higher scores indicate better documentation quality (100 is highest).+- **Source reputation**: Prefer High or Medium reputation when available.+- **Version**: If the user specified a version (e.g. "React 19", "Next.js 15"), prefer a version-specific library ID if listed (e.g. `/org/project/v1.2.0`).++### Step 3: Fetch the Documentation++Call the **query-docs** MCP tool with:++- **libraryId**: The selected Context7 library ID from Step 2 (e.g. `/vercel/next.js`).+- **query**: The user's specific question or task. Be specific to get relevant snippets.++Limit: do not call query-docs (or resolve-library-id) more than 3 times per question. If the answer is unclear after 3 calls, use the best information you have.++### Step 4: Use the Documentation++- Answer the user's question using the fetched, current information.+- Include relevant code examples from the docs when helpful.+- Cite the library or version when it matters (e.g. "In Next.js 15...").++## Code Examples++Example flow for "How do I set up Next.js middleware?":++1. Call **resolve-library-id** with `libraryName: "Next.js"`, `query: "How do I set up Next.js middleware?"`.+2. From results, pick the best match (e.g. `/vercel/next.js`) by name and benchmark score.+3. Call **query-docs** with `libraryId: "/vercel/next.js"`, `query: "How do I set up Next.js middleware?"`.+4. Use the returned snippets and text to answer; include a minimal `middleware.ts` example from the docs if relevant.++## Best Practices++- **Be specific**: Use the user's full question as the query where possible for better relevance.+- **Version awareness**: When users mention versions, use version-specific library IDs from the resolve step when available.+- **Prefer official sources**: When multiple matches exist, prefer official or primary packages over community forks.+- **No sensitive data**: Do not include API keys, passwords, or other secrets in any query sent to Context7.++## When to Use++Use this skill whenever the user's request depends on accurate, up-to-date behavior of a library, framework, or API. It applies across harnesses that have the Context7 MCP configured (e.g. Claude Code, Cursor, Codex with Context7).diff --git a/.cursor/skills/nextjs-turbopack/SKILL.md b/.cursor/skills/nextjs-turbopack/SKILL.mdnew file mode 100644index 000000000..be57a03b3--- /dev/null+++ b/.cursor/skills/nextjs-turbopack/SKILL.md@@ -0,0 +1,60 @@+---+name: nextjs-turbopack+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.+origin: ECC+---++# Next.js and Turbopack++Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates. Use this skill when working with Next.js 16+ or tuning build performance.++## Core Concepts++- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.+- **Production**: Next.js production builds still use the existing production bundler (webpack-based); Turbopack is focused on dev today.++## When to Use Turbopack vs Webpack++- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with env or flag (e.g. `--no-turbopack` if your version supports it).+- **Production**: No change; production build pipeline is unchanged.++## Commands++```bash+# Dev with Turbopack (Next.js 16+ default)+next dev++# Build (unchanged; not Turbopack)+next build++# Start production server+next start+```++## File-System Caching++Turbopack caches work on disk so that:++- Restarts reuse previous work; second run is much faster.+- Large projects see 5–14x faster compile times on restart in practice.+- Cache is typically under `.next` or a similar project-local directory; no extra config needed for basic use.++## Bundle Analyzer (Next.js 16.1+)++Next.js 16.1 introduced an experimental Bundle Analyzer to inspect output and find heavy dependencies:++- Enable via config or experimental flag (see Next.js docs for your version).+- Use to optimize code-splitting and trim large dependencies.++## Best Practices++- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.+- For production bundle size issues, use the Bundle Analyzer and `next/bundle-analysis` or equivalent tooling.+- Prefer App Router and server components where possible; they align with current Next.js and Turbopack optimizations.++## When to Use This Skill++Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles with Next.js tooling.diff --git a/skills/documentation-lookup/SKILL.md b/skills/documentation-lookup/SKILL.mdindex cb4cbefbd..56c6ad9bc 100644--- a/skills/documentation-lookup/SKILL.md+++ b/skills/documentation-lookup/SKILL.md@@ -8,6 +8,12 @@ origin: ECCWhen the user asks about libraries, frameworks, or APIs, fetch current documentation via the Context7 MCP (tools `resolve-library-id` and `query-docs`) instead of relying on training data.+## Core Concepts++- **Context7**: MCP server that exposes live documentation; use it instead of training data for libraries and APIs.+- **resolve-library-id**: Returns Context7-compatible library IDs (e.g. `/vercel/next.js`) from a library name and query.+- **query-docs**: Fetches documentation and code snippets for a given library ID and question. Always call resolve-library-id first to get a valid library ID.+## When to Use This SkillActivate when the user:@@ -52,7 +58,16 @@ Limit: do not call query-docs (or resolve-library-id) more than 3 times per ques- Include relevant code examples from the docs when helpful.- Cite the library or version when it matters (e.g. "In Next.js 15...").-## Guidelines+## Code Examples++Example flow for "How do I set up Next.js middleware?":++1. Call **resolve-library-id** with `libraryName: "Next.js"`, `query: "How do I set up Next.js middleware?"`.+2. From results, pick the best match (e.g. `/vercel/next.js`) by name and benchmark score.+3. Call **query-docs** with `libraryId: "/vercel/next.js"`, `query: "How do I set up Next.js middleware?"`.+4. Use the returned snippets and text to answer; include a minimal `middleware.ts` example from the docs if relevant.++## Best Practices- **Be specific**: Use the user's full question as the query where possible for better relevance.- **Version awareness**: When users mention versions, use version-specific library IDs from the resolve step when available.