diff --git a/.claude/agents/architect.md b/.claude/agents/architect.md
new file mode 100644
index 000000000..50af22b84
--- /dev/null
+++ b/.claude/agents/architect.md
@@ -0,0 +1,21 @@
+---
+name: architect
+description: Design and planning. Component deep dives, architectural evaluation, implementation and refactoring plans, and design proposals, persisted to docs/planning/.
+tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal, Agent, Write, Edit, WebFetch, WebSearch
+---
+
+Your instructions are maintained for opencode in `.opencode/agent/architect.md`, relative to the
+repository root. Before doing anything else, read that file and adopt everything after its YAML
+frontmatter as your instructions. The frontmatter configures opencode only; ignore it.
+
+When following those instructions in Claude Code:
+
+- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of
+ the same names.
+- Skills are loaded with the Skill tool.
+- An `explore` subagent is the `Explore` agent. Claude Code subagents cannot start other agents,
+ so when you are running as a subagent, explore directly.
+- Use Write and Edit only under `docs/planning/`. Bash is not restricted to the read-only
+ commands the frontmatter lists, but you must keep to them.
+- Where the instructions say to switch to Build mode, tell the user to continue in a normal
+ Claude Code session.
diff --git a/.claude/agents/code-review.md b/.claude/agents/code-review.md
new file mode 100644
index 000000000..46f0bb876
--- /dev/null
+++ b/.claude/agents/code-review.md
@@ -0,0 +1,22 @@
+---
+name: code-review
+description: Code review of local changes and GitHub pull requests. Works the safety, API, and style checklists, fans out to per-axis reviewers, and reports findings without changing code. Use for PR reviews, safety and security audits, and pre-submit checks.
+tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal, Agent, Write, WebFetch, WebSearch
+---
+
+Your instructions are maintained for opencode in `.opencode/agent/code-review.md`, relative to the
+repository root. Before doing anything else, read that file and adopt everything after its YAML
+frontmatter as your instructions. The frontmatter configures opencode only; ignore it.
+
+When following those instructions in Claude Code:
+
+- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of
+ the same names.
+- Skills are loaded with the Skill tool.
+- An `explore` subagent is the `Explore` agent; `review-safety`, `review-api`, and `review-style`
+ are agents of the same names. Claude Code subagents cannot start other agents, so when you are
+ running as a subagent, skip the fan-out and work the checklists yourself.
+- Use Write only for scratch files under `/tmp/opencode/`. Bash is not restricted to the
+ read-only commands the frontmatter lists, but you must keep to them.
+- Where the instructions say to switch to Build mode, tell the user to continue in a normal
+ Claude Code session.
diff --git a/.claude/agents/review-api.md b/.claude/agents/review-api.md
new file mode 100644
index 000000000..9df624e2b
--- /dev/null
+++ b/.claude/agents/review-api.md
@@ -0,0 +1,17 @@
+---
+name: review-api
+description: Single-axis review of performance, API design, backward compatibility, security and standards compliance for a diff or component. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own.
+tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal
+---
+
+Your instructions are maintained for opencode in `.opencode/agent/review-api.md`, relative to the
+repository root. Before doing anything else, read that file and adopt everything after its YAML
+frontmatter as your instructions. The frontmatter configures opencode only; ignore it.
+
+When following those instructions in Claude Code:
+
+- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of
+ the same names.
+- Skills are loaded with the Skill tool.
+- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to
+ them.
diff --git a/.claude/agents/review-safety.md b/.claude/agents/review-safety.md
new file mode 100644
index 000000000..9cfdda8a0
--- /dev/null
+++ b/.claude/agents/review-safety.md
@@ -0,0 +1,17 @@
+---
+name: review-safety
+description: Single-axis memory-safety and thread-safety review of C++ and Rust in a diff or component, including unsafe blocks and CXX bridges. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own.
+tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal
+---
+
+Your instructions are maintained for opencode in `.opencode/agent/review-safety.md`, relative to the
+repository root. Before doing anything else, read that file and adopt everything after its YAML
+frontmatter as your instructions. The frontmatter configures opencode only; ignore it.
+
+When following those instructions in Claude Code:
+
+- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of
+ the same names.
+- Skills are loaded with the Skill tool.
+- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to
+ them.
diff --git a/.claude/agents/review-style.md b/.claude/agents/review-style.md
new file mode 100644
index 000000000..eb36a8e47
--- /dev/null
+++ b/.claude/agents/review-style.md
@@ -0,0 +1,17 @@
+---
+name: review-style
+description: Single-axis style and coding-convention review of a diff or component, dispatching to the KJ/C++, Rust or TypeScript guide by file type. Returns findings only, in the shared finding format. Invoked by the code-review agent's review fan-out; not useful on its own.
+tools: Read, Grep, Glob, Bash, Skill, mcp__workerd__compat-date-at, mcp__workerd__next-capnp-ordinal
+---
+
+Your instructions are maintained for opencode in `.opencode/agent/review-style.md`, relative to the
+repository root. Before doing anything else, read that file and adopt everything after its YAML
+frontmatter as your instructions. The frontmatter configures opencode only; ignore it.
+
+When following those instructions in Claude Code:
+
+- Tools named `compat-date-at` and `next-capnp-ordinal` are the `workerd` MCP server's tools of
+ the same names.
+- Skills are loaded with the Skill tool.
+- Bash is not restricted to the read-only commands the frontmatter lists, but you must keep to
+ them.
diff --git a/.claude/commands b/.claude/commands
new file mode 120000
index 000000000..8f0a3d838
--- /dev/null
+++ b/.claude/commands
@@ -0,0 +1 @@
+../.opencode/commands
\ No newline at end of file
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 000000000..e5da19da9
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../.opencode/skills
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index d89d37f4f..8c62cb2cd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,7 +37,12 @@ package-lock.json
coverage
perf.data
-.claude
+# Claude Code: track the shared project config, which reuses the opencode agents, commands,
+# skills, and tools under .opencode/; ignore everything else, such as settings.local.json.
+.claude/*
+!.claude/agents/
+!.claude/commands
+!.claude/skills
# opencode auto-generates package.json, bun.lock, and .gitignore inside .opencode/
# at startup to install plugin dependencies. These are runtime artifacts that should
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 000000000..d68529486
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,11 @@
+{
+ "mcpServers": {
+ "workerd": {
+ "command": "sh",
+ "args": [
+ "-c",
+ "exec node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON \"$(git rev-parse --show-toplevel)/.opencode/lib/mcp-server.ts\""
+ ]
+ }
+ }
+}
diff --git a/.opencode/tools/capnp.ts b/.opencode/lib/capnp.ts
similarity index 53%
rename from .opencode/tools/capnp.ts
rename to .opencode/lib/capnp.ts
index bf11105b1..63c34ae44 100644
--- a/.opencode/tools/capnp.ts
+++ b/.opencode/lib/capnp.ts
@@ -1,7 +1,12 @@
// Shared helper for running capnpc-capnp on .capnp schema files.
// Used by next-capnp-ordinal and compat-date-at tools.
-import path from 'path';
+import { execFile } from 'node:child_process';
+import { access, constants, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
/**
* Run capnpc-capnp on a .capnp file and return the canonical text output.
@@ -9,7 +14,7 @@ import path from 'path';
* Automatically locates the bazel-built capnp tools, building them if needed.
* Includes standard import paths for workerd's capnp files.
*
- * @param root - Project root directory (ctx.worktree or ctx.directory)
+ * @param root - Project root directory (the workerd checkout)
* @param filePath - Absolute path to the .capnp file
* @returns The canonical schema text, or an error string prefixed with "Error:"
*/
@@ -25,19 +30,22 @@ export async function runCapnpcCapnp(
root,
'bazel-bin/external/+http+capnp-cpp/src/capnp/capnpc-capnp'
);
- const importPath = path.join(
- root,
- 'bazel-workerd/external/+http+capnp-cpp/src'
- );
// Check tools exist, build if needed
try {
- await Bun.$`test -x ${capnp} && test -x ${capnpcCapnp}`.quiet();
+ await access(capnp, constants.X_OK);
+ await access(capnpcCapnp, constants.X_OK);
} catch {
try {
- await Bun.$`bazel build @capnp-cpp//src/capnp:capnp_tool @capnp-cpp//src/capnp:capnpc-capnp`
- .cwd(root)
- .quiet();
+ await execFileAsync(
+ 'bazel',
+ [
+ 'build',
+ '@capnp-cpp//src/capnp:capnp_tool',
+ '@capnp-cpp//src/capnp:capnpc-capnp',
+ ],
+ { cwd: root, maxBuffer: 64 * 1024 * 1024 }
+ );
} catch {
return {
error:
@@ -46,6 +54,20 @@ export async function runCapnpcCapnp(
}
}
+ // The execroot's convenience symlink is named after the checkout directory (`bazel-workerd`,
+ // or `bazel-
` in a worktree), so reach the execroot through `bazel-out` instead.
+ let execroot: string;
+ try {
+ execroot = path.dirname(await realpath(path.join(root, 'bazel-out')));
+ } catch {
+ return {
+ error:
+ 'Could not locate the bazel execroot: the bazel-out symlink in the project root is ' +
+ 'missing. Run a bazel build (without --symlink_prefix or --experimental_convenience_symlinks=ignore) first.',
+ };
+ }
+ const importPath = path.join(execroot, 'external/+http+capnp-cpp/src');
+
const fileDir = path.dirname(filePath);
const importArgs = [
'--no-standard-import',
@@ -57,9 +79,12 @@ export async function runCapnpcCapnp(
];
try {
- return await Bun.$`${capnp} compile ${importArgs} -o${capnpcCapnp} ${filePath}`
- .cwd(root)
- .text();
+ const { stdout } = await execFileAsync(
+ capnp,
+ ['compile', ...importArgs, `-o${capnpcCapnp}`, filePath],
+ { cwd: root, maxBuffer: 64 * 1024 * 1024 }
+ );
+ return stdout;
} catch (e: any) {
return { error: `capnpc-capnp failed:\n${e.stderr || e.message}` };
}
diff --git a/.opencode/lib/compat-date-at.ts b/.opencode/lib/compat-date-at.ts
new file mode 100644
index 000000000..2b71f9fc6
--- /dev/null
+++ b/.opencode/lib/compat-date-at.ts
@@ -0,0 +1,229 @@
+import { runCapnpcCapnp, resolveCapnpPath } from './capnp.ts';
+import type { ToolDef } from './tool-def.ts';
+
+export const compatDateAt: ToolDef<{ date?: string; flag?: string }> = {
+ name: 'compat-date-at',
+ description:
+ 'List which compatibility flags are active or inactive at a given date. ' +
+ 'Parses compatibility-date.capnp via the capnp compiler. Useful for understanding ' +
+ 'what behavior a worker gets at a specific compat date, debugging test variant ' +
+ 'failures (@, @all-compat-flags, @all-autogates), and writing .wd-test configs.',
+ args: {
+ date: {
+ optional: true,
+ description:
+ 'Compatibility date (YYYY-MM-DD). Omit to list all flags with their enable dates.',
+ },
+ flag: {
+ optional: true,
+ description:
+ 'Filter by flag name substring (matches enable flag, disable flag, or field name)',
+ },
+ },
+ async run(root, args) {
+ const flags = await parseCompatFlags(root);
+ if (typeof flags === 'string') return flags;
+
+ let filtered = flags;
+
+ if (args.flag) {
+ const q = args.flag.toLowerCase();
+ filtered = flags.filter(
+ (f) =>
+ f.fieldName.toLowerCase().includes(q) ||
+ f.enableFlag?.toLowerCase().includes(q) ||
+ f.disableFlag?.toLowerCase().includes(q)
+ );
+ if (filtered.length === 0) {
+ return `No flags matching '${args.flag}'. There are ${flags.length} total flags.`;
+ }
+ }
+
+ if (!args.date) {
+ return formatAllFlags(filtered);
+ }
+
+ if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) {
+ return `Invalid date format: '${args.date}'. Use YYYY-MM-DD.`;
+ }
+
+ return formatAtDate(filtered, args.date);
+ },
+};
+
+// --- Types ---
+
+interface CompatFlag {
+ fieldName: string;
+ ordinal: number;
+ enableFlag: string | null;
+ disableFlag: string | null;
+ enableDate: string | null;
+ enableAllDates: boolean;
+ experimental: boolean;
+ neededByFl: boolean;
+ impliedBy: string | null;
+ obsolete: boolean;
+}
+
+// --- Parsing ---
+
+const COMPAT_CAPNP = 'src/workerd/io/compatibility-date.capnp';
+
+async function parseCompatFlags(root: string): Promise {
+ const filePath = resolveCapnpPath(root, COMPAT_CAPNP);
+ const result = await runCapnpcCapnp(root, filePath);
+ if (typeof result !== 'string') return result.error;
+
+ const flags: CompatFlag[] = [];
+
+ for (const line of result.split('\n')) {
+ const m = line.match(/^\s+(\w+)\s+@(\d+)\s+:Bool/);
+ if (!m) continue;
+
+ const fieldName = m[1];
+ const ordinal = parseInt(m[2], 10);
+
+ flags.push({
+ fieldName,
+ ordinal,
+ enableFlag: extractAnno(line, 'compatEnableFlag'),
+ disableFlag: extractAnno(line, 'compatDisableFlag'),
+ enableDate: extractAnno(line, 'compatEnableDate'),
+ enableAllDates: line.includes('$compatEnableAllDates('),
+ experimental: line.includes('$experimental('),
+ neededByFl: line.includes('$neededByFl('),
+ impliedBy: extractRawAnno(line, 'impliedByAfterDate'),
+ obsolete: fieldName.startsWith('obsolete'),
+ });
+ }
+
+ return flags;
+}
+
+function extractAnno(line: string, name: string): string | null {
+ const m = line.match(new RegExp(`\\$${name}\\("([^"]*)"\\)`));
+ return m ? m[1] : null;
+}
+
+function extractRawAnno(line: string, name: string): string | null {
+ const m = line.match(new RegExp(`\\$${name}\\(([^)]+)\\)`));
+ return m ? m[1] : null;
+}
+
+// --- Formatting ---
+
+function formatAllFlags(flags: CompatFlag[]): string {
+ const active = flags.filter((f) => !f.obsolete);
+ const obsolete = flags.filter((f) => f.obsolete);
+
+ const dated = active
+ .filter((f) => f.enableDate || f.enableAllDates)
+ .sort((a, b) => (a.enableDate || '').localeCompare(b.enableDate || ''));
+ const experimental = active.filter(
+ (f) => f.experimental && !f.enableDate && !f.enableAllDates
+ );
+ const noDate = active.filter(
+ (f) => !f.experimental && !f.enableDate && !f.enableAllDates
+ );
+
+ let out = `## All Compatibility Flags (${active.length} active, ${obsolete.length} obsolete)\n\n`;
+
+ if (dated.length > 0) {
+ out += `### Date-gated (${dated.length})\n\n`;
+ for (const f of dated) {
+ const d = f.enableAllDates ? 'ALL DATES' : f.enableDate;
+ const extra: string[] = [];
+ if (f.neededByFl) extra.push('FL');
+ if (f.experimental) extra.push('experimental');
+ if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`);
+ const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : '';
+ out += `- **${d}**: \`${f.enableFlag || f.fieldName}\`${suffix}\n`;
+ }
+ }
+
+ if (noDate.length > 0) {
+ out += `\n### Opt-in only — no default date (${noDate.length})\n\n`;
+ for (const f of noDate) {
+ const extra: string[] = [];
+ if (f.impliedBy) extra.push(`implied by ${f.impliedBy}`);
+ const suffix = extra.length > 0 ? ` (${extra.join(', ')})` : '';
+ out += `- \`${f.enableFlag || f.fieldName}\`${suffix}\n`;
+ }
+ }
+
+ if (experimental.length > 0) {
+ out += `\n### Experimental — requires --experimental (${experimental.length})\n\n`;
+ for (const f of experimental) {
+ out += `- \`${f.enableFlag || f.fieldName}\`\n`;
+ }
+ }
+
+ return out;
+}
+
+function formatAtDate(flags: CompatFlag[], date: string): string {
+ const active = flags.filter((f) => !f.obsolete);
+
+ const enabled: CompatFlag[] = [];
+ const notYetEnabled: CompatFlag[] = [];
+ const optInOnly: CompatFlag[] = [];
+ const experimental: CompatFlag[] = [];
+
+ for (const f of active) {
+ if (f.enableAllDates) {
+ enabled.push(f);
+ } else if (f.enableDate) {
+ if (f.enableDate <= date) {
+ enabled.push(f);
+ } else {
+ notYetEnabled.push(f);
+ }
+ } else if (f.experimental) {
+ experimental.push(f);
+ } else {
+ optInOnly.push(f);
+ }
+ }
+
+ let out = `## Flags at compatibility date "${date}"\n\n`;
+ out += `- **${enabled.length}** enabled by default\n`;
+ out += `- **${notYetEnabled.length}** not yet enabled (future date)\n`;
+ out += `- **${optInOnly.length}** opt-in only (no date set)\n`;
+ out += `- **${experimental.length}** experimental\n\n`;
+
+ if (enabled.length > 0) {
+ out += `### Enabled by default (${enabled.length})\n\n`;
+ for (const f of enabled.sort((a, b) =>
+ (a.enableDate || '').localeCompare(b.enableDate || '')
+ )) {
+ const d = f.enableAllDates ? 'all' : f.enableDate;
+ out += `- \`${f.enableFlag || f.fieldName}\` (since ${d})\n`;
+ }
+ }
+
+ if (notYetEnabled.length > 0) {
+ out += `\n### Not yet enabled — date is after "${date}" (${notYetEnabled.length})\n\n`;
+ for (const f of notYetEnabled.sort((a, b) =>
+ (a.enableDate || '').localeCompare(b.enableDate || '')
+ )) {
+ out += `- \`${f.enableFlag || f.fieldName}\` (${f.enableDate})\n`;
+ }
+ }
+
+ if (optInOnly.length > 0) {
+ out += `\n### Opt-in only (${optInOnly.length})\n\n`;
+ for (const f of optInOnly) {
+ out += `- \`${f.enableFlag || f.fieldName}\`\n`;
+ }
+ }
+
+ if (experimental.length > 0) {
+ out += `\n### Experimental (${experimental.length})\n\n`;
+ for (const f of experimental) {
+ out += `- \`${f.enableFlag || f.fieldName}\`\n`;
+ }
+ }
+
+ return out;
+}
diff --git a/.opencode/lib/mcp-server.ts b/.opencode/lib/mcp-server.ts
new file mode 100644
index 000000000..7b3ae5d25
--- /dev/null
+++ b/.opencode/lib/mcp-server.ts
@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Minimal stdio MCP server exposing the tools in this directory to Claude Code, which registers
+// it in `/.mcp.json`. opencode loads the same tools natively from `.opencode/tools/`.
+//
+// Speaks newline-delimited JSON-RPC 2.0 and implements only what a tools-only server needs:
+// `initialize`, `ping`, `tools/list`, and `tools/call`. It has no dependencies, so it runs on a
+// fresh checkout with Node 22.18 or later (for TypeScript type stripping).
+
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { compatDateAt } from './compat-date-at.ts';
+import { nextCapnpOrdinal } from './next-capnp-ordinal.ts';
+import { toJsonSchema, type ToolDef } from './tool-def.ts';
+
+const TOOLS: ToolDef[] = [compatDateAt, nextCapnpOrdinal];
+const ROOT = path.resolve(import.meta.dirname, '../..');
+
+type Id = string | number | null;
+
+function send(message: object): void {
+ process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n');
+}
+
+async function handle(method: string, params: any): Promise