@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/scripts/generate-mavis-next.mjs

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+/**
+ * Derive presets/mavis/next/** and adapter-map.json from cursor/next.
+ * Maintainer tool for WP-C; 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 mavisRoot = path.join(packageRoot, 'presets', 'mavis', 'next');
+
+const ALWAYS_ON_RULES = new Set([
+  'next-app-core',
+  'package-manager',
+  'code-quality-and-refactoring',
+  'ai-local-overlay',
+]);
+
+const OMIT = new Map([
+  [
+    'BUGBOT.md',
+    'no-equivalent: Bugbot is Cursor-only; review stays a Verifier skill/role',
+  ],
+  [
+    'hooks.json',
+    'omit until a documented MiniMax hook schema exists',
+  ],
+  [
+    '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 a Mavis hook event API is confirmed',
+  ],
+  [
+    'hooks/examples/secret-guard.example.sh',
+    'omit until a Mavis hook event API is confirmed',
+  ],
+  [
+    'hooks/examples/test-on-save.example.sh',
+    'omit until a Mavis hook event API is confirmed',
+  ],
+]);
+
+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/, ''),
+  };
+}
+
+const sharedCoreRoot = path.join(packageRoot, 'presets', '_shared', 'core');
+
+function rewriteConsumerPaths(text) {
+  return text
+    .replaceAll('.cursor/team', '.mavis/team')
+    .replaceAll('.cursor/rules', '.mavis/rules')
+    .replaceAll('.cursor/skills', '.mavis/skills')
+    .replaceAll('.cursor/agents', '.mavis/agents')
+    .replaceAll('.cursor/commands', '.mavis/commands')
+    .replaceAll('.cursor/hooks', '.mavis/hooks')
+    .replaceAll('.cursor/AGENTS.md', '.mavis/AGENTS.md')
+    .replaceAll("'.cursor'", "'.mavis'")
+    .replaceAll('".cursor"', '".mavis"');
+}
+
+function rewriteProse(text) {
+  return finalizeMavisProse(text);
+}
+
+function finalizeMavisProse(text) {
+  return rewriteConsumerPaths(text)
+    .replace(/`([^`\n]+)\.mdc`/g, '`$1.md`')
+    .replace(/(?<![\w./-])([\w-]+)\.mdc\b/g, '$1.md')
+    .replaceAll('init cursor --preset', 'init mavis --preset')
+    .replaceAll('# MCP (preset `next`, Cursor)', '# MCP (preset `next`, Mavis)')
+    .replaceAll('(preset `next`, Cursor)', '(preset `next`, Mavis)')
+    .replaceAll('Copied to `.cursor/mcp.json`', 'Staged at `.mavis/mcp.json`')
+    .replaceAll('OAuth in Cursor', 'OAuth in MiniMax Code (manual import)');
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function writeFile(relPath, content) {
+  const dest = path.join(mavisRoot, 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, { command = false, 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);
+  }
+  if (command) {
+    next = next
+      .replaceAll('`/task-continue <slug>`', 'continue `<slug>` using `.mavis/commands/task-continue.md`')
+      .replaceAll('`/task-continue`', 'the task-continue procedure in `.mavis/commands/task-continue.md`')
+      .replaceAll('`/technical-retro`', 'the technical-retro procedure in `.mavis/commands/technical-retro.md`')
+      .replaceAll('`/spec-start`', 'the spec-start procedure in `.mavis/commands/spec-start.md`')
+      .replaceAll('`/task`', 'the task procedure in `.mavis/commands/task.md`');
+  }
+  return next.endsWith('\n') ? next : `${next}\n`;
+}
+
+function main() {
+  fs.rmSync(mavisRoot, { recursive: true, force: true });
+  fs.mkdirSync(mavisRoot, { 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 = 'MAVIS.md';
+      writeFile(target, buildMavisEntry(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'entry',
+          disposition: 'embed-entry',
+          loadMode: 'root-entry',
+          reason: 'Cursor AGENTS.md semantics feed .mavis/AGENTS.md; not a MiniMax-reserved name',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'REPO_AGENTS.md') {
+      const target = 'REPO_AGENTS.md';
+      writeFile(target, buildRepoAgents(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'entry',
+          disposition: 'transform',
+          loadMode: 'root-entry',
+          reason: 'Root AGENTS.md compatibility floor plus explicit .mavis/AGENTS.md pointer',
+          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);
+      writeFile(target, transformMarkdown(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'rules',
+          disposition: 'transform',
+          loadMode: alwaysOn ? 'root-entry' : 'referenced',
+          reason: alwaysOn
+            ? 'Essential always-on Cursor rule: summary in entry files; full body referenced from .mavis/rules'
+            : 'Requestable Cursor rule: referenced from entry files; not claimed as MiniMax auto-load',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('agents/') && source.endsWith('.md')) {
+      const target = source;
+      writeFile(target, transformMarkdown(sourceText, { allowEmbedEntry: false }));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'agents',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'Native workspace agent discovery is unknown; attach with mcode exec --file',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('skills/') && source.endsWith('/SKILL.md')) {
+      const target = source;
+      writeFile(target, transformMarkdown(sourceText));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'skills',
+          disposition: 'transform',
+          loadMode: 'referenced',
+          reason: 'Workspace skill discovery without a root reference is unknown',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source.startsWith('commands/') && source.endsWith('.md')) {
+      const target = source;
+      writeFile(target, transformMarkdown(sourceText, { command: true }));
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'commands',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'No file-defined slash command API; keep as an explicit procedure plus exec --file',
+          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 .mavis/hooks; not auto-registered',
+          sourceText,
+        }),
+      );
+      continue;
+    }
+
+    if (source === 'mcp.json' || source === 'MCP.md') {
+      const target = source;
+      writeFile(target, source === 'MCP.md' ? rewriteProse(sourceText) : sourceText);
+      entries.push(
+        entry({
+          source,
+          target,
+          category: 'mcp',
+          disposition: source === 'MCP.md' ? 'transform' : 'copy',
+          loadMode: 'manual',
+          reason: 'Fallback merge into .mavis/mcp.json plus manual MiniMax UI import',
+          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 .mavis/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: 'mavis',
+    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/mavis/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 buildRepoAgents(_sourceText) {
+  return `# Next.js — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under \`.cursor/AGENTS.md\`,
+\`.claude/CLAUDE.md\`, \`.mavis/AGENTS.md\`, and \`.opencode/AGENTS.md\`.
+
+**.mavis/** is an ai-rules-owned namespace, not a MiniMax-native discovery path.
+When this Mavis preset is installed, read \`.mavis/AGENTS.md\` on every turn.
+Do not write \`~/.minimax/**\`. Do not mutate
+\`.mavis/team/tasks/<slug>/status.json\` or \`metrics.json\` — the chain runner
+owns those files.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code,
+  Mavis / MiniMax Code, OpenCode, or other).
+- Install:
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init cursor --preset next
+npx @bonesofspring/ai-rules init claude --preset next
+npx @bonesofspring/ai-rules init mavis --preset next
+npx @bonesofspring/ai-rules init opencode --preset next
+\`\`\`
+
+\`init\` overwrites this file from the preset (\`REPO_AGENTS.md\` → \`AGENTS.md\`).
+Living gotchas belong in \`team/conventions.md\`, not here.
+
+## Mavis compatibility entry
+
+After install, also read:
+
+- \`.mavis/AGENTS.md\` — Mavis load map, roles, and procedures
+- \`.mavis/rules/next-app-core.md\`
+- \`.mavis/rules/package-manager.md\`
+- \`.mavis/rules/code-quality-and-refactoring.md\`
+- \`.mavis/rules/ai-local-overlay.md\`
+
+Launch roles with \`mcode exec --file .mavis/agents/<role>.md\`. Start work with
+the task procedure in \`.mavis/commands/task.md\`.
+
+## Commands (test / lint / build)
+
+Working directory for app scripts: **\`app/\`**. Detect the package manager from
+lockfile / \`packageManager\` (\`package-manager\` rule).
+
+| Gate | Typical command |
+|------|-----------------|
+| Lint JS | \`yarn lint:js\` (or project equivalent) from \`app/\` |
+| Lint CSS | \`yarn lint:css\` from \`app/\` |
+| Unit tests | project unit script under \`app/\` |
+| Build | project \`build\` under \`app/\` |
+
+After code edits: invoke **\`post-change-lint\`** (requestable). Full gate: agent
+\`build-verifier\`.
+
+## Security basics
+
+- Do not commit secrets (\`.env\`, tokens, credentials).
+- Review destructive git (\`reset --hard\`, force-push) before running; respect
+  shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | \`.cursor/AGENTS.md\` (optional if Cursor not installed) |
+| Claude Code | \`.claude/CLAUDE.md\` (optional if Claude Code not installed) |
+| Mavis | \`.mavis/AGENTS.md\` (optional if Mavis not installed) |
+| OpenCode | \`.opencode/AGENTS.md\` (optional if OpenCode not installed) |
+
+Rules: \`.cursor/rules/\`, \`.claude/rules/\`, \`.mavis/rules/\`, or \`.opencode/rules/\`.
+Skills: \`.cursor/skills/\`, \`.claude/skills/\`, \`.mavis/skills/\`, or \`.opencode/skills/\`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions:
+**\`.cursor/team/conventions.md\`**, **\`.claude/team/conventions.md\`**,
+**\`.mavis/team/conventions.md\`**, and/or **\`.opencode/team/conventions.md\`**
+(fill after init; not overwritten on every dogfood sync when already present).
+
+## Local overlay (\`.ai.local/\`) — MANDATORY
+
+A \`.ai.local/\` directory MAY exist at the repo root or at any nesting depth in
+monorepos. **All agents MUST read and apply it on every turn.** Rules there
+override preset rules; in conflicts, the local rule wins.
+\`override: kill <preset-rule-name>\` drops the named preset rule from the
+agent's context entirely.
+
+Plain markdown rules under \`.ai.local/rules/*.md\` are read by the agent with
+higher priority than preset rules. Living gotchas live in
+\`.ai.local/conventions.md\`.
+
+Authoring guide: \`docs/LOCAL-OVERLAY.md\` in the \`@bonesofspring/ai-rules\`
+package. The \`ai-local-overlay\` rule is the mechanism; this \`MANDATORY\`
+section is the reinforcement.
+`;
+}
+
+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 `\.mavis\/rules\/README\.md` for the full catalog[^\n]*\n+/m,
+    '',
+  );
+}
+
+function buildMavisEntry(sourceText) {
+  const body = stripEmbeddedCatalogLine(
+    stripInstallSection(
+      dropLeadingHeading(rewriteProse(stripFrontmatter(sourceText).body)),
+    ),
+  );
+  return `# Next.js stack — Mavis agent team
+
+Short Mavis entry. Detailed rules live under \`.mavis/rules/*.md\`; procedures
+under \`.mavis/skills/**\`. This file is ai-rules-owned (\`.mavis/AGENTS.md\`),
+not a MiniMax-reserved filename.
+
+Root \`AGENTS.md\` is the compatibility floor. Read it first, then this file.
+
+## How to load
+
+- Rules and skills: follow the explicit paths in this file and root \`AGENTS.md\`.
+  Native project discovery without a reference is unconfirmed.
+- Roles: \`mcode exec --file .mavis/agents/<role>.md --output-format json\`.
+- Commands: natural-language procedures in \`.mavis/commands/\`, or
+  \`mcode exec --file .mavis/commands/task.md "<task>"\`.
+- After a producer receipt, run \`bash .mavis/hooks/chain-team-phases.sh\`.
+  Agents must not write lifecycle fields in \`status.json\` / \`metrics.json\`.
+
+## Essential rules (read every turn)
+
+- \`.mavis/rules/next-app-core.md\`
+- \`.mavis/rules/package-manager.md\`
+- \`.mavis/rules/code-quality-and-refactoring.md\`
+- \`.mavis/rules/ai-local-overlay.md\`
+
+See \`.mavis/rules/README.md\` for the full catalog and loading strategy.
+
+**Platform docs:** capability matrix and install guide — [\`docs/MAVIS.md\`](../../docs/MAVIS.md) and
+[\`docs/MAVIS-COMPATIBILITY.md\`](../../docs/MAVIS-COMPATIBILITY.md) in the
+\`@bonesofspring/ai-rules\` package (typically under \`node_modules/\` after install).
+
+${body}
+
+## Install
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init mavis --preset next
+\`\`\`
+
+Copies rules, commands, agents, hooks, skills, team, \`MAVIS.md\` → \`.mavis/AGENTS.md\`,
+\`MCP.md\`, \`mcp.json\` → \`.mavis/mcp.json\`, plus \`REPO_AGENTS.md\` → root \`AGENTS.md\`.
+Skills: \`write-adr\`, \`react-performance\` (on-demand). Import MCP from \`.mavis/mcp.json\`
+in the MiniMax Code UI.
+`;
+}
+
+function buildCommandsReadme() {
+  let text = rewriteProse(readSiblingReadme('commands/README.md'));
+  text = text.replace(
+    '# Cursor commands (next preset)',
+    '# Mavis commands (next preset)',
+  );
+  text = text.replace(
+    'Slash commands are copied to `.mavis/commands/` on `ai-rules init mavis --preset next`.',
+    'Procedure files are copied to `.mavis/commands/` on `ai-rules init mavis --preset next`. Invoke via `mcode exec --file .mavis/commands/<name>.md` or natural-language procedures in the MiniMax UI.',
+  );
+  text = text.replace(
+    '- Subagents: `../agents/` (**22** roles, including `task-router.md`, `codebase-analyzer.md`)',
+    '- Subagents: `../agents/` (**24** roles, including `task-router.md`, `codebase-analyzer.md`)',
+  );
+  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` in mavis)',
+  );
+  text = text.replace(
+    'Create and edit commands via `/commands` in Cursor or directly in this preset folder.',
+    'Edit procedure files in this preset folder or in the installed `.mavis/commands/` copy after `init`.',
+  );
+  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 Mavis team pipeline (`mcode exec --file`).',
+  );
+  text = text.replace(
+    /## Frontmatter `readonly`[\s\S]*?(?=## Orchestration)/,
+    `## Mavis packaging (no YAML frontmatter)
+
+Mavis agents ship as **plain Markdown** without Cursor-style YAML frontmatter (\`name\`, \`readonly\`, \`model\`). Adapter-map marks every agent \`loadMode: manual\`; attach with:
+
+\`\`\`bash
+mcode exec --file .mavis/agents/<role>.md --output-format json
+\`\`\`
+
+**Team artifacts:** agents write \`.mavis/team/**\` deliverables (\`pipeline.json\`, \`brief.md\`, \`review.md\`, \`artifact-manifest.json\`, …). They must **not** mutate lifecycle fields in \`status.json\` or \`metrics.json\` — \`bash .mavis/hooks/chain-team-phases.sh\` owns those after each producer receipt.
+
+Production-code restrictions live in each agent's **prompt body**, not in frontmatter flags.
+
+## Model tiers (advisory)
+
+Model routing is **prose-only** in this preset (no YAML \`model\` frontmatter). Optional \`steps[].model\` in \`pipeline.json\` (\`cheap\` | \`standard\` | \`strong\`) is advisory for \`mcode\` operators — see \`task-router.md\` and \`agent-team-orchestrator.md\`.
+
+| Tier | Agents |
+|------|--------|
+| **cheap** | \`task-router\`, \`task-analyst\`, \`build-verifier\`, \`code-reviewer\`, \`tech-writer\`, \`codebase-analyzer\` |
+| **standard** | \`feature-developer\`, \`debugger\`, \`ci-investigator\`, \`api-contract-reviewer\`, \`accessibility-reviewer\`, \`qa-tester\`, \`unit-test-*\`, \`playwright-test-*\`, \`openspec-author\` |
+| **strong** | \`solution-architect\`, \`migration-specialist\`, \`security-reviewer\`, \`performance-auditor\`, \`mockup-reviewer\` |
+
+`,
+  );
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function buildStackReadme() {
+  return `# Next.js preset (Mavis)
+
+Sibling adapter derived from \`presets/cursor/next\`. Platform id \`mavis\`;
+runtime \`mcode\`. Consumer install root is \`.mavis/\` (ai-rules-owned).
+
+Mapping: \`adapter-map.json\`. Do not derive this tree from Claude.
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init mavis --preset next
+\`\`\`
+
+\`releasedStacks\` currently lists **\`next\`** only. Other stacks ship in WP-F after the Next pilot human gate.
+
+Omitted from this pilot: \`BUGBOT.md\`, \`hooks.json\`, hook examples, and
+unwired \`guard-shell-command.sh\`.
+`;
+}
+
+function buildRulesReadme() {
+  return `# Mavis Next rules
+
+Plain Markdown. MiniMax does not auto-load these files; root \`AGENTS.md\` and
+\`.mavis/AGENTS.md\` reference them explicitly.
+
+## Essential (entry-critical)
+
+\`next-app-core\`, \`package-manager\`, \`code-quality-and-refactoring\`,
+\`ai-local-overlay\`.
+
+## Requestable
+
+All other \`*.md\` files in this directory. Read when the task matches the
+catalog in the Cursor source \`rules/README.md\` (same stems).
+
+Shared-core markers (\`<!-- shared-core: … -->\`) are preserved from Cursor.
+`;
+}
+
+function buildHooksReadme() {
+  return `# Mavis hooks
+
+No documented MiniMax project hook API is assumed.
+
+## Shipped
+
+\`chain-team-phases.sh\` — manual/semi-auto runner. After a producer receipt:
+
+\`\`\`bash
+printf '%s\\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \\
+  | bash .mavis/hooks/chain-team-phases.sh
+\`\`\`
+
+\`<runtime-attempt-id>\` comes from \`.mavis/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
+- \`guard-shell-command.sh\` — not wired; do not describe it as enforcement
+- \`hooks/examples/**\` — no confirmed Mavis event API
+`;
+}
+
+main();