@dusky-bluehour/agent-service 0.6.5 → 0.6.7

package/scripts/generate-from-common.mjs

@@ -0,0 +1,872 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+
+const DEFAULT_TOOL_IDS = ['claude-code', 'codex', 'antigravity'];
+const args = new Set(process.argv.slice(2));
+const checkMode = args.has('--check');
+
+function usageAndExit() {
+  console.log('Usage: node scripts/generate-from-common.mjs [--check]');
+  process.exit(1);
+}
+
+if (args.size > 1 || (args.size === 1 && !args.has('--check'))) {
+  usageAndExit();
+}
+
+async function readJson(relativePath) {
+  const fullPath = path.join(rootDir, relativePath);
+  const raw = await fs.readFile(fullPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function toPrettyJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function quoteYamlString(value) {
+  const normalized = String(value ?? '');
+  return `"${normalized.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function normalizeCommandBasename(commandId) {
+  const normalized = String(commandId ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!normalized) {
+    throw new Error(`[commands] command id가 비어 있습니다: ${commandId}`);
+  }
+  return normalized;
+}
+
+function toBulletLines(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return ['- (없음)'];
+  }
+  return values.map((value) => `- ${value}`);
+}
+
+function toNumberedLines(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return ['1. (없음)'];
+  }
+  return values.map((value, index) => `${index + 1}. ${value}`);
+}
+
+function toBashRule(pattern) {
+  return `Bash(${pattern})`;
+}
+
+function toPathRule(kind, pattern) {
+  return `${kind}(${pattern})`;
+}
+
+function renderCodexOpenAiYaml(skill) {
+  const ui = skill.codex_openai ?? {};
+  return [
+    'skill:',
+    `  display_name: ${quoteYamlString(ui.display_name ?? '')}`,
+    `  short_description: ${quoteYamlString(ui.short_description ?? '')}`,
+    `  default_prompt: ${quoteYamlString(ui.default_prompt ?? '')}`,
+    ''
+  ].join('\n');
+}
+
+function renderSkillMarkdown(skill, toolId) {
+  const name = skill.names?.[toolId] ?? skill.id;
+  const description = skill.descriptions?.[toolId];
+  const procedure = skill.procedures?.[toolId];
+  const qualityRules = skill.quality_rules?.[toolId];
+  const inputChecklist = skill.input_checklist;
+  const reportFormat = skill.report_format;
+  const stopConditions = skill.stop_conditions;
+
+  if (typeof description !== 'string' || !Array.isArray(procedure) || !Array.isArray(qualityRules)) {
+    throw new Error(`[skills] ${skill.id}(${toolId}) 정의가 불완전합니다.`);
+  }
+  if (!Array.isArray(inputChecklist) || !Array.isArray(reportFormat) || !Array.isArray(stopConditions)) {
+    throw new Error(`[skills] ${skill.id} 공통 체크리스트/리포트/중단조건 정의가 누락되었습니다.`);
+  }
+
+  const procedureLines = procedure.map((step, index) => `${index + 1}. ${step}`);
+  const checklistLines = inputChecklist.map((item) => `- ${item}`);
+  const reportLines = reportFormat.map((item) => `- ${item}`);
+  const stopLines = stopConditions.map((item) => `- ${item}`);
+  const qualityRuleLines = qualityRules.map((rule) => `- ${rule}`);
+
+  return [
+    '---',
+    `name: ${name}`,
+    `description: ${description}`,
+    '---',
+    '',
+    '# 시작 전 체크리스트',
+    '',
+    ...checklistLines,
+    '',
+    '# 실행 절차',
+    '',
+    ...procedureLines,
+    '',
+    '# 결과 보고 형식',
+    '',
+    ...reportLines,
+    '',
+    '# 중단 조건',
+    '',
+    ...stopLines,
+    '',
+    '# 품질 규칙',
+    '',
+    ...qualityRuleLines,
+    ''
+  ].join('\n');
+}
+
+function renderClaudeSubagentMarkdown(subagent) {
+  const tools = Array.isArray(subagent.tools) ? subagent.tools.join(', ') : '';
+  const bodyLines = Array.isArray(subagent.body_lines) ? subagent.body_lines : [];
+  return [
+    '---',
+    `name: ${subagent.name ?? subagent.id}`,
+    `description: ${subagent.description ?? ''}`,
+    `tools: ${tools}`,
+    `model: ${subagent.model ?? 'sonnet'}`,
+    '---',
+    '',
+    ...bodyLines,
+    ''
+  ].join('\n');
+}
+
+function renderYamlList(lines, indent, values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    lines.push(`${indent}[]`);
+    return;
+  }
+  for (const value of values) {
+    lines.push(`${indent}- ${quoteYamlString(value)}`);
+  }
+}
+
+function renderAntigravityWorkflowDefinition(workflow) {
+  const lines = [];
+  lines.push('# generated by scripts/generate-from-common.mjs');
+  lines.push('workflow:');
+  lines.push(`  id: ${quoteYamlString(workflow.id)}`);
+  lines.push(`  name: ${quoteYamlString(workflow.name)}`);
+  lines.push(`  summary: ${quoteYamlString(workflow.summary ?? '')}`);
+  lines.push(`  orchestrator: ${quoteYamlString(workflow.orchestrator ?? '')}`);
+  lines.push(`  when_to_use: ${quoteYamlString(workflow.when_to_use ?? '')}`);
+  lines.push('  stages:');
+
+  for (const stage of workflow.stages ?? []) {
+    lines.push(`    - order: ${Number(stage.order ?? 0)}`);
+    lines.push(`      stage_id: ${quoteYamlString(stage.stage_id ?? '')}`);
+    lines.push(`      agent: ${quoteYamlString(stage.agent ?? '')}`);
+    lines.push('      commands:');
+    renderYamlList(lines, '        ', stage.commands);
+    lines.push(`      input_artifact: ${quoteYamlString(stage.input_artifact ?? '')}`);
+    lines.push(`      output_artifact: ${quoteYamlString(stage.output_artifact ?? '')}`);
+    lines.push('      exit_criteria:');
+    renderYamlList(lines, '        ', stage.exit_criteria);
+  }
+
+  lines.push('  final_outputs:');
+  renderYamlList(lines, '    ', workflow.final_outputs);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderClaudeCommandMarkdown(command) {
+  const requiredInputs = command.input_contract?.required;
+  const optionalInputs = command.input_contract?.optional;
+  const executionSteps = command.execution_contract?.steps;
+  const qualityGates = command.quality_gates;
+  const artifacts = command.output_contract?.artifacts;
+  const nextRoles = command.handoff?.next_roles;
+  const blockers = command.handoff?.blockers;
+
+  return [
+    '---',
+    `description: ${quoteYamlString(`${command.name} (${command.id})`)}`,
+    'argument-hint: "[추가 컨텍스트]"',
+    '---',
+    '',
+    `이 명령은 \`${command.id}\` 계약을 그대로 적용합니다.`,
+    `추가 컨텍스트가 있으면 반영하세요: $ARGUMENTS`,
+    '',
+    '## 목적',
+    '',
+    String(command.purpose ?? ''),
+    '',
+    '## 입력 계약',
+    '',
+    '### 필수 입력',
+    ...toBulletLines(requiredInputs),
+    '',
+    '### 선택 입력',
+    ...toBulletLines(optionalInputs),
+    '',
+    '## 실행 절차',
+    '',
+    ...toNumberedLines(executionSteps),
+    '',
+    '## 품질 게이트',
+    '',
+    ...toBulletLines(qualityGates),
+    '',
+    '## 산출물',
+    '',
+    ...toBulletLines(artifacts),
+    '',
+    '## 핸드오프',
+    '',
+    `- 다음 역할: ${(Array.isArray(nextRoles) && nextRoles.length > 0 ? nextRoles.join(', ') : '(없음)')}`,
+    `- 차단 요인: ${(Array.isArray(blockers) && blockers.length > 0 ? blockers.join(', ') : '(없음)')}`,
+    '',
+    '## 결과 응답 형식',
+    '',
+    '- 실행 요약(무엇을 왜 수행했는지)',
+    '- 입력 검증(충족/누락 항목)',
+    '- 품질 게이트 통과 여부',
+    '- 산출물 및 다음 핸드오프',
+    ''
+  ].join('\n');
+}
+
+function renderAntigravityCommandDefinition(command) {
+  const requiredInputs = command.input_contract?.required;
+  const optionalInputs = command.input_contract?.optional;
+  const executionSteps = command.execution_contract?.steps;
+  const qualityGates = command.quality_gates;
+  const artifacts = command.output_contract?.artifacts;
+  const nextRoles = command.handoff?.next_roles;
+  const blockers = command.handoff?.blockers;
+
+  return [
+    '# generated by scripts/generate-from-common.mjs',
+    '',
+    `# ${command.id} - ${command.name}`,
+    '',
+    `- phase: ${command.phase ?? ''}`,
+    `- owner_role: ${command.owner_role ?? ''}`,
+    '',
+    '## Purpose',
+    '',
+    String(command.purpose ?? ''),
+    '',
+    '## Input Contract',
+    '',
+    '### Required',
+    ...toBulletLines(requiredInputs),
+    '',
+    '### Optional',
+    ...toBulletLines(optionalInputs),
+    '',
+    '## Execution Contract',
+    '',
+    ...toNumberedLines(executionSteps),
+    '',
+    '## Quality Gates',
+    '',
+    ...toBulletLines(qualityGates),
+    '',
+    '## Output Contract',
+    '',
+    ...toBulletLines(artifacts),
+    '',
+    '## Handoff',
+    '',
+    `- next_roles: ${(Array.isArray(nextRoles) && nextRoles.length > 0 ? nextRoles.join(', ') : '(none)')}`,
+    `- blockers: ${(Array.isArray(blockers) && blockers.length > 0 ? blockers.join(', ') : '(none)')}`,
+    ''
+  ].join('\n');
+}
+
+function renderCodexCommandSkillMarkdown(command, skillName) {
+  const requiredInputs = Array.isArray(command.input_contract?.required)
+    ? command.input_contract.required.map((item) => `[필수] ${item}`)
+    : [];
+  const optionalInputs = Array.isArray(command.input_contract?.optional)
+    ? command.input_contract.optional.map((item) => `[선택] ${item}`)
+    : [];
+  const executionSteps = Array.isArray(command.execution_contract?.steps)
+    ? command.execution_contract.steps
+    : [];
+  const qualityGates = Array.isArray(command.quality_gates) ? command.quality_gates : [];
+  const artifacts = Array.isArray(command.output_contract?.artifacts)
+    ? command.output_contract.artifacts
+    : [];
+  const nextRoles = Array.isArray(command.handoff?.next_roles) ? command.handoff.next_roles : [];
+  const blockers = Array.isArray(command.handoff?.blockers) ? command.handoff.blockers : [];
+
+  const checklistLines = toBulletLines([...requiredInputs, ...optionalInputs]);
+  const procedureLines = toNumberedLines([
+    `명령 계약을 확인한다: ${command.id} (${command.name})`,
+    ...executionSteps,
+    '품질 게이트를 검증한다.',
+    '산출물과 핸드오프를 보고한다.'
+  ]);
+  const reportLines = toBulletLines([
+    `실행 명령: ${command.id}`,
+    `입력 검증: 필수 입력 충족 여부 / 누락 항목`,
+    `품질 게이트: ${qualityGates.length > 0 ? qualityGates.join(' | ') : '(없음)'}`,
+    `산출물: ${artifacts.length > 0 ? artifacts.join(', ') : '(없음)'}`,
+    `핸드오프: 다음 역할 ${nextRoles.length > 0 ? nextRoles.join(', ') : '(없음)'}`
+  ]);
+  const stopLines = toBulletLines([
+    '필수 입력이 누락된 경우',
+    '품질 게이트를 충족하지 못한 경우',
+    ...blockers
+  ]);
+  const qualityRuleLines = toBulletLines([
+    '검증되지 않은 추정은 사실과 분리해서 기록한다.',
+    '품질 게이트를 우회하지 않는다.',
+    ...qualityGates
+  ]);
+
+  return [
+    '---',
+    `name: ${skillName}`,
+    `description: ${command.name} 명령 계약을 Codex 스킬 형태로 실행한다.`,
+    '---',
+    '',
+    '# 시작 전 체크리스트',
+    '',
+    ...checklistLines,
+    '',
+    '# 실행 절차',
+    '',
+    ...procedureLines,
+    '',
+    '# 결과 보고 형식',
+    '',
+    ...reportLines,
+    '',
+    '# 중단 조건',
+    '',
+    ...stopLines,
+    '',
+    '# 품질 규칙',
+    '',
+    ...qualityRuleLines,
+    ''
+  ].join('\n');
+}
+
+function renderCodexCommandOpenAiYaml(command) {
+  return [
+    'skill:',
+    `  display_name: ${quoteYamlString(command.name ?? command.id)}`,
+    `  short_description: ${quoteYamlString(`${command.phase ?? ''} · ${command.owner_role ?? ''}`)}`,
+    `  default_prompt: ${quoteYamlString(`${command.id} 명령 계약을 준수해 실행해줘.`)}`,
+    ''
+  ].join('\n');
+}
+
+function buildClaudePermissionsFromSecurityPolicy(securityPolicy, includeLocalOverrides = false) {
+  const shared = securityPolicy.shared_permissions ?? {};
+  const claude = securityPolicy.claude_code ?? {};
+
+  const allow = [];
+  const ask = [];
+  const deny = [];
+
+  if (shared.read_all) {
+    allow.push('Read');
+  }
+  if (shared.edit_all) {
+    allow.push('Edit');
+  }
+
+  for (const pattern of shared.allow_bash ?? []) {
+    allow.push(toBashRule(pattern));
+  }
+  for (const pattern of shared.ask_bash ?? []) {
+    ask.push(toBashRule(pattern));
+  }
+  for (const pattern of shared.deny_bash ?? []) {
+    deny.push(toBashRule(pattern));
+  }
+  for (const pattern of shared.deny_read ?? []) {
+    deny.push(toPathRule('Read', pattern));
+  }
+  for (const pattern of shared.deny_edit ?? []) {
+    deny.push(toPathRule('Edit', pattern));
+  }
+
+  if (includeLocalOverrides) {
+    for (const pattern of claude.local_overrides?.ask_bash ?? []) {
+      ask.push(toBashRule(pattern));
+    }
+  }
+
+  return {
+    defaultMode: claude.default_mode ?? 'acceptEdits',
+    disableBypassPermissionsMode: claude.disable_bypass_permissions_mode ?? 'disable',
+    additionalDirectories: includeLocalOverrides
+      ? (claude.local_overrides?.additional_directories ?? [])
+      : (claude.additional_directories ?? []),
+    allow: [...new Set(allow)],
+    ask: [...new Set(ask)],
+    deny: [...new Set(deny)]
+  };
+}
+
+function renderClaudeProjectSettingsJson(securityPolicy) {
+  return {
+    $schema: 'https://json.schemastore.org/claude-code-settings.json',
+    permissions: buildClaudePermissionsFromSecurityPolicy(securityPolicy, false),
+    enabledPlugins: securityPolicy.claude_code?.enabled_plugins ?? {}
+  };
+}
+
+function renderClaudeLocalSettingsJson(securityPolicy) {
+  const claude = securityPolicy.claude_code ?? {};
+  return {
+    $schema: 'https://json.schemastore.org/claude-code-settings.json',
+    permissions: {
+      additionalDirectories: claude.local_overrides?.additional_directories ?? [],
+      ask: [...new Set((claude.local_overrides?.ask_bash ?? []).map((pattern) => toBashRule(pattern)))]
+    }
+  };
+}
+
+function renderAntigravityEditorPolicyJson(securityPolicy) {
+  const shared = securityPolicy.shared_permissions ?? {};
+  return {
+    schema_version: '1.0.0',
+    policy_id: securityPolicy.policy_id ?? 'strict-dev',
+    description_ko:
+      'Antigravity Editor에서 수동 반영할 수 있는 프로젝트 보안/권한 정책 템플릿',
+    editor: securityPolicy.antigravity?.editor_settings ?? {},
+    command_policy: {
+      allow_shell: shared.allow_bash ?? [],
+      ask_shell: shared.ask_bash ?? [],
+      deny_shell: shared.deny_bash ?? []
+    },
+    path_policy: {
+      deny_read: shared.deny_read ?? [],
+      deny_edit: shared.deny_edit ?? []
+    }
+  };
+}
+
+function renderCodexRuntimePolicyJson(securityPolicy) {
+  const shared = securityPolicy.shared_permissions ?? {};
+  return {
+    schema_version: '1.0.0',
+    policy_id: securityPolicy.policy_id ?? 'strict-dev',
+    description_ko:
+      'Codex 프로젝트 규칙(AGENTS.md)과 함께 사용하는 런타임 권한 정책 템플릿',
+    runtime: securityPolicy.codex?.runtime_policy ?? {},
+    command_policy: {
+      allow_shell: shared.allow_bash ?? [],
+      ask_shell: shared.ask_bash ?? [],
+      deny_shell: shared.deny_bash ?? []
+    },
+    path_policy: {
+      deny_read: shared.deny_read ?? [],
+      deny_edit: shared.deny_edit ?? []
+    }
+  };
+}
+
+function renderCodexPermissionsMarkdown(securityPolicy) {
+  const shared = securityPolicy.shared_permissions ?? {};
+  const runtime = securityPolicy.codex?.runtime_policy ?? {};
+  const allowShell = shared.allow_bash ?? [];
+  const askShell = shared.ask_bash ?? [];
+  const denyShell = shared.deny_bash ?? [];
+
+  return [
+    '# Codex 권한 정책 템플릿',
+    '',
+    '이 문서는 `common/settings/security-policy.json`에서 자동 생성됩니다.',
+    '`AGENTS.md`의 프로젝트 규칙 섹션에 붙여 넣어 팀 기본 정책으로 사용하세요.',
+    '',
+    '## 런타임 정책',
+    '',
+    ...toBulletLines([
+      `sandbox_mode: ${runtime.sandbox_mode ?? 'workspace-write'}`,
+      `network_access: ${runtime.network_access ?? 'restricted'}`,
+      `git_write_actions: ${runtime.git_write_actions ?? 'ask'}`,
+      `destructive_shell: ${runtime.destructive_shell ?? 'deny'}`,
+      `global_package_installs: ${runtime.global_package_installs ?? 'deny'}`
+    ]),
+    '',
+    '## Shell 허용 규칙',
+    '',
+    ...toBulletLines(allowShell.map((rule) => `\`${rule}\``)),
+    '',
+    '## Shell 확인(ask) 규칙',
+    '',
+    ...toBulletLines(askShell.map((rule) => `\`${rule}\``)),
+    '',
+    '## Shell 차단 규칙',
+    '',
+    ...toBulletLines(denyShell.map((rule) => `\`${rule}\``)),
+    ''
+  ].join('\n');
+}
+
+function buildWorkflowCatalogByTool(commonWorkflowCatalog) {
+  const toolIds = Array.isArray(commonWorkflowCatalog.tools)
+    ? commonWorkflowCatalog.tools
+    : DEFAULT_TOOL_IDS;
+  const validToolSet = new Set(toolIds);
+
+  const workflowById = new Map();
+  for (const workflow of commonWorkflowCatalog.workflows ?? []) {
+    if (!workflow?.id || typeof workflow.id !== 'string') {
+      throw new Error('[workflows] workflow id가 비어 있습니다.');
+    }
+    if (workflowById.has(workflow.id)) {
+      throw new Error(`[workflows] workflow id 중복: ${workflow.id}`);
+    }
+    workflowById.set(workflow.id, workflow);
+  }
+
+  const catalogs = {};
+  for (const toolId of toolIds) {
+    const workflowPolicy = commonWorkflowCatalog.workflow_policy?.[toolId] ?? {};
+    const order = Array.isArray(commonWorkflowCatalog.workflow_order?.[toolId])
+      ? commonWorkflowCatalog.workflow_order[toolId]
+      : [];
+
+    const orderedIds = [];
+    const seen = new Set();
+    for (const workflowId of order) {
+      if (!workflowById.has(workflowId)) {
+        throw new Error(`[workflows] ${toolId} workflow_order가 없는 workflow를 참조합니다: ${workflowId}`);
+      }
+      const profile = workflowById.get(workflowId).profiles?.[toolId];
+      if (!profile) {
+        throw new Error(`[workflows] ${toolId} profile 누락: ${workflowId}`);
+      }
+      if (seen.has(workflowId)) {
+        throw new Error(`[workflows] ${toolId} workflow_order 중복: ${workflowId}`);
+      }
+      seen.add(workflowId);
+      orderedIds.push(workflowId);
+    }
+
+    for (const workflow of commonWorkflowCatalog.workflows ?? []) {
+      const profile = workflow.profiles?.[toolId];
+      if (!profile) continue;
+      if (seen.has(workflow.id)) continue;
+      seen.add(workflow.id);
+      orderedIds.push(workflow.id);
+    }
+
+    const workflows = orderedIds.map((workflowId) => {
+      const workflow = workflowById.get(workflowId);
+      const profile = workflow.profiles?.[toolId];
+      if (!profile) {
+        throw new Error(`[workflows] ${toolId} profile 누락: ${workflowId}`);
+      }
+      return {
+        id: workflowId,
+        ...profile
+      };
+    });
+
+    catalogs[toolId] = {
+      schema_version: '1.0.0',
+      workflow_policy: workflowPolicy,
+      workflows
+    };
+  }
+
+  for (const workflow of commonWorkflowCatalog.workflows ?? []) {
+    const profileTools = Object.keys(workflow.profiles ?? {});
+    for (const toolId of profileTools) {
+      if (!validToolSet.has(toolId)) {
+        throw new Error(`[workflows] workflow(${workflow.id})에 알 수 없는 tool profile이 있습니다: ${toolId}`);
+      }
+    }
+  }
+
+  return { toolIds, catalogs };
+}
+
+async function ensureDir(filePath) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function readIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeOrCheck(filePath, expected, state) {
+  const current = await readIfExists(filePath);
+
+  if (checkMode) {
+    if (current !== expected) {
+      state.outOfDate.push(path.relative(rootDir, filePath));
+    }
+    return;
+  }
+
+  if (current === expected) {
+    state.unchanged += 1;
+    return;
+  }
+
+  await ensureDir(filePath);
+  await fs.writeFile(filePath, expected, 'utf8');
+  state.written += 1;
+}
+
+async function pruneGeneratedFilesBySuffix(dir, suffix, expectedFileNames, state) {
+  await fs.mkdir(dir, { recursive: true });
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(suffix)) {
+      continue;
+    }
+    if (expectedFileNames.has(entry.name)) {
+      continue;
+    }
+    const removePath = path.join(dir, entry.name);
+    if (checkMode) {
+      state.outOfDate.push(path.relative(rootDir, removePath));
+      continue;
+    }
+    await fs.unlink(removePath);
+    state.deleted += 1;
+  }
+}
+
+async function pruneCodexCommandSkills(expectedDirNames, state) {
+  const dir = path.join(rootDir, 'codex', 'skills');
+  await fs.mkdir(dir, { recursive: true });
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^cmd-[a-z0-9-]+$/.test(entry.name)) {
+      continue;
+    }
+    if (expectedDirNames.has(entry.name)) {
+      continue;
+    }
+
+    const removePath = path.join(dir, entry.name);
+    if (checkMode) {
+      state.outOfDate.push(path.relative(rootDir, removePath));
+      continue;
+    }
+    await fs.rm(removePath, { recursive: true, force: true });
+    state.deleted += 1;
+  }
+}
+
+async function main() {
+  const commands = await readJson('common/commands/command-catalog.json');
+  const commonWorkflowCatalog = await readJson('common/workflows/workflow-catalog.json');
+  const skillCatalog = await readJson('common/skills/skill-catalog.json');
+  const securityPolicy = await readJson('common/settings/security-policy.json');
+  const claudeSubagents = await readJson('common/claude/subagent-catalog.json');
+  const claudeTeams = await readJson('common/claude/team-catalog.json');
+  const antigravityAgents = await readJson('common/antigravity/agent-catalog.json');
+  const antigravityArtifacts = await readJson('common/antigravity/artifact-catalog.json');
+  const { toolIds, catalogs: workflowCatalogByTool } = buildWorkflowCatalogByTool(
+    commonWorkflowCatalog
+  );
+
+  const state = {
+    written: 0,
+    unchanged: 0,
+    deleted: 0,
+    outOfDate: []
+  };
+
+  for (const toolId of toolIds) {
+    const commandPath = path.join(rootDir, toolId, 'commands', 'command-catalog.json');
+    await writeOrCheck(commandPath, toPrettyJson(commands), state);
+  }
+
+  await writeOrCheck(
+    path.join(rootDir, 'claude-code', 'settings', 'settings.json'),
+    toPrettyJson(renderClaudeProjectSettingsJson(securityPolicy)),
+    state
+  );
+  await writeOrCheck(
+    path.join(rootDir, 'claude-code', 'settings', 'settings.local.json'),
+    toPrettyJson(renderClaudeLocalSettingsJson(securityPolicy)),
+    state
+  );
+  await writeOrCheck(
+    path.join(rootDir, 'antigravity', 'settings', 'editor-policy.json'),
+    toPrettyJson(renderAntigravityEditorPolicyJson(securityPolicy)),
+    state
+  );
+  await writeOrCheck(
+    path.join(rootDir, 'codex', 'settings', 'runtime-policy.json'),
+    toPrettyJson(renderCodexRuntimePolicyJson(securityPolicy)),
+    state
+  );
+  await writeOrCheck(
+    path.join(rootDir, 'codex', 'instructions', 'AGENTS.permissions.generated.md'),
+    renderCodexPermissionsMarkdown(securityPolicy),
+    state
+  );
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'claude-code', 'settings'),
+    '.json',
+    new Set(['settings.json', 'settings.local.json']),
+    state
+  );
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'antigravity', 'settings'),
+    '.json',
+    new Set(['editor-policy.json']),
+    state
+  );
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'codex', 'settings'),
+    '.json',
+    new Set(['runtime-policy.json']),
+    state
+  );
+
+  const commandFileNames = new Set();
+  const codexCommandSkillNames = new Set();
+  for (const command of commands.commands ?? []) {
+    if (!command?.id) {
+      throw new Error('[commands] command id가 비어 있습니다.');
+    }
+    const basename = normalizeCommandBasename(command.id);
+    commandFileNames.add(`${basename}.md`);
+    codexCommandSkillNames.add(basename);
+
+    await writeOrCheck(
+      path.join(rootDir, 'claude-code', 'commands', 'native', `${basename}.md`),
+      renderClaudeCommandMarkdown(command),
+      state
+    );
+    await writeOrCheck(
+      path.join(rootDir, 'antigravity', 'commands', 'definitions', `${basename}.md`),
+      renderAntigravityCommandDefinition(command),
+      state
+    );
+    await writeOrCheck(
+      path.join(rootDir, 'codex', 'skills', basename, 'SKILL.md'),
+      renderCodexCommandSkillMarkdown(command, basename),
+      state
+    );
+    await writeOrCheck(
+      path.join(rootDir, 'codex', 'skills', basename, 'agents', 'openai.yaml'),
+      renderCodexCommandOpenAiYaml(command),
+      state
+    );
+  }
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'claude-code', 'commands', 'native'),
+    '.md',
+    commandFileNames,
+    state
+  );
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'antigravity', 'commands', 'definitions'),
+    '.md',
+    commandFileNames,
+    state
+  );
+  await pruneCodexCommandSkills(codexCommandSkillNames, state);
+
+  for (const toolId of toolIds) {
+    const catalog = workflowCatalogByTool?.[toolId];
+    if (!catalog) {
+      throw new Error(`[workflows] tool 누락: ${toolId}`);
+    }
+    const workflowPath = path.join(rootDir, toolId, 'workflows', 'workflow-catalog.json');
+    await writeOrCheck(workflowPath, toPrettyJson(catalog), state);
+  }
+
+  const antigravityWorkflowNames = new Set();
+  for (const workflow of workflowCatalogByTool.antigravity?.workflows ?? []) {
+    const filename = `${workflow.id}.workflow.yaml`;
+    antigravityWorkflowNames.add(filename);
+    const definitionPath = path.join(rootDir, 'antigravity', 'workflows', 'definitions', filename);
+    await writeOrCheck(definitionPath, renderAntigravityWorkflowDefinition(workflow), state);
+  }
+  await pruneGeneratedFilesBySuffix(
+    path.join(rootDir, 'antigravity', 'workflows', 'definitions'),
+    '.workflow.yaml',
+    antigravityWorkflowNames,
+    state
+  );
+
+  for (const skill of skillCatalog.skills ?? []) {
+    for (const toolId of toolIds) {
+      const skillPath = path.join(rootDir, toolId, 'skills', skill.id, 'SKILL.md');
+      await writeOrCheck(skillPath, renderSkillMarkdown(skill, toolId), state);
+    }
+
+    const codexYamlPath = path.join(rootDir, 'codex', 'skills', skill.id, 'agents', 'openai.yaml');
+    await writeOrCheck(codexYamlPath, renderCodexOpenAiYaml(skill), state);
+  }
+
+  for (const subagent of claudeSubagents.subagents ?? []) {
+    const subagentPath = path.join(rootDir, 'claude-code', 'subagents', `${subagent.id}.md`);
+    await writeOrCheck(subagentPath, renderClaudeSubagentMarkdown(subagent), state);
+  }
+
+  await writeOrCheck(
+    path.join(rootDir, 'claude-code', 'agent-teams', 'team-catalog.json'),
+    toPrettyJson(claudeTeams),
+    state
+  );
+
+  await writeOrCheck(
+    path.join(rootDir, 'antigravity', 'agents', 'agent-catalog.json'),
+    toPrettyJson(antigravityAgents),
+    state
+  );
+
+  await writeOrCheck(
+    path.join(rootDir, 'antigravity', 'artifacts', 'artifact-catalog.json'),
+    toPrettyJson(antigravityArtifacts),
+    state
+  );
+
+  if (checkMode) {
+    if (state.outOfDate.length > 0) {
+      console.error('Generated files are out of date:');
+      for (const relPath of [...new Set(state.outOfDate)].sort()) {
+        console.error(`- ${relPath}`);
+      }
+      process.exit(1);
+    }
+    console.log('All generated files are up to date.');
+    return;
+  }
+
+  console.log(
+    `Generation complete. written=${state.written}, unchanged=${state.unchanged}, deleted=${state.deleted}`
+  );
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});