@dmsdc-ai/aigentry-deliberation 0.0.20 → 0.0.21

package/README.md

@@ -107,6 +107,22 @@ open demo/forum/index.html
 | `researcher` | Data, benchmarks, references |
 | `free` | No role constraint (default) |
 
+### deliberation-gate (Superpowers Integration)
+
+Inserts multi-AI verification gates at key [superpowers](https://github.com/anthropics/superpowers) workflow decision points.
+
+**Scenarios:**
+- **brainstorming** → multi-AI design validation before writing plans
+- **code-review** → multi-AI review via `deliberation_request_review`
+- **debugging** → multi-AI hypothesis verification when stuck
+
+**Trigger:** Semi-automatic — skill recommends deliberation, user approves.
+
+**Install:**
+```bash
+cp skills/deliberation-gate/SKILL.md ~/.claude/skills/deliberation-gate/SKILL.md
+```
+
 ## aigentry Ecosystem
 
 aigentry-deliberation is one component of the unified aigentry platform. All packages work together to make AI decisions transparent and auditable.

package/index.js

@@ -2739,9 +2739,24 @@ server.tool(
 
     const speaker = state.current_speaker;
     const { transport, profile, reason } = resolveTransportForSpeaker(state, speaker);
-    const guidance = formatTransportGuidance(transport, state, speaker);
     const turnId = state.pending_turn_id || null;
 
+    // ── Self-speaker detection ──
+    // If the current speaker is the same CLI as the orchestrator (caller),
+    // cli_auto_turn would recursively spawn the same process and timeout.
+    // Instead, instruct the orchestrator to respond directly.
+    const callerSpeaker = detectCallerSpeaker();
+    const isSelfSpeaker = callerSpeaker && speaker === callerSpeaker && transport === "cli_respond";
+
+    let guidance;
+    if (isSelfSpeaker) {
+      guidance = `🟢 **본인 턴입니다.** 당신(${speaker})이 현재 speaker입니다.\n\n` +
+        `직접 응답을 작성하여 \`deliberation_respond(session_id: "${state.id}", speaker: "${speaker}", content: "...")\`로 제출하세요.\n\n` +
+        `⚠️ **cli_auto_turn 사용 금지**: 자기 자신을 재귀 호출하면 타임아웃이 발생합니다. 반드시 직접 deliberation_respond를 사용하세요.`;
+    } else {
+      guidance = formatTransportGuidance(transport, state, speaker);
+    }
+
     let extra = "";
 
     if (transport === "browser_auto") {
@@ -2963,6 +2978,17 @@ server.tool(
       return { content: [{ type: "text", text: `speaker "${speaker}"는 CLI 타입이 아닙니다 (transport: ${transport}). 브라우저 speaker는 deliberation_browser_auto_turn을 사용하세요.` }] };
     }
 
+    // Block recursive self-spawn: if the speaker is the same CLI as the caller,
+    // spawning it would create infinite recursion and timeout.
+    const callerSpeaker = detectCallerSpeaker();
+    if (callerSpeaker && speaker === callerSpeaker) {
+      return { content: [{ type: "text", text:
+        `⚠️ **재귀 호출 차단**: speaker "${speaker}"는 현재 오케스트레이터와 동일한 CLI입니다.\n\n` +
+        `cli_auto_turn으로 자기 자신을 spawn하면 타임아웃이 발생합니다.\n` +
+        `직접 응답을 작성하여 \`deliberation_respond(session_id: "${resolved}", speaker: "${speaker}", content: "...")\`로 제출하세요.`
+      }] };
+    }
+
     const hint = CLI_INVOCATION_HINTS[speaker];
     if (!hint) {
       return { content: [{ type: "text", text: `speaker "${speaker}"에 대한 CLI 호출 정보가 없습니다. CLI_INVOCATION_HINTS에 등록되지 않은 speaker입니다.` }] };

package/install.js

@@ -13,6 +13,7 @@
  *   3. Registers MCP server in ~/.claude/.mcp.json (Claude Code)
  *   4. Registers MCP server in ~/.gemini/settings.json (Gemini CLI)
  *   5. Ready to use — next Claude Code or Gemini CLI session will auto-load
+ *   6. 스킬 파일 설치 (~/.claude/skills/deliberation-gate/SKILL.md)
  */
 
 import { execSync } from "node:child_process";
@@ -28,6 +29,10 @@ const INSTALL_DIR = IS_WIN
   : path.join(HOME, ".local", "lib", "mcp-deliberation");
 const MCP_CONFIG = path.join(HOME, ".claude", ".mcp.json");
 const GEMINI_CONFIG = path.join(HOME, ".gemini", "settings.json");
+const SKILL_SRC = path.join(__dirname, "skills", "deliberation-gate", "SKILL.md");
+const SKILL_DEST_DIR = path.join(HOME, ".claude", "skills", "deliberation-gate");
+const SKILL_DEST = path.join(SKILL_DEST_DIR, "SKILL.md");
+const MANIFEST_PATH = path.join(INSTALL_DIR, ".install-manifest.json");
 
 /** Normalize path to forward slashes for JSON config (Windows backslash → forward slash) */
 function toForwardSlash(p) {
@@ -175,12 +180,53 @@ function install() {
     } catch { /* ignore on Windows */ }
   }
 
-  // Step 6: Preserve existing config
+  // Step 6b: Preserve existing config
   const configPath = path.join(INSTALL_DIR, "config.json");
   if (!fs.existsSync(configPath)) {
     fs.writeFileSync(configPath, JSON.stringify({}, null, 2));
   }
 
+  // Step 7: Deploy deliberation-gate skill
+  log("🎓 deliberation-gate 스킬 파일 설치...");
+  if (!fs.existsSync(SKILL_SRC)) {
+    log("   ⚠️ 스킬 소스 파일 없음, 스킵: " + SKILL_SRC);
+  } else {
+    try {
+      fs.mkdirSync(SKILL_DEST_DIR, { recursive: true });
+      let shouldCopy = true;
+      if (fs.existsSync(SKILL_DEST) && !FORCE) {
+        const existing = fs.readFileSync(SKILL_DEST, "utf-8");
+        const incoming = fs.readFileSync(SKILL_SRC, "utf-8");
+        if (existing === incoming) {
+          log("   → 이미 최신 상태, 스킵");
+          shouldCopy = false;
+        } else {
+          fs.copyFileSync(SKILL_DEST, SKILL_DEST + ".backup");
+          log("   → 기존 파일 백업: SKILL.md.backup");
+        }
+      }
+      if (shouldCopy) {
+        fs.copyFileSync(SKILL_SRC, SKILL_DEST);
+        log("   → " + SKILL_DEST);
+      }
+    } catch (err) {
+      log(`   ⚠️ 스킬 설치 실패: ${err.message}`);
+    }
+  }
+
+  // Write install manifest
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf-8"));
+    const manifest = {
+      version: pkg.version,
+      installedAt: new Date().toISOString(),
+      skills: [SKILL_DEST],
+    };
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
+  } catch (err) {
+    log(`   ⚠️ manifest 작성 실패: ${err.message}`);
+  }
+
   // Done
   console.log("\n✅ 설치 완료!\n");
   console.log("  다음 단계:");
@@ -191,6 +237,7 @@ function install() {
 
 // Entry point
 const args = process.argv.slice(2);
+const FORCE = args.includes("--force");
 if (args.includes("--help") || args.includes("-h")) {
   console.log(`
 Deliberation MCP Server Installer
@@ -202,10 +249,18 @@ Usage:
 Options:
   --help, -h     이 도움말 표시
   --uninstall    서버 제거
+  --force        기존 스킬 파일 비교 없이 강제 덮어쓰기
+
+기능:
+  - 서버 파일을 설치 경로에 복사
+  - npm 의존성 설치
+  - Claude Code / Gemini CLI MCP 서버 등록
+  - 스킬 파일 설치 (~/.claude/skills/deliberation-gate/SKILL.md)
 
 설치 경로: ${INSTALL_DIR}
 MCP 설정:  ${MCP_CONFIG}
 Gemini:    ${GEMINI_CONFIG}
+스킬 경로: ${SKILL_DEST}
 `);
 } else if (args.includes("--uninstall") || args.includes("uninstall")) {
   console.log("\n🗑️ Deliberation MCP Server 제거\n");
@@ -234,6 +289,39 @@ Gemini:    ${GEMINI_CONFIG}
     } catch { /* ignore */ }
   }
 
+  // Remove skill files tracked by manifest (or fall back to default path)
+  let skillsToRemove = [SKILL_DEST];
+  const manifestFile = path.join(INSTALL_DIR, ".install-manifest.json");
+  if (fs.existsSync(manifestFile)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf-8"));
+      if (Array.isArray(manifest.skills) && manifest.skills.length > 0) {
+        skillsToRemove = manifest.skills;
+      }
+    } catch { /* use default */ }
+  }
+  for (const skillPath of skillsToRemove) {
+    if (fs.existsSync(skillPath)) {
+      try {
+        fs.rmSync(skillPath, { force: true });
+        log(`스킬 파일 삭제: ${skillPath}`);
+        const backupPath = skillPath + ".backup";
+        if (fs.existsSync(backupPath)) {
+          log(`  💡 백업 파일이 남아 있습니다: ${backupPath}`);
+          log(`     복원하려면: cp "${backupPath}" "${skillPath}"`);
+        }
+        // Remove directory if empty
+        const dir = path.dirname(skillPath);
+        if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+          fs.rmdirSync(dir);
+          log(`빈 스킬 디렉토리 삭제: ${dir}`);
+        }
+      } catch (err) {
+        log(`  ⚠️ 스킬 파일 삭제 실패: ${err.message}`);
+      }
+    }
+  }
+
   // Remove install directory
   if (fs.existsSync(INSTALL_DIR)) {
     fs.rmSync(INSTALL_DIR, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-deliberation",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "MCP Deliberation Server — Multi-session AI deliberation with smart speaker ordering and persona roles",
   "type": "module",
   "license": "MIT",

package/skills/deliberation/SKILL.md

@@ -176,3 +176,8 @@ bash deliberation-monitor.sh --tmux
 4. 실시간 sync 파일은 state 디렉토리에 저장되며 완료 시 자동 삭제됨 (프로젝트 루트 오염 없음)
 5. `Transport closed` 발생 시 현재 CLI 세션 재시작 후 재시도 (stdio 연결은 세션 바인딩)
 6. 멀티 세션 운영 중 `pkill -f mcp-deliberation` 사용 금지 (다른 세션 연결까지 끊길 수 있음)
+
+## 관련 스킬
+
+- **deliberation-gate**: superpowers 워크플로우 통합 스킬. brainstorming/code-review/debugging 의사결정 지점에 멀티-AI 검증 게이트를 삽입합니다. `~/.claude/skills/deliberation-gate/SKILL.md`에 설치.
+- **deliberation-executor**: deliberation 합의안을 실제 코드 구현으로 전환하는 실행 전용 스킬.

package/skills/deliberation-gate/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: deliberation-gate
+description: |
+  Use after brainstorming produces design doc, after code-review produces feedback,
+  when debugging hits dead end with failed hypotheses, or when user says
+  "deliberate this", "토론해줘", "검증해줘", "멀티-AI 리뷰", "multi-AI verify"
+version: 0.1.0
+prerequisites:
+  mcp: ["aigentry-deliberation"]
+fallback: self-criticism
+---
+
+# Deliberation Gate — Multi-AI Verification for Superpowers Workflows
+
+Insert multi-AI deliberation gates at key decision points in superpowers workflow chains.
+Uses aigentry-deliberation MCP tools to orchestrate structured debate between multiple AI systems.
+
+**Semi-automatic**: Recommends deliberation at decision points. User approves before starting.
+
+## Context Detection
+
+Detect the current workflow context by checking these signals IN ORDER:
+
+| Priority | Signal | Context |
+|----------|--------|---------|
+| 1 | User says "deliberate", "토론", "debate", "검증", "멀티-AI" | explicit |
+| 2 | Design doc recently written in session (docs/plans/*-design.md) | brainstorming |
+| 3 | git diff output, PR number, or code review feedback in conversation | code-review |
+| 4 | Error traces + failed hypotheses / "root cause" in conversation | debugging |
+| 5 | None of above | general |
+
+### Scenario Preset Map
+
+| Context | preset | rounds | roles | MCP path |
+|---------|--------|--------|-------|----------|
+| brainstorming | brainstorm | 2 | critic, implementer, researcher | deliberation_start → route_turn loop → synthesize |
+| code-review | review | 1 | critic, implementer | deliberation_request_review (lightweight) |
+| debugging | research | 2 | researcher, implementer, critic | deliberation_start → route_turn loop → synthesize |
+| general | balanced | 3 | user-selected via AskUserQuestion | deliberation_start → route_turn loop → synthesize |
+
+## Recommendation Protocol (Semi-Automatic)
+
+When you detect a decision point, recommend deliberation to the user.
+
+### Step 1: Detect and Announce
+
+Announce the detected context:
+
+> 🔔 **멀티-AI 검증 추천** — [context] 시나리오 감지
+>
+> 이 [설계안/코드 리뷰/디버깅 가설]을 다른 AI의 관점으로 검증하면 더 견고해질 수 있습니다.
+
+### Step 2: Ask User
+
+Use AskUserQuestion to get approval:
+
+```
+AskUserQuestion:
+  question: "이 [artifact]을 멀티-AI 토론으로 검증할까요?"
+  header: "멀티-AI 검증"
+  options:
+    - label: "시작 (Recommended)"
+      description: "[preset] preset, [N]라운드, [roles] 역할로 deliberation 시작"
+    - label: "설정 변경 후 시작"
+      description: "preset, rounds, roles를 직접 선택"
+    - label: "건너뛰기"
+      description: "deliberation 없이 원래 워크플로우 계속"
+```
+
+### Step 3: On Decline
+
+If user chooses "건너뛰기":
+- Do NOT persist or re-ask
+- Continue the original workflow immediately
+- No penalty, no warning
+
+## Deliberation Execution
+
+When user approves, execute this sequence:
+
+### Standard Path (brainstorming, debugging, general)
+
+1. **Speaker discovery**: `deliberation_speaker_candidates` → get available CLI + browser speakers
+2. **Speaker selection**: `AskUserQuestion(multiSelect: true)` → user selects which speakers to include
+3. **Start deliberation**: `deliberation_start`
+   - `topic`: the artifact being validated (design summary / error description + hypotheses / user's question)
+   - `speakers`: user-selected list
+   - `speaker_roles`: from scenario preset map above
+   - `rounds`: from scenario preset map above
+   - `ordering_strategy`: "auto"
+   - `role_preset`: from scenario preset map above
+4. **Turn loop**: For each turn:
+   - Call `deliberation_route_turn` — it auto-detects the correct transport
+   - **Self-speaker** (you are the current speaker): Compose your response based on your role, submit via `deliberation_respond(speaker: "claude", content: "...")`
+   - **Other CLI speaker**: `deliberation_route_turn` will guide to `deliberation_cli_auto_turn` which spawns the actual CLI
+   - **Browser speaker**: `deliberation_route_turn` will auto-execute via CDP
+5. **Synthesize**: After all rounds complete, call `deliberation_synthesize` with a summary of the consensus
+6. **Apply synthesis**: Follow the Integration Rules below
+
+### Lightweight Path (code-review only)
+
+1. **Speaker discovery**: `deliberation_speaker_candidates` → get available speakers
+2. **Reviewer selection**: `AskUserQuestion(multiSelect: true)` → user selects reviewers
+3. **Request review**: `deliberation_request_review`
+   - `context`: the diff or code under review
+   - `question`: "이 코드 변경사항을 리뷰해주세요. 버그, 설계 문제, 보안 취약점을 중심으로."
+   - `reviewers`: user-selected list
+   - `mode`: "sync"
+   - `deadline_ms`: 120000
+4. **Apply results**: Follow the Integration Rules below
+
+## Synthesis Integration Rules
+
+### brainstorming → design doc update
+
+After deliberation on a design:
+1. Read the synthesis from `deliberation_synthesize`
+2. Append a `## 멀티-AI 합의` section to the design doc with:
+   - **합의 사항**: Key agreements from all participants
+   - **이견**: Dissenting points (if any)
+   - **권장 변경**: Concrete changes recommended by consensus
+3. Apply the agreed changes to the design document
+4. Continue to `writing-plans` skill with the updated design
+
+### code-review → receiving-code-review
+
+After multi-AI code review:
+1. Parse review results into severity categories:
+   - **Critical**: Must fix before merge
+   - **Major**: Should fix
+   - **Minor**: Optional improvements
+2. Present the categorized feedback to user
+3. Continue to `receiving-code-review` skill workflow
+
+### debugging → hypothesis reordering
+
+After deliberation on debugging hypotheses:
+1. Extract the consensus hypothesis ranking from synthesis
+2. Update the debugging state:
+   - Move consensus-top hypothesis to position 1
+   - Mark disproven hypotheses as eliminated
+   - Add any new hypotheses suggested by other AIs
+3. Resume `systematic-debugging` with the new priorities
+
+### general → user-directed
+
+For explicit or general deliberation:
+1. Present the synthesis summary to user
+2. Ask how to proceed with the consensus
+3. Follow user's direction
+
+## MCP 미설치 시 Fallback (Graceful Degradation)
+
+deliberation MCP 도구(`deliberation_start`, `deliberation_speaker_candidates` 등)가 사용 불가능할 경우:
+
+### 감지 방법
+- MCP 도구 호출 시 "tool not found" 또는 연결 실패 에러 발생
+- `deliberation_speaker_candidates` 호출이 실패하면 MCP 미설치로 판단
+
+### Fallback 프로토콜
+
+1. **안내**: AskUserQuestion으로 상황 설명
+   ```
+   question: "멀티-AI 검증 MCP 서버가 감지되지 않았습니다. 단일 모델 자가 검증으로 대체할까요?"
+   options:
+     - label: "자가 검증 진행"
+       description: "3관점 self-criticism으로 검증 (Silver 등급)"
+     - label: "MCP 설치 안내"
+       description: "npx @dmsdc-ai/aigentry-deliberation install 실행 방법 안내"
+     - label: "건너뛰기"
+       description: "검증 없이 원래 워크플로우 계속"
+   ```
+
+2. **Self-Criticism 실행** (자가 검증 선택 시):
+   - 동일 artifact에 대해 3가지 관점으로 순차 분석:
+     - **비판적 분석가**: 약점, 리스크, 누락된 고려사항
+     - **현실적 실행가**: 구현 가능성, 비용, 복잡도
+     - **리서처**: 대안, 선례, 데이터 기반 근거
+   - 3관점 결과를 종합하여 합의 포맷으로 출력
+
+3. **투명성 라벨링**:
+   - 모든 검증 결과에 출처 라벨 필수 표시:
+     - `🥇 Verification: Multi-AI Deliberation (Gold)` — 실제 멀티-AI 토론 결과
+     - `🥈 Verification: Self-Criticism (Silver)` — 단일 모델 자가 검증 결과
+   - 라벨은 합의 섹션 상단에 표시
+
+### MCP 설치 안내 (선택 시)
+```
+npx @dmsdc-ai/aigentry-deliberation install
+```
+설치 후 Claude Code 세션을 재시작하면 멀티-AI 검증이 활성화됩니다.
+
+## Anti-Patterns (NEVER)
+
+1. **NEVER skip user approval** — Always use AskUserQuestion before starting deliberation. This is a HARD GATE.
+2. **NEVER fabricate speaker responses** — Use `deliberation_route_turn` for other speakers. Never write responses on behalf of codex, gemini, or any other speaker. The MCP server blocks this.
+3. **NEVER use cli_auto_turn for self-speaker** — If you (claude) are the current speaker, compose your response and submit via `deliberation_respond` directly. Using `cli_auto_turn` would recursively spawn yourself and timeout.
+4. **NEVER re-ask after decline** — If user chooses "건너뛰기", respect it immediately. Do not ask again.
+5. **NEVER block on deliberation failure** — If MCP tools fail (server not running, speaker unavailable), warn the user and continue the original workflow. Deliberation is enhancement, not requirement.
+6. **NEVER modify existing superpowers skills** — This skill is purely additive. It works alongside existing skills without changing them.
+7. **NEVER omit verification source label** — 모든 검증 결과에 Gold/Silver 라벨을 반드시 표시. Self-criticism 결과를 Multi-AI 결과와 구분 없이 제시하면 신뢰도를 왜곡한다.
+
+## Workflow Position
+
+```
+brainstorming ──────→ [deliberation-gate] → writing-plans → executing-plans
+code-review ────────→ [deliberation-gate] → receiving-code-review
+systematic-debugging → [deliberation-gate] → resume with consensus
+explicit request ───→ [deliberation-gate] → context-dependent
+```
+
+This skill is invoked BETWEEN existing superpowers skills, not within them. It consumes the output of one skill and feeds enhanced output to the next.