@joseph0926/plan-loop 1.0.0

package/README.ko.md

@@ -0,0 +1,245 @@
+# Plan Loop
+
+Plan Loop는 Claude-Code(설계자)와 Codex(검토자) 간의 비동기 계획 검토 루프를 디스크의 세션 상태 공유를 통해 가능하게 하는 MCP 서버입니다.
+
+## 저장소 구조
+
+- src/: MCP 서버 소스 코드 (Node.js + TypeScript)
+- .mcp.json.example: MCP 서버 설정 샘플 (`.mcp.json`으로 복사하여 사용)
+
+## 빠른 시작
+
+1) 설치 및 설정 (권장)
+
+```bash
+# npx로 1회 실행 (설치 불필요)
+npx @joseph0926/plan-loop setup
+
+# 또는 글로벌 설치
+npm install -g @joseph0926/plan-loop
+plan-loop setup
+```
+
+### 설정 옵션
+
+```bash
+plan-loop setup                    # Claude (project) + Codex (user) 모두 설정
+plan-loop setup --claude           # Claude Code만 (project scope)
+plan-loop setup --claude --user    # Claude Code (user scope, ~/.claude.json)
+plan-loop setup --codex            # Codex만 (user scope)
+```
+
+2) 수동 등록 (선택)
+
+**Claude Code** - `.mcp.json` (프로젝트) 또는 `~/.claude.json` (사용자)에 추가:
+
+```json
+{
+  "mcpServers": {
+    "plan-loop": {
+      "command": "npx",
+      "args": ["-y", "@joseph0926/plan-loop"]
+    }
+  }
+}
+```
+
+**Codex** - `~/.codex/config.toml`에 추가:
+
+```toml
+[mcp_servers.plan-loop]
+command = "npx"
+args = ["-y", "@joseph0926/plan-loop"]
+```
+
+3) 도구 사용 예시
+
+```text
+pl_start({ goal: "로그인 기능 계획" })
+pl_submit({ session_id: "abc123", plan: "1. ..." })
+pl_get_plan({ session_id: "abc123" })
+pl_feedback({ session_id: "abc123", rating: "🟢", content: "LGTM" })
+```
+
+## 도구 목록
+
+- pl_start: 세션 시작
+- pl_submit: 계획 제출
+- pl_get_plan: 최신 계획 조회
+- pl_feedback: 최신 계획에 대한 피드백 제출
+- pl_get_feedback: 최신 피드백 조회
+- pl_status: 전체 세션 데이터 조회
+- pl_list: 모든 세션 목록 (필터/정렬 지원)
+- pl_delete: 세션 삭제
+- pl_force_approve: exhausted 세션 강제 승인
+
+## 에이전트 협업
+
+Claude-Code(설계자)와 Codex(검토자)가 협업하여 계획을 검토합니다.
+
+### 빠른 시작
+
+```text
+# 1. Claude-Code: 세션 시작 및 계획 제출
+pl_start({ goal: "로그인 기능 구현" })
+pl_submit({ session_id: "...", plan: "1. DB 스키마..." })
+
+# 2. Codex: 계획 조회 및 피드백
+pl_get_plan({ session_id: "..." })
+pl_feedback({ session_id: "...", rating: "🟡", content: "인증 방식 명시 필요" })
+
+# 3. Claude-Code: 피드백 확인 및 수정
+pl_get_feedback({ session_id: "..." })
+pl_submit({ session_id: "...", plan: "수정된 계획..." })
+
+# 4. Codex: 승인
+pl_feedback({ session_id: "...", rating: "🟢", content: "LGTM" })
+```
+
+### 역할별 상세 지침
+
+자세한 워크플로우와 피드백 자동완성 가이드는 [AGENTS.md](AGENTS.md) 참조.
+
+## 상태 저장
+
+세션 파일은 `~/.plan-loop/sessions/`에 저장됩니다.
+
+## 상태 전이
+
+```
+                              pl_start
+                                  │
+                                  ▼
+                            [drafting]
+                                  │
+                             pl_submit
+                                  │
+                                  ▼
+                          [pending_review]
+                                  │
+                            pl_feedback
+                                  │
+        ┌─────────────────────────┼─────────────────────────┐
+        ▼                         ▼                         ▼
+    🔴 / 🟡                      🟢                   iteration >= max
+        │                         │                         │
+        ▼                         ▼                         ▼
+[pending_revision]           [approved]              [exhausted]
+        │                         │                         │
+   pl_submit                  pl_delete               pl_force_approve
+        │                         │                         │
+        ▼                         ▼                         ▼
+[pending_review]              [deleted]               [approved]
+```
+
+## 응답 형식
+
+### 성공 응답 (데이터 있음)
+```typescript
+{ ready: true, data: { ... } }
+```
+
+### 대기 응답 (데이터 없음)
+```typescript
+{ ready: false, reason: "no_plan_submitted" | "no_feedback_yet" | "awaiting_feedback" }
+```
+
+#### Pending reason 매핑
+- `pl_get_plan`: plan 없음 → `no_plan_submitted`
+- `pl_get_feedback`:
+  - plan 없음 → `no_plan_submitted`
+  - 최신 plan에 대한 피드백 대기 → `awaiting_feedback`
+  - 기타 피드백 없음 → `no_feedback_yet`
+
+### 에러 응답
+```typescript
+{
+  isError: true,
+  content: [{ type: "text", text: "Invalid state: current='approved', expected=['drafting']" }]
+}
+```
+
+## 세션 관리
+
+### pl_list 필터링 및 정렬
+
+```
+// status 필터
+> pl_list({ status: "approved" })
+> pl_list({ status: ["drafting", "pending_review"] })
+
+// 정렬
+> pl_list({ sort: "createdAt", order: "asc" })
+> pl_list({ sort: "updatedAt", order: "desc" })  // 기본값
+```
+
+### pl_delete 세션 삭제
+
+```
+// approved/exhausted 세션 삭제
+> pl_delete({ session_id: "abc123" })
+
+// 활성 세션 삭제 (force 필요)
+> pl_delete({ session_id: "abc123", force: true })
+```
+
+## 버전 규칙
+
+| 필드 | 증가 시점 |
+|------|-----------|
+| `version` | `pl_submit` 호출 시 +1 |
+| `iteration` | `pl_feedback`에서 🔴/🟡 시 +1 |
+
+`maxIterations`는 기본값 5이며 **1 이상의 정수**만 허용됩니다.
+
+## 설계 결정
+
+### 최신 plan 자동 매핑
+- `pl_feedback`은 항상 최신 plan에 매핑됨
+- planVersion 파라미터 없음 (단순화)
+- **Trade-off**: 동시 호출 시 race condition 가능 → 운영 규칙으로 관리
+
+### 역할 구분
+- 서버는 호출자를 검증하지 않음
+- Claude-Code는 submit 계열, Codex는 feedback 계열 사용 (약속)
+
+### 상태 영속화
+- `~/.plan-loop/sessions/{id}.json`
+- Atomic write (temp → rename)
+
+### goal 길이 제한
+- `pl_list` 응답에서 goal은 30자(UTF-16 코드 유닛 기준) 초과 시 `...` 추가
+- 최대 33자 (30자 + "...")
+
+## 개발
+
+```bash
+npm run dev
+npm run build
+```
+
+## 샘플 설정 파일
+
+프로젝트에 MCP 설정을 추가하려면:
+
+```bash
+cp .mcp.json.example .mcp.json
+```
+
+## 테스트
+
+```bash
+npm test              # 테스트 실행
+npm run test:watch    # 워치 모드
+npm run test:coverage # 커버리지 리포트
+```
+
+테스트 격리를 위해 `PLAN_LOOP_STATE_DIR` 환경변수를 지원합니다:
+
+```bash
+PLAN_LOOP_STATE_DIR=/tmp/test-sessions npm test
+```
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,124 @@
+# Plan Loop
+
+Plan Loop is an MCP server that enables an asynchronous plan review loop between Claude-Code (planner) and Codex (reviewer) by sharing session state on disk.
+
+## Repository layout
+
+- src/: MCP server source code (Node.js + TypeScript)
+- .mcp.json.example: sample MCP server configuration (copy to `.mcp.json` to use)
+
+## Quick start
+
+1) Install & setup (recommended)
+
+```bash
+# Run once with npx (no install)
+npx @joseph0926/plan-loop setup
+
+# Or install globally
+npm install -g @joseph0926/plan-loop
+plan-loop setup
+```
+
+### Setup options
+
+```bash
+plan-loop setup                    # Setup both Claude (project) + Codex (user)
+plan-loop setup --claude           # Claude Code only (project scope)
+plan-loop setup --claude --user    # Claude Code (user scope, ~/.claude.json)
+plan-loop setup --codex            # Codex only (user scope)
+```
+
+2) Manual registration (optional)
+
+**Claude Code** - Add to `.mcp.json` (project) or `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "plan-loop": {
+      "command": "npx",
+      "args": ["-y", "@joseph0926/plan-loop"]
+    }
+  }
+}
+```
+
+**Codex** - Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.plan-loop]
+command = "npx"
+args = ["-y", "@joseph0926/plan-loop"]
+```
+
+3) Use tools (example)
+
+```text
+pl_start({ goal: "Plan a login feature" })
+pl_submit({ session_id: "abc123", plan: "1. ..." })
+pl_get_plan({ session_id: "abc123" })
+pl_feedback({ session_id: "abc123", rating: "🟢", content: "LGTM" })
+```
+
+## Tool list
+
+- pl_start: start a session
+- pl_submit: submit a plan
+- pl_get_plan: fetch the latest plan
+- pl_feedback: submit feedback for the latest plan
+- pl_get_feedback: fetch the latest feedback
+- pl_status: fetch full session data
+- pl_list: list all sessions (with filter/sort)
+- pl_delete: delete a session
+- pl_force_approve: approve an exhausted session
+
+## Agent Collaboration
+
+Claude-Code (planner) and Codex (reviewer) collaborate to review plans.
+
+### Quick Start
+
+```text
+# 1. Claude-Code: Start session and submit plan
+pl_start({ goal: "Implement login feature" })
+pl_submit({ session_id: "...", plan: "1. DB schema..." })
+
+# 2. Codex: Fetch plan and provide feedback
+pl_get_plan({ session_id: "..." })
+pl_feedback({ session_id: "...", rating: "🟡", content: "Please specify auth method" })
+
+# 3. Claude-Code: Check feedback and revise
+pl_get_feedback({ session_id: "..." })
+pl_submit({ session_id: "...", plan: "Revised plan..." })
+
+# 4. Codex: Approve
+pl_feedback({ session_id: "...", rating: "🟢", content: "LGTM" })
+```
+
+### Detailed Agent Guidelines
+
+See [AGENTS.md](AGENTS.md) for detailed workflows and feedback auto-completion guide.
+
+## State storage
+
+Session files are stored under `~/.plan-loop/sessions/`.
+
+## Development
+
+```bash
+npm run dev
+npm run build
+```
+
+## Sample configuration
+
+To add MCP configuration to your project:
+
+```bash
+cp .mcp.json.example .mcp.json
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Plan Loop CLI
+ * Setup MCP server for Claude Code and Codex
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Plan Loop CLI
+ * Setup MCP server for Claude Code and Codex
+ */
+import { setupClaude } from './setup/claude.js';
+import { setupCodex } from './setup/codex.js';
+const HELP_TEXT = `
+plan-loop - MCP server for Claude Code and Codex collaboration
+
+Usage:
+  plan-loop                     Start MCP server (default)
+  plan-loop setup [options]     Configure MCP for Claude Code and/or Codex
+
+Setup Options:
+  --claude          Setup Claude Code only (default: project scope)
+  --codex           Setup Codex only (always user scope)
+  --user            Use user scope for Claude Code (~/.claude.json)
+  --help, -h        Show this help message
+
+Examples:
+  npx @joseph0926/plan-loop setup              # Setup both Claude + Codex
+  npx @joseph0926/plan-loop setup --claude     # Claude Code only (project)
+  npx @joseph0926/plan-loop setup --codex      # Codex only
+  npx @joseph0926/plan-loop setup --user       # Claude Code user scope
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    // Help
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(HELP_TEXT);
+        process.exit(0);
+    }
+    // Setup command
+    if (command === 'setup') {
+        const claudeOnly = args.includes('--claude');
+        const codexOnly = args.includes('--codex');
+        const userScope = args.includes('--user');
+        const both = !claudeOnly && !codexOnly;
+        console.log('🔧 Plan Loop Setup\n');
+        let success = true;
+        if (both || claudeOnly) {
+            const scope = userScope ? 'user' : 'project';
+            console.log(`📦 Claude Code (${scope} scope)...`);
+            const result = await setupClaude({ scope });
+            if (result.success) {
+                console.log(`   ✅ ${result.message}\n`);
+            }
+            else {
+                console.log(`   ❌ ${result.message}\n`);
+                success = false;
+            }
+        }
+        if (both || codexOnly) {
+            console.log('📦 Codex (user scope)...');
+            const result = await setupCodex();
+            if (result.success) {
+                console.log(`   ✅ ${result.message}\n`);
+            }
+            else {
+                console.log(`   ❌ ${result.message}\n`);
+                success = false;
+            }
+        }
+        if (success) {
+            console.log('🎉 Setup complete!\n');
+            console.log('Verify with:');
+            if (both || claudeOnly)
+                console.log('  claude mcp list');
+            if (both || codexOnly)
+                console.log('  codex mcp list');
+            console.log('\nOr use /mcp command inside the IDE.');
+        }
+        else {
+            console.log('⚠️  Setup completed with some errors.');
+            process.exit(1);
+        }
+        return;
+    }
+    // Default: start MCP server
+    if (!command || command.startsWith('-')) {
+        // Dynamic import to start MCP server
+        await import('./index.js');
+        return;
+    }
+    // Unknown command
+    console.error(`Unknown command: ${command}`);
+    console.log(HELP_TEXT);
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Plan Loop MCP Server
+ * Claude-Code와 Codex 간의 비동기 협업을 위한 MCP 서버
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}