@bonesofspring/ai-rules 0.2.23 → 0.2.25

package/scripts/generate-opencode-next.mjs

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+/**
+ * Derive presets/opencode/next/** and adapter-map.json from cursor/next.
+ * Maintainer tool; not a consumer CLI command.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDirectory, '..');
+const cursorRoot = path.join(packageRoot, 'presets', 'cursor', 'next');
+const opencodeRoot = path.join(packageRoot, 'presets', 'opencode', 'next');
+
+const ALWAYS_ON_RULES = new Set([
+  'next-app-core',
+  'package-manager',
+  'code-quality-and-refactoring',
+  'ai-local-overlay',
+]);
+
+const DEVELOPER_AGENTS = new Set([
+  'feature-developer',
+  'debugger',
+  'ci-investigator',
+  'qa-tester',
+  'unit-test-generator',
+  'unit-test-healer',
+  'playwright-test-generator',
+  'playwright-test-healer',
+]);
+
+const REVIEW_AGENTS = new Set(['code-reviewer']);
+
+const OMIT = new Map([
+  [
+    'BUGBOT.md',
+    'no-equivalent: Bugbot is Cursor-only; review stays a Verifier skill/role',
+  ],
+  [
+    'hooks.json',
+    'omit until an OpenCode plugin wraps chain-team-phases.sh',
+  ],
+  [
+    'hooks/guard-shell-command.sh',
+    'omit from active wiring; safety policy stays in entry prose, not enforcement',
+  ],
+  [
+    'hooks/examples/format-edited.example.sh',
+    'omit until an OpenCode plugin event API is shipped',
+  ],
+  [
+    'hooks/examples/secret-guard.example.sh',
+    'omit until an OpenCode plugin event API is shipped',
+  ],
+  [
+    'hooks/examples/test-on-save.example.sh',
+    'omit until an OpenCode plugin event API is shipped',
+  ],
+]);
+
+function walkFiles(root) {
+  const files = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        files.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function stripFrontmatter(text) {
+  if (!text.startsWith('---\n')) {
+    return { frontmatter: '', body: text };
+  }
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0) {
+    return { frontmatter: '', body: text };
+  }
+  return {
+    frontmatter: text.slice(4, end),
+    body: text.slice(end + 5).replace(/^\n/, ''),
+  };
+}
+
+function parseFrontmatterFields(frontmatter) {
+  const fields = {};
+  for (const line of frontmatter.split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      continue;
+    }
+    const raw = match[2].trim();
+    fields[match[1]] = raw.replace(/^["']|["']$/g, '');
+  }
+  return fields;
+}
+
+const sharedCoreRoot = path.join(packageRoot, 'presets', '_shared', 'core');
+
+function rewriteConsumerPaths(text) {
+  return text
+    .replaceAll('.cursor/team', '.opencode/team')
+    .replaceAll('.cursor/rules', '.opencode/rules')
+    .replaceAll('.cursor/skills', '.opencode/skills')
+    .replaceAll('.cursor/agents', '.opencode/agents')
+    .replaceAll('.cursor/commands', '.opencode/commands')
+    .replaceAll('.cursor/hooks', '.opencode/hooks')
+    .replaceAll('.cursor/AGENTS.md', '.opencode/AGENTS.md')
+    .replaceAll("'.cursor'", "'.opencode'")
+    .replaceAll('".cursor"', '".opencode"');
+}
+
+function finalizeOpencodeProse(text) {
+  return rewriteConsumerPaths(text)
+    .replace(/`([^`\n]+)\.mdc`/g, '`$1.md`')
+    .replace(/(?<![\w./-])([\w-]+)\.mdc\b/g, '$1.md')
+    .replaceAll('init cursor --preset', 'init opencode --preset')
+    .replaceAll('# MCP (preset `next`, Cursor)', '# MCP (preset `next`, OpenCode)')
+    .replaceAll('(preset `next`, Cursor)', '(preset `next`, OpenCode)')
+    .replaceAll('Copied to `.cursor/mcp.json`', 'Merged into project `opencode.json` `mcp`')
+    .replaceAll('OAuth in Cursor', 'OAuth in OpenCode (operator MCP config)');
+}
+
+function rewriteProse(text) {
+  return finalizeOpencodeProse(text);
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function writeFile(relPath, content) {
+  const dest = path.join(opencodeRoot, relPath);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+}
+
+function sharedCoreStem(text) {
+  const match = text.match(/<!--\s*shared-core:\s*([^\s>]+)\s*-->/);
+  return match ? match[1] : undefined;
+}
+
+function entry({
+  source,
+  target,
+  category,
+  disposition,
+  loadMode,
+  reason,
+  sourceText,
+}) {
+  const item = {
+    source,
+    target,
+    category,
+    disposition,
+    loadMode,
+    reason,
+  };
+  const stem = sourceText ? sharedCoreStem(sourceText) : undefined;
+  if (stem) {
+    item.sharedCoreStem = stem;
+  }
+  return item;
+}
+
+function isEmbedEntryBody(body) {
+  const first = body
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  return Boolean(first && /^<!--\s*shared-core:\s*[^\s>]+\s*-->\s*$/.test(first));
+}
+
+function transformMarkdown(sourceText, { allowEmbedEntry = true } = {}) {
+  const { body } = stripFrontmatter(sourceText);
+  const stem =
+    allowEmbedEntry && isEmbedEntryBody(body) ? sharedCoreStem(body) : undefined;
+  let next;
+  if (stem) {
+    const corePath = path.join(sharedCoreRoot, stem);
+    if (fs.existsSync(corePath)) {
+      const coreBody = fs.readFileSync(corePath, 'utf8').trimEnd();
+      const marker = `<!-- shared-core: ${stem} -->`;
+      next = `${marker}\n\n${coreBody}\n`;
+      next = rewriteConsumerPaths(next);
+    } else {
+      next = rewriteProse(body);
+    }
+  } else {
+    next = rewriteProse(body);
+  }
+  return next.endsWith('\n') ? next : `${next}\n`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(value ?? '');
+}
+
+function transformAgent(source, sourceText) {
+  const { frontmatter, body } = stripFrontmatter(sourceText);
+  const fields = parseFrontmatterFields(frontmatter);
+  const stem = path.basename(source, '.md');
+  const canEditProduction = DEVELOPER_AGENTS.has(stem);
+  const permission = canEditProduction
+    ? 'permission:\n  edit: allow'
+    : 'permission:\n  edit:\n    "*": deny\n    ".opencode/team/**": allow';
+  const description = fields.description || stem;
+  const header = `---\nname: ${stem}\ndescription: ${yamlString(description)}\nmode: subagent\n${permission}\n---\n\n`;
+  const transformed = rewriteProse(body);
+  let withNote = transformed;
+  if (!canEditProduction) {
+    const leadIn = REVIEW_AGENTS.has(stem)
+      ? 'Write only review artifacts under `.opencode/team/**`. Do not edit production code.'
+      : 'Write only team artifacts under `.opencode/team/**`. Do not edit production code.';
+    withNote = `${leadIn}\n\n${transformed}`;
+  }
+  return `${header}${withNote.endsWith('\n') ? withNote : `${withNote}\n`}`;
+}
+
+function transformOrchestrator(markdown) {
+  let next = markdown.replace(
+    /\*\*Cursor frontmatter:\*\* all team pipeline agents use `readonly: false` so they can write team artifacts\. Production\/app restrictions live in the agent prompt body — do \*\*not\*\* set `readonly: true`\./,
+    '**OpenCode frontmatter:** all team pipeline agents use `mode: subagent` and `permission.edit` so they can write team artifacts (`edit: allow` for implementers; deny except `.opencode/team/**` for reviewers/planners). Production/app restrictions live in the agent prompt body. See `agents/README.md`.',
+  );
+  next = next.replace(
+    '## Team artifact I/O (Cursor Shell sandbox)',
+    '## Team artifact I/O',
+  );
+  if (!next.includes('## Stack notes')) {
+    next = next.replace(
+      '## Dynamic pipeline',
+      `## Stack notes
+
+Roles, write scopes, and OpenCode \`mode\` / \`permission\` packaging — **\`agents/README.md\`**.
+
+## Dynamic pipeline`,
+    );
+  }
+  return next;
+}
+
+function transformSkill(sourceText) {
+  const { frontmatter, body } = stripFrontmatter(sourceText);
+  const fields = parseFrontmatterFields(frontmatter);
+  const name = fields.name || '';
+  const description = fields.description || '';
+  const header = `---\nname: ${name}\ndescription: ${description}\n---\n\n`;
+  const transformed = rewriteProse(body);
+  return `${header}${transformed.endsWith('\n') ? transformed : `${transformed}\n`}`;
+}
+
+function transformCommand(sourceText) {
+  const { frontmatter, body } = stripFrontmatter(sourceText);
+  const fields = parseFrontmatterFields(frontmatter);
+  const description = fields.description || '';
+  let next = rewriteProse(body);
+  if (!next.includes('$ARGUMENTS')) {
+    next = `## Invocation arguments\n\n$ARGUMENTS\n\n${next}`;
+  }
+  const header = `---\ndescription: ${description}\n---\n\n`;
+  return `${header}${next.endsWith('\n') ? next : `${next}\n`}`;
+}
+
+function cursorMcpToOpencode(sourceText) {
+  const parsed = JSON.parse(sourceText);
+  const mcp = {};
+  for (const [id, server] of Object.entries(parsed.mcpServers || {})) {
+    if (!server || typeof server !== 'object') {
+      continue;
+    }
+    if (typeof server.url === 'string' && server.url) {
+      mcp[id] = { type: 'remote', url: server.url };
+      continue;
+    }
+    if (typeof server.command === 'string' && server.command) {
+      const command = [server.command, ...(Array.isArray(server.args) ? server.args : [])];
+      const entry = { type: 'local', command };
+      if (server.env && typeof server.env === 'object') {
+        entry.environment = server.env;
+      }
+      mcp[id] = entry;
+    }
+  }
+  return `${JSON.stringify({ $schema: 'https://opencode.ai/config.json', mcp }, null, 2)}\n`;
+}
+
+function main() {
+  fs.rmSync(opencodeRoot, { recursive: true, force: true });
+  fs.mkdirSync(opencodeRoot, { recursive: true });
+
+  const cursorFiles = walkFiles(cursorRoot);
+  const mappedSources = cursorFiles.filter((rel) => path.basename(rel) !== 'README.md');
+  const entries = [];
+  const digestParts = [];
+
+  for (const source of mappedSources) {
+    const abs = path.join(cursorRoot, source);
+    const sourceText = fs.readFileSync(abs, 'utf8');
+    digestParts.push(`${source}\t${sha256(sourceText)}`);
+
+    if (OMIT.has(source)) {
+      entries.push(
+        entry({
+          source,
+          target: null,
+          category: source.startsWith('hooks') ? 'hooks' : 'platform',
+          disposition: 'omit',
+          loadMode: 'not-installed',
+          reason: OMIT.get(source),
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'AGENTS.md') {
+      const target = 'OPENCODE.md';
+      writeFile(target, buildOpencodeEntry(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'entry',
+          disposition: 'embed-entry',
+          loadMode: 'root-entry',
+          reason: 'Cursor AGENTS.md semantics feed .opencode/AGENTS.md',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'REPO_AGENTS.md') {
+      const target = 'REPO_AGENTS.md';
+      writeFile(target, sourceText);
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'entry',
+          disposition: 'copy',
+          loadMode: 'root-entry',
+          reason: 'Canonical cross-tool root AGENTS.md; identical for all platforms',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('rules/') && source.endsWith('.mdc')) {
+      const stem = path.basename(source, '.mdc');
+      const target = `rules/${stem}.md`;
+      const alwaysOn = ALWAYS_ON_RULES.has(stem);
+      let markdown = transformMarkdown(sourceText);
+      if (stem === 'agent-team-orchestrator') {
+        markdown = transformOrchestrator(markdown);
+      }
+      writeFile(target, markdown);
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'rules',
+          disposition: 'transform',
+          loadMode: alwaysOn ? 'root-entry' : 'referenced',
+          reason: alwaysOn
+            ? 'Essential Cursor always-on rule: listed in AGENTS.md; body under .opencode/rules'
+            : 'Requestable Cursor rule: lazy Read from .opencode/rules; not auto-loaded',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('agents/') && source.endsWith('.md')) {
+      const target = source;
+      writeFile(target, transformAgent(source, sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'agents',
+          disposition: 'transform',
+          loadMode: 'native-team',
+          reason: 'Native .opencode/agents discovery; OpenCode frontmatter (mode/permission)',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('skills/') && source.endsWith('/SKILL.md')) {
+      const target = source;
+      writeFile(target, transformSkill(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'skills',
+          disposition: 'transform',
+          loadMode: 'native-skill',
+          reason: 'Native .opencode/skills/<name>/SKILL.md',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('commands/') && source.endsWith('.md')) {
+      const target = source;
+      writeFile(target, transformCommand(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'commands',
+          disposition: 'transform',
+          loadMode: 'native-skill',
+          reason: 'Native slash commands under .opencode/commands; $ARGUMENTS kept',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'hooks/chain-team-phases.sh') {
+      const target = source;
+      writeFile(target, rewriteProse(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'hooks',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'Manual/semi-auto chain runner under .opencode/hooks; not a plugin',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'mcp.json') {
+      const target = 'opencode.json';
+      writeFile(target, cursorMcpToOpencode(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'mcp',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'Cursor mcp.json → opencode.json mcp (local/remote types)',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'MCP.md') {
+      const target = source;
+      writeFile(target, rewriteProse(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'mcp',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'MCP operator notes copied to .opencode/MCP.md',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('team/')) {
+      const target = source;
+      const transformed = source.endsWith('.md') ? rewriteProse(sourceText) : sourceText;
+      writeFile(
+        target,
+        transformed.endsWith('\n') || !source.endsWith('.md') ? transformed : `${transformed}\n`,
+      );
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'team',
+          disposition: source.endsWith('.md') ? 'transform' : 'copy',
+          loadMode: 'manual',
+          reason: 'File pipeline remains audit SoT under .opencode/team',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    throw new Error(`unmapped cursor source: ${source}`);
+  }
+
+  writeFile('README.md', buildStackReadme());
+  writeFile('rules/README.md', buildRulesReadme());
+  writeFile('agents/README.md', buildAgentsReadme());
+  writeFile('skills/README.md', rewriteProse(readSiblingReadme('skills/README.md')));
+  writeFile('commands/README.md', buildCommandsReadme());
+  writeFile('hooks/README.md', buildHooksReadme());
+  writeFile('team/README.md', rewriteProse(readSiblingReadme('team/README.md')));
+
+  digestParts.sort();
+  const adapterMap = {
+    schemaVersion: 1,
+    platform: 'opencode',
+    stack: 'next',
+    semanticSource: 'cursor/next',
+    sourceRevision: sha256(digestParts.join('\n')),
+    entries,
+  };
+  writeFile('adapter-map.json', `${JSON.stringify(adapterMap, null, 2)}\n`);
+  console.log(
+    `generated presets/opencode/next (${entries.length} mapped sources, revision ${adapterMap.sourceRevision.slice(0, 12)})`,
+  );
+}
+
+function readSiblingReadme(rel) {
+  const filePath = path.join(cursorRoot, rel);
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : `# ${rel}\n`;
+}
+
+function dropLeadingHeading(text) {
+  return text
+    .replace(/^# [^\n]+\n+/, '')
+    .replace(/^Short Cursor entry point\.[^\n]*\n+/, '');
+}
+
+function stripInstallSection(body) {
+  const index = body.search(/^## Install\r?\n/m);
+  if (index < 0) {
+    return body.trimEnd();
+  }
+  return body.slice(0, index).trimEnd();
+}
+
+function stripEmbeddedCatalogLine(body) {
+  return body.replace(
+    /^See `\.opencode\/rules\/README\.md` for the full catalog[^\n]*\n+/m,
+    '',
+  );
+}
+
+function buildOpencodeEntry(sourceText) {
+  const body = stripEmbeddedCatalogLine(
+    stripInstallSection(
+      dropLeadingHeading(rewriteProse(stripFrontmatter(sourceText).body)),
+    ),
+  );
+  return `# Next.js stack — OpenCode agent team
+
+Short OpenCode entry. Native discovery: \`.opencode/agents/\`,
+\`.opencode/skills/\`, \`.opencode/commands/\`. Rule files under
+\`.opencode/rules/*.md\` are **not** auto-loaded.
+
+Root \`AGENTS.md\` is native always-on. Read it first, then this file.
+
+## How to load
+
+- Essential rules: Read immediately (paths below). Do not preload the catalog.
+- Other rules: lazy \`Read\` \`.opencode/rules/<stem>.md\` when the task matches.
+- Agents: native \`@name\` / Task from \`.opencode/agents/\`.
+- Commands: native \`/task\` from \`.opencode/commands/\`.
+- After a producer receipt, run \`bash .opencode/hooks/chain-team-phases.sh\`.
+  Agents must not write lifecycle fields in \`status.json\` / \`metrics.json\`.
+
+## Essential rules (read every turn)
+
+- \`.opencode/rules/next-app-core.md\`
+- \`.opencode/rules/package-manager.md\`
+- \`.opencode/rules/code-quality-and-refactoring.md\`
+- \`.opencode/rules/ai-local-overlay.md\`
+
+See \`.opencode/rules/README.md\` for the full catalog and loading strategy.
+
+**Platform docs:** published with the \`@bonesofspring/ai-rules\` package
+(\`docs/OPENCODE.md\`, \`docs/OPENCODE-COMPATIBILITY.md\`) — **not** copied into
+the consumer repo. Source: https://github.com/bonesofspring/ai-rules
+
+${body}
+
+## Install
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init opencode --preset next
+\`\`\`
+
+Copies rules, commands, agents, hooks, skills, team, \`OPENCODE.md\` →
+\`.opencode/AGENTS.md\`, \`MCP.md\`, \`opencode.json\` → project \`opencode.json\`
+(\`mcp\` merge), plus \`REPO_AGENTS.md\` → root \`AGENTS.md\`.
+`;
+}
+
+function buildCommandsReadme() {
+  let text = rewriteProse(readSiblingReadme('commands/README.md'));
+  text = text.replace(
+    '# Cursor commands (next preset)',
+    '# OpenCode commands (next preset)',
+  );
+  text = text.replace(
+    'Slash commands are copied to `.opencode/commands/` on `ai-rules init opencode --preset next`.',
+    'Slash commands are copied to `.opencode/commands/` on `ai-rules init opencode --preset next`. OpenCode loads `/<filename>` natively.',
+  );
+  text = text.replace(
+    '- Orchestrator: `../rules/agent-team-orchestrator.mdc`',
+    '- Orchestrator: `../rules/agent-team-orchestrator.md`',
+  );
+  text = text.replace(
+    '- Hooks: `../hooks.json`, `../hooks/chain-team-phases.sh`',
+    '- Hooks: `../hooks/chain-team-phases.sh` only (semi-auto runner; no `hooks.json`)',
+  );
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function buildAgentsReadme() {
+  let text = rewriteProse(readSiblingReadme('agents/README.md'));
+  text = text.replace(
+    'Role-based subagents for the Cursor team pipeline.',
+    'Role-based subagents for the OpenCode team pipeline (native `.opencode/agents/`).',
+  );
+  text = text.replace(
+    /## Frontmatter `readonly`[\s\S]*?(?=## Orchestration)/,
+    `## OpenCode packaging
+
+Agents ship with OpenCode YAML frontmatter: \`description\`, \`mode: subagent\`,
+and \`permission\`. Do **not** pin \`model\` in this preset.
+
+- Implementers (\`feature-developer\`, \`debugger\`, \`ci-investigator\`, test generators/healers): \`permission.edit: allow\`.
+- Reviewer / planner roles: \`edit\` deny except \`.opencode/team/**\`. Prompt bodies still forbid production edits.
+
+**Team artifacts:** agents write \`.opencode/team/**\` deliverables. They must
+**not** mutate lifecycle fields in \`status.json\` or \`metrics.json\` —
+\`bash .opencode/hooks/chain-team-phases.sh\` owns those after each producer receipt.
+
+## Model tiers (advisory)
+
+Optional \`steps[].model\` in \`pipeline.json\` (\`cheap\` | \`standard\` | \`strong\`)
+is advisory for the operator's OpenCode provider — see \`task-router.md\`.
+
+`,
+  );
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function buildStackReadme() {
+  return `# Next.js preset (OpenCode)
+
+Sibling adapter derived from \`presets/cursor/next\`. Platform id \`opencode\`;
+runtime \`opencode\`. Consumer install root is \`.opencode/\` (native agents,
+skills, commands) plus root \`AGENTS.md\` and \`opencode.json\`.
+
+Mapping: \`adapter-map.json\`. Do not derive this tree from Claude.
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init opencode --preset next
+\`\`\`
+
+\`releasedStacks\` currently lists **\`next\`** only.
+
+Omitted from this pilot: \`BUGBOT.md\`, \`hooks.json\`, hook examples, and
+unwired \`guard-shell-command.sh\`.
+`;
+}
+
+function buildRulesReadme() {
+  return `# OpenCode Next rules
+
+Plain Markdown. OpenCode does **not** auto-load these files. Root \`AGENTS.md\`
+and \`.opencode/AGENTS.md\` list four essential paths to Read immediately; the
+rest are lazy-loaded when the task matches.
+
+Do not put this catalog into \`opencode.json\` \`instructions\` as the only
+always-on path (V2 may ignore that field).
+
+## Essential (entry-critical)
+
+\`next-app-core\`, \`package-manager\`, \`code-quality-and-refactoring\`,
+\`ai-local-overlay\`.
+
+## Requestable
+
+All other \`*.md\` files in this directory. Same stems as Cursor
+\`rules/README.md\`.
+
+Shared-core markers (\`<!-- shared-core: … -->\`) are preserved from Cursor.
+`;
+}
+
+function buildHooksReadme() {
+  return `# OpenCode hooks
+
+No Cursor \`hooks.json\` and no TypeScript plugin in v1.
+
+## Shipped
+
+\`chain-team-phases.sh\` — manual/semi-auto runner. After a producer receipt:
+
+\`\`\`bash
+printf '%s\\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \\
+  | bash .opencode/hooks/chain-team-phases.sh
+\`\`\`
+
+\`<runtime-attempt-id>\` comes from \`.opencode/team/tasks/<slug>/status.json\`.
+Do not invent it. Agents never write lifecycle fields in \`status.json\` or
+\`metrics.json\`.
+
+## Omitted
+
+- \`hooks.json\` — no native registration schema in this preset
+- \`guard-shell-command.sh\` — not wired; do not describe it as enforcement
+- \`hooks/examples/**\` — plugin port is a follow-up
+`;
+}
+
+main();