@dusky-bluehour/agent-service 0.6.6 → 0.6.8

package/README.md

@@ -1,66 +1,285 @@
 # tri-agent-manager
 
-```bash
-pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive
-```
+Claude Code, Gemini CLI, Codex 3개 AI 에이전트용 **서비스 운영 스킬/워크플로우 설치기**입니다.
 
-`@dusky-bluehour/agent-service` 패키지로 Claude Code / Antigravity / Codex 운영팩을 설치/업데이트하는 CLI입니다.
+공통 정의(common/) 하나로 3개 플랫폼에 동일한 운영 역량을 배포합니다.
 
-## 빠른 실행 (설치 없이)
+## 아키텍처 개요
 
-```bash
-pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --interactive
+```
+common/                          ← 단일 원천 (Single Source of Truth)
+  skills/skill-catalog.json         스킬 8개 (플랫폼별 procedures 포함)
+  commands/command-catalog.json     명령 20개
+  workflows/workflow-catalog.json   워크플로우 5개 (Gemini CLI 전용)
+  settings/security-policy.json     보안 정책
+  claude/subagent-catalog.json      Claude 서브에이전트 15개
+  claude/team-catalog.json          Claude 팀 3개
+  gemini/agent-catalog.json         Gemini 에이전트 카탈로그
+  gemini/artifact-catalog.json      Gemini 아티팩트 계약
+       │
+       ▼  npm run generate
+       │
+  ┌────┴────────────────────────────────────────────┐
+  │                                                  │
+claude-code/          gemini/              codex/
+  skills/               skills/              skills/
+  subagents/            agents/              skills/cmd-*/
+  agent-teams/          artifacts/           automations/
+  commands/native/      commands/definitions/  commands/
+    *.md (Slash Cmd)      *.toml (Extension)   command-catalog.json
+  instructions/         workflows/           instructions/
+    CLAUDE.template.md    definitions/*.yaml   AGENTS.template.md
+  settings/             gemini-extension.json  settings/
+    settings.json       instructions/
+                          GEMINI.template.md
 ```
 
+## 빠른 시작
+
 ```bash
+# 대화형 설치 (프리셋 선택 → 도구/구성요소 선택 → 설치)
 npx --yes --package @dusky-bluehour/agent-service tri-agent-manager --interactive
 ```
 
-## 패키지 다운로드 후 사용
-
 ```bash
-# 프로젝트에 패키지 설치
-pnpm add -D @dusky-bluehour/agent-service@latest
+# 명시적 install / update
+npx --yes --package @dusky-bluehour/agent-service tri-agent-manager install --interactive
+npx --yes --package @dusky-bluehour/agent-service tri-agent-manager update --interactive
+```
 
-# 실행
-pnpm exec tri-agent-manager --interactive
+```bash
+# Non-interactive (CI/스크립트용)
+npx --yes --package @dusky-bluehour/agent-service tri-agent-manager install \
+  --preset balanced-core --target . --yes
 ```
 
-npm 사용자:
+## 설치하면 무슨 일이 생기나
 
-```bash
-npm install -D @dusky-bluehour/agent-service@latest
-npx tri-agent-manager --interactive
+설치 대상 프로젝트에 아래 파일이 생성됩니다.
+
+```
+<project>/
+  .claude/                    ← Claude Code 선택 시
+    skills/<name>/SKILL.md       8개 스킬
+    agents/<role>.md             15개 서브에이전트
+    agent-teams/team-catalog.json
+    commands/<name>.md           20개 네이티브 슬래시 명령
+    instructions/CLAUDE.template.md
+    settings/settings.json
+  .gemini/                    ← Gemini CLI 선택 시
+    skills/<name>/SKILL.md       8개 스킬
+    agents/agent-catalog.json
+    artifacts/artifact-catalog.json
+    workflows/                   5개 워크플로우 정의
+    commands/definitions/*.toml  20개 커스텀 명령
+    gemini-extension.json        Extension 매니페스트
+    instructions/GEMINI.template.md
+    settings/editor-policy.json
+  .codex/                     ← Codex 선택 시
+    skills/<name>/SKILL.md       8개 스킬
+    skills/cmd-*/SKILL.md        20개 명령 스킬
+    automations/automation-recipes.toml
+    commands/command-catalog.json
+    instructions/AGENTS.template.md
+    settings/runtime-policy.json
+  CLAUDE.md                   ← 프로젝트 규칙 파일 (Claude Code)
+  GEMINI.md                   ← 프로젝트 규칙 파일 (Gemini CLI)
+  AGENTS.md                   ← 프로젝트 규칙 파일 (Codex)
+  .tri-agent-manager/
+    state.json                   설치 상태 기록
+    USAGE.ko.md                  실행 가이드
 ```
 
-## 자주 쓰는 명령
+## 동작 방법
 
-```bash
-# 업데이트 대화형
-pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager update --interactive
+### 1. 스킬 (Skills) — 3개 플랫폼 공통
+
+8개 운영 스킬이 각 에이전트의 네이티브 포맷으로 설치됩니다.
+
+| 스킬 ID | 역할 |
+|---------|------|
+| `change-safety-review` | 변경사항 회귀 검증 + 코드 리뷰 |
+| `code-review-and-improvement` | 코드 품질 개선 + 기술부채 정리 |
+| `frontend-repetition-pack` | UI 컴포넌트화 → Hook 분리 → 성능 최적화 |
+| `incident-response` | 장애 트리아지 → 근본원인 수정 → 포스트모템 |
+| `prd-to-production-pipeline` | PRD 작성 → 자동 구현 → 검증 → 배포 |
+| `release-and-operations` | CI/CD 게이트 → 배포 → 모니터링 |
+| `security-hardening` | 위협 모델링 → 취약점 감사 → 하드닝 |
+| `service-lifecycle-orchestration` | 전체 수명주기 오케스트레이션 |
+
+각 스킬은 자체적으로 실행 가능한 상세 절차를 포함합니다. 외부 명령(CMD-*) 참조 없이 절차를 직접 기술합니다.
+
+사용 방법:
+- **Claude Code**: `.claude/skills/<name>/SKILL.md`를 자동 인식하여 사용자 요청에 매칭
+- **Gemini CLI**: `.gemini/skills/<name>/SKILL.md`를 Extension 내 스킬로 로드
+- **Codex**: `.codex/skills/<name>/SKILL.md` + `agents/openai.yaml`로 스킬 UI 표시
+
+### 2. 명령 (Commands) — 플랫폼별 네이티브 변환
+
+20개 공통 명령이 각 플랫폼의 네이티브 실행 포맷으로 변환됩니다.
+
+| 플랫폼 | 변환 결과 | 실행 방식 |
+|--------|----------|----------|
+| Claude Code | `commands/native/*.md` | `/cmd-dev-be-api` 슬래시 명령으로 실행 |
+| Gemini CLI | `commands/definitions/*.toml` | Extension 커스텀 명령으로 실행 |
+| Codex | `skills/cmd-*/SKILL.md` | 스킬로 변환하여 네이티브 실행 |
+
+### 3. 워크플로우 (Workflows) — Gemini CLI 전용
+
+단계형 에이전트 체인 워크플로우는 Gemini CLI만 네이티브 지원합니다.
+
+| 워크플로우 ID | 용도 |
+|--------------|------|
+| `WF-SERVICE-E2E` | 신규 서비스 E2E (Plan→Implement→Test→Review→Release) |
+| `WF-FRONTEND-REFACTOR` | 프론트엔드 반복 개선 (UI→Hook→성능) |
+| `WF-SECURITY-HARDENING` | 보안 강화 배치 (진단→보완→검증) |
+| `WF-INCIDENT-RESPONSE` | 장애 대응 (트리아지→근본수정→포스트모템) |
+| `WF-PRD-TO-PRODUCTION` | PRD 대화형 작성 → 순차 자동 구현 |
+
+각 워크플로우는 `workflow-catalog.json`에 단계/에이전트/아티팩트 계약이 정의되어 있고, `definitions/*.workflow.yaml`로 실행합니다.
+
+### 4. 서브에이전트 & 팀 — Claude Code 전용
+
+Claude Code는 리드-전문가 구조의 서브에이전트 팀을 지원합니다.
+
+- 15개 서브에이전트: `lead-orchestrator`, `backend-engineer`, `security-engineer`, `sre-release-engineer` 등
+- 3개 팀: `TEAM-SVC-DELIVERY` (서비스 딜리버리), `TEAM-SEC-HARDENING` (보안), `TEAM-INCIDENT` (장애 대응)
+
+### 5. 프로젝트 규칙 파일
+
+설치 시 프로젝트 루트에 에이전트별 규칙 파일을 자동 생성합니다 (기존 파일 유지).
+
+| 에이전트 | 규칙 파일 | 템플릿 원본 |
+|---------|----------|------------|
+| Claude Code | `CLAUDE.md` | `instructions/CLAUDE.template.md` |
+| Gemini CLI | `GEMINI.md` | `instructions/GEMINI.template.md` |
+| Codex | `AGENTS.md` | `instructions/AGENTS.template.md` |
+
+## 프리셋
+
+자주 쓰는 도구/구성요소 조합을 프리셋으로 제공합니다.
+
+| 프리셋 ID | 포함 도구 | 설명 |
+|----------|----------|------|
+| `balanced-core` | Codex + Claude Code | 빠르게 시작하는 기본 구성 (추천) |
+| `full-suite` | Claude Code + Gemini CLI + Codex | 모든 구성요소 설치 |
+| `security-first` | Claude Code + Gemini CLI + Codex | 보안 점검/하드닝 중심 |
+| `frontend-refactor` | Claude Code + Codex | UI 컴포넌트화/성능 최적화 |
+| `prd-to-production` | Claude Code + Gemini CLI + Codex | PRD→구현 자동 파이프라인 |
+
+## CLI 옵션
 
-# 도움말
-pnpm dlx --package=@dusky-bluehour/agent-service@latest tri-agent-manager --help
 ```
+tri-agent-manager [command] [options]
 
-## 설치 결과
+Commands:
+  install          설치 (기본값)
+  update           업데이트
+  list             설치 가능 도구/구성요소 목록
 
-- Claude Code: `<target>/.claude/*`
-- Antigravity: `<target>/.agent/*`
-- Codex: `<target>/.codex/*`
-- 가이드: `<target>/.tri-agent-manager/USAGE.ko.md`
+Options:
+  --interactive    대화형 모드 (TUI 메뉴)
+  --preset <id>    프리셋으로 도구/구성요소 사전 선택
+  --tool <ids>     도구 지정 (쉼표 구분: claude-code,gemini,codex)
+  --components <ids>  구성요소 지정 (쉼표 구분: skills,commands,...)
+  --target <path>  설치 대상 경로 (기본: 현재 디렉토리)
+  --project-rules <policy>  규칙 파일 정책 (always|if-instructions|if-present|never)
+  --force          install 시 기존 파일 덮어쓰기
+  --dry-run        실제 파일 쓰기 없이 계획만 출력
+  --yes            확인 프롬프트 건너뛰기
+  --help           도움말
+```
 
-## 개발자용 (정의 변경 시)
+### install vs update
 
-```bash
-# common 정의를 툴별 파일로 생성
-npm run generate
+| 명령 | 기존 파일 처리 | 용도 |
+|------|-------------|------|
+| `install` | 기존 파일 유지 (건너뜀) | 최초 설치, 추가 도구 설치 |
+| `install --force` | 기존 파일 덮어씀 | 템플릿 강제 재적용 |
+| `update` | 선택한 항목 업데이트 반영 | 버전 갱신, 유지보수 |
+
+## 도구별 구성요소
+
+<details>
+<summary><strong>Claude Code (.claude)</strong></summary>
+
+| 구성요소 ID | 설치 경로 | 설명 |
+|------------|----------|------|
+| `skills` | `.claude/skills` | 8개 운영 스킬 |
+| `subagents` | `.claude/agents` | 15개 역할별 서브에이전트 프롬프트 |
+| `agent-teams` | `.claude/agent-teams` | 리드+전문가 팀 구성 |
+| `commands` | `.claude/commands` | 20개 네이티브 슬래시 명령 |
+| `instructions` | `.claude/instructions` | `CLAUDE.md` 템플릿 |
+| `settings` | `.claude/settings` | 권한/보안 설정 템플릿 |
+
+규칙 파일: `<target>/CLAUDE.md`
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI (.gemini)</strong></summary>
+
+| 구성요소 ID | 설치 경로 | 설명 |
+|------------|----------|------|
+| `skills` | `.gemini/skills` | 8개 운영 스킬 |
+| `agents` | `.gemini/agents` | 에이전트 역할 카탈로그 |
+| `artifacts` | `.gemini/artifacts` | 단계 입출력 아티팩트 계약 |
+| `workflows` | `.gemini/workflows` | 5개 워크플로우 + YAML 정의 |
+| `commands` | `.gemini/commands` | 20개 TOML 커스텀 명령 |
+| `instructions` | `.gemini/instructions` | `GEMINI.md` 템플릿 |
+| `settings` | `.gemini/settings` | 에디터 보안/권한 정책 |
 
-# 생성 결과가 최신인지 확인 + 전체 검증
-npm run validate
+규칙 파일: `<target>/GEMINI.md`
+
+</details>
+
+<details>
+<summary><strong>Codex (.codex)</strong></summary>
+
+| 구성요소 ID | 설치 경로 | 설명 |
+|------------|----------|------|
+| `skills` | `.codex/skills` | 8개 운영 스킬 + 20개 명령 스킬 |
+| `instructions` | `.codex/instructions` | `AGENTS.md` 템플릿 + 권한 스니펫 |
+| `automations` | `.codex/automations` | 반복 작업 자동화 레시피 |
+| `commands` | `.codex/commands` | 공통 명령 계약 |
+| `settings` | `.codex/settings` | 런타임 권한 정책 |
+
+규칙 파일: `<target>/AGENTS.md`
+
+</details>
+
+## 개발자용
+
+### 파이프라인
+
+```
+common/* 수정 → npm run generate → npm run validate → npm publish
 ```
 
-원칙:
+- `npm run generate` — 공통 정의를 플랫폼별 파일로 생성
+- `npm run generate:check` — 생성 결과가 최신인지 검증
+- `npm run validate` — 구조/계약/CLI 동작 검증
+- `npm run prepublish:check` — 배포 전 전체 검증
+
+### 규칙
 
 - 공통 원천은 `common/*`에서만 수정합니다.
-- `claude-code/*`, `codex/*`, `antigravity/*`는 생성 결과로 취급합니다.
+- `claude-code/*`, `codex/*`, `gemini/*`는 생성 결과로 취급합니다. 직접 수정하지 마세요.
+- 명령은 공통 계약에서 플랫폼별 네이티브 포맷으로 자동 변환됩니다:
+  - Claude Code: `commands/native/*.md` (Slash Command)
+  - Gemini CLI: `commands/definitions/*.toml` (Extension 커스텀 명령)
+  - Codex: `skills/cmd-*/SKILL.md` (스킬 변환)
+- 보안 정책(`common/settings/security-policy.json`)에서 플랫폼별 설정 템플릿으로 변환됩니다.
+
+### 검증 대상
+
+- 생성 결과 최신성
+- 스킬 frontmatter/절차 유효성 (CMD-*/WF-*/ART-* 참조 금지)
+- 명령/워크플로우 참조 무결성
+- 카탈로그/프리셋 무결성
+- Gemini Extension 구조 (`gemini-extension.json`, `.toml` 커스텀 명령)
+- CLI 스모크 테스트 (list/install/update + preset)
+
+## 라이선스
+
+MIT

package/catalog/tool-catalog.ko.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0.0",
   "package": {
     "name": "tri-agent-manager",
-    "description_ko": "Claude Code, Antigravity, Codex용 서비스 운영 스킬/워크플로우 운영팩"
+    "description_ko": "Claude Code, Gemini CLI, Codex용 서비스 운영 스킬/워크플로우 운영팩"
   },
   "tools": [
     {
@@ -39,31 +39,38 @@
           "title": "서브에이전트 팀",
           "description": "리드+전문가 협업 팀 구성과 기본 워크플로우 매핑"
         },
-        {
-          "id": "workflows",
-          "path": "workflows",
-          "install_path": "workflows",
-          "title": "워크플로우",
-          "description": "기획-개발-검증-배포-운영 단계형 시나리오"
-        },
         {
           "id": "commands",
           "path": "commands",
           "install_path": "commands",
           "title": "명령 카탈로그",
           "description": "입력/실행/품질게이트/산출물 계약이 고정된 명령 집합"
+        },
+        {
+          "id": "instructions",
+          "path": "instructions",
+          "install_path": "instructions",
+          "title": "프로젝트 규칙 템플릿",
+          "description": "프로젝트 루트 CLAUDE.md 자동 생성용 템플릿"
+        },
+        {
+          "id": "settings",
+          "path": "settings",
+          "install_path": "settings",
+          "title": "설정 템플릿",
+          "description": "프로젝트 단위 권한/보안 설정(settings.json) 템플릿"
         }
       ]
     },
     {
-      "id": "antigravity",
-      "title": "Antigravity",
-      "description": "Manager-Agent-Artifact 기반 오케스트레이션 구조",
-      "root": "antigravity",
-      "install_root": ".agent",
-      "install_root_basis": "Antigravity 생태계의 워크스페이스 로컬 규약(.agent/*)을 기본값으로 사용",
+      "id": "gemini",
+      "title": "Gemini CLI",
+      "description": "Extension/Commands/Skills 기반 오케스트레이션 구조",
+      "root": "gemini",
+      "install_root": ".gemini",
+      "install_root_basis": "Gemini CLI 확장 표준(.gemini/*)을 기본값으로 사용",
       "install_root_reference": [
-        "antigravity/README.md"
+        "gemini/README.md"
       ],
       "readme": "README.md",
       "components": [
@@ -101,6 +108,20 @@
           "install_path": "commands",
           "title": "명령 카탈로그",
           "description": "공통 명령 계약"
+        },
+        {
+          "id": "instructions",
+          "path": "instructions",
+          "install_path": "instructions",
+          "title": "프로젝트 규칙 템플릿",
+          "description": "GEMINI.md 자동 생성용 템플릿"
+        },
+        {
+          "id": "settings",
+          "path": "settings",
+          "install_path": "settings",
+          "title": "에디터 설정 템플릿",
+          "description": "Gemini CLI 에디터 반영용 보안/권한 정책 템플릿"
         }
       ]
     },
@@ -138,19 +159,19 @@
           "title": "자동화 레시피",
           "description": "주기 점검/리뷰/보안 배치 프리셋"
         },
-        {
-          "id": "workflows",
-          "path": "workflows",
-          "install_path": "workflows",
-          "title": "워크플로우",
-          "description": "Codex 실행 명령(/plan,/review) 연계 단계 정의"
-        },
         {
           "id": "commands",
           "path": "commands",
           "install_path": "commands",
           "title": "명령 카탈로그",
           "description": "공통 명령 계약"
+        },
+        {
+          "id": "settings",
+          "path": "settings",
+          "install_path": "settings",
+          "title": "런타임 정책 템플릿",
+          "description": "Codex 프로젝트 권한/실행 정책 템플릿"
         }
       ]
     }
@@ -164,21 +185,24 @@
       "claude-code": [
         "skills",
         "subagents",
-        "workflows",
-        "commands"
+        "commands",
+        "instructions",
+        "settings"
       ],
-      "antigravity": [
+      "gemini": [
         "skills",
         "agents",
         "artifacts",
         "workflows",
-        "commands"
+        "commands",
+        "instructions",
+        "settings"
       ],
       "codex": [
         "skills",
         "instructions",
-        "workflows",
-        "commands"
+        "commands",
+        "settings"
       ]
     }
   },
@@ -195,14 +219,15 @@
         "codex": [
           "skills",
           "instructions",
-          "workflows",
-          "commands"
+          "commands",
+          "settings"
         ],
         "claude-code": [
           "skills",
           "subagents",
-          "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ]
       }
     },
@@ -212,7 +237,7 @@
       "description": "세 도구의 모든 구성요소를 설치한다.",
       "tools": [
         "claude-code",
-        "antigravity",
+        "gemini",
         "codex"
       ],
       "components": {
@@ -220,22 +245,25 @@
           "skills",
           "subagents",
           "agent-teams",
-          "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
-        "antigravity": [
+        "gemini": [
           "skills",
           "agents",
           "artifacts",
           "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
         "codex": [
           "skills",
           "instructions",
           "automations",
-          "workflows",
-          "commands"
+          "commands",
+          "settings"
         ]
       }
     },
@@ -245,27 +273,30 @@
       "description": "보안 점검/하드닝/배포 게이트를 중심으로 필요한 구성만 설치한다.",
       "tools": [
         "claude-code",
-        "antigravity",
+        "gemini",
         "codex"
       ],
       "components": {
         "claude-code": [
           "skills",
           "subagents",
-          "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
-        "antigravity": [
+        "gemini": [
           "skills",
           "agents",
           "artifacts",
           "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
         "codex": [
           "skills",
-          "workflows",
-          "commands"
+          "commands",
+          "settings"
         ]
       }
     },
@@ -281,14 +312,15 @@
         "claude-code": [
           "skills",
           "subagents",
-          "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
         "codex": [
           "skills",
           "instructions",
-          "workflows",
-          "commands"
+          "commands",
+          "settings"
         ]
       }
     },
@@ -298,7 +330,7 @@
       "description": "PRD 대화형 작성 후 순차 자동 구현 워크플로우(WF-PRD-TO-PRODUCTION)를 사용하는 구성",
       "tools": [
         "claude-code",
-        "antigravity",
+        "gemini",
         "codex"
       ],
       "components": {
@@ -306,21 +338,24 @@
           "skills",
           "subagents",
           "agent-teams",
-          "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
-        "antigravity": [
+        "gemini": [
           "skills",
           "agents",
           "artifacts",
           "workflows",
-          "commands"
+          "commands",
+          "instructions",
+          "settings"
         ],
         "codex": [
           "skills",
           "instructions",
-          "workflows",
-          "commands"
+          "commands",
+          "settings"
         ]
       }
     }