@dusky-bluehour/agent-service 0.6.4 → 0.6.5

package/README.md

@@ -1,255 +1,47 @@
 # tri-agent-manager
 
 ```bash
-pnpm dlx --package=@dusky-bluehour/agent-service tri-agent-manager --interactive
+pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive
 ```
 
-Claude Code, Antigravity, Codex에서 공통으로 사용하실 수 있는 서비스 운영형 스킬/워크플로우 패키지입니다.
+`@dusky-bluehour/agent-service` 패키지로 Claude Code / Antigravity / Codex 운영팩을 설치/업데이트하는 CLI입니다.
 
-## 목적
-
-- 기획(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 공식 문서
-
-조작 키:
-
-- `↑/↓`: 이동
-- `←/→`: 해제/선택 또는 항목 이동
-- `Space`: 다중 선택 토글
-- `Enter`: 확정
-
-업데이트도 동일하게 대화형으로 진행하실 수 있습니다.
+## 패키지 다운로드 후 사용
 
 ```bash
-pnpm dlx tri-agent-manager update --interactive
-```
+# 프로젝트에 패키지 설치
+pnpm add -D @dusky-bluehour/agent-service@latest
 
-`setup` 별칭도 동일하게 동작합니다.
-
-```bash
-pnpm dlx tri-agent-manager setup
+# 실행
+pnpm exec tri-agent-manager --interactive
 ```
 
-### npm 사용 시
+npm 사용자:
 
 ```bash
+npm install -D @dusky-bluehour/agent-service@latest
 npx tri-agent-manager --interactive
-npx tri-agent-manager update --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회로 정리됩니다.
-
-### 다른 폴더에 설치하는 명령어
-
-```bash
-# 1) 전체 프리셋을 다른 프로젝트 경로에 설치
-pnpm dlx --package=@dusky-bluehour/agent-service tri-agent-manager install \
-  --preset full-suite \
-  --target /path/to/your-project \
-  --yes --non-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.4",
+  "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('### 워크플로우 선택 가이드');
@@ -1305,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;
@@ -1397,9 +1456,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)}`);
+    }
   }
 }
 

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)) {