ralph-mcp 1.1.0 → 1.1.2

package/README.md

@@ -39,13 +39,42 @@ Claude: ralph_start → Task Agent handles everything automatically
 - **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
+- **Dependency Management** - PRDs can depend on other PRDs, auto-triggered when dependencies complete
+- **Stagnation Detection** - Auto-detects stuck agents (no progress, repeated errors) and marks as failed
 - **Agent Memory** - Persistent "Progress Log" learns from mistakes across User Stories
 - **Context Injection** - Inject project rules (CLAUDE.md) into agent context
 - **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
+- **Merge Queue** - Serial merge queue to avoid conflicts
 - **Notifications** - Windows Toast when PRD completes
 
+## Progress Log (Agent Memory)
+
+Ralph maintains a `ralph-progress.md` file in each worktree that persists learnings across User Stories. This gives agents "memory" of what worked and what didn't.
+
+### How it works
+
+1. When an agent completes a User Story, it records learnings in the `notes` field of `ralph_update`
+2. Ralph appends these notes to `ralph-progress.md` in the worktree
+3. When the next User Story starts, the agent receives this log in its prompt
+4. The file is automatically git-ignored (via `.git/info/exclude`)
+
+### Example progress log
+
+```markdown
+## [2024-01-15 14:30] US-001: Setup Database Schema
+- Used Prisma with PostgreSQL
+- Added index on `userId` for faster queries
+- Note: Must run `pnpm db:migrate:dev` after schema changes
+
+## [2024-01-15 15:45] US-002: User Registration API
+- Reused validation patterns from existing auth module
+- BCrypt rounds set to 12 for password hashing
+- Integration test requires test database to be running
+```
+
+This allows later stories to benefit from earlier discoveries without re-learning.
+
 ## Installation
 
 ### From npm
@@ -128,6 +157,7 @@ This enables Claude to automatically use Ralph when you mention PRD execution.
 | Tool | Description |
 |------|-------------|
 | `ralph_start` | Start PRD execution (parse PRD, create worktree, return agent prompt) |
+| `ralph_batch_start` | Start multiple PRDs with dependency resolution |
 | `ralph_status` | View all PRD execution status |
 | `ralph_get` | Get single PRD details |
 | `ralph_update` | Update User Story status (called by agent) |
@@ -135,6 +165,8 @@ This enables Claude to automatically use Ralph when you mention PRD execution.
 | `ralph_merge` | Merge to main + cleanup worktree |
 | `ralph_merge_queue` | Manage serial merge queue |
 | `ralph_set_agent_id` | Record Task agent ID |
+| `ralph_retry` | Retry a failed PRD execution |
+| `ralph_reset_stagnation` | Reset stagnation counters after manual intervention |
 
 ## Usage
 
@@ -193,6 +225,9 @@ ralph_merge({ branch: "ralph/prd-feature" })
 // Start PRD execution (returns agent prompt)
 ralph_start({ prdPath: "tasks/prd-feature.md" })
 
+// Start multiple PRDs in parallel
+ralph_batch_start({ prdPaths: ["tasks/prd-a.md", "tasks/prd-b.md"] })
+
 // View all PRD status
 ralph_status()
 
@@ -210,6 +245,12 @@ ralph_merge({ branch: "ralph/prd-feature" })
 
 // Record Task agent ID (for tracking)
 ralph_set_agent_id({ branch: "ralph/prd-feature", agentTaskId: "abc123" })
+
+// Retry a failed execution
+ralph_retry({ branch: "ralph/prd-feature" })
+
+// Reset stagnation counters (after manual fix)
+ralph_reset_stagnation({ branch: "ralph/prd-feature" })
 ```
 
 ## PRD Format
@@ -291,6 +332,60 @@ ralph_start({
 })
 ```
 
+### ralph_batch_start options
+
+Start multiple PRDs with dependency resolution and serial `pnpm install`.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `prdPaths` | required | Array of paths to PRD markdown files |
+| `projectRoot` | cwd | Project root directory |
+| `worktree` | `true` | Create worktrees for isolation |
+| `autoMerge` | `true` | Auto add to merge queue when all stories pass |
+| `notifyOnComplete` | `true` | Show Windows notification on completion |
+| `onConflict` | `"agent"` | Conflict resolution strategy |
+| `contextInjectionPath` | `undefined` | Path to file (e.g. CLAUDE.md) to inject into prompt |
+| `preheat` | `true` | Run pnpm install serially before starting agents |
+
+```javascript
+ralph_batch_start({
+  prdPaths: [
+    "tasks/prd-auth.md",
+    "tasks/prd-dashboard.md",
+    "tasks/prd-settings.md"
+  ],
+  contextInjectionPath: "CLAUDE.md",
+  autoMerge: true
+})
+```
+
+### ralph_retry
+
+Retry a failed PRD execution. Resets stagnation counters and generates a new agent prompt to continue from where it left off.
+
+```javascript
+// Retry a failed execution
+ralph_retry({ branch: "ralph/prd-feature" })
+// Returns: { success, branch, message, previousStatus, agentPrompt, progress }
+```
+
+### ralph_reset_stagnation
+
+Reset stagnation counters after manual intervention. Use when you've fixed an issue and want the agent to continue.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `branch` | required | Branch name |
+| `resumeExecution` | `true` | Also set status back to 'running' if currently 'failed' |
+
+```javascript
+// Reset counters and resume
+ralph_reset_stagnation({ branch: "ralph/prd-feature" })
+
+// Reset counters only (keep failed status)
+ralph_reset_stagnation({ branch: "ralph/prd-feature", resumeExecution: false })
+```
+
 ## Credits
 
 - [Geoffrey Huntley](https://ghuntley.com/) - Original Ralph pattern

package/dist/index.js

@@ -10,6 +10,8 @@ import { update, updateInputSchema } from "./tools/update.js";
 import { stop, stopInputSchema } from "./tools/stop.js";
 import { merge, mergeInputSchema, mergeQueueAction, mergeQueueInputSchema } from "./tools/merge.js";
 import { setAgentId, setAgentIdInputSchema } from "./tools/set-agent-id.js";
+import { resetStagnationTool, resetStagnationInputSchema } from "./tools/reset-stagnation.js";
+import { retry, retryInputSchema } from "./tools/retry.js";
 const server = new Server({
     name: "ralph",
     version: "1.0.0",
@@ -120,6 +122,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Implementation notes",
                         },
+                        filesChanged: {
+                            type: "number",
+                            description: "Number of files changed (for stagnation detection)",
+                        },
+                        error: {
+                            type: "string",
+                            description: "Error message if stuck (for stagnation detection)",
+                        },
                     },
                     required: ["branch", "storyId", "passes"],
                 },
@@ -258,6 +268,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["prdPaths"],
                 },
             },
+            {
+                name: "ralph_reset_stagnation",
+                description: "Reset stagnation counters for an execution. Use after manual intervention to allow the agent to continue.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                        resumeExecution: {
+                            type: "boolean",
+                            description: "Also set status back to 'running' if currently 'failed' (default: true)",
+                            default: true,
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_retry",
+                description: "Retry a failed PRD execution. Resets stagnation counters and generates a new agent prompt to continue from where it left off.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
         ],
     };
 });
@@ -294,6 +337,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "ralph_batch_start":
                 result = await batchStart(batchStartInputSchema.parse(args));
                 break;
+            case "ralph_reset_stagnation":
+                result = await resetStagnationTool(resetStagnationInputSchema.parse(args));
+                break;
+            case "ralph_retry":
+                result = await retry(retryInputSchema.parse(args));
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/tools/reset-stagnation.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const resetStagnationInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+    resumeExecution: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+    resumeExecution: boolean;
+}, {
+    branch: string;
+    resumeExecution?: boolean | undefined;
+}>;
+export type ResetStagnationInput = z.infer<typeof resetStagnationInputSchema>;
+export interface ResetStagnationResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    newStatus: string;
+}
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export declare function resetStagnationTool(input: ResetStagnationInput): Promise<ResetStagnationResult>;

package/dist/tools/reset-stagnation.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { findExecutionByBranch, resetStagnation, updateExecution, } from "../store/state.js";
+export const resetStagnationInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+    resumeExecution: z
+        .boolean()
+        .default(true)
+        .describe("Also set status back to 'running' if currently 'failed'"),
+});
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export async function resetStagnationTool(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Optionally resume execution
+    let newStatus = previousStatus;
+    if (input.resumeExecution && previousStatus === "failed") {
+        await updateExecution(exec.id, {
+            status: "running",
+            updatedAt: new Date(),
+        });
+        newStatus = "running";
+    }
+    return {
+        success: true,
+        branch: input.branch,
+        message: previousStatus === "failed" && input.resumeExecution
+            ? "Stagnation counters reset and execution resumed"
+            : "Stagnation counters reset",
+        previousStatus,
+        newStatus,
+    };
+}

package/dist/tools/retry.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const retryInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+}, {
+    branch: string;
+}>;
+export type RetryInput = z.infer<typeof retryInputSchema>;
+export interface RetryResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    agentPrompt: string | null;
+    progress: {
+        completed: number;
+        total: number;
+        percentage: number;
+    };
+}
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export declare function retry(input: RetryInput): Promise<RetryResult>;

package/dist/tools/retry.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { findExecutionByBranch, listUserStoriesByExecutionId, resetStagnation, updateExecution, } from "../store/state.js";
+import { generateAgentPrompt } from "../utils/agent.js";
+export const retryInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+});
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export async function retry(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Only allow retry for failed or stopped executions
+    if (previousStatus !== "failed" && previousStatus !== "stopped") {
+        return {
+            success: false,
+            branch: input.branch,
+            message: `Cannot retry execution with status '${previousStatus}'. Only 'failed' or 'stopped' executions can be retried.`,
+            previousStatus,
+            agentPrompt: null,
+            progress: { completed: 0, total: 0, percentage: 0 },
+        };
+    }
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Set status back to running
+    await updateExecution(exec.id, {
+        status: "running",
+        updatedAt: new Date(),
+    });
+    // Get stories and generate new agent prompt
+    const stories = await listUserStoriesByExecutionId(exec.id);
+    const completed = stories.filter((s) => s.passes).length;
+    const total = stories.length;
+    const agentPrompt = generateAgentPrompt(exec.branch, exec.description, exec.worktreePath || exec.projectRoot, stories.map((s) => ({
+        storyId: s.storyId,
+        title: s.title,
+        description: s.description,
+        acceptanceCriteria: s.acceptanceCriteria,
+        priority: s.priority,
+        passes: s.passes,
+    })), undefined, // contextPath - would need to re-read from PRD
+    {
+        loopCount: 0, // Reset loop context for fresh start
+        consecutiveNoProgress: 0,
+        consecutiveErrors: 0,
+        lastError: null,
+    });
+    return {
+        success: true,
+        branch: input.branch,
+        message: `Execution retried. ${total - completed} stories remaining.`,
+        previousStatus,
+        agentPrompt,
+        progress: {
+            completed,
+            total,
+            percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+        },
+    };
+}

package/dist/tools/status.d.ts

@@ -34,6 +34,7 @@ export interface StatusResult {
         completed: number;
         failed: number;
         pending: number;
+        atRisk: number;
     };
 }
 export declare function status(input: StatusInput): Promise<StatusResult>;

package/dist/tools/status.js

@@ -50,6 +50,7 @@ export async function status(input) {
         completed: executionStatuses.filter((e) => e.status === "completed").length,
         failed: executionStatuses.filter((e) => e.status === "failed").length,
         pending: executionStatuses.filter((e) => e.status === "pending").length,
+        atRisk: executionStatuses.filter((e) => e.consecutiveNoProgress >= 2 || e.consecutiveErrors >= 3).length,
     };
     return {
         executions: executionStatuses,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
   "type": "module",
   "main": "dist/index.js",