@sun-asterisk/sungen 3.2.2 → 3.2.3-beta.3

package/src/orchestrator/ai-rules-updater.ts

@@ -6,106 +6,15 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { buildOutputs } from './ai-skills/build';
+import { applyOutputs } from './ai-skills/writer';
+import { AdapterKey } from './ai-skills/adapters';
 
-// File mapping: [templateFile, outputPath]
-// Shared with project-initializer.ts
-export const AI_RULES_FILE_MAPPING: [string, string][] = [
-  // Config
-  ['claude-config.md', 'CLAUDE.md'],
-  ['copilot-config.md', '.github/copilot-instructions.md'],
-
-  // Commands — Claude Code
-  ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
-  ['claude-cmd-add-flow.md', '.claude/commands/sungen/add-flow.md'],
-  ['claude-cmd-create-test.md', '.claude/commands/sungen/create-test.md'],
-  ['claude-cmd-design.md', '.claude/commands/sungen/design.md'],
-  ['claude-cmd-run-test.md', '.claude/commands/sungen/run-test.md'],
-  ['claude-cmd-review.md', '.claude/commands/sungen/review.md'],
-  ['claude-cmd-delivery.md', '.claude/commands/sungen/delivery.md'],
-  ['claude-cmd-dashboard.md', '.claude/commands/sungen/dashboard.md'],
-  ['claude-cmd-locale.md', '.claude/commands/sungen/locale.md'],
-  ['claude-cmd-feedback.md', '.claude/commands/sungen/feedback.md'],
-
-  // Commands — GitHub Copilot
-  ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
-  ['copilot-cmd-add-flow.md', '.github/prompts/sungen-add-flow.prompt.md'],
-  ['copilot-cmd-create-test.md', '.github/prompts/sungen-create-test.prompt.md'],
-  ['copilot-cmd-design.md', '.github/prompts/sungen-design.prompt.md'],
-  ['copilot-cmd-run-test.md', '.github/prompts/sungen-run-test.prompt.md'],
-  ['copilot-cmd-review.md', '.github/prompts/sungen-review.prompt.md'],
-  ['copilot-cmd-delivery.md', '.github/prompts/sungen-delivery.prompt.md'],
-  ['copilot-cmd-dashboard.md', '.github/prompts/sungen-dashboard.prompt.md'],
-  ['copilot-cmd-locale.md', '.github/prompts/sungen-locale.prompt.md'],
-  ['copilot-cmd-feedback.md', '.github/prompts/sungen-feedback.prompt.md'],
-
-  // Skills — Claude Code
-  ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
-  ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
-  ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
-  ['claude-skill-tc-generation.md', '.claude/skills/sungen-tc-generation/SKILL.md'],
-  ['claude-skill-test-design-techniques.md', '.claude/skills/sungen-test-design-techniques/SKILL.md'],
-  ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
-  ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
-  ['claude-skill-harness-audit.md', '.claude/skills/sungen-harness-audit/SKILL.md'],
-  ['claude-skill-api-design.md', '.claude/skills/sungen-api-design/SKILL.md'],
-  ['claude-skill-ingest-legacy.md', '.claude/skills/sungen-ingest-legacy/SKILL.md'],
-  ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
-  ['claude-skill-viewpoint-group-a-data-entry.md', '.claude/skills/sungen-viewpoint/group-a-data-entry.md'],
-  ['claude-skill-viewpoint-group-b-data-ops.md', '.claude/skills/sungen-viewpoint/group-b-data-ops.md'],
-  ['claude-skill-viewpoint-group-c-data-explore.md', '.claude/skills/sungen-viewpoint/group-c-data-explore.md'],
-  ['claude-skill-viewpoint-group-d-display.md', '.claude/skills/sungen-viewpoint/group-d-display.md'],
-  ['claude-skill-viewpoint-group-e-identity.md', '.claude/skills/sungen-viewpoint/group-e-identity.md'],
-  ['claude-skill-delivery.md', '.claude/skills/sungen-delivery/SKILL.md'],
-  ['claude-skill-dashboard.md', '.claude/skills/sungen-dashboard/SKILL.md'],
-  // sungen-capture — router skill (1 SKILL.md + 4 mode files). Replaces the former
-  // capture-figma / capture-live / capture-local / figma-source standalone skills.
-  ['claude-skill-capture.md', '.claude/skills/sungen-capture/SKILL.md'],
-  ['claude-skill-capture-mode-figma-mcp.md', '.claude/skills/sungen-capture/mode-figma-mcp.md'],
-  ['claude-skill-capture-mode-figma-pat.md', '.claude/skills/sungen-capture/mode-figma-pat.md'],
-  ['claude-skill-capture-mode-live.md', '.claude/skills/sungen-capture/mode-live.md'],
-  ['claude-skill-capture-mode-local.md', '.claude/skills/sungen-capture/mode-local.md'],
-  ['claude-skill-locale.md', '.claude/skills/sungen-locale/SKILL.md'],
-  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
-  ['claude-skill-mobile-gestures.md', '.claude/skills/sungen-mobile-gestures/SKILL.md'],
-  ['claude-skill-capture-mobile.md', '.claude/skills/sungen-capture-mobile/SKILL.md'],
-  ['claude-skill-selector-fix-mobile.md', '.claude/skills/sungen-selector-fix-mobile/SKILL.md'],
-
-  // Agents — Claude Code sub-agents (isolated context). Copilot runs these inline.
-  ['claude-agent-reviewer.md', '.claude/agents/sungen-reviewer.md'],
-  ['claude-agent-discovery.md', '.claude/agents/sungen-discovery.md'],
-  ['claude-agent-challenge.md', '.claude/agents/sungen-challenge.md'],
-  ['claude-agent-generator.md', '.claude/agents/sungen-generator.md'],
+function sungenVersion(): string {
+  try { return require(path.join(__dirname, '..', '..', 'package.json')).version || '0.0.0'; }
+  catch { return '0.0.0'; }
+}
 
-  // Skills — GitHub Copilot
-  ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
-  ['github-skill-sungen-selector-keys.md', '.github/skills/sungen-selector-keys/SKILL.md'],
-  ['github-skill-sungen-error-mapping.md', '.github/skills/sungen-error-mapping/SKILL.md'],
-  ['github-skill-sungen-tc-generation.md', '.github/skills/sungen-tc-generation/SKILL.md'],
-  ['github-skill-sungen-test-design-techniques.md', '.github/skills/sungen-test-design-techniques/SKILL.md'],
-  ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
-  ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
-  ['github-skill-sungen-harness-audit.md', '.github/skills/sungen-harness-audit/SKILL.md'],
-  ['github-skill-sungen-api-design.md', '.github/skills/sungen-api-design/SKILL.md'],
-  ['github-skill-sungen-ingest-legacy.md', '.github/skills/sungen-ingest-legacy/SKILL.md'],
-  ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
-  ['github-skill-sungen-viewpoint-group-a-data-entry.md', '.github/skills/sungen-viewpoint/group-a-data-entry.md'],
-  ['github-skill-sungen-viewpoint-group-b-data-ops.md', '.github/skills/sungen-viewpoint/group-b-data-ops.md'],
-  ['github-skill-sungen-viewpoint-group-c-data-explore.md', '.github/skills/sungen-viewpoint/group-c-data-explore.md'],
-  ['github-skill-sungen-viewpoint-group-d-display.md', '.github/skills/sungen-viewpoint/group-d-display.md'],
-  ['github-skill-sungen-viewpoint-group-e-identity.md', '.github/skills/sungen-viewpoint/group-e-identity.md'],
-  ['github-skill-sungen-delivery.md', '.github/skills/sungen-delivery/SKILL.md'],
-  ['github-skill-sungen-dashboard.md', '.github/skills/sungen-dashboard/SKILL.md'],
-  ['github-skill-sungen-capture.md', '.github/skills/sungen-capture/SKILL.md'],
-  ['github-skill-sungen-capture-mode-figma-mcp.md', '.github/skills/sungen-capture/mode-figma-mcp.md'],
-  ['github-skill-sungen-capture-mode-figma-pat.md', '.github/skills/sungen-capture/mode-figma-pat.md'],
-  ['github-skill-sungen-capture-mode-live.md', '.github/skills/sungen-capture/mode-live.md'],
-  ['github-skill-sungen-capture-mode-local.md', '.github/skills/sungen-capture/mode-local.md'],
-  ['github-skill-sungen-locale.md', '.github/skills/sungen-locale/SKILL.md'],
-  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
-  ['github-skill-sungen-mobile-gestures.md', '.github/skills/sungen-mobile-gestures/SKILL.md'],
-  ['github-skill-sungen-capture-mobile.md', '.github/skills/sungen-capture-mobile/SKILL.md'],
-  ['github-skill-sungen-selector-fix-mobile.md', '.github/skills/sungen-selector-fix-mobile/SKILL.md'],
-];
 
 // Skill/asset directories retired in a previous refactor. `sungen update` removes
 // these so already-initialized projects don't keep loading stale skill descriptions.
@@ -124,119 +33,48 @@ export const STALE_AI_RULES_PATHS: string[] = [
 
 export class AIRulesUpdater {
   private cwd: string;
-  private aiTemplateDir: string;
 
   constructor(cwd: string) {
     this.cwd = cwd;
-    this.aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
   }
 
-  async update(dryRun: boolean): Promise<void> {
-    console.log('🔄 Updating AI rules, commands, and skills...\n');
-
-    const updated: string[] = [];
-    const created: string[] = [];
-    const unchanged: string[] = [];
-    const missing: string[] = [];
-
-    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
-      const templatePath = path.join(this.aiTemplateDir, templateFile);
-      const outputPath = path.join(this.cwd, outputRelPath);
-
-      if (!fs.existsSync(templatePath)) {
-        missing.push(templateFile);
-        continue;
-      }
-
-      const newContent = fs.readFileSync(templatePath, 'utf-8');
-
-      if (fs.existsSync(outputPath)) {
-        const currentContent = fs.readFileSync(outputPath, 'utf-8');
-        if (currentContent === newContent) {
-          unchanged.push(outputRelPath);
-          continue;
-        }
-
-        if (!dryRun) {
-          fs.writeFileSync(outputPath, newContent, 'utf-8');
-        }
-        updated.push(outputRelPath);
-      } else {
-        if (!dryRun) {
-          const outputDir = path.dirname(outputPath);
-          if (!fs.existsSync(outputDir)) {
-            fs.mkdirSync(outputDir, { recursive: true });
-          }
-          fs.writeFileSync(outputPath, newContent, 'utf-8');
-        }
-        created.push(outputRelPath);
-      }
-    }
-
-    // Remove retired skills/assets so stale descriptions stop loading.
+  /**
+   * Refresh AI rules/commands/skills from the single-source generator.
+   * @param dryRun show changes without writing
+   * @param opts.agents which assistants to install (default: claude — decision T5)
+   * @param opts.force overwrite user config files (CLAUDE.md/AGENTS.md/copilot-instructions)
+   */
+  async update(dryRun: boolean, opts: { agents?: AdapterKey[]; force?: boolean } = {}): Promise<void> {
+    const agents = opts.agents && opts.agents.length ? opts.agents : (['claude'] as AdapterKey[]);
+    console.log(`🔄 Updating AI rules for: ${agents.join(', ')}${dryRun ? ' (dry-run)' : ''}\n`);
+
+    // One-time legacy cleanup for projects created before the manifest existed.
     const removed: string[] = [];
     for (const staleRelPath of STALE_AI_RULES_PATHS) {
       const stalePath = path.join(this.cwd, staleRelPath);
       if (fs.existsSync(stalePath)) {
-        if (!dryRun) {
-          fs.rmSync(stalePath, { recursive: true, force: true });
-        }
+        if (!dryRun) fs.rmSync(stalePath, { recursive: true, force: true });
         removed.push(staleRelPath);
       }
     }
 
-    // Print results
-    if (dryRun) {
-      console.log('📋 Dry run — no files changed\n');
+    const outputs = buildOutputs(agents);
+    const r = applyOutputs(this.cwd, outputs, { version: sungenVersion(), dryRun, force: opts.force });
+
+    if (dryRun) console.log('📋 Dry run — no files changed\n');
+    if (removed.length) console.log(`🗑️  Removed retired assets (${removed.length})`);
+    if (r.deletedOrphans.length) console.log(`🗑️  Removed orphans (${r.deletedOrphans.length}): ${r.deletedOrphans.join(', ')}`);
+    if (r.created.length) console.log(`✨ Created (${r.created.length})`);
+    if (r.overwritten.length) console.log(`✏️  Updated (${r.overwritten.length})`);
+    if (r.skippedConfig.length) console.log(`⏭️  Config preserved (use --force to overwrite): ${r.skippedConfig.join(', ')}`);
+    if (r.handEditWarnings.length) {
+      console.log(`\n⚠️  Overwrote files that look hand-edited (sungen owns these — version-managed):`);
+      for (const f of r.handEditWarnings) console.log(`   ${f}`);
     }
 
-    if (removed.length > 0) {
-      console.log(`🗑️  Removed retired assets (${removed.length}):`);
-      for (const f of removed) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (updated.length > 0) {
-      console.log(`✏️  Updated (${updated.length}):`);
-      for (const f of updated) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (created.length > 0) {
-      console.log(`✨ Created (${created.length}):`);
-      for (const f of created) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (unchanged.length > 0) {
-      console.log(`✅ Already up to date (${unchanged.length}):`);
-      for (const f of unchanged) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (missing.length > 0) {
-      console.log(`⚠️  Template not found (${missing.length}):`);
-      for (const f of missing) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    const totalChanges = updated.length + created.length;
-    if (totalChanges === 0) {
-      console.log('All AI rules are up to date. No changes needed.');
-    } else if (dryRun) {
-      console.log(`${totalChanges} file(s) would be changed. Run without --dry-run to apply.`);
-    } else {
-      console.log(`${totalChanges} file(s) updated successfully.`);
-    }
+    const total = r.created.length + r.overwritten.length;
+    if (total === 0 && !removed.length && !r.deletedOrphans.length) console.log('All AI rules are up to date. No changes needed.');
+    else if (dryRun) console.log(`\n${total} file(s) would change. Run without --dry-run to apply.`);
+    else console.log(`\n${total} file(s) updated for ${agents.join(', ')}.`);
   }
 }

package/src/orchestrator/ai-skills/adapters.ts

@@ -0,0 +1,52 @@
+/**
+ * Adapter table — one row per assistant. Adding a new assistant = one row here,
+ * zero new content files (the whole point of the single-source migration).
+ *
+ * Output paths preserve the EXACT existing Claude/Copilot conventions (decision 4A) so the
+ * golden-regression net stays byte-identical for Claude. Codex is additive (`.agents/skills/`).
+ */
+
+export type AdapterKey = 'claude' | 'copilot' | 'codex';
+
+export interface Adapter {
+  key: AdapterKey;
+  /** capability tags this adapter owns; cap-fences resolve against this */
+  caps: string[];
+  /** output path for a `kind: skill` unit, given the skill dir name + relative file */
+  skillPath: (skillDir: string, file: string) => string;
+  /** output path for a `kind: command` unit; null => commands render as skills */
+  commandPath: ((name: string) => string) | null;
+  /**
+   * When commandPath is null (Codex), a command renders into the skill tree. This computes
+   * the skill dir for a command, and a backing skill whose name collides gets a `-guide`
+   * suffix (the flat-namespace collision found during spike prep: delivery/dashboard/locale).
+   */
+  commandAsSkillDir?: (name: string) => string;
+  /** Codex needs an explicit trigger prefixed onto the command-skill description */
+  commandTriggerPrefix?: boolean;
+}
+
+export const ADAPTERS: Record<AdapterKey, Adapter> = {
+  claude: {
+    key: 'claude',
+    caps: ['parallel-subagents'],
+    skillPath: (dir, file) => `.claude/skills/${dir}/${file}`,
+    commandPath: (name) => `.claude/commands/sungen/${name}.md`,
+  },
+  copilot: {
+    key: 'copilot',
+    caps: [],
+    skillPath: (dir, file) => `.github/skills/${dir}/${file}`,
+    commandPath: (name) => `.github/prompts/sungen-${name}.prompt.md`,
+  },
+  codex: {
+    key: 'codex',
+    caps: [],
+    skillPath: (dir, file) => `.agents/skills/${dir}/${file}`,
+    commandPath: null, // commands become skills
+    commandAsSkillDir: (name) => `.agents/skills/sungen-${name}`,
+    commandTriggerPrefix: true,
+  },
+};
+
+export const ALL_ADAPTERS: AdapterKey[] = ['claude', 'copilot', 'codex'];

package/src/orchestrator/ai-skills/build.ts

@@ -0,0 +1,103 @@
+/**
+ * buildOutputs — the single entry point init/update call (decision 1A).
+ * Produces the full [outputPath, content, class] set for the selected adapters from the
+ * canonical source. Pure: never touches disk.
+ *
+ * class:
+ *   'managed' — skill/command files; sungen owns them, always overwritten (version-managed)
+ *   'config'  — CLAUDE.md / copilot-instructions.md / AGENTS.md; user-customizable,
+ *               skip-if-exists unless --force (decision 2)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripCaps } from './cap-stripper';
+import { ADAPTERS, AdapterKey } from './adapters';
+import { parseCommandSource, generateCommand } from './commands';
+
+export type FileClass = 'managed' | 'config';
+export interface BuiltFile {
+  outputPath: string;
+  content: string;
+  cls: FileClass;
+}
+
+const SRC_SKILLS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'skills');
+const SRC_CMDS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'commands');
+const SRC_AGENTS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'agents');
+const SRC_CONFIG = path.resolve(__dirname, '..', 'templates', 'ai-src', 'config');
+
+// Config files per adapter: [source file under ai-src/config, outputPath].
+const CONFIG: Record<AdapterKey, { src: string; out: string }> = {
+  claude: { src: 'claude.md', out: 'CLAUDE.md' },
+  copilot: { src: 'copilot.md', out: '.github/copilot-instructions.md' },
+  codex: { src: 'codex.md', out: 'AGENTS.md' },
+};
+
+function commandIds(): Set<string> {
+  if (!fs.existsSync(SRC_CMDS)) return new Set();
+  return new Set(fs.readdirSync(SRC_CMDS).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')));
+}
+
+/** Build every output file for the given adapters. */
+export function buildOutputs(adapters: AdapterKey[]): BuiltFile[] {
+  const out: BuiltFile[] = [];
+  const cmdIds = commandIds();
+
+  for (const key of adapters) {
+    const adapter = ADAPTERS[key];
+
+    // --- Skills ---
+    if (fs.existsSync(SRC_SKILLS)) {
+      for (const skillDir of fs.readdirSync(SRC_SKILLS)) {
+        const dirPath = path.join(SRC_SKILLS, skillDir);
+        if (!fs.statSync(dirPath).isDirectory()) continue;
+        // Codex flat namespace: a skill whose name collides with a command becomes <dir>-guide.
+        // Both the output dir AND the SKILL.md `name:` frontmatter must change, or Codex would
+        // discover two skills with the same `name` (breaking $name + description selection).
+        const bare = skillDir.replace(/^sungen-/, '');
+        const collide = key === 'codex' && cmdIds.has(bare);
+        const outDir = collide ? `${skillDir}-guide` : skillDir;
+        for (const file of fs.readdirSync(dirPath)) {
+          if (!file.endsWith('.md')) continue;
+          let raw = fs.readFileSync(path.join(dirPath, file), 'utf8');
+          if (collide && file === 'SKILL.md') {
+            raw = raw.replace(/^(name:\s*)sungen-[^\n]*/m, `$1sungen-${bare}-guide`);
+          }
+          out.push({
+            outputPath: adapter.skillPath(outDir, file),
+            content: stripCaps(raw, adapter.caps, `${skillDir}/${file}`),
+            cls: 'managed',
+          });
+        }
+      }
+    }
+
+    // --- Commands ---
+    if (fs.existsSync(SRC_CMDS)) {
+      for (const f of fs.readdirSync(SRC_CMDS)) {
+        if (!f.endsWith('.md')) continue;
+        const id = f.replace(/\.md$/, '');
+        const src = parseCommandSource(fs.readFileSync(path.join(SRC_CMDS, f), 'utf8'), id);
+        const g = generateCommand(src, key);
+        out.push({ outputPath: g.outputPath, content: g.content, cls: 'managed' });
+      }
+    }
+
+    // --- Agents (Claude-only sub-agents; Copilot runs them inline, Codex has no equivalent) ---
+    if (key === 'claude' && fs.existsSync(SRC_AGENTS)) {
+      for (const f of fs.readdirSync(SRC_AGENTS)) {
+        if (!f.endsWith('.md')) continue;
+        const role = f.replace(/\.md$/, '');
+        const raw = fs.readFileSync(path.join(SRC_AGENTS, f), 'utf8');
+        out.push({ outputPath: `.claude/agents/sungen-${role}.md`, content: stripCaps(raw, adapter.caps, `agents/${f}`), cls: 'managed' });
+      }
+    }
+
+    // --- Config (skip-unless-force) ---
+    const cfg = CONFIG[key];
+    const content = fs.readFileSync(path.join(SRC_CONFIG, cfg.src), 'utf8');
+    out.push({ outputPath: cfg.out, content, cls: 'config' });
+  }
+
+  return out;
+}

package/src/orchestrator/ai-skills/cap-stripper.ts

@@ -0,0 +1,85 @@
+/**
+ * Cap-fence stripper for single-source AI skill templates.
+ *
+ * A single source body may contain capability-fenced blocks that are kept or dropped
+ * per target adapter:
+ *
+ *   {{#cap parallel-subagents}}   ... kept only if the adapter HAS the cap ...   {{/cap}}
+ *   {{^cap parallel-subagents}}   ... kept only if the adapter LACKS the cap ... {{/cap}}
+ *
+ * Fence lines must be on their own line. Nesting is forbidden. Unknown cap tags and
+ * unclosed fences FAIL LOUD (decision 5A) so a typo can never silently delete content.
+ *
+ * Blank lines left where a block is removed are normalized (no run of 3+ blank lines),
+ * so the diff-regression golden net stays quiet (decision 3A).
+ */
+
+// Central list of valid capability tags. Adding a capability = adding it here.
+// Measured divergence (2026-06-27) shows essentially one axis today.
+export const VALID_CAPS = ['parallel-subagents'] as const;
+export type Cap = (typeof VALID_CAPS)[number];
+
+const OPEN_POS = /^\s*\{\{#cap\s+([a-z0-9-]+)\s*\}\}\s*$/;
+const OPEN_NEG = /^\s*\{\{\^cap\s+([a-z0-9-]+)\s*\}\}\s*$/;
+const CLOSE = /^\s*\{\{\/cap\}\}\s*$/;
+
+export class CapFenceError extends Error {}
+
+/**
+ * Render `body` for an adapter that owns `caps`.
+ * @param body      raw single-source body (frontmatter already removed)
+ * @param caps      capability tags the target adapter has
+ * @param skillName for error messages
+ */
+export function stripCaps(body: string, caps: readonly string[], skillName = '<unknown>'): string {
+  const has = (tag: string) => caps.includes(tag);
+  const out: string[] = [];
+  let open: { tag: string; keep: boolean; line: number } | null = null;
+
+  const lines = body.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const mPos = line.match(OPEN_POS);
+    const mNeg = line.match(OPEN_NEG);
+    const mClose = CLOSE.test(line);
+
+    if (mPos || mNeg) {
+      if (open) {
+        throw new CapFenceError(
+          `${skillName}: nested cap fence at line ${i + 1} (already inside {{#cap ${open.tag}}} from line ${open.line}); nesting is forbidden`,
+        );
+      }
+      const tag = (mPos ? mPos[1] : mNeg![1]);
+      if (!VALID_CAPS.includes(tag as Cap)) {
+        throw new CapFenceError(
+          `${skillName}: unknown cap tag "${tag}" at line ${i + 1} (valid: ${VALID_CAPS.join(', ')})`,
+        );
+      }
+      // positive: keep when adapter HAS cap; negative: keep when adapter LACKS cap
+      open = { tag, keep: mPos ? has(tag) : !has(tag), line: i + 1 };
+      continue; // fence line itself is never emitted
+    }
+
+    if (mClose) {
+      if (!open) {
+        throw new CapFenceError(`${skillName}: stray {{/cap}} at line ${i + 1} with no open fence`);
+      }
+      open = null;
+      continue; // fence line itself is never emitted
+    }
+
+    if (open) {
+      if (open.keep) out.push(line);
+      // dropped block: skip the line
+      continue;
+    }
+    out.push(line);
+  }
+
+  if (open) {
+    throw new CapFenceError(`${skillName}: unclosed {{#cap ${open.tag}}} opened at line ${open.line}`);
+  }
+
+  // Normalize: collapse 3+ consecutive blank lines (left by removed blocks) to one.
+  return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/src/orchestrator/ai-skills/commands.ts

@@ -0,0 +1,112 @@
+/**
+ * Command generator. Commands diverge per-adapter in BOTH frontmatter shape and body
+ * (measured 2026-06-27: all 10 pairs differ, create-test by 123 lines). Claude output must
+ * be byte-identical (gate); Copilot/Codex are re-derived from the canonical source (lenient).
+ *
+ * Source: templates/ai-src/commands/<name>.md
+ *   ---
+ *   name: create-test
+ *   description: "<canonical Claude description>"
+ *   argument-hint: "[screen-name]"
+ *   order: 20
+ *   claude-tools: "Read, Grep, ..."          # verbatim allowed-tools line for Claude
+ *   codex-trigger: "Run when the user asks to ..."   # explicit trigger for Codex (P2 mitigation)
+ *   copilot-tools: "[vscode, execute, ...]"  # optional; default used if absent
+ *   ---
+ *   <body with cap-fences>
+ */
+import { stripCaps } from './cap-stripper';
+import { GenFile } from './generator';
+
+export interface CommandSource {
+  id: string;   // command identity (from source filename) — drives output paths
+  name: string; // frontmatter `name:` value; '' means the original had no name line
+  description: string;
+  argumentHint: string; // raw, e.g. "[screen-name]"
+  order?: number;
+  claudeTools: string;
+  copilotTools: string;
+  codexTrigger: string;
+  body: string; // with cap-fences
+}
+
+const DEFAULT_COPILOT_TOOLS = '[vscode, execute, read, edit, search, todo]';
+
+/** Parse a source command file into a CommandSource. */
+export function parseCommandSource(text: string, id: string): CommandSource {
+  const end = text.indexOf('\n---', 3);
+  const raw: Record<string, string> = {};
+  for (const line of text.slice(3, end).trim().split('\n')) {
+    const m = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
+    if (m) raw[m[1]] = m[2];
+  }
+  // JSON-encoded fields decode losslessly; argument-hint is kept VERBATIM so Claude output
+  // reproduces the original quoting (some commands quote it, some don't).
+  const dec = (k: string): string => {
+    const v = raw[k];
+    if (v == null) return '';
+    if (v.startsWith('"')) { try { return JSON.parse(v); } catch { /* fall through */ } }
+    return v.replace(/^['"]|['"]$/g, '');
+  };
+  const body = text.slice(end + 4).replace(/^\n+/, '');
+  return {
+    id,
+    name: raw['name'] != null ? dec('name') : '',
+    description: dec('description'),
+    argumentHint: raw['argument-hint'] || '', // verbatim
+    order: raw.order ? Number(raw.order) : undefined,
+    claudeTools: dec('claude-tools'),
+    copilotTools: raw['copilot-tools'] ? dec('copilot-tools') : DEFAULT_COPILOT_TOOLS,
+    codexTrigger: dec('codex-trigger'),
+    body,
+  };
+}
+
+const unquote = (s: string) => s.replace(/^['"]|['"]$/g, '');
+
+/** Claude command file — MUST reproduce the exact existing format (byte-identical gate). */
+export function renderClaudeCommand(c: CommandSource): string {
+  const fm = [
+    '---',
+    ...(c.name ? [`name: ${c.name}`] : []), // some commands (locale) omit name
+    `description: '${c.description}'`,
+    `argument-hint: ${c.argumentHint}`,
+    `allowed-tools: ${c.claudeTools}`,
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, ['parallel-subagents'], `cmd:${c.id}`);
+}
+
+/** Copilot prompt file — re-derived (lenient). */
+export function renderCopilotCommand(c: CommandSource): string {
+  const fm = [
+    '---',
+    `name: sungen-${c.id}`,
+    `description: '${c.description}'`,
+    `argument-hint: '${unquote(c.argumentHint)}'`,
+    `agent: 'agent'`,
+    `tools: ${c.copilotTools}`,
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+}
+
+/** Codex command-skill — command folds into a skill with an explicit trigger (decision P2). */
+export function renderCodexCommand(c: CommandSource): string {
+  const desc = c.codexTrigger ? `${c.codexTrigger}` : c.description;
+  const fm = [
+    '---',
+    `name: sungen-${c.id}`,
+    `description: ${JSON.stringify(desc)}`,
+    `kind: command`,
+    ...(c.order != null ? [`order: ${c.order}`] : []),
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+}
+
+export function generateCommand(c: CommandSource, adapter: 'claude' | 'copilot' | 'codex'): GenFile {
+  if (adapter === 'claude') return { outputPath: `.claude/commands/sungen/${c.id}.md`, content: renderClaudeCommand(c) };
+  if (adapter === 'copilot') return { outputPath: `.github/prompts/sungen-${c.id}.prompt.md`, content: renderCopilotCommand(c) };
+  return { outputPath: `.agents/skills/sungen-${c.id}/SKILL.md`, content: renderCodexCommand(c) };
+}

package/src/orchestrator/ai-skills/generator.ts

@@ -0,0 +1,47 @@
+/**
+ * Single-source generator (decision 1A).
+ *
+ * Produces an in-memory list of [outputPath, content] pairs from canonical source skill
+ * files, for the selected adapters. `init` and `update` consume this list and keep their own
+ * write semantics — this module never touches disk.
+ *
+ * Source layout (canonical = Claude content, decision 2):
+ *   templates/ai-src/skills/<skillDir>/<file>.md   (kind: skill, possibly multi-file)
+ *   templates/ai-src/commands/<name>.md            (kind: command)  [wired in a later step]
+ *
+ * Each source file may contain cap-fences ({{#cap}} / {{^cap}}) for per-adapter deltas.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripCaps } from './cap-stripper';
+import { ADAPTERS, AdapterKey } from './adapters';
+
+export interface GenFile {
+  outputPath: string; // repo-relative
+  content: string;
+}
+
+/** Render all skill units under `srcSkillsDir` for one adapter. */
+export function generateSkills(srcSkillsDir: string, adapterKey: AdapterKey): GenFile[] {
+  const adapter = ADAPTERS[adapterKey];
+  const out: GenFile[] = [];
+  if (!fs.existsSync(srcSkillsDir)) return out;
+
+  for (const skillDir of fs.readdirSync(srcSkillsDir)) {
+    const dirPath = path.join(srcSkillsDir, skillDir);
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    for (const file of fs.readdirSync(dirPath)) {
+      if (!file.endsWith('.md')) continue;
+      const raw = fs.readFileSync(path.join(dirPath, file), 'utf8');
+      const content = stripCaps(raw, adapter.caps, `${skillDir}/${file}`);
+      out.push({ outputPath: adapter.skillPath(skillDir, file), content });
+    }
+  }
+  return out;
+}
+
+/** Render for several adapters at once. */
+export function generate(srcSkillsDir: string, adapters: AdapterKey[]): GenFile[] {
+  return adapters.flatMap((a) => generateSkills(srcSkillsDir, a));
+}