@dusky-bluehour/agent-service 0.6.3 → 0.6.5

package/README.md

@@ -1,251 +1,47 @@
 # tri-agent-manager
 
-Claude Code, Antigravity, Codex에서 공통으로 사용하실 수 있는 서비스 운영형 스킬/워크플로우 패키지입니다.
-
-## 목적
-
-- 기획(PRD) → 설계 → 개발 → 코드리뷰/보안 → 배포/운영까지 동일한 품질 기준으로 실행하실 수 있습니다.
-- 반복 작업(UI 컴포넌트화, Hook 분리, 최적화)을 역할/명령 단위로 고정해 일관성을 높입니다.
-- 툴이 달라도 동일한 계약(명령 ID, 품질 게이트, 워크플로우)으로 결과를 맞출 수 있습니다.
-
-## 용어 설명
-
-| 용어 | 의미 |
-| --- | --- |
-| Skill | 작업 방식/규칙을 담은 실행 단위입니다. 툴마다 포맷은 다르지만 역할은 같습니다. |
-| Workflow | 단계형 실행 시나리오입니다. 각 단계는 진입/종료 조건을 가집니다. |
-| Command Contract | 입력/실행/품질게이트/산출물을 고정한 명령 계약입니다. |
-| Agent / Subagent | 역할별 실행 주체입니다. 리드가 전문 역할에 위임할 수 있습니다. |
-| Artifact (Antigravity) | 단계 입출력 계약 문서입니다. 스키마 검증 통과 후 다음 단계로 진행합니다. |
-| PRD→구현 파이프라인 | PRD는 대화형으로 작성하고, 구현은 최종 수동 세팅 전까지 순차 자동 실행합니다. |
-
-## 핵심 기능
-
-| 기능 | 설명 | 관련 워크플로우 |
-| --- | --- | --- |
-| 표준 E2E 딜리버리 | 기획부터 배포 준비까지 표준 단계를 실행합니다. | `WF-SVC-001` |
-| 코드리뷰/개선 루프 | 리뷰 지적 → 수정 → 재검증 루프를 수행합니다. | `WF-SVC-003` / `WF-SVC-002` |
-| 보안 하드닝 | 위협 모델링 + 취약점 감사 + 재검증을 수행합니다. | `WF-SVC-004` / `WF-SVC-003` |
-| 반복 프론트 개선 | 컴포넌트화, Hook 분리, 성능 최적화를 진행합니다. | `WF-SVC-006` / `WF-SVC-002` |
-| 장애 대응 | 복구, RCA, 재발 방지를 수행합니다. | `WF-SVC-007` / `WF-SVC-005` |
-| PRD→구현 자동 파이프라인 | PRD 대화형 작성 후 구현을 자동 순차 실행합니다. | `WF-PRD-IMPLEMENT-E2E` |
-
-## 목록 (토글)
-
-<details>
-<summary><strong>Claude Code - Skills</strong></summary>
-
-| Skill | 목적 |
-| --- | --- |
-| `service-lifecycle-orchestration` | 기획~배포 전체 수명주기를 실행합니다. |
-| `code-review-and-improvement` | 리뷰/개선 루프를 실행합니다. |
-| `security-hardening` | 위협/취약점 기반 보안 강화를 수행합니다. |
-| `frontend-repetition-pack` | UI 컴포넌트화/Hook/최적화를 수행합니다. |
-| `release-and-operations` | 배포/모니터링/인수인계를 수행합니다. |
-| `incident-response` | 장애 대응~재발 방지를 수행합니다. |
-| `prd-to-production-pipeline` | PRD 대화형 작성 후 순차 자동 구현을 수행합니다. |
-
-</details>
-
-<details>
-<summary><strong>Claude Code - Subagents</strong></summary>
-
-| Subagent | 역할 |
-| --- | --- |
-| `lead-orchestrator` | 전체 단계를 오케스트레이션합니다. |
-| `prd-writer` | 마스터/세부 PRD를 작성합니다. |
-| `product-planner` | 요구사항 잠금/범위 관리를 수행합니다. |
-| `solution-architect` | ADR/기술 경계를 정의합니다. |
-| `backend-engineer` | 계약 우선 API 구현을 수행합니다. |
-| `frontend-engineer` | 프론트 기능 구현을 수행합니다. |
-| `ui-component-engineer` | 반복 UI를 컴포넌트화합니다. |
-| `hook-refactor-engineer` | Hook 분리/정규화를 수행합니다. |
-| `performance-engineer` | 성능 병목을 개선합니다. |
-| `qa-engineer` | 테스트/회귀 차단을 수행합니다. |
-| `code-reviewer` | 코드리뷰/개선안을 도출합니다. |
-| `security-engineer` | 위협/취약점 대응을 수행합니다. |
-| `sre-release-engineer` | CI/CD 게이트/배포를 수행합니다. |
-| `operations-owner` | 운영 대시보드/런북을 관리합니다. |
-| `incident-commander` | 장애 워룸/복구 우선순위를 관리합니다. |
-
-</details>
-
-<details>
-<summary><strong>Antigravity - Skills / Agents</strong></summary>
-
-| 타입 | ID | 설명 |
-| --- | --- | --- |
-| Skill | `service-lifecycle-orchestration` | Plan-Implement-Test-Review-Release를 실행합니다. |
-| Skill | `code-review-and-improvement` | 리뷰/개선 루프를 실행합니다. |
-| Skill | `security-hardening` | 보안 하드닝을 수행합니다. |
-| Skill | `frontend-repetition-pack` | 프론트 반복 개선을 수행합니다. |
-| Skill | `release-and-operations` | 배포/운영 전환을 수행합니다. |
-| Skill | `incident-response` | 장애 대응을 수행합니다. |
-| Skill | `prd-to-production-pipeline` | PRD 대화형→자동 구현을 수행합니다. |
-| Agent | `manager-agent` | 기본 오케스트레이터 역할을 수행합니다. |
-| Agent | `prd-writer-agent` | PRD 대화형 작성을 수행합니다. |
-| Agent | `implementation-agent` | 구현 자동 실행을 수행합니다. |
-| Agent | `review-security-agent` | 리뷰/보안 검증을 수행합니다. |
-| Agent | `release-ops-agent` | 최종 세팅/배포를 수행합니다. |
-
-</details>
-
-<details>
-<summary><strong>Codex - Skills</strong></summary>
-
-| Skill | 목적 |
-| --- | --- |
-| `service-lifecycle-orchestration` | 기획~배포 표준 실행을 수행합니다. |
-| `code-review-and-improvement` | 리뷰/개선 루프를 수행합니다. |
-| `security-hardening` | 보안 강화를 수행합니다. |
-| `frontend-repetition-pack` | UI/Hook/성능 개선을 수행합니다. |
-| `release-and-operations` | 릴리즈/운영 전환을 수행합니다. |
-| `incident-response` | 장애 대응을 수행합니다. |
-| `prd-to-production-pipeline` | PRD 대화형→순차 자동 구현을 수행합니다. |
-
-</details>
-
-## PRD→구현 자동 파이프라인 (신규)
-
-- 워크플로우: `WF-PRD-IMPLEMENT-E2E`
-- 단계:
-  1. 마스터 PRD 작성 (`CMD-PLAN-PRD-MASTER`) - 대화형
-  2. 세부 PRD 분해 (`CMD-PLAN-PRD-DETAILS`) - 대화형
-  3. 구현 부트스트랩 (`CMD-PLAN-IMPLEMENTATION-BOOTSTRAP`) - 대화형
-  4. 순차 자동 구현 (`CMD-DEV-SEQUENTIAL-AUTORUN`) - 자동
-  5. 검증/보안 - 자동
-  6. 최종 세팅/배포 준비 - 수동
-
-PRD 단계에서는 UI 컴포넌트화, 톤앤매너, 성능, 보안, 가독성 기준을 명시하시고, 자동 단계에서는 배치별 검증을 통과해야 다음 배치로 진행됩니다.
-
-## 설치/업데이트 사용법
-
-### 가장 쉬운 시작 (pnpm dlx, 전부 대화형)
-
 ```bash
-pnpm dlx tri-agent-manager --interactive
+pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive
 ```
 
-위 한 줄로 아래를 터미널에서 순서대로 선택하실 수 있습니다.
-
-1. 설치 경로 (현재 위치 또는 직접 입력)
-2. 프리셋
-3. 도구(Claude Code/Antigravity/Codex)
-4. 구성요소(스킬, 워크플로우 등)
-5. 실행 확인
-
-도구별 실제 설치 루트:
-
-- Claude Code: `<target>/.claude/*`
-- Antigravity: `<target>/.agent/*`
-- Codex: `<target>/.codex/*`
-- 설치 직후 사용 가이드 자동 생성: `<target>/.tri-agent-manager/USAGE.ko.md`
-
-설치 경로 기준(근거 문서):
-
-- Claude Code: `claude-code/README.md` + Claude Code Subagents 공식 문서
-- Antigravity: `antigravity/README.md` 기준의 로컬 워크스페이스 규약(`.agent/*`)
-- Codex: `codex/README.md` + Codex 공식 문서
-
-조작 키:
+`@dusky-bluehour/agent-service` 패키지로 Claude Code / Antigravity / Codex 운영팩을 설치/업데이트하는 CLI입니다.
 
-- `↑/↓`: 이동
-- `←/→`: 해제/선택 또는 항목 이동
-- `Space`: 다중 선택 토글
-- `Enter`: 확정
-
-업데이트도 동일하게 대화형으로 진행하실 수 있습니다.
+## 빠른 실행 (설치 없이)
 
 ```bash
-pnpm dlx tri-agent-manager update --interactive
+pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive
 ```
 
-`setup` 별칭도 동일하게 동작합니다.
+## 패키지 다운로드 후 사용
 
 ```bash
-pnpm dlx tri-agent-manager setup
-```
+# 프로젝트에 패키지 설치
+pnpm add -D @dusky-bluehour/agent-service@latest
 
-### npm 사용 시
-
-```bash
-npx tri-agent-manager --interactive
-npx tri-agent-manager update --interactive
+# 실행
+pnpm exec tri-agent-manager --interactive
 ```
 
-이전 CLI 별칭 `tri-agent-os`도 호환용으로 함께 제공됩니다.
-
-### 고급 옵션(필요한 경우)
-
-- `--preset`: 미리 정의된 구성을 선택합니다.
-- `--tool`: 툴을 직접 선택합니다. (`codex,claude-code` 등)
-- `--components`: 구성요소를 직접 선택합니다. (`skills,workflows,commands` 등)
-- `--install-root`: 도구별 설치 루트를 직접 지정합니다. (`codex=.codex,antigravity=.agent`)
-- `--interactive`: 한글 대화형 선택 UI를 사용합니다.
-- `--dry-run`: 실제 반영 없이 계획만 확인합니다.
-- `--yes`: 확인 프롬프트를 생략합니다.
-
-중복 선택 입력(예: `codex,codex,claude-code`)은 자동으로 1회로 정리됩니다.
-
-### 다른 폴더에 설치하는 명령어
+npm 사용자:
 
 ```bash
-# 1) 전체 프리셋을 다른 프로젝트 경로에 설치
-pnpm dlx --package=@dusky-bluehour/agent-service tri-agent-manager install \
-  --preset full-suite \
-  --target /path/to/your-project \
-  --yes --non-interactive
+npm install -D @dusky-bluehour/agent-service@latest
+npx tri-agent-manager --interactive
 ```
 
-```bash
-# 2) 특정 도구만 설치 (예: Antigravity)
-pnpm dlx --package=@dusky-bluehour/agent-service tri-agent-manager install \
-  --tool antigravity \
-  --components skills,agents,artifacts,workflows,commands \
-  --target /path/to/your-project \
-  --yes --non-interactive
-```
+## 자주 쓰는 명령
 
 ```bash
-# 3) 도구별 설치 루트를 커스텀
-pnpm dlx --package=@dusky-bluehour/agent-service tri-agent-manager install \
-  --preset balanced-core \
-  --install-root codex=.codex,claude-code=.claude,antigravity=.agent \
-  --target /path/to/your-project \
-  --yes --non-interactive
-```
-
-설치 후 실행 가이드는 아래 파일에서 확인하실 수 있습니다.
-
-- `<target>/.tri-agent-manager/USAGE.ko.md`
-
-## 프리셋
-
-- `balanced-core`: 기본 운영팩(추천)
-- `full-suite`: 전체 설치
-- `security-first`: 보안 우선
-- `frontend-refactor`: 프론트 반복개선
-- `prd-to-production`: PRD→구현 자동 파이프라인
-
-## 체크리스트 자동화
-
-배포 전 자동 점검:
+# 업데이트 대화형
+pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager update --interactive
 
-```bash
-npm run prepublish:check
+# 도움말
+pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --help
 ```
 
-`prepublishOnly`가 설정되어 있어 `npm publish` 시에도 자동 실행됩니다.
-
-## 다음 단계 추천
-
-1. `pnpm dlx tri-agent-manager --interactive`로 `prd-to-production` 프리셋을 먼저 설치해 보세요.
-2. 첫 실행은 `--dry-run`으로 계획만 확인하신 뒤 실제 반영을 진행해 주세요.
-3. 반영 후 `npm run prepublish:check`로 검증을 고정하신 뒤 배포해 주세요.
-
-## 상세 구성 문서
+## 설치 결과
 
-- 구조/설계/계약 상세: `docs/COMPOSITION.ko.md`
-- 대화형 UX 흐름 그림: `docs/UX-FLOW.ko.md`
-- 배포 절차 가이드: `docs/DEPLOYMENT-GUIDE.ko.md`
-- 업데이트 절차 가이드: `docs/UPDATE-GUIDE.ko.md`
+- Claude Code: `<target>/.claude/*`
+- Antigravity: `<target>/.agent/*`
+- Codex: `<target>/.codex/*`
+- 가이드: `<target>/.tri-agent-manager/USAGE.ko.md`

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@dusky-bluehour/agent-service",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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",

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) {
@@ -450,6 +446,52 @@ 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, '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 +550,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('### 워크플로우 선택 가이드');
@@ -1146,32 +1196,82 @@ function statusLabel(status) {
   }
 }
 
-function printPlan(catalog, selection, mode, targetDir) {
-  console.log('');
-  console.log('실행 계획');
-  console.log(`- 모드: ${mode}`);
-  console.log(`- 프리셋: ${selection.presetId ?? '수동/없음'}`);
-  console.log(`- 대상 경로: ${targetDir}`);
+function statusIcon(status) {
+  switch (status) {
+    case 'copied':
+      return '✅';
+    case 'overwritten':
+      return '♻️';
+    case 'skipped':
+      return '⏭️';
+    case 'would-copy':
+      return '📝';
+    case 'would-overwrite':
+      return '🛠️';
+    default:
+      return '•';
+  }
+}
 
-  for (const toolId of selection.selectedToolIds) {
+function normalizeChoiceInput(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replaceAll('１', '1')
+    .replaceAll('２', '2')
+    .replaceAll('３', '3')
+    .replaceAll('４', '4')
+    .replaceAll('５', '5');
+}
+
+function printPlan(catalog, selection, mode, targetDir, dryRun = false) {
+  console.log('');
+  console.log('━━━━━━━━ 실행 계획 ━━━━━━━━');
+  console.log(`모드       : ${mode}`);
+  console.log(`실행 타입  : ${dryRun ? 'dry-run (실제 파일 변경 없음)' : '실행 (파일 변경 반영)'}`);
+  console.log(`프리셋     : ${selection.presetId ?? '수동/없음'}`);
+  console.log(`대상 경로  : ${targetDir}`);
+  console.log(`선택 도구  : ${selection.selectedToolIds.length}개`);
+
+  selection.selectedToolIds.forEach((toolId, index) => {
     const tool = findTool(catalog, toolId);
+    if (!tool) {
+      return;
+    }
     const installRoot = getEffectiveInstallRoot(tool, selection);
     const installReferences = getToolInstallReferences(tool);
     const componentIds = selection.componentSelection[toolId] ?? [];
-    const labels = tool.components
-      .filter((c) => componentIds.includes(c.id))
-      .map((c) => `${c.title}(${c.id} → ${path.join(installRoot, getComponentInstallPath(c))})`)
-      .join(', ');
-    console.log(
-      `- ${tool.title}(${tool.id}) [설치 루트: ${installRoot}]: ${labels || '선택된 항목 없음'}`
-    );
+
+    console.log('');
+    console.log(`${index + 1}. ${tool.title} (${tool.id})`);
+    console.log(`   설치 루트 : ${installRoot}`);
+    console.log('   구성요소  :');
+
+    if (componentIds.length === 0) {
+      console.log('    - 선택된 항목 없음');
+    } else {
+      for (const componentId of componentIds) {
+        const component = tool.components.find((candidate) => candidate.id === componentId);
+        if (!component) continue;
+        console.log(
+          `    - ${component.title} (${component.id}) -> ${path.join(
+            installRoot,
+            getComponentInstallPath(component)
+          )}`
+        );
+      }
+    }
+
     if (tool.install_root_basis) {
-      console.log(`  경로 기준: ${tool.install_root_basis}`);
+      console.log(`   경로 기준 : ${tool.install_root_basis}`);
     }
     if (installReferences.length > 0) {
-      console.log(`  참고 문서: ${installReferences.join(', ')}`);
+      console.log('   참고 문서 :');
+      installReferences.forEach((ref) => {
+        console.log(`    - ${ref}`);
+      });
     }
-  }
+  });
 }
 
 async function confirmProceed(yesFlag) {
@@ -1180,9 +1280,23 @@ async function confirmProceed(yesFlag) {
 
   const rl = createInterface({ input, output });
   try {
-    const answer = await rl.question('계속 진행할까요? (y/N)\n> ');
-    const normalized = answer.trim().toLowerCase();
-    return normalized === 'y' || normalized === 'yes';
+    while (true) {
+      console.log('');
+      console.log('진행 여부를 선택해 주세요.');
+      console.log('1) 진행');
+      console.log('2) 취소 (기본값)');
+      const answer = await rl.question('번호를 입력하세요. [기본: 2]\n> ');
+      const normalized = normalizeChoiceInput(answer);
+
+      if (!normalized || normalized === '2' || normalized === '취소' || normalized === '아니오') {
+        return false;
+      }
+      if (normalized === '1' || normalized === '진행' || normalized === '예') {
+        return true;
+      }
+
+      console.log('잘못된 입력입니다. 1 또는 2를 입력해 주세요.');
+    }
   } finally {
     rl.close();
   }
@@ -1241,6 +1355,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;
@@ -1289,12 +1412,40 @@ async function runInstallOrUpdate({ catalog, packageData, mode, selection, force
   }
 
   console.log('');
-  console.log('적용 결과');
+  console.log('━━━━━━━━ 적용 결과 ━━━━━━━━');
+  const summaryCounter = {
+    copied: 0,
+    overwritten: 0,
+    skipped: 0,
+    'would-copy': 0,
+    'would-overwrite': 0
+  };
   for (const item of results) {
-    console.log(
-      `- [${item.toolId}] ${item.source} -> ${item.destination}: ${statusLabel(item.status)}`
-    );
+    if (item.status in summaryCounter) {
+      summaryCounter[item.status] += 1;
+    }
+  }
+
+  const groupedResults = new Map();
+  for (const item of results) {
+    const list = groupedResults.get(item.toolId) ?? [];
+    list.push(item);
+    groupedResults.set(item.toolId, list);
+  }
+  for (const toolId of selection.selectedToolIds) {
+    const items = groupedResults.get(toolId) ?? [];
+    if (items.length === 0) continue;
+    console.log(`[${toolId}]`);
+    for (const item of items) {
+      console.log(
+        `  - ${statusIcon(item.status)} ${statusLabel(item.status)} | ${item.source} -> ${item.destination}`
+      );
+    }
   }
+  console.log('');
+  console.log(
+    `요약: 복사 ${summaryCounter.copied} · 업데이트 ${summaryCounter.overwritten} · 건너뜀 ${summaryCounter.skipped} · 복사예정 ${summaryCounter['would-copy']} · 업데이트예정 ${summaryCounter['would-overwrite']}`
+  );
 
   const usageGuidePath = path.join(targetDir, STATE_DIR_NAME, GUIDE_FILE_NAME);
   if (dryRun) {
@@ -1305,54 +1456,73 @@ 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)}`);
+    }
   }
 }
 
 function printList(catalog) {
   console.log('');
-  console.log(`${CLI_NAME} 카탈로그 (한글)`);
-  console.log('');
-  for (const tool of catalog.tools) {
+  console.log('━━━━━━━━ 도구 카탈로그 ━━━━━━━━');
+  console.log(`CLI: ${CLI_NAME}`);
+
+  catalog.tools.forEach((tool, toolIndex) => {
     const installRoot = getToolInstallRoot(tool);
     const installReferences = getToolInstallReferences(tool);
-    console.log(`- ${tool.title} (${tool.id})`);
-    console.log(`  설명: ${tool.description}`);
-    console.log(`  설치 루트: ${installRoot}`);
+    console.log('');
+    console.log(`${toolIndex + 1}. ${tool.title} (${tool.id})`);
+    console.log(`   설명      : ${tool.description}`);
+    console.log(`   설치 루트 : ${installRoot}`);
     if (tool.install_root_basis) {
-      console.log(`  경로 기준: ${tool.install_root_basis}`);
+      console.log(`   경로 기준 : ${tool.install_root_basis}`);
     }
     if (installReferences.length > 0) {
-      console.log(`  참고 문서: ${installReferences.join(', ')}`);
+      console.log('   참고 문서 :');
+      installReferences.forEach((ref) => {
+        console.log(`    - ${ref}`);
+      });
     }
-    console.log('  구성요소:');
-    for (const component of tool.components) {
+    console.log('   구성요소  :');
+    tool.components.forEach((component) => {
       console.log(
-        `  - ${component.title} (${component.id}): ${component.description} -> ${path.join(
+        `    - ${component.title} (${component.id}) -> ${path.join(
           installRoot,
           getComponentInstallPath(component)
         )}`
       );
-    }
-    console.log('');
-  }
+      if (component.description) {
+        console.log(`      ${component.description}`);
+      }
+    });
+  });
 
   const presets = Array.isArray(catalog.presets) ? catalog.presets : [];
   if (presets.length > 0) {
-    console.log('프리셋 목록');
-    for (const preset of presets) {
-      console.log(`- ${preset.title} (${preset.id})`);
-      console.log(`  설명: ${preset.description}`);
-    }
+    console.log('');
+    console.log('━━━━━━━━ 프리셋 목록 ━━━━━━━━');
+    presets.forEach((preset, index) => {
+      const toolCount = Array.isArray(preset.tools) ? preset.tools.length : 0;
+      console.log(`${index + 1}. ${preset.title} (${preset.id})`);
+      console.log(`   설명      : ${preset.description}`);
+      console.log(`   포함 도구 : ${toolCount}개 (${(preset.tools ?? []).join(', ')})`);
+    });
+    console.log('');
+    console.log('프리셋 사용 예시:');
+    console.log(
+      `  ${CLI_NAME} install --preset balanced-core --target /path/to/project --yes --non-interactive`
+    );
     console.log('');
   }
 
-  console.log('권장 UX 흐름');
-  console.log('1) pnpm dlx tri-agent-manager --interactive 로 시작합니다.');
-  console.log('2) 설치 후 state.json을 기준으로 update를 수행한다.');
-  console.log('3) update 시 필요한 도구만 부분 갱신한다.');
+  console.log('━━━━━━━━ 권장 흐름 ━━━━━━━━');
+  console.log(`1) pnpm dlx ${CLI_NAME} --interactive`);
+  console.log('2) 설치 후 .tri-agent-manager/state.json 기준으로 update');
+  console.log('3) update 시 필요한 도구만 부분 갱신');
 }
 
 async function main() {
@@ -1427,7 +1597,7 @@ async function main() {
     })
   };
 
-  printPlan(catalog, selection, command, selection.targetDir);
+  printPlan(catalog, selection, command, selection.targetDir, options.dryRun);
 
   const proceed = await confirmProceed(options.yes);
   if (!proceed) {
@@ -1445,7 +1615,12 @@ async function main() {
   });
 
   console.log('');
-  console.log('완료: 선택한 운영팩 반영이 끝났습니다.');
+  if (options.dryRun) {
+    console.log('완료: dry-run 계획 확인이 끝났습니다. 실제 반영하려면 --dry-run 없이 다시 실행해 주세요.');
+  } else {
+    console.log('완료: 선택한 운영팩 반영이 끝났습니다.');
+    console.log(`가이드 확인: ${path.join(selection.targetDir, STATE_DIR_NAME, GUIDE_FILE_NAME)}`);
+  }
 }
 
 main().catch((error) => {

package/scripts/validate.mjs

@@ -210,6 +210,10 @@ async function validatePackageJson() {
     }
   }
 
+  if (!pkg.bin || pkg.bin['tri-agent-manager'] !== 'scripts/init.mjs') {
+    fail('[package] bin 설정 오류: tri-agent-manager -> scripts/init.mjs 가 필요합니다.');
+  }
+
   const requiredFiles = [
     'claude-code',
     'antigravity',
@@ -228,7 +232,8 @@ async function validatePackageJson() {
     'docs/COMPOSITION.ko.md',
     'docs/DEPLOYMENT-GUIDE.ko.md',
     'docs/UPDATE-GUIDE.ko.md',
-    'docs/UX-FLOW.ko.md'
+    'docs/UX-FLOW.ko.md',
+    'docs/NPM-PUBLISH-REPO-ONLY.ko.md'
   ];
   for (const fileEntry of excludedFromPublish) {
     if (Array.isArray(pkg.files) && pkg.files.includes(fileEntry)) {