@dmsdc-ai/aigentry-deliberation 0.0.1

package/skills/deliberation/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: deliberation
+description: |
+  AI 간 deliberation(토론) 세션을 관리합니다. 멀티 세션 병렬 토론 지원.
+  MCP deliberation 서버를 통해 MCP를 지원하는 모든 CLI가 구조화된 토론을 진행합니다.
+  "deliberation", "deliberate", "토론", "토론 시작", "deliberation 시작",
+  "저장소 전략 토론", "컨셉 토론", "debate" 키워드 시 자동 트리거됩니다.
+---
+
+# AI Deliberation 스킬 (v2.4 — Multi-Session)
+
+Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토론을 진행합니다.
+**여러 토론을 동시에 병렬 진행할 수 있습니다.**
+**이 스킬은 토론/합의 전용이며, 실제 구현은 `deliberation-executor`로 handoff합니다.**
+
+## MCP 서버 위치
+- **서버**: `~/.local/lib/mcp-deliberation/index.js` (v2.4.0)
+- **상태**: `~/.local/lib/mcp-deliberation/state/{프로젝트명}/sessions/{session_id}.json`
+- **등록**: 각 CLI 환경의 MCP 설정에 `deliberation` 서버 등록
+- **브라우저 탭 스캔**: macOS 자동화 + CDP(Windows/Linux는 remote-debugging port 권장)
+
+## 사용 가능한 MCP 도구
+
+| 도구 | 설명 | session_id |
+|------|------|:---:|
+| `deliberation_start` | 새 토론 시작 → **session_id 반환** | 반환 |
+| `deliberation_speaker_candidates` | 참가 가능한 speaker 후보 목록 조회 | 불필요 |
+| `deliberation_list_active` | 진행 중인 모든 세션 목록 | 불필요 |
+| `deliberation_status` | 토론 상태 조회 | 선택적* |
+| `deliberation_context` | 프로젝트 컨텍스트 로드 | 불필요 |
+| `deliberation_browser_llm_tabs` | 브라우저 LLM 탭 목록 (웹 기반 LLM 참여용) | 불필요 |
+| `deliberation_route_turn` | 현재 차례 speaker의 transport(CLI/browser_auto/manual)를 자동 라우팅 | 선택적* |
+| `deliberation_respond` | 현재 차례의 응답 제출 | 선택적* |
+| `deliberation_history` | 전체 토론 기록 조회 | 선택적* |
+| `deliberation_synthesize` | 합성 보고서 생성 및 토론 완료 | 선택적* |
+| `deliberation_list` | 과거 토론 아카이브 목록 | 불필요 |
+| `deliberation_reset` | 세션 초기화 (지정 시 해당 세션만, 미지정 시 전체) | 선택적 |
+
+*\*선택적: 활성 세션이 1개면 자동 선택. 여러 세션 진행 중이면 필수.*
+
+## session_id 규칙
+
+- `deliberation_start` 호출 시 session_id가 자동 생성되어 반환됨
+- 이후 모든 도구 호출에 해당 session_id를 전달
+- 활성 세션이 1개뿐이면 session_id 생략 가능 (자동 선택)
+- 여러 세션이 동시 진행 중이면 반드시 session_id 지정
+
+## 자동 트리거 키워드
+다음 키워드가 감지되면 이 스킬을 자동으로 활성화합니다:
+- "deliberation", "deliberate", "토론", "debate"
+- "deliberation 시작", "토론 시작", "토론해", "토론하자"
+- "deliberation_start", "deliberation_respond", "deliberation_route_turn"
+- "speaker candidates", "브라우저 LLM"
+- "크롬", "브라우저", "웹 LLM", "chrome", "browser LLM"
+- "{주제} 토론", "{주제} deliberation"
+
+## 워크플로우
+
+### A. 사용자 선택형 진행 (권장)
+1. `deliberation_speaker_candidates` → 참가 가능한 CLI/브라우저 speaker 확인
+2. **AskUserQuestion으로 참가자 선택** — 감지된 CLI/브라우저 speaker 목록을 `multiSelect: true`로 제시하여 사용자가 원하는 참가자만 체크. 예:
+   ```
+   AskUserQuestion({
+     questions: [{
+       question: "토론에 참여할 speaker를 선택하세요",
+       header: "참가자",
+       multiSelect: true,
+       options: [
+         { label: "claude", description: "CLI (자동 응답)" },
+         { label: "codex", description: "CLI (자동 응답)" },
+         { label: "gemini", description: "CLI (자동 응답)" },
+         { label: "web-chatgpt-1", description: "⚡자동 (CDP 자동 연결)" },
+         { label: "web-claude-1", description: "⚡자동 (CDP 자동 연결)" },
+         { label: "web-gemini-1", description: "⚡자동 (CDP 자동 연결)" }
+       ]
+     }]
+   })
+   ```
+3. `deliberation_start` (선택된 speakers 전달) → session_id 획득
+4. `deliberation_route_turn` → 현재 차례 speaker transport 자동 결정
+   - CLI speaker → 자동 응답
+   - browser_auto → CDP로 자동 전송/수집
+5. 반복 후 `deliberation_synthesize(session_id)` → 합성 완료
+6. 구현이 필요하면 `deliberation-executor` 스킬로 handoff
+   예: "session_id {id} 합의안 구현해줘"
+
+### B. 병렬 세션 운영
+1. `deliberation_start` (topic: "주제A") → session_id_A
+2. `deliberation_start` (topic: "주제B") → session_id_B
+3. `deliberation_list_active` → 진행 중 세션 확인
+4. 각 세션을 `session_id`로 명시해 독립 진행
+5. 각각 `deliberation_synthesize`로 개별 종료
+
+### C. 자동 진행 (스크립트)
+```bash
+# 새 토론
+bash auto-deliberate.sh "저장소 전략"
+
+# 5라운드로 진행
+bash auto-deliberate.sh "API 설계" 5
+
+# 기존 세션 재개
+bash auto-deliberate.sh --resume <session_id>
+```
+
+### D. 모니터링
+```bash
+# 모든 활성 세션 모니터링
+bash deliberation-monitor.sh
+
+# 특정 세션만
+bash deliberation-monitor.sh <session_id>
+
+# tmux에서
+bash deliberation-monitor.sh --tmux
+```
+
+### E. 브라우저 LLM 자동 연결 (CDP Auto-Activation)
+- 브라우저 LLM speaker가 선택되면 CDP(Chrome DevTools Protocol)가 자동으로 활성화됩니다.
+- macOS에서는 Chrome이 실행되지 않은 경우 `--remote-debugging-port=9222`로 자동 실행을 시도합니다.
+- **Chrome이 이미 CDP 없이 실행 중인 경우**: Chrome을 완전히 종료한 후 다시 시도해야 합니다. (최초 1회만 필요)
+- CDP 연결 성공 시 모든 브라우저 speaker는 ⚡자동 모드로 동작합니다.
+- Windows/Linux에서는 사용자가 직접 Chrome을 `--remote-debugging-port=9222`로 실행해야 합니다.
+
+### F. Chrome 확장 프로그램 사이드패널 지원
+- **Chrome 확장 프로그램 사이드패널 (chrome-extension:// URL)은 지원됩니다.**
+- Claude, ChatGPT, Gemini 등의 Chrome 확장 사이드패널도 CDP를 통해 deliberation 참가자로 사용 가능합니다.
+- 사이드패널은 title 기반 매칭으로 감지됩니다 (extension ID가 아닌 탭 제목으로 식별).
+- `deliberation_browser_llm_tabs`에서 사이드패널 탭이 `[Extension]` 태그와 함께 표시됩니다.
+- **절대로 "사이드패널은 지원 안 됨"이라고 안내하지 마세요.** 사이드패널은 일반 웹 탭과 동일하게 CDP로 자동화됩니다.
+
+## 역할 규칙
+
+### 역할 예시 A: 비판적 분석가
+- 제안의 약점을 먼저 찾는다
+- 구체적 근거와 수치를 요구한다
+- 리스크를 명시하되 대안을 함께 제시한다
+
+### 역할 예시 B: 현실적 실행가
+- 실행 가능성을 우선 평가한다
+- 구체적 기술 스택과 구현 방안을 제시한다
+- 비용/복잡도/일정을 현실적으로 산정한다
+
+## 응답 형식
+
+매 턴의 응답은 다음 구조를 따릅니다:
+
+```markdown
+**상대 평가:** (동의/반박/보완)
+**핵심 입장:** (구체적 제안)
+**근거:** (2-3개)
+**리스크/우려:** (약점 1-2개)
+**상대에게 질문:** (1-2개)
+**합의 가능 포인트:** (동의할 수 있는 것)
+**미합의 포인트:** (결론 안 난 것)
+```
+
+## 주의사항
+1. 여러 deliberation을 동시에 병렬 진행 가능
+2. session_id는 `deliberation_start` 응답에서 확인
+3. 토론 결과는 Obsidian vault에 자동 아카이브 (프로젝트 폴더 존재 시)
+4. 실시간 sync 파일은 state 디렉토리에 저장되며 완료 시 자동 삭제됨 (프로젝트 루트 오염 없음)
+5. `Transport closed` 발생 시 현재 CLI 세션 재시작 후 재시도 (stdio 연결은 세션 바인딩)
+6. 멀티 세션 운영 중 `pkill -f mcp-deliberation` 사용 금지 (다른 세션 연결까지 끊길 수 있음)

package/skills/deliberation-executor/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: deliberation-executor
+description: |
+  deliberation 합의안을 실제 구현으로 전환하는 실행 전용 스킬.
+  synthesis/결론을 작업 단위로 분해하고 코드 수정, 테스트, 검증까지 진행합니다.
+  "합의안 구현", "토론 결과 구현", "deliberation 구현", "synthesis 구현", "executor" 요청 시 사용합니다.
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+# Deliberation Executor
+
+토론(deliberation) 결과를 실제 코드 변경으로 연결하는 실행 스킬입니다.
+
+## 입력 기준
+
+다음 중 하나를 받아 구현을 시작합니다:
+
+1. `deliberation-{session_id}.md` 파일
+2. `deliberation_synthesize` 결과 텍스트
+3. 사용자가 직접 붙여넣은 합의안/결론
+
+입력이 불완전하면 즉시 확인:
+- 목표 산출물(코드/문서/스크립트)
+- 완료 조건(테스트 통과, 동작 확인, 품질 기준)
+- 범위(이번 턴에서 처리할 것과 제외할 것)
+
+## 실행 워크플로우
+
+### 1) 합의안 -> 실행 백로그 변환
+
+합의안을 3~8개 작업으로 분해합니다:
+- `task_id`
+- `목표`
+- `영향 파일/모듈`
+- `검증 방법`
+- `완료 기준`
+
+작업은 작고 독립적으로 나눕니다. 모호한 작업은 바로 구현하지 않고 먼저 구체화합니다.
+
+### 2) 적재적소 스킬/에이전트 라우팅
+
+요청 성격에 따라 필요한 보조 스킬을 함께 사용합니다:
+
+- 환경변수/배포 설정/direnv: `env-manager`
+- 스크린샷/클립보드 이미지 분석: `clipboard-image`
+- YouTube 링크 분석/요약 근거 추출: `youtube-analyzer`
+- 설계 불확실성이 큰 경우: 짧은 `deliberation` 세션 재개 후 합의 업데이트
+
+기본 원칙:
+- 구현은 이 스킬에서 진행
+- 조사/분석성 하위 작업만 보조 스킬로 위임
+
+### 3) 구현 루프
+
+각 task마다 아래 순서를 지킵니다:
+
+1. 관련 파일 탐색 (`rg`, `rg --files`)
+2. 최소 변경으로 코드 수정
+3. 영향 범위 테스트/검증 실행
+4. 실패 시 원인 수정 후 재검증
+5. task 상태 업데이트
+
+### 4) 결과 보고 형식
+
+최종 보고에는 반드시 포함:
+
+- 완료된 task 목록
+- 변경 파일 목록
+- 실행한 검증 명령과 결과 요약
+- 남은 리스크/미완료 task
+- 다음 액션(필요 시)
+
+## 품질 규칙
+
+- 합의안에 없는 기능 확장은 금지(범위 드리프트 방지)
+- 테스트가 있으면 반드시 실행하고 결과를 남김
+- 테스트가 없으면 최소 실행 검증 절차를 명시
+- 실패를 숨기지 말고 재현 가능한 형태로 보고
+
+## 빠른 시작 예시
+
+```text
+"deliberation 합의안 구현해줘. session_id는 abc123"
+"토론 결과를 코드로 반영하고 테스트까지 돌려줘"
+"synthesis 구현 진행하고 남은 리스크도 정리해줘"
+```