ralph-mcp 1.0.1 → 1.0.2

package/README.md

@@ -3,21 +3,46 @@
 [![npm version](https://badge.fury.io/js/ralph-mcp.svg)](https://www.npmjs.com/package/ralph-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.
+**Parallel Ralph loop**: PRD → `ralph_start` → merged. Run multiple PRDs simultaneously in isolated worktrees with auto quality gates and merge.
 
 Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
 
 [中文文档](./README.zh-CN.md)
 
+## The Ralph Loop (2 Steps)
+
+```
+Step 1: Generate PRD
+User: "Create a PRD for user authentication"
+Claude: [Generates tasks/prd-auth.md]
+
+Step 2: Execute
+User: "Start" or "Execute this PRD"
+Claude: ralph_start → Task Agent handles everything automatically
+```
+
+**That's it.** Ralph MCP automatically handles: branch creation, worktree isolation, code implementation, quality checks, commits, merge, and doc sync.
+
+## Why Ralph MCP?
+
+| Without Ralph | With Ralph |
+|---------------|------------|
+| One feature at a time | Multiple features in parallel |
+| Manual PRD writing | Claude generates PRD for you |
+| Manual git branch management | Automatic worktree isolation |
+| Lost progress on restart | Persistent state (JSON) |
+| Manual merge coordination | Auto merge with conflict resolution |
+| No visibility into progress | Real-time status tracking |
+
 ## Features
 
-- **PRD Parsing** - Extracts User Stories from markdown PRD files
-- **Git Worktree Isolation** - Each PRD runs in isolated worktree
-- **Background Execution** - Works with Claude Code's Task tool for parallel PRD execution
-- **Progress Tracking** - Real-time status via `ralph_status()`
-- **Auto Merge** - One-click merge with conflict resolution
+- **2-Step Workflow** - Just create PRD and run `ralph_start`, everything else is automatic
+- **Parallel Execution** - Run 5+ PRDs simultaneously with Claude Code Task tool
+- **Git Worktree Isolation** - Each PRD runs in its own worktree, zero conflicts
+- **Auto Quality Gates** - Type check, lint, build before every commit
+- **Auto Merge** - Merges to main when all User Stories pass
+- **Doc Sync** - Automatically updates TODO.md with completed items
 - **Notifications** - Windows Toast when PRD completes
-- **State Persistence** - Survives Claude Code restarts (JSON storage)
 
 ## Installation
 
@@ -66,6 +91,36 @@ Or if installed from source:
 
 Restart Claude Code to load.
 
+## Claude Code Skill Setup (Recommended)
+
+For the best experience, create a skill file that teaches Claude how to use Ralph.
+
+See **[SKILL-EXAMPLE.md](./SKILL-EXAMPLE.md)** for a complete, copy-paste ready skill configuration.
+
+### Quick Setup
+
+```bash
+# 1. Create skill directory
+mkdir -p .claude/skills/ralph
+
+# 2. Copy the example (adjust path as needed)
+cp /path/to/ralph-mcp/SKILL-EXAMPLE.md .claude/skills/ralph/SKILL.md
+
+# 3. Customize quality check commands for your project
+```
+
+### Add to CLAUDE.md (optional)
+
+```markdown
+## Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `ralph` | PRD execution (generate PRD → start → auto merge) |
+```
+
+This enables Claude to automatically use Ralph when you mention PRD execution.
+
 ## Tools
 
 | Tool | Description |
@@ -81,65 +136,53 @@ Restart Claude Code to load.
 
 ## Usage
 
-### Basic Workflow
-
-```javascript
-// 1. Start PRD execution
-ralph_start({ prdPath: "tasks/prd-feature.md" })
+### Typical Session
 
-// 2. Check status anytime
-ralph_status()
-
-// 3. Merge when complete
-ralph_merge({ branch: "ralph/prd-feature" })
 ```
+User: Help me finish the Speaking module from TODO.md
 
-### Parallel Execution with Claude Code Task Tool
+Claude: Let me check TODO.md... Found 3 incomplete items:
+  - Speaking dialogue practice
+  - Speaking scoring optimization
+  - Speaking question bank
 
-Ralph MCP is designed to work with Claude Code's Task tool for parallel PRD execution:
+I'll create 3 PRDs...
+[Generates prd-speaking-dialogue.md]
+[Generates prd-speaking-scoring.md]
+[Generates prd-speaking-qb.md]
 
-```
-1. Analyze PRDs to identify independent tasks that can run in parallel
-2. Start multiple PRDs via ralph_start()
-3. Launch background Task agents for each PRD
-4. Continue chatting - plan next features, review code, etc.
-5. Get Windows Toast notification when PRDs complete
-6. Merge completed PRDs to main via ralph_merge()
-```
+User: Start
 
-**Example session:**
+Claude:
+[ralph_start × 3]
+[Task Agent × 3 running in parallel]
 
-```
-User: Execute these 3 PRDs in parallel
-
-Claude: Let me analyze the PRDs...
-        - prd-auth.md (independent)
-        - prd-dashboard.md (independent)
-        - prd-api.md (independent)
-
-        All 3 can run in parallel. Starting...
+3 PRDs started. They'll auto-merge when complete.
+Use ralph_status to check progress.
 
-        [Calls ralph_start() for each PRD]
-        [Launches 3 background Task agents]
+--- Some time later ---
 
-        PRDs are running in background. You can continue working.
-        I'll notify you when they complete.
+User: Progress?
 
-User: Great, let's plan the next feature while waiting...
+Claude: [ralph_status]
+✅ prd-speaking-dialogue - Merged
+✅ prd-speaking-scoring - Merged
+🔄 prd-speaking-qb - US-003/005 in progress
 
-[Later - Windows Toast notification appears]
+User: 👍
+```
 
-Claude: All 3 PRDs completed successfully!
-        - ralph/prd-auth: 4/4 US ✓
-        - ralph/prd-dashboard: 3/3 US ✓
-        - ralph/prd-api: 5/5 US ✓
+### Manual Workflow
 
-        Ready to merge?
+```javascript
+// 1. Start PRD execution
+ralph_start({ prdPath: "tasks/prd-feature.md" })
 
-User: Yes, merge all
+// 2. Check status anytime
+ralph_status()
 
-Claude: [Calls ralph_merge() for each branch]
-        All PRDs merged to main successfully.
+// 3. Manual merge if needed (usually automatic)
+ralph_merge({ branch: "ralph/prd-feature" })
 ```
 
 ### API Reference

package/README.zh-CN.md

@@ -3,21 +3,31 @@
 [![npm version](https://badge.fury.io/js/ralph-mcp.svg)](https://www.npmjs.com/package/ralph-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-用于 Claude Code 自主执行 PRD 的 MCP 服务器。支持 Git worktree 隔离、进度追踪、自动合并。
+自主并行执行 PRD 的 Claude Code MCP 服务器。自动解析 PRD、创建隔离 worktree、追踪进度、合并完成的功能。
 
 基于 [Geoffrey Huntley 的 Ralph 模式](https://ghuntley.com/ralph/)。
 
 [English](./README.md)
 
+## 为什么选择 Ralph MCP？
+
+| 没有 Ralph | 有 Ralph |
+|------------|----------|
+| 一次只能做一个功能 | 多个功能并行执行 |
+| 手动管理 git 分支 | 自动 worktree 隔离 |
+| 重启后进度丢失 | 状态持久化（JSON） |
+| 手动协调合并 | 串行合并队列 |
+| 看不到执行进度 | 实时状态追踪 |
+
 ## 特性
 
-- **PRD 解析** - 从 markdown PRD 文件中提取 User Stories
-- **Git Worktree 隔离** - 每个 PRD 在独立的 worktree 中运行
-- **后台执行** - 配合 Claude Code 的 Task 工具并行执行多个 PRD
+- **并行执行** - 配合 Claude Code Task 工具同时执行多个 PRD
+- **Git Worktree 隔离** - 每个 PRD 在独立 worktree 中运行，零冲突
+- **智能合并队列** - 串行合并避免并行合并冲突
 - **进度追踪** - 通过 `ralph_status()` 实时查看状态
-- **自动合并** - 一键合并，支持冲突解决策略
-- **完成通知** - PRD 完成时弹出 Windows Toast 通知
 - **状态持久化** - 重启 Claude Code 不丢失状态（JSON 存储）
+- **自动合并** - 一键合并，支持多种冲突解决策略
+- **完成通知** - PRD 完成时弹出 Windows Toast 通知
 
 ## 安装
 

package/dist/tools/merge.js

@@ -92,7 +92,7 @@ export async function merge(input) {
         const commitMessage = generateCommitMessage(exec.branch, exec.description, completedStories);
         // Step 4: Attempt merge to main
         console.log(">>> Merging to main...");
-        const mergeResult = await mergeBranchWithMessage(exec.projectRoot, exec.branch, commitMessage, onConflict);
+        const mergeResult = await mergeBranchWithMessage(exec.projectRoot, exec.worktreePath || undefined, exec.branch, commitMessage, onConflict);
         if (mergeResult.success) {
             // Step 5: Update docs
             const docsUpdated = [];
@@ -138,7 +138,9 @@ export async function merge(input) {
                     : { typeCheck: true, build: true },
                 docsUpdated: docsUpdated.length > 0 ? docsUpdated : undefined,
                 mergedStories: completedStories.map((s) => s.id),
-                message: `Successfully merged ${input.branch} to main`,
+                message: mergeResult.alreadyMerged
+                    ? `Branch ${input.branch} was already merged to main`
+                    : `Successfully merged ${input.branch} to main`,
             };
         }
         // Handle conflicts
@@ -250,13 +252,56 @@ export async function merge(input) {
 }
 /**
  * Merge branch with custom commit message
+ * Always merges in projectRoot (main repo) since it's already on main branch.
+ * Worktree is only used for development, not for merging.
  */
-async function mergeBranchWithMessage(projectRoot, branch, commitMessage, onConflict) {
+async function mergeBranchWithMessage(projectRoot, _worktreePath, // Unused, kept for API compatibility
+branch, commitMessage, onConflict) {
     const { exec: execAsync } = await import("child_process");
     const { promisify } = await import("util");
     const execPromise = promisify(execAsync);
-    // Checkout main and pull
-    await execPromise("git checkout main && git pull", { cwd: projectRoot });
+    // Always merge in projectRoot (main repo is already on main branch)
+    const cwd = projectRoot;
+    // Check if origin remote exists
+    let hasOrigin = false;
+    try {
+        const { stdout } = await execPromise("git remote", { cwd });
+        hasOrigin = stdout.includes("origin");
+    }
+    catch {
+        hasOrigin = false;
+    }
+    // Fetch latest main and pull
+    if (hasOrigin) {
+        try {
+            await execPromise("git fetch origin main", { cwd });
+            await execPromise("git pull origin main", { cwd });
+        }
+        catch {
+            // Ignore fetch/pull errors
+        }
+    }
+    // Check if branch is already merged into main
+    try {
+        const mergeBase = hasOrigin ? "origin/main" : "main";
+        const { stdout: mergedBranches } = await execPromise(`git branch --merged ${mergeBase}`, { cwd });
+        const isMerged = mergedBranches
+            .split("\n")
+            .map((b) => b.trim().replace(/^\* /, ""))
+            .includes(branch);
+        if (isMerged) {
+            const { stdout: hash } = await execPromise(`git rev-parse ${mergeBase}`, { cwd });
+            return {
+                success: true,
+                commitHash: hash.trim(),
+                hasConflicts: false,
+                alreadyMerged: true,
+            };
+        }
+    }
+    catch {
+        // Continue with merge attempt if check fails
+    }
     // Build merge strategy
     let mergeStrategy = "";
     if (onConflict === "auto_theirs") {
@@ -266,23 +311,27 @@ async function mergeBranchWithMessage(projectRoot, branch, commitMessage, onConf
         mergeStrategy = "-X ours";
     }
     try {
-        // Use heredoc-style commit message to handle special characters
+        // Perform merge (main repo is already on main branch, no checkout needed)
         const escapedMessage = commitMessage.replace(/'/g, "'\\''");
-        await execPromise(`git merge --no-ff ${mergeStrategy} "${branch}" -m '${escapedMessage}'`, { cwd: projectRoot });
-        const { stdout: hash } = await execPromise("git rev-parse HEAD", {
-            cwd: projectRoot,
-        });
+        const { stdout: mergeOutput } = await execPromise(`git merge --no-ff ${mergeStrategy} "${branch}" -m '${escapedMessage}'`, { cwd });
+        const { stdout: hash } = await execPromise("git rev-parse HEAD", { cwd });
+        const commitHash = hash.trim();
+        // Check if "Already up to date" (no new commit created)
+        const alreadyUpToDate = mergeOutput.includes("Already up to date");
+        // Push to origin if available
+        if (hasOrigin) {
+            await execPromise("git push origin main", { cwd });
+        }
         return {
             success: true,
-            commitHash: hash.trim(),
+            commitHash,
             hasConflicts: false,
+            alreadyMerged: alreadyUpToDate,
         };
     }
     catch {
         // Check for conflicts
-        const { stdout: status } = await execPromise("git status --porcelain", {
-            cwd: projectRoot,
-        });
+        const { stdout: status } = await execPromise("git status --porcelain", { cwd });
         const conflictFiles = status
             .split("\n")
             .filter((line) => line.startsWith("UU ") || line.startsWith("AA "))

package/dist/tools/update.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import notifier from "node-notifier";
 import { findExecutionByBranch, findMergeQueueItemByExecutionId, findUserStoryById, insertMergeQueueItem, listMergeQueue, listUserStoriesByExecutionId, updateExecution, updateUserStory, } from "../store/state.js";
+import { mergeQueueAction } from "./merge.js";
 export const updateInputSchema = z.object({
     branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
     storyId: z.string().describe("Story ID (e.g., US-001)"),
@@ -49,6 +50,15 @@ export async function update(input) {
                 createdAt: new Date(),
             });
             addedToMergeQueue = true;
+            // Auto-process merge queue (fire and forget)
+            setImmediate(async () => {
+                try {
+                    await mergeQueueAction({ action: "process" });
+                }
+                catch (e) {
+                    console.error("Auto-merge failed:", e);
+                }
+            });
         }
     }
     // Send Windows toast notification when all complete (if enabled)

package/dist/utils/merge-helpers.d.ts

@@ -35,7 +35,8 @@ export declare function generateCommitMessage(branch: string, description: strin
  */
 export declare function getBranchCommits(projectRoot: string, branch: string): Promise<string[]>;
 /**
- * Update TODO.md to mark PRD as completed
+ * Update TODO.md to mark PRD-related items as completed
+ * Uses fuzzy matching based on keywords from the PRD description
  */
 export declare function updateTodoDoc(projectRoot: string, branch: string, description: string): boolean;
 /**

package/dist/utils/merge-helpers.js

@@ -8,11 +8,23 @@ const execAsync = promisify(exec);
  */
 export async function syncMainToBranch(worktreePath, branch) {
     try {
-        // Fetch latest main
-        await execAsync("git fetch origin main", { cwd: worktreePath });
+        // Check if origin remote exists
+        let hasOrigin = false;
+        try {
+            const { stdout } = await execAsync("git remote", { cwd: worktreePath });
+            hasOrigin = stdout.includes("origin");
+        }
+        catch {
+            hasOrigin = false;
+        }
+        // Fetch latest main only if origin exists
+        if (hasOrigin) {
+            await execAsync("git fetch origin main", { cwd: worktreePath });
+        }
         // Try to merge main into feature branch
+        const mergeTarget = hasOrigin ? "origin/main" : "main";
         try {
-            await execAsync("git merge origin/main --no-edit", { cwd: worktreePath });
+            await execAsync(`git merge ${mergeTarget} --no-edit`, { cwd: worktreePath });
             return {
                 success: true,
                 hasConflicts: false,
@@ -118,7 +130,8 @@ export async function getBranchCommits(projectRoot, branch) {
     }
 }
 /**
- * Update TODO.md to mark PRD as completed
+ * Update TODO.md to mark PRD-related items as completed
+ * Uses fuzzy matching based on keywords from the PRD description
  */
 export function updateTodoDoc(projectRoot, branch, description) {
     const todoPath = join(projectRoot, "docs", "TODO.md");
@@ -127,12 +140,28 @@ export function updateTodoDoc(projectRoot, branch, description) {
     }
     try {
         let content = readFileSync(todoPath, "utf-8");
-        // Find and update the PRD entry (mark as completed)
-        // Pattern: - [ ] PRD description -> - [x] PRD description
-        const prdPattern = new RegExp(`- \\[ \\] (.*${description.slice(0, 30)}.*|.*${branch}.*)`);
-        if (prdPattern.test(content)) {
-            content = content.replace(prdPattern, "- [x] $1");
-            writeFileSync(todoPath, content, "utf-8");
+        let updated = false;
+        // Extract keywords from description and branch for matching
+        const keywords = extractKeywords(description, branch);
+        // Find unchecked items that match keywords
+        const lines = content.split("\n");
+        const updatedLines = lines.map((line) => {
+            // Only process unchecked items
+            if (!line.match(/^(\s*)- \[ \]/)) {
+                return line;
+            }
+            // Check if line matches any keywords
+            const lineLower = line.toLowerCase();
+            const matchCount = keywords.filter((kw) => lineLower.includes(kw)).length;
+            // Require at least 2 keyword matches for confidence
+            if (matchCount >= 2) {
+                updated = true;
+                return line.replace("- [ ]", "- [x]");
+            }
+            return line;
+        });
+        if (updated) {
+            writeFileSync(todoPath, updatedLines.join("\n"), "utf-8");
             return true;
         }
         return false;
@@ -141,6 +170,36 @@ export function updateTodoDoc(projectRoot, branch, description) {
         return false;
     }
 }
+/**
+ * Extract keywords from PRD description and branch name
+ */
+function extractKeywords(description, branch) {
+    const keywords = [];
+    // Common words to ignore
+    const stopWords = new Set([
+        "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+        "of", "with", "by", "from", "as", "is", "was", "are", "were", "been",
+        "be", "have", "has", "had", "do", "does", "did", "will", "would",
+        "could", "should", "may", "might", "must", "shall", "can", "need",
+        "prd", "ralph", "user", "want", "that", "this", "which", "who",
+    ]);
+    // Extract from description
+    const descWords = description
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !stopWords.has(w));
+    keywords.push(...descWords);
+    // Extract from branch name (e.g., ralph/prd-speaking-dialogue-coach)
+    const branchWords = branch
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !stopWords.has(w));
+    keywords.push(...branchWords);
+    // Dedupe and return
+    return [...new Set(keywords)];
+}
 /**
  * Update PROJECT-STATUS.md with merge info
  */

package/dist/utils/prd-parser.js

@@ -35,8 +35,7 @@ function parsePrdMarkdown(content) {
     const titleMatch = body.match(/^#\s+(.+)$/m);
     const title = frontmatter.title || titleMatch?.[1] || "Untitled PRD";
     // Extract branch name from frontmatter or generate from title
-    const branchName = frontmatter.branch ||
-        `ralph/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+    const branchName = frontmatter.branch || generateBranchName(title);
     // Extract description
     const descMatch = body.match(/##\s*(?:Description|描述|Overview|概述)\s*\n([\s\S]*?)(?=\n##|\n$)/i);
     const description = descMatch?.[1]?.trim() || title;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,11 @@
     "prd",
     "ai-agent",
     "autonomous",
-    "git-worktree"
+    "git-worktree",
+    "project-management",
+    "task-management",
+    "user-story",
+    "merge-queue"
   ],
   "author": "G0d2i11a",
   "license": "MIT",
@@ -40,15 +44,15 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.25.3",
     "gray-matter": "^4.0.3",
     "node-notifier": "^10.0.1",
-    "zod": "^3.24.1"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/node": "^22.10.5",
+    "@types/node": "^22.19.7",
     "@types/node-notifier": "^8.0.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   }
 }