agentboot 0.1.0

package/scripts/compile.ts

@@ -0,0 +1,1000 @@
+/**
+ * AgentBoot compile script.
+ *
+ * Reads agentboot.config.json, traverses core/traits/ and core/personas/,
+ * composes each persona by inlining trait content, and writes output to
+ * dist/{platform}/ — one self-contained distribution per platform.
+ *
+ * Output structure:
+ *   dist/skill/   — cross-platform SKILL.md (agentskills.io, traits inlined)
+ *   dist/claude/  — Claude Code native (.claude/ format)
+ *   dist/copilot/ — GitHub Copilot (.github/ format)
+ *
+ * Each platform folder contains the full scope hierarchy:
+ *   dist/{platform}/core/
+ *   dist/{platform}/groups/{group}/
+ *   dist/{platform}/teams/{group}/{team}/
+ *
+ * Trait injection points in SKILL.md:
+ *   <!-- traits:start -->
+ *   (existing content is replaced on each build)
+ *   <!-- traits:end -->
+ *
+ * Usage:
+ *   npm run build
+ *   tsx scripts/compile.ts
+ *   tsx scripts/compile.ts --config path/to/agentboot.config.json
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import {
+  type AgentBootConfig,
+  type PersonaConfig,
+  resolveConfigPath,
+  loadConfig,
+  stripJsoncComments,
+} from "./lib/config.js";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+interface TraitContent {
+  name: string;
+  content: string;
+  filePath: string;
+}
+
+interface CompileResult {
+  persona: string;
+  platforms: string[];
+  traitsInjected: string[];
+  scope: "core" | "group" | "team";
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fatal(msg: string): never {
+  console.error(chalk.red(`✗ FATAL: ${msg}`));
+  process.exit(1);
+}
+
+function log(msg: string): void {
+  console.log(msg);
+}
+
+function ensureDir(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function provenanceHeader(sourceFile: string, config: AgentBootConfig): string {
+  const relSource = path.relative(ROOT, sourceFile);
+  const timestamp = new Date().toISOString();
+  const org = config.orgDisplayName ?? config.org;
+  return [
+    `<!-- ============================================================ -->`,
+    `<!-- AgentBoot compiled output — do not edit manually.           -->`,
+    `<!-- Source:    ${relSource.padEnd(44)} -->`,
+    `<!-- Compiled:  ${timestamp.padEnd(44)} -->`,
+    `<!-- Org:       ${org.padEnd(44)} -->`,
+    `<!-- ============================================================ -->`,
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Trait loading
+// ---------------------------------------------------------------------------
+
+function loadTraits(
+  coreTraitsDir: string,
+  enabledTraits: string[] | undefined
+): Map<string, TraitContent> {
+  const traits = new Map<string, TraitContent>();
+
+  if (!fs.existsSync(coreTraitsDir)) {
+    log(chalk.yellow(`  ⚠ Traits directory not found: ${coreTraitsDir} — skipping trait injection`));
+    return traits;
+  }
+
+  const traitFiles = fs.readdirSync(coreTraitsDir).filter((f) => f.endsWith(".md"));
+
+  for (const file of traitFiles) {
+    const traitName = path.basename(file, ".md");
+
+    if (enabledTraits && !enabledTraits.includes(traitName)) {
+      continue;
+    }
+
+    const filePath = path.join(coreTraitsDir, file);
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    traits.set(traitName, {
+      name: traitName,
+      content: content.trim(),
+      filePath,
+    });
+  }
+
+  return traits;
+}
+
+// ---------------------------------------------------------------------------
+// Persona config loading
+// ---------------------------------------------------------------------------
+
+function loadPersonaConfig(personaDir: string): PersonaConfig | null {
+  const configPath = path.join(personaDir, "persona.config.json");
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(configPath, "utf-8");
+  try {
+    return JSON.parse(stripJsoncComments(raw)) as PersonaConfig;
+  } catch {
+    log(chalk.yellow(`  ⚠ Failed to parse persona.config.json in ${personaDir}`));
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Trait injection
+// ---------------------------------------------------------------------------
+
+const TRAITS_START_MARKER = "<!-- traits:start -->";
+const TRAITS_END_MARKER = "<!-- traits:end -->";
+
+function injectTraits(
+  skillContent: string,
+  traitNames: string[],
+  traits: Map<string, TraitContent>,
+  personaName: string
+): { result: string; injected: string[] } {
+  const injected: string[] = [];
+  const missing: string[] = [];
+
+  const blocks: string[] = [];
+  for (const traitName of traitNames) {
+    const trait = traits.get(traitName);
+    if (!trait) {
+      missing.push(traitName);
+      continue;
+    }
+    injected.push(traitName);
+    blocks.push(
+      `<!-- trait: ${traitName} -->\n${trait.content}\n<!-- /trait: ${traitName} -->`
+    );
+  }
+
+  if (missing.length > 0) {
+    log(
+      chalk.yellow(
+        `  ⚠ [${personaName}] Traits not found (skipped): ${missing.join(", ")}`
+      )
+    );
+  }
+
+  const injectedBlock =
+    blocks.length > 0
+      ? `\n\n${blocks.join("\n\n")}\n\n`
+      : "\n\n<!-- no traits configured -->\n\n";
+
+  const startIdx = skillContent.indexOf(TRAITS_START_MARKER);
+  const endIdx = skillContent.indexOf(TRAITS_END_MARKER);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = skillContent.slice(0, startIdx + TRAITS_START_MARKER.length);
+    const after = skillContent.slice(endIdx);
+    return {
+      result: `${before}${injectedBlock}${after}`,
+      injected,
+    };
+  }
+
+  return {
+    result: `${skillContent.trimEnd()}\n\n${TRAITS_START_MARKER}${injectedBlock}${TRAITS_END_MARKER}\n`,
+    injected,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Platform-specific output builders
+// ---------------------------------------------------------------------------
+
+function buildSkillOutput(
+  personaName: string,
+  _personaConfig: PersonaConfig | null,
+  composedContent: string,
+  config: AgentBootConfig,
+  skillPath: string
+): string {
+  const provenanceEnabled = config.output?.provenanceHeaders !== false;
+  return provenanceEnabled
+    ? `${provenanceHeader(skillPath, config)}${composedContent}`
+    : composedContent;
+}
+
+/**
+ * Build CC-native skill file.
+ * CC expects: .claude/skills/{skill-name}.md with description frontmatter.
+ * The skill name comes from the invocation (e.g., "/review-code" → "review-code").
+ */
+function buildClaudeOutput(
+  personaName: string,
+  personaConfig: PersonaConfig | null,
+  composedContent: string,
+  _config: AgentBootConfig
+): { content: string; skillName: string } {
+  const invocation = personaConfig?.invocation ?? `/${personaName}`;
+  const skillName = invocation.replace(/^\//, "");
+  const description = personaConfig?.description ?? personaName;
+  // Escape newlines and quotes in description to prevent YAML injection
+  const safeDescription = description.replace(/\n/g, " ").replace(/"/g, '\\"');
+
+  // AB-18: CC skill frontmatter with context:fork → delegates to agent
+  const frontmatterLines: string[] = [
+    "---",
+    `description: "${safeDescription}"`,
+    "context: fork",
+    `agent: "${personaName}"`,
+  ];
+
+  // Optional: include model override if specified
+  if (personaConfig?.model) {
+    frontmatterLines.push(`model: "${personaConfig.model}"`);
+  }
+
+  frontmatterLines.push("---", "");
+
+  // Strip any existing frontmatter from composed content (it's SKILL.md format)
+  const withoutFrontmatter = composedContent.replace(/^---\n[\s\S]*?\n---\n*/, "");
+
+  return {
+    content: `${frontmatterLines.join("\n")}\n${withoutFrontmatter}`,
+    skillName,
+  };
+}
+
+function buildCopilotOutput(
+  personaName: string,
+  personaConfig: PersonaConfig | null,
+  composedContent: string,
+  config: AgentBootConfig,
+  skillPath: string
+): string {
+  const header = `# ${personaConfig?.name ?? personaName} (AgentBoot)\n\n`;
+  const description = personaConfig?.description
+    ? `${personaConfig.description}\n\n---\n\n`
+    : "";
+  // Strip HTML comments for Copilot output.
+  const stripped = composedContent.replace(/<!--[\s\S]*?-->/g, "").trim();
+  return `${provenanceHeader(skillPath, config)}${header}${description}${stripped}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Persona compilation — writes to each platform's dist folder
+// ---------------------------------------------------------------------------
+
+function compilePersona(
+  personaName: string,
+  personaDir: string,
+  traits: Map<string, TraitContent>,
+  config: AgentBootConfig,
+  distPath: string,
+  scopePath: string,
+  groupName?: string,
+  teamName?: string
+): CompileResult {
+  const skillPath = path.join(personaDir, "SKILL.md");
+  const scope: "core" | "group" | "team" = teamName ? "team" : groupName ? "group" : "core";
+
+  if (!fs.existsSync(skillPath)) {
+    log(chalk.yellow(`  ⚠ [${personaName}] No SKILL.md found — skipping`));
+    return { persona: personaName, platforms: [], traitsInjected: [], scope };
+  }
+
+  const personaConfig = loadPersonaConfig(personaDir);
+  const skillContent = fs.readFileSync(skillPath, "utf-8");
+
+  // Determine which traits to inject.
+  let traitNames: string[] = personaConfig?.traits ?? [];
+
+  if (groupName && personaConfig?.groups?.[groupName]?.traits) {
+    traitNames = [...traitNames, ...(personaConfig.groups[groupName]!.traits ?? [])];
+  }
+
+  if (teamName && personaConfig?.teams?.[teamName]?.traits) {
+    traitNames = [...traitNames, ...(personaConfig.teams[teamName]!.traits ?? [])];
+  }
+
+  traitNames = [...new Set(traitNames)];
+
+  const { result: composed, injected } = injectTraits(
+    skillContent,
+    traitNames,
+    traits,
+    personaName
+  );
+
+  const outputFormats = config.personas?.outputFormats ?? ["skill", "claude", "copilot"];
+  const platforms: string[] = [];
+
+  // Write to dist/{platform}/{scopePath}/{persona}/ (or skills/{name}/ for claude)
+  // e.g., dist/skill/core/code-reviewer/SKILL.md
+  //        dist/claude/core/skills/review-code/SKILL.md
+
+  if (outputFormats.includes("skill")) {
+    const outDir = path.join(distPath, "skill", scopePath, personaName);
+    ensureDir(outDir);
+    const content = buildSkillOutput(personaName, personaConfig, composed, config, skillPath);
+    fs.writeFileSync(path.join(outDir, "SKILL.md"), content, "utf-8");
+    if (personaConfig) {
+      fs.writeFileSync(
+        path.join(outDir, "persona.config.json"),
+        JSON.stringify(personaConfig, null, 2) + "\n",
+        "utf-8"
+      );
+    }
+    platforms.push("skill");
+  }
+
+  if (outputFormats.includes("claude")) {
+    const { content, skillName } = buildClaudeOutput(personaName, personaConfig, composed, config);
+    // CC-native: write to dist/claude/{scope}/skills/{skillName}/SKILL.md
+    const skillDir = path.join(distPath, "claude", scopePath, "skills", skillName);
+    ensureDir(skillDir);
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), content, "utf-8");
+    platforms.push("claude");
+  }
+
+  if (outputFormats.includes("claude")) {
+    // AB-17: Write agent file to dist/claude/{scope}/agents/{personaName}.md
+    const agentDir = path.join(distPath, "claude", scopePath, "agents");
+    ensureDir(agentDir);
+
+    const model = personaConfig?.model;  // undefined = omit from frontmatter
+    const permMode = personaConfig?.permissionMode;
+    const agentDescription = personaConfig?.description ?? personaName;
+    // Escape newlines and quotes in description to prevent YAML injection.
+    // JS '\\"' produces the string \" which is the correct YAML double-quote escape.
+    const safeDescription = agentDescription.replace(/\n/g, " ").replace(/"/g, '\\"');
+    const withoutFrontmatter = composed.replace(/^---\n[\s\S]*?\n---\n*/, "");
+    const agentFrontmatter: string[] = [
+      "---",
+      `name: "${personaName}"`,
+      `description: "${safeDescription}"`,
+    ];
+    if (model) agentFrontmatter.push(`model: "${model}"`);
+    if (permMode && permMode !== "default") agentFrontmatter.push(`permissionMode: "${permMode}"`);
+    agentFrontmatter.push("---");
+    const agentContent = [...agentFrontmatter, "", withoutFrontmatter].join("\n");
+
+    fs.writeFileSync(path.join(agentDir, `${personaName}.md`), agentContent, "utf-8");
+  }
+
+  if (outputFormats.includes("copilot")) {
+    const outDir = path.join(distPath, "copilot", scopePath, personaName);
+    ensureDir(outDir);
+    const content = buildCopilotOutput(personaName, personaConfig, composed, config, skillPath);
+    fs.writeFileSync(path.join(outDir, "copilot-instructions.md"), content, "utf-8");
+    if (personaConfig) {
+      fs.writeFileSync(
+        path.join(outDir, "persona.config.json"),
+        JSON.stringify(personaConfig, null, 2) + "\n",
+        "utf-8"
+      );
+    }
+    platforms.push("copilot");
+  }
+
+  return { persona: personaName, platforms, traitsInjected: injected, scope };
+}
+
+// ---------------------------------------------------------------------------
+// Always-on instructions compilation — writes to each platform
+// ---------------------------------------------------------------------------
+
+function compileInstructions(
+  instructionsDir: string,
+  enabledInstructions: string[] | undefined,
+  distPath: string,
+  scopePath: string,
+  config: AgentBootConfig,
+  outputFormats: string[]
+): void {
+  if (!fs.existsSync(instructionsDir)) {
+    return;
+  }
+
+  const files = fs.readdirSync(instructionsDir).filter((f) => f.endsWith(".md"));
+  const provenanceEnabled = config.output?.provenanceHeaders !== false;
+
+  for (const platform of outputFormats) {
+    // CC uses "rules/" for always-on instructions; other platforms use "instructions/"
+    const dirName = platform === "claude" ? "rules" : "instructions";
+    const outDir = path.join(distPath, platform, scopePath, dirName);
+    ensureDir(outDir);
+
+    for (const file of files) {
+      const name = path.basename(file, ".md");
+      if (enabledInstructions && !enabledInstructions.includes(name)) {
+        continue;
+      }
+      const srcPath = path.join(instructionsDir, file);
+      let content = fs.readFileSync(srcPath, "utf-8");
+
+      // Strip HTML comments for copilot output
+      if (platform === "copilot") {
+        content = content.replace(/<!--[\s\S]*?-->/g, "").trim() + "\n";
+      }
+
+      let finalContent: string;
+      if (!provenanceEnabled) {
+        finalContent = content;
+      } else if (platform === "claude") {
+        // For CC rules, frontmatter must be the first thing in the file.
+        // Insert provenance after the closing --- of frontmatter.
+        const fmMatch = content.match(/^(---\n[\s\S]*?\n---\n)/);
+        if (fmMatch) {
+          const afterFm = content.slice(fmMatch[1].length);
+          finalContent = `${fmMatch[1]}\n${provenanceHeader(srcPath, config)}${afterFm}`;
+        } else {
+          finalContent = `${provenanceHeader(srcPath, config)}${content}`;
+        }
+      } else {
+        finalContent = `${provenanceHeader(srcPath, config)}${content}`;
+      }
+      fs.writeFileSync(path.join(outDir, file), finalContent, "utf-8");
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AB-52: Gotchas compilation — path-scoped knowledge rules
+// ---------------------------------------------------------------------------
+
+function compileGotchas(
+  gotchasDir: string,
+  distPath: string,
+  scopePath: string,
+  config: AgentBootConfig,
+  outputFormats: string[]
+): void {
+  if (!fs.existsSync(gotchasDir)) {
+    return;
+  }
+
+  const gotchaFiles = fs.readdirSync(gotchasDir).filter(
+    (f) => f.endsWith(".md") && f !== "README.md"
+  );
+
+  if (gotchaFiles.length === 0) return;
+
+  log(chalk.gray(`  Gotchas: ${gotchaFiles.length} rule(s)`));
+
+  for (const file of gotchaFiles) {
+    const content = fs.readFileSync(path.join(gotchasDir, file), "utf-8");
+    const provenanceEnabled = config.output?.provenanceHeaders !== false;
+    const header = provenanceEnabled
+      ? provenanceHeader(path.join(gotchasDir, file), config)
+      : "";
+
+    // Write to claude rules (gotchas are path-scoped rules)
+    if (outputFormats.includes("claude")) {
+      const rulesDir = path.join(distPath, "claude", scopePath, "rules");
+      ensureDir(rulesDir);
+      fs.writeFileSync(path.join(rulesDir, file), `${header}${content}`, "utf-8");
+    }
+
+    // Write to skill output as well
+    if (outputFormats.includes("skill")) {
+      const gotchaOutDir = path.join(distPath, "skill", scopePath, "gotchas");
+      ensureDir(gotchaOutDir);
+      fs.writeFileSync(path.join(gotchaOutDir, file), `${header}${content}`, "utf-8");
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PERSONAS.md index generation — writes to each platform
+// ---------------------------------------------------------------------------
+
+function generatePersonasIndex(
+  results: CompileResult[],
+  config: AgentBootConfig,
+  personasBaseDir: string,
+  distPath: string,
+  scopePath: string,
+  outputFormats: string[]
+): void {
+  const org = config.orgDisplayName ?? config.org;
+  const lines: string[] = [
+    `<!-- AgentBoot generated — do not edit manually. Org: ${org} -->`,
+    "",
+    `# Available Personas`,
+    "",
+    `> Generated by AgentBoot for **${org}**. Run \`npm run build\` to refresh.`,
+    "",
+    "| Persona | Invocation | Description |",
+    "|---|---|---|",
+  ];
+
+  for (const result of results.filter((r) => r.platforms.length > 0)) {
+    const personaConfigPath = path.join(personasBaseDir, result.persona, "persona.config.json");
+    let invocation = `/${result.persona}`;
+    let description = "";
+
+    if (fs.existsSync(personaConfigPath)) {
+      try {
+        const pc = JSON.parse(fs.readFileSync(personaConfigPath, "utf-8")) as PersonaConfig;
+        invocation = pc.invocation ?? invocation;
+        description = pc.description ?? "";
+      } catch {
+        // ignore
+      }
+    }
+
+    lines.push(`| **${result.persona}** | \`${invocation}\` | ${description} |`);
+  }
+
+  lines.push("", `*Last compiled: ${new Date().toISOString()}*`, "");
+  const content = lines.join("\n");
+
+  for (const platform of outputFormats) {
+    const outDir = path.join(distPath, platform, scopePath);
+    ensureDir(outDir);
+    fs.writeFileSync(path.join(outDir, "PERSONAS.md"), content, "utf-8");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AB-19: CLAUDE.md with @import directives + trait files
+// ---------------------------------------------------------------------------
+
+function generateClaudeMd(
+  traitNames: string[],
+  traits: Map<string, TraitContent>,
+  instructionFileNames: string[],
+  config: AgentBootConfig,
+  distPath: string,
+  scopePath: string,
+  personaConfigs?: Map<string, PersonaConfig>
+): void {
+  const org = config.orgDisplayName ?? config.org;
+
+  // Write trait files to dist/claude/{scopePath}/traits/
+  const traitsDir = path.join(distPath, "claude", scopePath, "traits");
+  ensureDir(traitsDir);
+
+  for (const traitName of traitNames) {
+    const trait = traits.get(traitName);
+    if (trait) {
+      fs.writeFileSync(path.join(traitsDir, `${traitName}.md`), trait.content, "utf-8");
+    }
+  }
+
+  // Build CLAUDE.md with @import directives
+  const lines: string[] = [
+    `# AgentBoot — ${org}`,
+    "",
+    "<!-- Auto-generated. Do not edit manually. -->",
+    "",
+  ];
+
+  if (traitNames.length > 0) {
+    lines.push("## Traits", "");
+    for (const traitName of traitNames) {
+      if (traits.has(traitName)) {
+        lines.push(`@.claude/traits/${traitName}.md`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (instructionFileNames.length > 0) {
+    lines.push("## Instructions", "");
+    for (const instrName of instructionFileNames) {
+      lines.push(`@.claude/rules/${instrName}.md`);
+    }
+    lines.push("");
+  }
+
+  // AB-77: First-session welcome fragment
+  if (personaConfigs && personaConfigs.size > 0) {
+    lines.push("## Available Personas", "");
+    for (const [, pc] of personaConfigs) {
+      const cmd = pc.invocation ?? `/${pc.name}`;
+      lines.push(`- \`${cmd}\` — ${pc.description}`);
+    }
+    lines.push("");
+  }
+
+  const claudeMdPath = path.join(distPath, "claude", scopePath, "CLAUDE.md");
+  fs.writeFileSync(claudeMdPath, lines.join("\n"), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// AB-26: settings.json generation
+// ---------------------------------------------------------------------------
+
+function generateSettingsJson(
+  config: AgentBootConfig,
+  distPath: string,
+  scopePath: string
+): void {
+  const hooks = config.claude?.hooks;
+  const permissions = config.claude?.permissions;
+
+  if (!hooks && !permissions) return;
+
+  // Validate hooks structure (must be an object with string keys)
+  if (hooks && typeof hooks !== "object") {
+    log(chalk.yellow("  ⚠ config.claude.hooks must be an object — skipping settings.json"));
+    return;
+  }
+  if (permissions) {
+    if (permissions.allow && !Array.isArray(permissions.allow)) {
+      log(chalk.yellow("  ⚠ config.claude.permissions.allow must be an array — skipping"));
+      return;
+    }
+    if (permissions.deny && !Array.isArray(permissions.deny)) {
+      log(chalk.yellow("  ⚠ config.claude.permissions.deny must be an array — skipping"));
+      return;
+    }
+  }
+
+  log(chalk.yellow("  ⚠ Generating settings.json with hooks/permissions — these will be synced to all target repos"));
+
+  const settings: Record<string, unknown> = {};
+  if (hooks) settings.hooks = hooks;
+  if (permissions) settings.permissions = permissions;
+
+  const settingsPath = path.join(distPath, "claude", scopePath, "settings.json");
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// AB-27: .mcp.json generation
+// ---------------------------------------------------------------------------
+
+function generateMcpJson(
+  config: AgentBootConfig,
+  distPath: string,
+  scopePath: string
+): void {
+  const mcpServers = config.claude?.mcpServers;
+  if (!mcpServers) return;
+
+  if (typeof mcpServers !== "object") {
+    log(chalk.yellow("  ⚠ config.claude.mcpServers must be an object — skipping .mcp.json"));
+    return;
+  }
+
+  log(chalk.yellow("  ⚠ Generating .mcp.json with MCP servers — these will be synced to all target repos"));
+
+  const mcpJson = { mcpServers };
+  const mcpPath = path.join(distPath, "claude", scopePath, ".mcp.json");
+  fs.writeFileSync(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  const configPath = resolveConfigPath(argv, ROOT);
+
+  log(chalk.bold("\nAgentBoot — compile"));
+  log(chalk.gray(`Config: ${configPath}\n`));
+
+  const config = loadConfig(configPath);
+  const configDir = path.dirname(configPath);
+
+  const distPath = path.resolve(
+    configDir,
+    config.output?.distPath ?? "./dist"
+  );
+
+  // Optional: fail on dirty dist.
+  if (config.output?.failOnDirtyDist && fs.existsSync(distPath)) {
+    const entries = fs.readdirSync(distPath);
+    if (entries.length > 0) {
+      fatal(
+        `dist/ is not empty and failOnDirtyDist is enabled. Run: rm -rf ${distPath}`
+      );
+    }
+  }
+
+  ensureDir(distPath);
+
+  const coreDir = path.join(ROOT, "core");
+  const corePersonasDir = path.join(coreDir, "personas");
+  const coreTraitsDir = path.join(coreDir, "traits");
+  const coreInstructionsDir = path.join(coreDir, "instructions");
+
+  const validFormats = ["skill", "claude", "copilot"];
+  const outputFormats = config.personas?.outputFormats ?? validFormats;
+  const unknownFormats = outputFormats.filter((f) => !validFormats.includes(f));
+  if (unknownFormats.length > 0) {
+    console.error(chalk.red(`Unknown output format(s): ${unknownFormats.join(", ")}. Valid: ${validFormats.join(", ")}`));
+    process.exit(1);
+  }
+
+  // Load traits.
+  const enabledTraits = config.traits?.enabled;
+  const traits = loadTraits(coreTraitsDir, enabledTraits);
+
+  log(chalk.cyan(`Traits loaded: ${traits.size}`));
+  for (const name of traits.keys()) {
+    log(chalk.gray(`  + ${name}`));
+  }
+  log(chalk.cyan(`Output formats: ${outputFormats.join(", ")}`));
+  log("");
+
+  const enabledPersonas = config.personas?.enabled;
+
+  // Discover persona directories.
+  const personaDirs = new Map<string, string>();
+
+  if (fs.existsSync(corePersonasDir)) {
+    for (const entry of fs.readdirSync(corePersonasDir)) {
+      const dir = path.join(corePersonasDir, entry);
+      if (fs.statSync(dir).isDirectory()) {
+        personaDirs.set(entry, dir);
+      }
+    }
+  }
+
+  if (config.personas?.customDir) {
+    const extendDir = path.resolve(configDir, config.personas.extend);
+    if (fs.existsSync(extendDir)) {
+      for (const entry of fs.readdirSync(extendDir)) {
+        const dir = path.join(extendDir, entry);
+        if (fs.statSync(dir).isDirectory()) {
+          if (personaDirs.has(entry)) {
+            log(chalk.yellow(`  ⚠ Extension persona overrides core: ${entry}`));
+          }
+          personaDirs.set(entry, dir);
+        }
+      }
+    } else {
+      log(chalk.yellow(`  ⚠ Extension path not found: ${extendDir}`));
+    }
+  }
+
+  const allResults: CompileResult[] = [];
+
+  // ---------------------------------------------------------------------------
+  // 1. Compile core personas → dist/{platform}/core/{persona}/
+  // ---------------------------------------------------------------------------
+
+  log(chalk.cyan("Compiling core personas..."));
+
+  for (const [personaName, personaDir] of personaDirs) {
+    if (enabledPersonas && !enabledPersonas.includes(personaName)) {
+      log(chalk.gray(`  - ${personaName} (disabled)`));
+      continue;
+    }
+
+    const result = compilePersona(
+      personaName,
+      personaDir,
+      traits,
+      config,
+      distPath,
+      "core"              // scopePath → dist/{platform}/core/{persona}/
+    );
+
+    allResults.push(result);
+
+    const traitsNote =
+      result.traitsInjected.length > 0
+        ? chalk.gray(` [traits: ${result.traitsInjected.join(", ")}]`)
+        : chalk.gray(" [no traits]");
+    log(`  ${chalk.green("✓")} ${personaName}${traitsNote}`);
+  }
+
+  // Compile always-on instructions.
+  compileInstructions(
+    coreInstructionsDir,
+    config.instructions?.enabled,
+    distPath,
+    "core",
+    config,
+    outputFormats
+  );
+
+  // AB-52: Compile gotchas (path-scoped knowledge rules)
+  const coreGotchasDir = path.join(coreDir, "gotchas");
+  compileGotchas(coreGotchasDir, distPath, "core", config, outputFormats);
+
+  // AB-19/26/27: Claude-specific output (CLAUDE.md, settings.json, .mcp.json)
+  if (outputFormats.includes("claude")) {
+    // Collect instruction file names for @import directives
+    const instrFileNames: string[] = [];
+    if (fs.existsSync(coreInstructionsDir)) {
+      const instrFiles = fs.readdirSync(coreInstructionsDir).filter((f) => f.endsWith(".md"));
+      for (const file of instrFiles) {
+        const name = path.basename(file, ".md");
+        if (!config.instructions?.enabled || config.instructions.enabled.includes(name)) {
+          instrFileNames.push(name);
+        }
+      }
+    }
+
+    // Collect persona configs for welcome fragment (AB-77)
+    const personaConfigs = new Map<string, PersonaConfig>();
+    for (const [personaName, personaDir] of personaDirs) {
+      if (enabledPersonas && !enabledPersonas.includes(personaName)) continue;
+      const pc = loadPersonaConfig(personaDir);
+      if (pc) personaConfigs.set(personaName, pc);
+    }
+
+    generateClaudeMd(
+      [...traits.keys()],
+      traits,
+      instrFileNames,
+      config,
+      distPath,
+      "core",
+      personaConfigs
+    );
+
+    generateSettingsJson(config, distPath, "core");
+    generateMcpJson(config, distPath, "core");
+  }
+
+  // ---------------------------------------------------------------------------
+  // 2. Compile group-level overrides → dist/{platform}/groups/{group}/{persona}/
+  // ---------------------------------------------------------------------------
+
+  if (config.groups) {
+    log(chalk.cyan("\nCompiling group-level personas..."));
+
+    for (const groupName of Object.keys(config.groups)) {
+      const groupPersonasDir = path.join(ROOT, "groups", groupName, "personas");
+
+      if (!fs.existsSync(groupPersonasDir)) {
+        continue;
+      }
+
+      const groupPersonaDirs = fs.readdirSync(groupPersonasDir).filter((entry) =>
+        fs.statSync(path.join(groupPersonasDir, entry)).isDirectory()
+      );
+
+      for (const personaName of groupPersonaDirs) {
+        if (enabledPersonas && !enabledPersonas.includes(personaName)) {
+          continue;
+        }
+
+        const personaDir = path.join(groupPersonasDir, personaName);
+        const result = compilePersona(
+          personaName,
+          personaDir,
+          traits,
+          config,
+          distPath,
+          `groups/${groupName}`,
+          groupName
+        );
+        allResults.push(result);
+        log(`  ${chalk.green("✓")} ${groupName}/${personaName}`);
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // 3. Compile team-level overrides → dist/{platform}/teams/{group}/{team}/{persona}/
+  // ---------------------------------------------------------------------------
+
+  if (config.groups) {
+    log(chalk.cyan("\nCompiling team-level personas..."));
+    let teamPersonasFound = false;
+
+    for (const groupName of Object.keys(config.groups)) {
+      const teams = config.groups[groupName]!.teams ?? [];
+
+      for (const teamName of teams) {
+        const teamPersonasDir = path.join(ROOT, "teams", groupName, teamName, "personas");
+
+        if (!fs.existsSync(teamPersonasDir)) {
+          continue;
+        }
+
+        teamPersonasFound = true;
+
+        const teamPersonaDirs = fs.readdirSync(teamPersonasDir).filter((entry) =>
+          fs.statSync(path.join(teamPersonasDir, entry)).isDirectory()
+        );
+
+        for (const personaName of teamPersonaDirs) {
+          if (enabledPersonas && !enabledPersonas.includes(personaName)) {
+            continue;
+          }
+
+          const personaDir = path.join(teamPersonasDir, personaName);
+          const result = compilePersona(
+            personaName,
+            personaDir,
+            traits,
+            config,
+            distPath,
+            `teams/${groupName}/${teamName}`,  // scopePath → dist/{platform}/teams/{group}/{team}/{persona}/
+            groupName,
+            teamName
+          );
+          allResults.push(result);
+          log(`  ${chalk.green("✓")} ${groupName}/${teamName}/${personaName}`);
+        }
+      }
+    }
+
+    if (!teamPersonasFound) {
+      log(chalk.gray("  (no team-level overrides found)"));
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // 4. Generate PERSONAS.md index in each platform
+  // ---------------------------------------------------------------------------
+
+  generatePersonasIndex(allResults, config, corePersonasDir, distPath, "core", outputFormats);
+  log(chalk.gray("\n  → PERSONAS.md written to each platform"));
+
+  // ---------------------------------------------------------------------------
+  // 5. AB-25: Token budget estimation
+  // ---------------------------------------------------------------------------
+
+  const tokenBudget = config.output?.tokenBudget?.warnAt ?? 8000;
+  log(chalk.cyan("\nToken estimates:"));
+
+  for (const result of allResults.filter((r) => r.platforms.length > 0)) {
+    const skillPath = path.join(distPath, "skill", "core", result.persona, "SKILL.md");
+    if (fs.existsSync(skillPath)) {
+      const content = fs.readFileSync(skillPath, "utf-8");
+      const estimatedTokens = Math.ceil(content.length / 4);
+
+      if (estimatedTokens > tokenBudget) {
+        log(
+          chalk.yellow(
+            `  ⚠ [${result.persona}] estimated ${estimatedTokens} tokens (budget: ${tokenBudget})`
+          )
+        );
+      } else {
+        log(chalk.gray(`  ${result.persona}: ~${estimatedTokens} tokens`));
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Summary
+  // ---------------------------------------------------------------------------
+
+  const successCount = allResults.filter((r) => r.platforms.length > 0).length;
+  const platformCount = allResults.reduce((acc, r) => acc + r.platforms.length, 0);
+
+  log(
+    chalk.bold(
+      `\n${chalk.green("✓")} Compiled ${successCount} persona(s) × ${outputFormats.length} platform(s) → ${path.relative(ROOT, distPath)}/`
+    )
+  );
+  for (const fmt of outputFormats) {
+    log(chalk.gray(`  → dist/${fmt}/`));
+  }
+}
+
+try {
+  main();
+} catch (err: unknown) {
+  console.error(chalk.red("Unexpected error:"), err);
+  process.exit(1);
+}