ralph-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,47 @@
 # Ralph MCP
 
-MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.
+[![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)
+
+**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
-- **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
 
 ## Installation
@@ -59,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 |
@@ -74,40 +136,113 @@ Restart Claude Code to load.
 
 ## Usage
 
+### Typical Session
+
+```
+User: Help me finish the Speaking module from TODO.md
+
+Claude: Let me check TODO.md... Found 3 incomplete items:
+  - Speaking dialogue practice
+  - Speaking scoring optimization
+  - Speaking question bank
+
+I'll create 3 PRDs...
+[Generates prd-speaking-dialogue.md]
+[Generates prd-speaking-scoring.md]
+[Generates prd-speaking-qb.md]
+
+User: Start
+
+Claude:
+[ralph_start × 3]
+[Task Agent × 3 running in parallel]
+
+3 PRDs started. They'll auto-merge when complete.
+Use ralph_status to check progress.
+
+--- Some time later ---
+
+User: Progress?
+
+Claude: [ralph_status]
+✅ prd-speaking-dialogue - Merged
+✅ prd-speaking-scoring - Merged
+🔄 prd-speaking-qb - US-003/005 in progress
+
+User: 👍
+```
+
+### Manual Workflow
+
 ```javascript
-// Start PRD execution
+// 1. Start PRD execution
 ralph_start({ prdPath: "tasks/prd-feature.md" })
 
-// Check all status
+// 2. Check status anytime
+ralph_status()
+
+// 3. Manual merge if needed (usually automatic)
+ralph_merge({ branch: "ralph/prd-feature" })
+```
+
+### API Reference
+
+```javascript
+// Start PRD execution (returns agent prompt)
+ralph_start({ prdPath: "tasks/prd-feature.md" })
+
+// View all PRD status
 ralph_status()
 
 // Get single PRD details
 ralph_get({ branch: "ralph/prd-feature" })
 
-// Update US status (agent calls this after completing a story)
+// Update User Story status (called by agent)
 ralph_update({ branch: "ralph/prd-feature", storyId: "US-1", passes: true, notes: "..." })
 
-// Merge completed PRD
+// Stop execution
+ralph_stop({ branch: "ralph/prd-feature" })
+
+// Merge to main
 ralph_merge({ branch: "ralph/prd-feature" })
+
+// Record Task agent ID (for tracking)
+ralph_set_agent_id({ branch: "ralph/prd-feature", agentTaskId: "abc123" })
 ```
 
 ## PRD Format
 
-Ralph parses markdown PRD files with User Stories:
+Ralph parses markdown PRD files. Example:
 
 ```markdown
-# Feature Name
+---
+title: User Authentication
+priority: high
+---
+
+# User Authentication
+
+Implement user login and registration.
 
 ## User Stories
 
-### US-1: Story Title
+### US-1: User Registration
+
+Users can create new accounts.
 
 **Acceptance Criteria:**
-- [ ] Criterion 1
-- [ ] Criterion 2
+- [ ] Email validation
+- [ ] Password strength check
+- [ ] Confirmation email sent
+
+### US-2: User Login
 
-### US-2: Another Story
-...
+Users can log into their accounts.
+
+**Acceptance Criteria:**
+- [ ] Email/password authentication
+- [ ] Remember me option
+- [ ] Forgot password flow
 ```
 
 ## Conflict Resolution
@@ -123,9 +258,41 @@ Ralph parses markdown PRD files with User Stories:
 
 ## Data Storage
 
-- State: `~/.ralph/state.json` (JSON file)
+- State: `~/.ralph/state.json`
 - Logs: `~/.ralph/logs/`
 
+Override data directory with `RALPH_DATA_DIR` environment variable.
+
+## Advanced Options
+
+### ralph_start options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `prdPath` | required | Path to PRD markdown file |
+| `projectRoot` | cwd | Project root directory |
+| `worktree` | `true` | Create isolated git worktree |
+| `autoStart` | `true` | Return agent prompt for immediate execution |
+| `autoMerge` | `false` | Auto-merge when all stories pass |
+| `notifyOnComplete` | `true` | Show Windows notification on completion |
+| `onConflict` | `"agent"` | Conflict resolution: `auto_theirs`, `auto_ours`, `notify`, `agent` |
+
+### Example with options
+
+```javascript
+ralph_start({
+  prdPath: "tasks/prd-feature.md",
+  autoMerge: true,           // Auto-merge when done
+  notifyOnComplete: true,    // Windows Toast notification
+  onConflict: "auto_theirs"  // Prefer main on conflicts
+})
+```
+
+## Credits
+
+- [Geoffrey Huntley](https://ghuntley.com/) - Original Ralph pattern
+- [Anthropic](https://anthropic.com/) - Claude Code & MCP protocol
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,265 @@
+# Ralph MCP
+
+[![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)
+
+自主并行执行 PRD 的 Claude Code MCP 服务器。自动解析 PRD、创建隔离 worktree、追踪进度、合并完成的功能。
+
+基于 [Geoffrey Huntley 的 Ralph 模式](https://ghuntley.com/ralph/)。
+
+[English](./README.md)
+
+## 为什么选择 Ralph MCP？
+
+| 没有 Ralph | 有 Ralph |
+|------------|----------|
+| 一次只能做一个功能 | 多个功能并行执行 |
+| 手动管理 git 分支 | 自动 worktree 隔离 |
+| 重启后进度丢失 | 状态持久化（JSON） |
+| 手动协调合并 | 串行合并队列 |
+| 看不到执行进度 | 实时状态追踪 |
+
+## 特性
+
+- **并行执行** - 配合 Claude Code Task 工具同时执行多个 PRD
+- **Git Worktree 隔离** - 每个 PRD 在独立 worktree 中运行，零冲突
+- **智能合并队列** - 串行合并避免并行合并冲突
+- **进度追踪** - 通过 `ralph_status()` 实时查看状态
+- **状态持久化** - 重启 Claude Code 不丢失状态（JSON 存储）
+- **自动合并** - 一键合并，支持多种冲突解决策略
+- **完成通知** - PRD 完成时弹出 Windows Toast 通知
+
+## 安装
+
+### 从 npm 安装
+
+```bash
+npm install -g ralph-mcp
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/G0d2i11a/ralph-mcp.git
+cd ralph-mcp
+npm install
+npm run build
+```
+
+## 配置
+
+添加到 `~/.claude/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "npx",
+      "args": ["ralph-mcp"]
+    }
+  }
+}
+```
+
+或者从源码安装时：
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "node",
+      "args": ["/path/to/ralph-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+重启 Claude Code 生效。
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `ralph_start` | 启动 PRD 执行（解析 PRD，创建 worktree，返回 agent prompt） |
+| `ralph_status` | 查看所有 PRD 执行状态 |
+| `ralph_get` | 获取单个 PRD 详情 |
+| `ralph_update` | 更新 User Story 状态（agent 调用） |
+| `ralph_stop` | 停止执行 |
+| `ralph_merge` | 合并到 main + 清理 worktree |
+| `ralph_merge_queue` | 管理串行合并队列 |
+| `ralph_set_agent_id` | 记录 Task agent ID |
+
+## 使用方法
+
+### 基本流程
+
+```javascript
+// 1. 启动 PRD 执行
+ralph_start({ prdPath: "tasks/prd-feature.md" })
+
+// 2. 随时查看状态
+ralph_status()
+
+// 3. 完成后合并
+ralph_merge({ branch: "ralph/prd-feature" })
+```
+
+### 配合 Claude Code Task 工具并行执行
+
+Ralph MCP 设计为配合 Claude Code 的 Task 工具实现并行 PRD 执行：
+
+```
+1. 分析 PRD，识别可以并行执行的独立任务
+2. 通过 ralph_start() 启动多个 PRD
+3. 为每个 PRD 启动后台 Task agent
+4. 继续聊天 - 规划下一个功能、审查代码等
+5. PRD 完成时收到 Windows Toast 通知
+6. 通过 ralph_merge() 将完成的 PRD 合并到 main
+```
+
+**示例会话：**
+
+```
+用户: 并行执行这 3 个 PRD
+
+Claude: 让我分析一下这些 PRD...
+        - prd-auth.md（独立）
+        - prd-dashboard.md（独立）
+        - prd-api.md（独立）
+
+        3 个都可以并行执行。正在启动...
+
+        [为每个 PRD 调用 ralph_start()]
+        [启动 3 个后台 Task agent]
+
+        PRD 正在后台运行。你可以继续其他工作。
+        完成后我会通知你。
+
+用户: 好的，等待的时候我们来规划下一个功能...
+
+[稍后 - Windows Toast 通知弹出]
+
+Claude: 3 个 PRD 全部完成！
+        - ralph/prd-auth: 4/4 US ✓
+        - ralph/prd-dashboard: 3/3 US ✓
+        - ralph/prd-api: 5/5 US ✓
+
+        准备合并吗？
+
+用户: 是的，全部合并
+
+Claude: [为每个分支调用 ralph_merge()]
+        所有 PRD 已成功合并到 main。
+```
+
+### API 参考
+
+```javascript
+// 启动 PRD 执行（返回 agent prompt）
+ralph_start({ prdPath: "tasks/prd-feature.md" })
+
+// 查看所有 PRD 状态
+ralph_status()
+
+// 获取单个 PRD 详情
+ralph_get({ branch: "ralph/prd-feature" })
+
+// 更新 User Story 状态（agent 调用）
+ralph_update({ branch: "ralph/prd-feature", storyId: "US-1", passes: true, notes: "..." })
+
+// 停止执行
+ralph_stop({ branch: "ralph/prd-feature" })
+
+// 合并到 main
+ralph_merge({ branch: "ralph/prd-feature" })
+
+// 记录 Task agent ID（用于追踪）
+ralph_set_agent_id({ branch: "ralph/prd-feature", agentTaskId: "abc123" })
+```
+
+## PRD 格式
+
+Ralph 解析 markdown 格式的 PRD 文件。示例：
+
+```markdown
+---
+title: 用户认证
+priority: high
+---
+
+# 用户认证
+
+实现用户登录和注册功能。
+
+## User Stories
+
+### US-1: 用户注册
+
+用户可以创建新账户。
+
+**Acceptance Criteria:**
+- [ ] 邮箱验证
+- [ ] 密码强度检查
+- [ ] 发送确认邮件
+
+### US-2: 用户登录
+
+用户可以登录账户。
+
+**Acceptance Criteria:**
+- [ ] 邮箱/密码认证
+- [ ] 记住我选项
+- [ ] 忘记密码流程
+```
+
+## 冲突解决
+
+`ralph_merge` 支持以下策略：
+
+| 策略 | 行为 |
+|------|------|
+| `auto_theirs` | `git merge -X theirs`，优先 main |
+| `auto_ours` | `git merge -X ours`，优先 branch |
+| `notify` | 暂停，通知用户手动处理 |
+| `agent` | 启动 merge subagent 解决冲突（默认） |
+
+## 数据存储
+
+- 状态文件：`~/.ralph/state.json`
+- 日志目录：`~/.ralph/logs/`
+
+可通过 `RALPH_DATA_DIR` 环境变量覆盖数据目录。
+
+## 高级选项
+
+### ralph_start 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `prdPath` | 必填 | PRD markdown 文件路径 |
+| `projectRoot` | 当前目录 | 项目根目录 |
+| `worktree` | `true` | 创建隔离的 git worktree |
+| `autoStart` | `true` | 返回 agent prompt 以便立即执行 |
+| `autoMerge` | `false` | 所有 story 通过后自动合并 |
+| `notifyOnComplete` | `true` | 完成时显示 Windows 通知 |
+| `onConflict` | `"agent"` | 冲突解决策略：`auto_theirs`, `auto_ours`, `notify`, `agent` |
+
+### 带参数示例
+
+```javascript
+ralph_start({
+  prdPath: "tasks/prd-feature.md",
+  autoMerge: true,           // 完成后自动合并
+  notifyOnComplete: true,    // Windows Toast 通知
+  onConflict: "auto_theirs"  // 冲突时优先 main
+})
+```
+
+## 致谢
+
+- [Geoffrey Huntley](https://ghuntley.com/) - 原始 Ralph 模式
+- [Anthropic](https://anthropic.com/) - Claude Code 和 MCP 协议
+
+## 许可证
+
+MIT

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/start.js

@@ -10,7 +10,7 @@ export const startInputSchema = z.object({
     projectRoot: z.string().optional().describe("Project root directory (defaults to cwd)"),
     worktree: z.boolean().default(true).describe("Create a worktree for isolation"),
     autoStart: z.boolean().default(true).describe("Generate agent prompt for auto-start"),
-    autoMerge: z.boolean().default(false).describe("Auto add to merge queue when all stories pass"),
+    autoMerge: z.boolean().default(true).describe("Auto add to merge queue when all stories pass"),
     notifyOnComplete: z.boolean().default(true).describe("Show Windows notification when all stories complete"),
     onConflict: z
         .enum(["auto_theirs", "auto_ours", "notify", "agent"])

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/dist/utils/worktree.d.ts

@@ -8,9 +8,9 @@ export interface WorktreeInfo {
  */
 export declare function createWorktree(projectRoot: string, branch: string): Promise<string>;
 /**
- * Remove a git worktree
+ * Remove a git worktree and optionally delete the branch
  */
-export declare function removeWorktree(projectRoot: string, worktreePath: string): Promise<void>;
+export declare function removeWorktree(projectRoot: string, worktreePath: string, deleteBranch?: boolean): Promise<void>;
 /**
  * List all worktrees
  */

package/dist/utils/worktree.js

@@ -28,16 +28,35 @@ export async function createWorktree(projectRoot, branch) {
     return worktreePath;
 }
 /**
- * Remove a git worktree
+ * Remove a git worktree and optionally delete the branch
  */
-export async function removeWorktree(projectRoot, worktreePath) {
-    if (!existsSync(worktreePath)) {
-        console.log(`Worktree does not exist at ${worktreePath}`);
-        return;
+export async function removeWorktree(projectRoot, worktreePath, deleteBranch = true) {
+    // Get branch name before removing worktree
+    let branchToDelete = null;
+    if (deleteBranch) {
+        const worktrees = listWorktrees(projectRoot);
+        const worktree = worktrees.find((w) => w.path === worktreePath);
+        if (worktree?.branch) {
+            branchToDelete = worktree.branch;
+        }
+    }
+    if (existsSync(worktreePath)) {
+        await execAsync(`git worktree remove "${worktreePath}" --force`, {
+            cwd: projectRoot,
+        });
+    }
+    // Delete the branch after worktree is removed
+    if (branchToDelete) {
+        try {
+            await execAsync(`git branch -D "${branchToDelete}"`, {
+                cwd: projectRoot,
+            });
+            console.log(`Deleted branch: ${branchToDelete}`);
+        }
+        catch (e) {
+            console.error(`Failed to delete branch ${branchToDelete}:`, e);
+        }
     }
-    await execAsync(`git worktree remove "${worktreePath}" --force`, {
-        cwd: projectRoot,
-    });
 }
 /**
  * List all worktrees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-mcp",
-  "version": "1.0.0",
+  "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"
   }
 }