@dusky-bluehour/agent-service 0.6.4 → 0.6.6

package/package.json

@@ -1,27 +1,30 @@
 {
   "name": "@dusky-bluehour/agent-service",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "publishConfig": {
     "access": "public"
   },
   "description": "Service operation skills/workflows pack for Claude Code, Antigravity, and Codex",
   "type": "module",
   "bin": {
-    "tri-agent-manager": "scripts/init.mjs",
-    "tri-agent-os": "scripts/init.mjs"
+    "tri-agent-manager": "scripts/init.mjs"
   },
   "scripts": {
-    "validate": "node scripts/validate.mjs",
+    "generate": "node scripts/generate-from-common.mjs",
+    "generate:check": "node scripts/generate-from-common.mjs --check",
+    "validate": "npm run generate:check && node scripts/validate.mjs",
     "pack:dry-run": "npm_config_cache=.npm-cache npm pack --dry-run",
     "prepublish:check": "npm run validate && npm run pack:dry-run",
     "prepublishOnly": "npm run prepublish:check"
   },
   "files": [
+    "common",
     "claude-code",
     "antigravity",
     "codex",
     "catalog/tool-catalog.ko.json",
     "scripts/init.mjs",
+    "scripts/generate-from-common.mjs",
     "scripts/validate.mjs",
     "README.md",
     "LICENSE"

package/scripts/generate-from-common.mjs

@@ -0,0 +1,387 @@
+#!/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 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 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 pruneAntigravityWorkflowDefinitions(expectedFileNames, state) {
+  const dir = path.join(rootDir, 'antigravity', 'workflows', 'definitions');
+  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('.workflow.yaml')) {
+      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 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 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);
+  }
+
+  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 pruneAntigravityWorkflowDefinitions(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);
+});

package/scripts/init.mjs

@@ -13,7 +13,6 @@ const rootDir = path.resolve(__dirname, '..');
 const catalogPath = path.join(rootDir, 'catalog', 'tool-catalog.ko.json');
 const packageJsonPath = path.join(rootDir, 'package.json');
 const CLI_NAME = 'tri-agent-manager';
-const CLI_COMPAT_NAME = 'tri-agent-os';
 const STATE_DIR_NAME = '.tri-agent-manager';
 const LEGACY_STATE_DIR_NAME = '.tri-agent-os';
 const GUIDE_FILE_NAME = 'USAGE.ko.md';
@@ -42,14 +41,11 @@ const HELP_TEXT = [
   '  --non-interactive 비대화형 모드 강제',
   '  (중복 선택 입력은 자동으로 1회로 정리됨)',
   '',
-  '호환 별칭:',
-  `  ${CLI_COMPAT_NAME} ... (동일 동작)`,
-  '',
   'pnpm 예시:',
-  '  pnpm dlx tri-agent-manager --interactive',
-  '  pnpm dlx tri-agent-manager update --interactive',
-  '  pnpm dlx tri-agent-manager setup',
-  `  pnpm exec ${CLI_NAME} list`
+  '  pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive',
+  '  pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager update --interactive',
+  '  pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager setup',
+  '  pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager list'
 ].join('\n');
 
 function parseArgs(argv) {
@@ -439,6 +435,11 @@ function getToolExecutionGuide(tool, installRoot) {
         'workflows',
         'workflow-catalog.json'
       )}\`에서 workflow ID를 선택합니다.`,
+      `선택한 workflow ID와 같은 이름의 정의 파일을 \`${path.join(
+        installRoot,
+        'workflows',
+        'definitions'
+      )}\`에서 확인합니다.`,
       `각 stage의 \`input_artifact\`를 \`${path.join(
         installRoot,
         'artifacts'
@@ -450,6 +451,57 @@ function getToolExecutionGuide(tool, installRoot) {
   return ['선택한 workflow의 stage.commands를 순서대로 실행합니다.'];
 }
 
+function getToolInteractionTips(tool, installRoot) {
+  if (tool.id === 'codex') {
+    return [
+      'Codex 대화 입력창에서 `$`를 누르면 사용 가능한 스킬 목록을 바로 열 수 있습니다.',
+      `프로젝트 루트에서 스킬 파일을 직접 확인하려면 \`ls ${path.join(
+        installRoot,
+        'skills'
+      )}\` 를 실행하세요.`,
+      `워크플로우 목록과 설명은 \`${path.join(
+        installRoot,
+        'workflows',
+        'workflow-catalog.json'
+      )}\` 에서 확인하세요.`
+    ];
+  }
+
+  if (tool.id === 'claude-code') {
+    return [
+      `서브에이전트 이름은 \`${path.join(installRoot, 'agents')}\` 경로의 파일명 기준입니다.`,
+      `프로젝트 루트에서 \`ls ${path.join(
+        installRoot,
+        'agents'
+      )} | sed 's/\\.md$//'\` 로 서브에이전트 이름을 확인하세요.`,
+      `Claude 스킬 목록은 \`ls ${path.join(installRoot, 'skills')}\` 로 확인하세요.`
+    ];
+  }
+
+  if (tool.id === 'antigravity') {
+    return [
+      `워크플로우 선택은 \`${path.join(
+        installRoot,
+        'workflows',
+        'workflow-catalog.json'
+      )}\` 에서 WF ID를 먼저 고르는 방식으로 진행하세요.`,
+      `실행용 정의 파일은 \`${path.join(
+        installRoot,
+        'workflows',
+        'definitions'
+      )}\` 의 \`*.workflow.yaml\`을 사용하세요.`,
+      `에이전트 역할은 \`${path.join(installRoot, 'agents', 'agent-catalog.json')}\` 에서 확인하세요.`,
+      `입출력 아티팩트 스키마는 \`${path.join(
+        installRoot,
+        'artifacts',
+        'artifact-catalog.json'
+      )}\` 기준으로 맞추세요.`
+    ];
+  }
+
+  return ['도구별 workflow 문서와 skill 문서를 기준으로 실행 순서를 고정하세요.'];
+}
+
 function renderMarkdownTable(headers, rows) {
   const head = `| ${headers.join(' | ')} |`;
   const divider = `| ${headers.map(() => '---').join(' | ')} |`;
@@ -508,6 +560,14 @@ async function writeUsageGuide({ catalog, selection, targetDir, mode }) {
       lines.push(`${index + 1}. ${step}`);
     });
 
+    lines.push('');
+    lines.push('### 도구별 실행 팁');
+    lines.push('아래 팁은 프로젝트 루트에서 바로 확인할 수 있는 방법입니다.');
+    const interactionTips = getToolInteractionTips(tool, installRoot);
+    interactionTips.forEach((tip, index) => {
+      lines.push(`${index + 1}. ${tip}`);
+    });
+
     if (workflowSummary.length > 0) {
       lines.push('');
       lines.push('### 워크플로우 선택 가이드');
@@ -1305,6 +1365,15 @@ async function writeState({ catalog, targetDir, packageData, mode, selection })
   await fs.writeFile(statePath, `${JSON.stringify(statePayload, null, 2)}\n`, 'utf8');
 }
 
+async function cleanupLegacyStateDir(targetDir) {
+  const legacyDir = path.join(targetDir, LEGACY_STATE_DIR_NAME);
+  if (!(await exists(legacyDir))) {
+    return false;
+  }
+  await fs.rm(legacyDir, { recursive: true, force: true });
+  return true;
+}
+
 async function runInstallOrUpdate({ catalog, packageData, mode, selection, force, dryRun }) {
   const overwrite = mode === 'update' || force;
   const targetDir = selection.targetDir;
@@ -1397,9 +1466,13 @@ async function runInstallOrUpdate({ catalog, packageData, mode, selection, force
   if (!dryRun) {
     const generatedGuidePath = await writeUsageGuide({ catalog, selection, targetDir, mode });
     await writeState({ catalog, targetDir, packageData, mode, selection });
+    const legacyStateRemoved = await cleanupLegacyStateDir(targetDir);
     console.log('');
     console.log(`실행 가이드 저장: ${generatedGuidePath}`);
     console.log(`상태 파일 저장: ${path.join(targetDir, STATE_DIR_NAME, 'state.json')}`);
+    if (legacyStateRemoved) {
+      console.log(`레거시 상태 폴더 정리: ${path.join(targetDir, LEGACY_STATE_DIR_NAME)}`);
+    }
   }
 }