eai-cli 0.0.0-bootstrap.0

package/resources/gofer/node-scripts/generate-commands.mjs

@@ -0,0 +1,1366 @@
+#!/usr/bin/env node
+/**
+ * generate-commands.mjs
+ * Generates surface-specific command/skill files from canonical stage definitions.
+ *
+ * Usage:
+ *   node generate-commands.mjs [--dry-run] [--surfaces <comma-list>] [--root <path>]
+ *
+ * Surfaces: claude, claude-mirror, copilot, github-prompts, github-agents,
+ *           github-skills, claude-skills, agents-skills, system-skills,
+ *           gemini, agents-md, codex-config
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { validateDescriptions } from './canonical-descriptions.mjs';
+import { parseStageCommand } from './parse-stage-command.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy compatibility export. Gofer now emits every command/helper to every
+ * supported surface when the stage frontmatter lists that surface.
+ */
+export const CLAUDE_ONLY_STAGES = [];
+
+const ALL_SURFACES = [
+  'claude',
+  'claude-mirror',
+  'claude-skills',
+  'copilot',
+  'github-prompts',
+  'github-agents',
+  'github-skills',
+  'agents-skills',
+  'system-skills',
+  'gemini',
+  'agents-md',
+  'codex-config',
+];
+
+const PUBLIC_SITE_URL = 'https://eai-tools.github.io/eai-gofer';
+const PUBLIC_RELEASES_URL = `${PUBLIC_SITE_URL}/releases`;
+const PUBLIC_PLUGIN_URL = `${PUBLIC_RELEASES_URL}/plugins/eai-gofer`;
+const SURFACE_WORKSPACE_HOSTS = {
+  'claude': 'claude',
+  'claude-mirror': 'claude',
+  'claude-skills': 'claude',
+  'copilot': 'copilot',
+  'github-prompts': 'copilot',
+  'github-agents': 'copilot',
+  'github-skills': 'copilot',
+  'agents-skills': 'codex',
+  'system-skills': 'codex',
+  'gemini': 'gemini',
+};
+const WORKSPACE_PREFLIGHT_EXCLUDED_COMMANDS = new Set([
+  'gofer:plan',
+  'gofer:side',
+  'gofer:personality',
+  'gofer:check-workspace',
+  'gofer:bootstrap-workspace',
+  'gofer:eai-first-run',
+]);
+const LEGACY_STAGE_STEMS = new Map([
+  ['0_gofer_start', ['0_business_scenario']],
+]);
+
+// ---------------------------------------------------------------------------
+// Exclusion logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the given stage should be excluded from the given surface.
+ * Gofer keeps this function for older tests/imports, but no stages are
+ * excluded by name anymore. Surface availability is controlled by stage
+ * frontmatter so Claude, Copilot, Codex, and Gemini stay in parity.
+ *
+ * @param {string} stageName
+ * @param {string} surface
+ * @returns {boolean}
+ */
+export function shouldExclude(stageName, surface) {
+  void stageName;
+  void surface;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensures a directory exists, creating it (and parents) if needed.
+ * @param {string} dirPath
+ */
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function detectPackageVersion(root) {
+  const candidates = [
+    path.join(root, 'package.json'),
+    path.join(root, 'extension', 'package.json'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(await fs.readFile(candidate, 'utf8'));
+      if (typeof parsed.version === 'string' && parsed.version.length > 0) {
+        return parsed.version;
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+
+  return '1.0.0';
+}
+
+function buildGeminiExtensionManifest(version) {
+  return {
+    name: 'eai-gofer',
+    version,
+    description: 'Gofer core pipeline and helper commands as a Gemini CLI extension',
+    license: 'Apache-2.0',
+    commands: '.gemini/commands/gofer/',
+    gofer: {
+      bundle_url: PUBLIC_PLUGIN_URL,
+      manifest_url: `${PUBLIC_PLUGIN_URL}/gemini-extension.json`,
+      commands_manifest_url: `${PUBLIC_PLUGIN_URL}/gemini-commands-manifest.json`,
+      download_url: `${PUBLIC_RELEASES_URL}/eai-gofer-agent-plugin-${version}.zip`,
+      latest_download_url: `${PUBLIC_RELEASES_URL}/eai-gofer-agent-plugin-latest.zip`,
+      vsix_url: `${PUBLIC_RELEASES_URL}/eai-gofer-${version}.vsix`,
+      latest_vsix_url: `${PUBLIC_RELEASES_URL}/eai-gofer-latest.vsix`,
+    },
+  };
+}
+
+/**
+ * Loads and parses all stage command files from .specify/commands/.
+ * Skips .gitkeep and any non-.md files.
+ *
+ * @param {string} root Absolute path to project root
+ * @returns {Promise<Array<{ filePath: string, frontmatter: Record<string, unknown>, body: string }>>}
+ */
+async function loadStages(root) {
+  const commandsDir = path.join(root, '.specify', 'commands');
+  let entries;
+  try {
+    entries = await fs.readdir(commandsDir);
+  } catch {
+    throw new Error(`.specify/commands/ not found at ${commandsDir}`);
+  }
+
+  const stages = [];
+  const parseErrors = [];
+  for (const entry of entries) {
+    if (!entry.endsWith('.md') || entry === '.gitkeep') continue;
+    const filePath = path.join(commandsDir, entry);
+    try {
+      const parsed = await parseStageCommand(filePath);
+      stages.push({ filePath, ...parsed });
+    } catch (err) {
+      parseErrors.push(`${entry}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (parseErrors.length > 0) {
+    throw new Error(
+      `Failed to parse ${parseErrors.length} command file(s):\n${parseErrors.join('\n')}`
+    );
+  }
+
+  return stages;
+}
+
+function getStageOutputStem(stage) {
+  return path.basename(stage.filePath, '.md');
+}
+
+function getLegacyStageStems(stage) {
+  return LEGACY_STAGE_STEMS.get(getStageOutputStem(stage)) ?? [];
+}
+
+async function removeLegacyGeneratedPath(outPath, legacyPath) {
+  if (outPath === legacyPath) {
+    return;
+  }
+
+  await fs.rm(legacyPath, { recursive: true, force: true });
+}
+
+async function removeLegacyGeneratedPaths(outPath, legacyPaths) {
+  for (const legacyPath of legacyPaths) {
+    await removeLegacyGeneratedPath(outPath, legacyPath);
+  }
+}
+
+function getCodexLegacySkillDirs(root, surfaceRoot, stageStem, stageName) {
+  return [
+    path.join(root, surfaceRoot, stageName),
+    path.join(root, surfaceRoot, 'gofer', stageStem),
+    path.join(root, surfaceRoot, 'gofer', stageName),
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Surface emitters
+// ---------------------------------------------------------------------------
+
+/**
+ * T037 — claude emitter
+ * Emits body to .claude/commands/<name>.md for stages that include 'claude' surface.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitClaude(stages, root, dryRun) {
+  const outDir = path.join(root, '.claude', 'commands');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, surfaces } = stage.frontmatter;
+    if (!surfaces.includes('claude')) continue;
+    if (shouldExclude(String(name), 'claude')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const outPath = path.join(outDir, `${stageStem}.md`);
+    const legacyPaths = [
+      path.join(outDir, `${name}.md`),
+      ...getLegacyStageStems(stage).map((legacyStem) => path.join(outDir, `${legacyStem}.md`)),
+    ];
+    if (dryRun) {
+      console.log(`[dry-run] claude: would write ${outPath}`);
+    } else {
+      await ensureDir(outDir);
+      await fs.writeFile(
+        outPath,
+        injectTokenCostPolicy(
+          injectWorkspacePreflight(stage.body, String(name), SURFACE_WORKSPACE_HOSTS['claude'])
+        ),
+        'utf8'
+      );
+      await removeLegacyGeneratedPaths(outPath, legacyPaths);
+      console.log(`claude: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`claude: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * T038 — claude-mirror emitter
+ * Emits body to extension/resources/claude-commands/<name>.md.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitClaudeMirror(stages, root, dryRun) {
+  const outDir = path.join(root, 'extension', 'resources', 'claude-commands');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, surfaces } = stage.frontmatter;
+    if (!surfaces.includes('claude-mirror')) continue;
+    if (shouldExclude(String(name), 'claude-mirror')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const outPath = path.join(outDir, `${stageStem}.md`);
+    const legacyPaths = [
+      path.join(outDir, `${name}.md`),
+      ...getLegacyStageStems(stage).map((legacyStem) => path.join(outDir, `${legacyStem}.md`)),
+    ];
+    if (dryRun) {
+      console.log(`[dry-run] claude-mirror: would write ${outPath}`);
+    } else {
+      await ensureDir(outDir);
+      await fs.writeFile(
+        outPath,
+        injectTokenCostPolicy(
+          injectWorkspacePreflight(
+            stage.body,
+            String(name),
+            SURFACE_WORKSPACE_HOSTS['claude-mirror']
+          )
+        ),
+        'utf8'
+      );
+      await removeLegacyGeneratedPaths(outPath, legacyPaths);
+      console.log(`claude-mirror: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`claude-mirror: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * T039 — copilot emitter
+ * Emits body to extension/resources/copilot-prompts/<name>.prompt.md.
+ * Emits every stage whose frontmatter includes the Copilot surface.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitCopilot(stages, root, dryRun) {
+  const outDir = path.join(root, 'extension', 'resources', 'copilot-prompts');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'copilot')) continue;
+    if (!surfaces.includes('copilot')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const outPath = path.join(outDir, `${stageStem}.prompt.md`);
+    const legacyPaths = [
+      path.join(outDir, `${name}.prompt.md`),
+      ...getLegacyStageStems(stage).map((legacyStem) =>
+        path.join(outDir, `${legacyStem}.prompt.md`)
+      ),
+    ];
+    if (dryRun) {
+      console.log(`[dry-run] copilot: would write ${outPath}`);
+    } else {
+      await ensureDir(outDir);
+      await fs.writeFile(
+        outPath,
+        buildCopilotPromptContent(stage, SURFACE_WORKSPACE_HOSTS['copilot']),
+        'utf8'
+      );
+      await removeLegacyGeneratedPaths(outPath, legacyPaths);
+      console.log(`copilot: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`copilot: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * T040 — github-prompts emitter
+ * Emits body to .github/prompts/<name>.prompt.md.
+ * Emits every stage whose frontmatter includes the GitHub prompts surface.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitGithubPrompts(stages, root, dryRun) {
+  const outDir = path.join(root, '.github', 'prompts');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'github-prompts')) continue;
+    if (!surfaces.includes('github-prompts')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const outPath = path.join(outDir, `${stageStem}.prompt.md`);
+    const legacyPaths = [
+      path.join(outDir, `${name}.prompt.md`),
+      ...getLegacyStageStems(stage).map((legacyStem) =>
+        path.join(outDir, `${legacyStem}.prompt.md`)
+      ),
+    ];
+    if (dryRun) {
+      console.log(`[dry-run] github-prompts: would write ${outPath}`);
+    } else {
+      await ensureDir(outDir);
+      await fs.writeFile(
+        outPath,
+        buildCopilotPromptContent(stage, SURFACE_WORKSPACE_HOSTS['github-prompts']),
+        'utf8'
+      );
+      await removeLegacyGeneratedPaths(outPath, legacyPaths);
+      console.log(`github-prompts: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`github-prompts: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * Builds a Copilot prompt using the same metadata and body transform as the
+ * runtime CommandGenerator. This keeps .github/prompts and bundled VSIX
+ * resources byte-equivalent to generated Copilot mirrors.
+ *
+ * @param {{ frontmatter: Record<string, unknown>, body: string }} stage
+ * @returns {string}
+ */
+function buildCopilotPromptContent(stage, host = SURFACE_WORKSPACE_HOSTS['copilot']) {
+  const stageName = String(stage.frontmatter.name);
+  const { frontmatter, body } = splitMarkdownFrontmatter(stage.body);
+  const description = readString(frontmatter.description) ?? String(stage.frontmatter.description);
+  const transformedBody = injectPipelineContinuation(
+    injectTokenCostPolicy(
+      injectWorkspacePreflight(transformClaudeContent(body, 'copilot'), stageName, host)
+    ),
+    'copilot',
+    stageName
+  );
+  const canonicalChecksum = createHash('sha256').update(body, 'utf8').digest('hex');
+  const sourceFileName = path.basename(stage.filePath);
+
+  return [
+    '---',
+    `name: ${stageName}`,
+    `description: ${description}`,
+    'agent: copilot-workspace',
+    'tools:',
+    '  - Read',
+    '  - Grep',
+    '  - Glob',
+    '  - Bash',
+    '  - WebSearch',
+    'argument-hint: feature-name-or-description',
+    'gofer:',
+    '  workflowProfile: standard',
+    `  canonicalSource: .specify/commands/${sourceFileName}`,
+    `  canonicalChecksum: ${canonicalChecksum}`,
+    '  metadataSource: scripts/generate-commands.ts',
+    '---',
+    '',
+    transformedBody,
+  ].join('\n');
+}
+
+/**
+ * @param {string} content
+ * @returns {{ frontmatter: Record<string, unknown>, body: string }}
+ */
+function splitMarkdownFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const fieldMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!fieldMatch) continue;
+    frontmatter[fieldMatch[1]] = fieldMatch[2].trim().replace(/^["']|["']$/g, '');
+  }
+
+  return { frontmatter, body: match[2] };
+}
+
+/**
+ * @param {string} content
+ * @param {'copilot'} toPlatform
+ * @returns {string}
+ */
+function transformClaudeContent(content, toPlatform) {
+  let transformed = content;
+  const stageCommandPattern = /\/(\d+[a-z]?_[a-z0-9_]+)/g;
+  const helperCommandPattern = /\/(gofer_[a-z0-9_]+)/g;
+
+  transformed = transformed.replace(/\*\*AUTO-CHAIN[^]*?(?=\n##|\n---|\n\*\*|$)/g, '');
+  transformed = transformed.replace(
+    /by calling the Skill tool with skill="[^"]+"/g,
+    'by running the next command'
+  );
+  transformed = transformed.replace(/Skill tool/g, 'next command');
+
+  if (toPlatform === 'copilot') {
+    transformed = transformed.replace(stageCommandPattern, '#$1');
+    transformed = transformed.replace(helperCommandPattern, '#$1');
+    transformed = transformed.replace(/(^SourceCommandId:\s*)#/gm, '$1/');
+  }
+
+  return transformed;
+}
+
+/**
+ * @param {string} content
+ * @param {'copilot'} platform
+ * @param {string} commandName
+ * @returns {string}
+ */
+function injectPipelineContinuation(content, platform, commandName) {
+  void platform;
+  const nextCommand = getNextCommand(commandName);
+  if (!nextCommand) return content;
+
+  const autoChainSection = `\n\n## Pipeline Continuation\n\nThis completes the ${commandName} stage. To continue the Gofer pipeline:\n\n**Next Command:** \`#${nextCommand}\`\n\nThe next stage will read the artifacts from this stage and continue the workflow automatically.\n\n**Note:** Copilot Chat supports context preservation. Your conversation history will be maintained as you progress through pipeline stages.\n`;
+
+  if (content.includes('## Key Rules')) {
+    return content.replace('## Key Rules', `${autoChainSection}\n## Key Rules`);
+  }
+
+  return content + autoChainSection;
+}
+
+function buildEaiPlatformSessionPreflightSection() {
+  return `
+## EAI Platform Session Preflight
+
+Before any Gofer stage/helper command does pipeline work:
+
+1. Treat durable delivery as EAI Platform delivery by default, with Azure second and every other stack only by explicit exception.
+2. Run \`eai whoami\` and confirm the EAI CLI is installed, the user is logged in, and an active tenant is visible.
+3. If \`eai\` is missing, \`eai whoami\` fails, the token is expired, or no active tenant is available, stop and run \`/gofer:eai-first-run\` or ask the user to approve login/setup before continuing.
+4. For EAI app delivery, do not continue into research, specification, planning, tasks, implementation, or validation until \`.specify/specs/{feature}/eai-preflight.md\` records login, tenant, template, app-readiness, and next-action evidence.
+5. Do not write tokens, secrets, private tenant IDs, or local \`.env\` values into Gofer artifacts; record only product-safe readiness status and evidence.
+`.trim();
+}
+
+function injectEaiPlatformSessionPreflight(content) {
+  if (content.includes('## EAI Platform Session Preflight')) {
+    return content;
+  }
+
+  const section = buildEaiPlatformSessionPreflightSection();
+  const workspaceHeadingIndex = content.indexOf('## Workspace Preflight');
+  if (workspaceHeadingIndex !== -1) {
+    const nextHeadingIndex = content.indexOf('\n## ', workspaceHeadingIndex + 1);
+    if (nextHeadingIndex !== -1) {
+      return `${content.slice(0, nextHeadingIndex).trimEnd()}\n\n${section}\n\n${content
+        .slice(nextHeadingIndex)
+        .replace(/^\n+/, '')}`;
+    }
+    return `${content.trimEnd()}\n\n${section}\n`;
+  }
+
+  return `${section}\n\n${content}`;
+}
+
+function buildWorkspacePreflightSection(host = 'auto', includeEaiPreflight = true) {
+  const eaiPreflight = includeEaiPreflight
+    ? `\n\n${buildEaiPlatformSessionPreflightSection()}`
+    : '';
+
+  return `
+## Workspace Preflight
+
+Before doing stage/helper work:
+
+1. Resolve the repository root.
+2. Check the core Gofer sentinels:
+   - \`.specify/.gofer-version\`
+   - \`.specify/commands/0_gofer_start.md\`
+   - \`.specify/templates/spec-template.md\`
+   - \`.specify/templates/loop-contract-template.json\`
+   - \`.specify/templates/working-backwards-prfaq-template.md\`
+   - \`.specify/templates/business-owner-summary-template.md\`
+   - \`.specify/templates/cto-architecture-summary-template.md\`
+   - \`.specify/templates/ciso-security-summary-template.md\`
+   - \`.specify/templates/stakeholder-review-index-template.md\`
+   - \`.specify/scripts/bash/create-new-feature.sh\`
+   - \`.specify/scripts/node/parse-stage-command.mjs\`
+   - \`.specify/scripts/node/gofer-loop-audit.mjs\`
+   - \`.specify/scripts/hooks/post-tool-use.mjs\`
+   - \`.specify/scripts/powershell/install-optional-tools.ps1\`
+   - \`.specify/templates/gofer-model-policy.yaml\`
+   - \`.specify/memory/gofer-model-policy.yaml\`
+   - \`.specify/specs/\`
+   - \`.specify/memory/\`
+3. Check host-specific repo-owned files when relevant:
+   - Claude: \`AGENTS.md\`, \`CLAUDE.md\`, \`.claude/settings.json\`
+   - Codex: \`AGENTS.md\`
+   - Copilot: \`.github/copilot-instructions.md\`
+   - VS Code extension mirrors Claude/Copilot/Gemini resources itself and should still keep the core scaffold healthy
+4. If the repo already has the workspace checker script, prefer running:
+   - \`node .specify/scripts/node/gofer-workspace-check.mjs --host ${host} --json\`
+5. If the workspace is missing or stale, ask exactly:
+   - **"This repo is missing or stale for Gofer. Initialize/update it now?"**
+6. If the user says yes, run the Gofer workspace bootstrap helper and then resume this command from the top.
+7. If the user says no, stop and explain that Gofer stage/helper work depends on the repo-owned scaffold.${eaiPreflight}
+`.trim();
+}
+
+function injectWorkspacePreflight(content, commandName, host = 'auto') {
+  if (WORKSPACE_PREFLIGHT_EXCLUDED_COMMANDS.has(commandName)) {
+    return content;
+  }
+
+  if (content.includes('## Workspace Preflight')) {
+    const updatedContent = content.replace(
+      /`node \.specify\/scripts\/node\/gofer-workspace-check\.mjs --host [^`\n]+ --json`/,
+      `\`node .specify/scripts/node/gofer-workspace-check.mjs --host ${host} --json\``
+    );
+    return injectEaiPlatformSessionPreflight(updatedContent);
+  }
+
+  const section = buildWorkspacePreflightSection(
+    host,
+    !content.includes('## EAI Platform Session Preflight')
+  );
+  const headingMatch = content.match(/^# [^\n]+\n+/);
+  if (!headingMatch) {
+    return `${section}\n\n${content}`;
+  }
+
+  const insertAt = headingMatch[0].length;
+  const prefix = content.slice(0, insertAt);
+  const suffix = content.slice(insertAt).replace(/^\n+/, '');
+  return `${prefix}${section}\n\n${suffix}`;
+}
+
+function buildTokenCostPolicySection() {
+  return `
+## Token And Cost Policy
+<!-- gofer:token-cost-policy:start -->
+
+Before spawning agents, calling tools, or loading large files:
+
+1. Treat \`.specify/memory/gofer-model-policy.yaml\` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run \`/gofer:bootstrap-workspace\` before continuing.
+2. Use the cheapest capable model first.
+   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
+   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
+   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
+   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
+3. Keep raw tool output out of the main conversation context. Save stable findings to \`.specify/specs/{feature}/context-bundle.md\`, then work from summaries.
+4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
+5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
+6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
+<!-- gofer:token-cost-policy:end -->
+`.trim();
+}
+
+function injectTokenCostPolicy(content) {
+  const section = buildTokenCostPolicySection();
+  const startMarker = '<!-- gofer:token-cost-policy:start -->';
+  const endMarker = '<!-- gofer:token-cost-policy:end -->';
+
+  if (content.includes(startMarker) && content.includes(endMarker)) {
+    const headingIndex = content.indexOf('## Token And Cost Policy');
+    const endIndex = content.indexOf(endMarker, headingIndex) + endMarker.length;
+    const suffix = content.slice(endIndex).replace(/^\n+/, '');
+    return suffix
+      ? `${content.slice(0, headingIndex).trimEnd()}\n\n${section}\n\n${suffix}`
+      : `${content.slice(0, headingIndex).trimEnd()}\n\n${section}\n`;
+  }
+
+  if (content.includes('## Token And Cost Policy')) {
+    const legacyPolicyPattern =
+      /## Token And Cost Policy\n\nBefore spawning agents, calling tools, or loading large files:\n\n[\s\S]*?^6\. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality\.\n?/m;
+    const legacyMatch = content.match(legacyPolicyPattern);
+    if (legacyMatch && legacyMatch.index !== undefined) {
+      const suffix = content.slice(legacyMatch.index + legacyMatch[0].length).replace(/^\n+/, '');
+      return suffix
+        ? `${content.slice(0, legacyMatch.index).trimEnd()}\n\n${section}\n\n${suffix}`
+        : `${content.slice(0, legacyMatch.index).trimEnd()}\n\n${section}\n`;
+    }
+
+    const headingIndex = content.indexOf('## Token And Cost Policy');
+    const nextHeading = content.indexOf('\n## ', headingIndex + 1);
+    if (nextHeading !== -1) {
+      return `${content.slice(0, headingIndex).trimEnd()}\n\n${section}\n\n${content
+        .slice(nextHeading)
+        .replace(/^\n+/, '')}`;
+    }
+
+    return content;
+  }
+
+  if (content.includes('## Workspace Preflight')) {
+    const nextHeading = content.indexOf('\n## ', content.indexOf('## Workspace Preflight') + 1);
+    if (nextHeading !== -1) {
+      return `${content.slice(0, nextHeading).trimEnd()}\n\n${section}\n\n${content
+        .slice(nextHeading)
+        .replace(/^\n+/, '')}`;
+    }
+  }
+
+  const headingMatch = content.match(/^# [^\n]+\n+/);
+  if (!headingMatch) {
+    return `${section}\n\n${content}`;
+  }
+
+  const insertAt = headingMatch[0].length;
+  const prefix = content.slice(0, insertAt);
+  const suffix = content.slice(insertAt).replace(/^\n+/, '');
+  return `${prefix}${section}\n\n${suffix}`;
+}
+
+/**
+ * @param {string} currentCommand
+ * @returns {string | null}
+ */
+function getNextCommand(currentCommand) {
+  const pipeline = [
+    '0_gofer_start',
+    '1_gofer_research',
+    '2_gofer_specify',
+    '3_gofer_plan',
+    '4_gofer_tasks',
+    '5_gofer_implement',
+    '6_gofer_validate',
+  ];
+
+  const currentIndex = pipeline.indexOf(currentCommand);
+  if (currentIndex >= 0 && currentIndex < pipeline.length - 1) {
+    return pipeline[currentIndex + 1];
+  }
+
+  return null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function readString(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+/**
+ * Builds a SKILL.md content string.
+ * @param {string} stageName
+ * @param {string} description
+ * @param {string} body
+ * @returns {string}
+ */
+function buildSkillContent(stageName, description, body) {
+  return `---\nname: ${stageName}\ndescription: "${description}"\n---\n\n${body}`;
+}
+
+function buildUmbrellaSkillContent(version, stages, hostLabel) {
+  const stageList = stages
+    .map((stage) => `- \`/${getStageOutputStem(stage)}\` - ${stage.frontmatter.description}`)
+    .join('\n');
+
+  return `---\nname: eai-gofer\ndescription: "Use Gofer's repo-owned pipeline, scripts, and validation tools without duplicating every slash command in the picker."\n---\n\n# EAI Gofer\n\nVersion: ${version}\nHost: ${hostLabel}\n\nUse this skill when the user asks to install, update, diagnose, run, or understand Gofer from an AI coding app. Prefer this umbrella skill for app-level discovery. Use the plain slash commands for individual pipeline stages.\n\n## Clean Surface Contract\n\n- Stage work uses the plain repo slash commands, for example \`/0_gofer_start\`, \`/1_gofer_research\`, and \`/6_gofer_validate\`.\n- App-level setup, troubleshooting, and explanation should use this \`eai-gofer\` skill plus the repo-owned scripts in \`.specify/scripts/\`.\n- Do not expose a second full set of namespaced stage commands in the same picker when plain slash commands are available.\n- Check workspace health before stage work: \`node .specify/scripts/node/gofer-workspace-check.mjs --host auto --json\`.\n- If missing or stale, ask the user before running: \`node .specify/scripts/node/gofer-workspace-bootstrap.mjs --host auto --include-mirrors\`.\n\n## Light Plugin And Repo Scripts\n\nThe light plugin installs durable Gofer knowledge and app integration metadata. The repository remains the source of truth for executable scripts, commands, templates, specs, and memory. After bootstrap, agents should prefer repo-local scripts over bundled fallback copies because the repo can be updated by \`eai gofer refresh\` or the VS Code extension.\n\n## First EAI Platform App\n\nIf the user is starting a first EAI Platform app, run \`/gofer:eai-first-run\` before \`/0_gofer_start\`. It is intentionally allowed before \`.specify/\` exists.\n\n## Current Pipeline\n\n${stageList}\n`;
+}
+
+function buildGithubAgentContent({ id, description, tools, handoffs, body }) {
+  const frontmatter = [
+    '---',
+    `description: ${JSON.stringify(description)}`,
+    `tools: ${JSON.stringify(tools)}`,
+  ];
+
+  if (handoffs.length > 0) {
+    frontmatter.push('handoffs:');
+    for (const handoff of handoffs) {
+      frontmatter.push(`  - agent: ${handoff.agent}`);
+      frontmatter.push(`    label: ${JSON.stringify(handoff.label)}`);
+      frontmatter.push(`    prompt: ${JSON.stringify(handoff.prompt)}`);
+      frontmatter.push(`    send: ${handoff.send ? 'true' : 'false'}`);
+    }
+  }
+
+  frontmatter.push('---');
+
+  return `${frontmatter.join('\n')}\n\n# ${id}\n\n${body.trim()}\n`;
+}
+
+function getGithubAgentSpecs() {
+  const goferTools = [
+    'search/codebase',
+    'vscode/askQuestion',
+    'gofer_check_workspace',
+    'gofer_bootstrap_workspace',
+    'gofer_get_pipeline_state',
+    'gofer_start_stage',
+    'gofer_validate_branch',
+    'gofer_open_artifact',
+  ];
+
+  return [
+    {
+      id: 'gofer-business',
+      description: 'Gofer start and setup agent. Use for first-run setup, workspace health, feature intake, and selecting the right pipeline entry point.',
+      tools: goferTools,
+      handoffs: [
+        {
+          agent: 'gofer-research',
+          label: 'Continue to Research',
+          prompt: 'Continue with Gofer research for the confirmed feature. Check workspace health first, then run /1_gofer_research or the equivalent repo-local stage instruction.',
+          send: false,
+        },
+      ],
+      body: `
+You are the Gofer start agent.
+
+Start by checking Gofer workspace health. If the repo is missing or stale, ask before bootstrapping. Keep the user-facing surface simple: use plain slash commands for pipeline stages and the eai-gofer skill/tools for app-level setup.
+
+Primary outputs:
+
+- A clear route into \`/0_gofer_start\`, \`/gofer:eai-first-run\`, or standalone research.
+- A concise statement of whether the repo has the Gofer scaffold, plugin/app support, and EAI first-run prerequisites.
+`,
+    },
+    {
+      id: 'gofer-research',
+      description: 'Gofer research agent. Use for codebase and documentation research before specification.',
+      tools: goferTools,
+      handoffs: [
+        {
+          agent: 'gofer-plan',
+          label: 'Continue to Plan',
+          prompt: 'Continue through Gofer specify and plan stages using the research artifacts. Preserve workspace checks and artifact evidence.',
+          send: false,
+        },
+      ],
+      body: `
+You are the Gofer research agent.
+
+Use \`/1_gofer_research\` as the stage contract. Keep raw output out of chat when it is large; write durable findings to \`.specify/specs/{feature}/research.md\` and \`context-bundle.md\`.
+`,
+    },
+    {
+      id: 'gofer-plan',
+      description: 'Gofer specification and planning agent. Use after research to produce spec, plan, contracts, and ordered tasks.',
+      tools: goferTools,
+      handoffs: [
+        {
+          agent: 'gofer-implement',
+          label: 'Implement Tasks',
+          prompt: 'Implement the approved Gofer tasks. Check pipeline state first and preserve traceability.',
+          send: false,
+        },
+      ],
+      body: `
+You are the Gofer planning agent.
+
+Use \`/2_gofer_specify\`, \`/3_gofer_plan\`, and \`/4_gofer_tasks\` as the stage contracts. Keep the plan grounded in existing repository scripts, current platform capabilities, and explicit validation obligations.
+`,
+    },
+    {
+      id: 'gofer-implement',
+      description: 'Gofer implementation agent. Use for task execution, code edits, tests, and repo-script driven changes.',
+      tools: goferTools,
+      handoffs: [
+        {
+          agent: 'gofer-validate',
+          label: 'Validate Changes',
+          prompt: 'Validate this implementation with Gofer. Run the relevant tests and produce validation evidence.',
+          send: false,
+        },
+      ],
+      body: `
+You are the Gofer implementation agent.
+
+Use \`/5_gofer_implement\` as the stage contract. Work from \`tasks.md\`, keep changes minimal, run repo tests, and update traceability evidence as tasks complete.
+`,
+    },
+    {
+      id: 'gofer-validate',
+      description: 'Gofer validation agent. Use for branch validation, security checks, test evidence, and release readiness.',
+      tools: goferTools,
+      handoffs: [],
+      body: `
+You are the Gofer validation agent.
+
+Use \`/6_gofer_validate\` as the terminal quality gate. Validate functional correctness, integration, security, standards, tests, generated artifacts, and release/public readiness where relevant.
+`,
+    },
+  ];
+}
+
+/**
+ * Escapes a string for a basic TOML double-quoted value.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeTomlString(value) {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * T041 — agents-skills emitter
+ * Emits Codex SKILL.md to .agents/skills/<name>/SKILL.md.
+ * Emits every stage whose frontmatter includes the agents-skills surface.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitAgentsSkills(stages, root, dryRun) {
+  const baseDir = path.join(root, '.agents', 'skills');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, description, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'agents-skills')) continue;
+    if (!surfaces.includes('agents-skills')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const legacyStageStems = getLegacyStageStems(stage);
+    const skillDir = path.join(baseDir, stageStem);
+    const outPath = path.join(skillDir, 'SKILL.md');
+    const legacySkillDir = path.join(baseDir, String(name));
+    const content = buildSkillContent(
+      String(name),
+      String(description),
+      injectTokenCostPolicy(
+        injectWorkspacePreflight(stage.body, String(name), SURFACE_WORKSPACE_HOSTS['agents-skills'])
+      )
+    );
+
+    if (dryRun) {
+      console.log(`[dry-run] agents-skills: would write ${outPath}`);
+    } else {
+      await ensureDir(skillDir);
+      await fs.writeFile(outPath, content, 'utf8');
+      await removeLegacyGeneratedPaths(skillDir, [
+        legacySkillDir,
+        ...legacyStageStems.map((legacyStem) => path.join(baseDir, legacyStem)),
+        ...getCodexLegacySkillDirs(root, '.agents/skills', stageStem, String(name)),
+      ]);
+      console.log(`agents-skills: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`agents-skills: ${count} file(s) emitted`);
+  return true;
+}
+
+async function emitGithubAgents(stages, root, dryRun) {
+  void stages;
+  const outDir = path.join(root, '.github', 'agents');
+  const agentSpecs = getGithubAgentSpecs();
+
+  if (dryRun) {
+    for (const agent of agentSpecs) {
+      console.log(`[dry-run] github-agents: would write ${path.join(outDir, `${agent.id}.agent.md`)}`);
+    }
+  } else {
+    await ensureDir(outDir);
+    for (const agent of agentSpecs) {
+      const outPath = path.join(outDir, `${agent.id}.agent.md`);
+      await fs.writeFile(outPath, buildGithubAgentContent(agent), 'utf8');
+      console.log(`github-agents: wrote ${outPath}`);
+    }
+  }
+
+  console.log(`github-agents: ${agentSpecs.length} file(s) emitted`);
+  return true;
+}
+
+async function emitGithubSkills(stages, root, dryRun) {
+  const version = await detectPackageVersion(root);
+  const outPath = path.join(root, '.github', 'skills', 'eai-gofer', 'SKILL.md');
+  const content = buildUmbrellaSkillContent(version, stages, 'VS Code and GitHub Copilot');
+
+  if (dryRun) {
+    console.log(`[dry-run] github-skills: would write ${outPath}`);
+  } else {
+    await ensureDir(path.dirname(outPath));
+    await fs.writeFile(outPath, content, 'utf8');
+    console.log(`github-skills: wrote ${outPath}`);
+  }
+
+  console.log('github-skills: 1 file(s) emitted');
+  return true;
+}
+
+async function emitClaudeSkills(stages, root, dryRun) {
+  const version = await detectPackageVersion(root);
+  const outPath = path.join(root, '.claude', 'skills', 'eai-gofer', 'SKILL.md');
+  const content = buildUmbrellaSkillContent(version, stages, 'Claude Code');
+
+  if (dryRun) {
+    console.log(`[dry-run] claude-skills: would write ${outPath}`);
+  } else {
+    await ensureDir(path.dirname(outPath));
+    await fs.writeFile(outPath, content, 'utf8');
+    console.log(`claude-skills: wrote ${outPath}`);
+  }
+
+  console.log('claude-skills: 1 file(s) emitted');
+  return true;
+}
+
+/**
+ * T042 — system-skills emitter
+ * Emits SKILL.md to .system/skills/<name>/SKILL.md.
+ * Emits every stage whose frontmatter includes the system-skills surface.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitSystemSkills(stages, root, dryRun) {
+  const baseDir = path.join(root, '.system', 'skills');
+  let count = 0;
+  for (const stage of stages) {
+    const { name, description, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'system-skills')) continue;
+    if (!surfaces.includes('system-skills')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const legacyStageStems = getLegacyStageStems(stage);
+    const skillDir = path.join(baseDir, stageStem);
+    const outPath = path.join(skillDir, 'SKILL.md');
+    const legacySkillDir = path.join(baseDir, String(name));
+    const content = buildSkillContent(
+      String(name),
+      String(description),
+      injectTokenCostPolicy(
+        injectWorkspacePreflight(stage.body, String(name), SURFACE_WORKSPACE_HOSTS['system-skills'])
+      )
+    );
+
+    if (dryRun) {
+      console.log(`[dry-run] system-skills: would write ${outPath}`);
+    } else {
+      await ensureDir(skillDir);
+      await fs.writeFile(outPath, content, 'utf8');
+      await removeLegacyGeneratedPaths(skillDir, [
+        legacySkillDir,
+        ...legacyStageStems.map((legacyStem) => path.join(baseDir, legacyStem)),
+        ...getCodexLegacySkillDirs(root, '.system/skills', stageStem, String(name)),
+      ]);
+      console.log(`system-skills: wrote ${outPath}`);
+    }
+    count++;
+  }
+  console.log(`system-skills: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * T065 — gemini emitter
+ * Emits plain markdown body and TOML command wrappers to
+ * .gemini/commands/gofer/<name>.md and <name>.toml.
+ * T066 — also creates .gemini/commands/gofer/manifest.json listing all emitted stage names.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitGemini(stages, root, dryRun) {
+  const outDir = path.join(root, '.gemini', 'commands', 'gofer');
+  const extensionPath = path.join(root, '.gemini', 'extension.json');
+  const version = await detectPackageVersion(root);
+  const emittedNames = [];
+  let count = 0;
+
+  for (const stage of stages) {
+    const { name, description, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'gemini')) continue;
+    if (!surfaces.includes('gemini')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    const markdownPath = path.join(outDir, `${stageStem}.md`);
+    const tomlPath = path.join(outDir, `${stageStem}.toml`);
+    const legacyStageStems = getLegacyStageStems(stage);
+    const legacyMarkdownPaths = [
+      path.join(outDir, `${name}.md`),
+      ...legacyStageStems.map((legacyStem) => path.join(outDir, `${legacyStem}.md`)),
+    ];
+    const legacyTomlPaths = [
+      path.join(outDir, `${name}.toml`),
+      ...legacyStageStems.map((legacyStem) => path.join(outDir, `${legacyStem}.toml`)),
+    ];
+    const sourceFileName = path.basename(stage.filePath);
+    const tomlContent = [
+      `description = "${escapeTomlString(String(description || name))}"`,
+      `prompt = "{{include: ../../../.specify/commands/${sourceFileName}}}"`,
+      '',
+    ].join('\n');
+
+    if (dryRun) {
+      console.log(`[dry-run] gemini: would write ${markdownPath}`);
+      console.log(`[dry-run] gemini: would write ${tomlPath}`);
+    } else {
+      await ensureDir(outDir);
+      await fs.writeFile(
+        markdownPath,
+        injectTokenCostPolicy(
+          injectWorkspacePreflight(stage.body, String(name), SURFACE_WORKSPACE_HOSTS['gemini'])
+        ),
+        'utf8'
+      );
+      await fs.writeFile(tomlPath, tomlContent, 'utf8');
+      await removeLegacyGeneratedPaths(markdownPath, legacyMarkdownPaths);
+      await removeLegacyGeneratedPaths(tomlPath, legacyTomlPaths);
+      console.log(`gemini: wrote ${markdownPath}`);
+      console.log(`gemini: wrote ${tomlPath}`);
+    }
+    emittedNames.push(String(name));
+    count++;
+  }
+
+  // T066 — write manifest.json
+  const manifestPath = path.join(outDir, 'manifest.json');
+  const sortedNames = [...emittedNames].sort();
+  const manifest = {
+    version: '1.0',
+    generated: new Date().toISOString(),
+    commands: sortedNames,
+  };
+
+  if (dryRun) {
+    console.log(`[dry-run] gemini: would write manifest ${manifestPath}`);
+    console.log(`[dry-run] gemini: would write extension manifest ${extensionPath}`);
+  } else {
+    await ensureDir(outDir);
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    await fs.writeFile(
+      extensionPath,
+      JSON.stringify(buildGeminiExtensionManifest(version), null, 2) + '\n',
+      'utf8'
+    );
+    console.log(`gemini: wrote manifest ${manifestPath}`);
+    console.log(`gemini: wrote extension manifest ${extensionPath}`);
+  }
+
+  console.log(`gemini: ${count} file(s) emitted`);
+  return true;
+}
+
+/**
+ * T067 — agents-md emitter
+ * Creates .agents/AGENTS.md — a consolidated AGENTS.md for Gemini/Codex.
+ * Includes all stages emitted to portable agent surfaces.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitAgentsMd(stages, root, dryRun) {
+  const outPath = path.join(root, '.agents', 'AGENTS.md');
+  const timestamp = new Date().toISOString();
+  const sections = [];
+
+  for (const stage of stages) {
+    const { name, title, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'agents-md')) continue;
+    if (!surfaces.includes('gemini') && !surfaces.includes('codex') && !surfaces.includes('agents-skills')) continue;
+
+    const summary = stage.body.slice(0, 200).replace(/\n+$/, '');
+    const sectionTitle = title ? String(title) : String(name);
+    sections.push(`### ${sectionTitle}\n${summary}...`);
+  }
+
+const content = `# Gofer Agent Commands
+
+This file documents all Gofer pipeline commands available as agent skills.
+
+Generated: ${timestamp}
+
+## EAI CLI Discovery And Recovery
+
+- Run \`eai update --check\` before first EAI platform work when the CLI may be stale.
+- Run \`eai --describe\` before assuming command syntax.
+- If advertised, run \`eai agent guide --format json\` before planning or fixing EAI workflows.
+- After any \`eai\` error, run \`eai errors explain <code-or-reason> --format json\` before guessing remediation.
+- If \`eai errors explain\` is unavailable, match \`.specify/references/platform/eai-error-catalog.yaml\`, run read-only diagnostics before mutating fixes, and stop at the retry or escalation condition.
+- For \`eai user invite\` 5xx or \`EXTERNAL_SERVICE_ERROR\`, check existing members with \`eai user list --tenant <tenant-id> --search <email> --format json\`; use \`eai user role set --tenant <tenant-id> --member-id <member-id> --role tenant-admin --format json\` only after verification and user approval, then tell the app user to sign out and sign back in.
+- Use \`eai publicapi\` only for authorized PublicAPI \`/v4/...\` routes.
+
+## Commands
+
+${sections.join('\n\n')}
+`;
+
+  if (dryRun) {
+    console.log(`[dry-run] agents-md: would write ${outPath}`);
+  } else {
+    await ensureDir(path.dirname(outPath));
+    await fs.writeFile(outPath, content, 'utf8');
+    console.log(`agents-md: wrote ${outPath}`);
+  }
+
+  console.log(`agents-md: ${sections.length} section(s) emitted`);
+  return true;
+}
+
+/**
+ * T068 — codex-config emitter
+ * Generates .specify/outputs/codex-config-fragment.toml containing skill entries
+ * for every stage emitted to Codex/agents-skills.
+ * Does NOT touch ~/.codex/config.toml.
+ *
+ * @param {Array} stages
+ * @param {string} root
+ * @param {boolean} dryRun
+ */
+async function emitCodexConfig(stages, root, dryRun) {
+  const outDir = path.join(root, '.specify', 'outputs');
+  const outPath = path.join(outDir, 'codex-config-fragment.toml');
+  const timestamp = new Date().toISOString();
+  const lines = [
+    `# Gofer skill overrides for ~/.codex/config.toml`,
+    `# Generated by generate-commands.mjs on ${timestamp}`,
+    `# Codex discovers repository-local Gofer skills from .agents/skills automatically.`,
+    `# Only use these [[skills.config]] blocks when you need explicit per-skill overrides.`,
+    `# Replace /full/path/to/repo with the absolute path to your local checkout.`,
+    ``,
+  ];
+
+  let count = 0;
+  for (const stage of stages) {
+    const { name, surfaces } = stage.frontmatter;
+    if (shouldExclude(String(name), 'codex-config')) continue;
+    if (!surfaces.includes('codex') && !surfaces.includes('agents-skills')) continue;
+
+    const stageStem = getStageOutputStem(stage);
+    lines.push(`[[skills.config]]`);
+    lines.push(`path = "/full/path/to/repo/.agents/skills/${escapeTomlString(stageStem)}"`);
+    lines.push(`enabled = true`);
+    lines.push(``);
+    count++;
+  }
+
+  const content = lines.join('\n');
+
+  if (dryRun) {
+    console.log(`[dry-run] codex-config: would write ${outPath}`);
+  } else {
+    await ensureDir(outDir);
+    await fs.writeFile(outPath, content, 'utf8');
+    console.log(`codex-config: wrote ${outPath}`);
+  }
+
+  console.log(`codex-config: ${count} skill entrie(s) emitted`);
+  return true;
+}
+
+const EMITTERS = {
+  'claude': emitClaude,
+  'claude-mirror': emitClaudeMirror,
+  'claude-skills': emitClaudeSkills,
+  'copilot': emitCopilot,
+  'github-prompts': emitGithubPrompts,
+  'github-agents': emitGithubAgents,
+  'github-skills': emitGithubSkills,
+  'agents-skills': emitAgentsSkills,
+  'system-skills': emitSystemSkills,
+  'gemini': emitGemini,
+  'agents-md': emitAgentsMd,
+  'codex-config': emitCodexConfig,
+};
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {
+    dryRun: false,
+    surfaces: ALL_SURFACES,
+    root: process.cwd(),
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--dry-run') {
+      args.dryRun = true;
+    } else if (arg === '--surfaces' && argv[i + 1]) {
+      args.surfaces = argv[i + 1].split(',').map((s) => s.trim()).filter(Boolean);
+      i++;
+    } else if (arg === '--root' && argv[i + 1]) {
+      args.root = argv[i + 1];
+      i++;
+    }
+  }
+
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// T043 — per-CLI exclusion enforcement (validation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that no stage is being emitted to a surface it should be excluded from.
+ * Logs a warning for any violations found.
+ *
+ * @param {Array} stages
+ * @param {string[]} surfaces
+ */
+function validateExclusions(stages, surfaces) {
+  let violations = 0;
+  for (const stage of stages) {
+    const stageName = String(stage.frontmatter.name);
+    for (const surface of surfaces) {
+      if (shouldExclude(stageName, surface) && stage.frontmatter.surfaces.includes(surface)) {
+        console.warn(
+          `[warn] Exclusion violation: stage '${stageName}' is listed under surface '${surface}' in its frontmatter, but shouldExclude() returns true for this combination. The emitter will skip this stage.`
+        );
+        violations++;
+      }
+    }
+  }
+  if (violations === 0) {
+    console.log(`Exclusion validation OK: no violations found`);
+  } else {
+    console.warn(`Exclusion validation: ${violations} violation(s) found (stages will still be skipped)`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { dryRun, surfaces, root } = parseArgs(argv);
+
+  // Validate canonical descriptions first (budget check)
+  try {
+    const { count, totalBytes } = validateDescriptions();
+    console.log(`Canonical descriptions OK: ${count} stages, ${totalBytes} bytes`);
+  } catch (err) {
+    console.error(`Canonical description validation failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Load all stage command files from .specify/commands/
+  let stages;
+  try {
+    stages = await loadStages(root);
+  } catch (err) {
+    console.error(`Stage loading failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (stages.length === 0) {
+    console.warn('[warn] No stage command files found in .specify/commands/ — nothing to emit');
+  } else {
+    console.log(`Loaded ${stages.length} stage(s): ${stages.map((s) => s.frontmatter.name).join(', ')}`);
+  }
+
+  // T043: validate exclusions
+  validateExclusions(stages, surfaces);
+
+  if (dryRun) {
+    console.log('[dry-run] Would emit to surfaces:', surfaces.join(', '));
+    console.log('[dry-run] Stages:', stages.map((s) => s.frontmatter.name).join(', '));
+    process.exit(0);
+  }
+
+  let allOk = true;
+  for (const surface of surfaces) {
+    const emitter = EMITTERS[surface];
+    if (!emitter) {
+      console.warn(`Unknown surface '${surface}' — skipping`);
+      continue;
+    }
+
+    try {
+      const ok = await emitter(stages, root, dryRun);
+      if (!ok) {
+        console.error(`Emitter for '${surface}' returned false`);
+        allOk = false;
+      }
+    } catch (err) {
+      console.error(`Emitter for '${surface}' threw: ${err.message}`);
+      allOk = false;
+    }
+  }
+
+  process.exit(allOk ? 0 : 1);
+}
+
+// Only run main when executed directly (not when imported as a module in tests)
+const isMain = process.argv[1] && (
+  process.argv[1].endsWith('generate-commands.mjs') ||
+  process.argv[1] === new URL(import.meta.url).pathname
+);
+
+if (isMain) {
+  main();
+}