ralph-mcp 1.0.11 → 1.0.13

package/dist/tools/update.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import notifier from "node-notifier";
-import { appendFile, mkdir } from "fs/promises";
+import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { areDependenciesSatisfied, findExecutionByBranch, findExecutionsDependingOn, findMergeQueueItemByExecutionId, findUserStoryById, insertMergeQueueItem, listMergeQueue, listUserStoriesByExecutionId, updateExecution, updateUserStory, } from "../store/state.js";
@@ -21,6 +21,54 @@ function formatDate(date) {
     const mm = pad(date.getMinutes());
     return `${yyyy}-${MM}-${dd} ${HH}:${mm}`;
 }
+/**
+ * Extract Codebase Pattern from notes if present.
+ * Looks for "**Codebase Pattern:**" section in the notes.
+ */
+function extractCodebasePattern(notes) {
+    const match = notes.match(/\*\*Codebase Pattern:\*\*\s*(.+?)(?=\n\*\*|\n##|$)/is);
+    if (match && match[1].trim()) {
+        return match[1].trim();
+    }
+    return null;
+}
+/**
+ * Update the Codebase Patterns section at the top of ralph-progress.md.
+ * Creates the section if it doesn't exist.
+ */
+async function updateCodebasePatterns(progressPath, newPattern) {
+    let content = "";
+    if (existsSync(progressPath)) {
+        content = await readFile(progressPath, "utf-8");
+    }
+    const patternsSectionHeader = "## Codebase Patterns\n";
+    const patternLine = `- ${newPattern}\n`;
+    if (content.includes(patternsSectionHeader)) {
+        // Find the end of the Codebase Patterns section (next ## or end of patterns)
+        const sectionStart = content.indexOf(patternsSectionHeader);
+        const sectionContentStart = sectionStart + patternsSectionHeader.length;
+        // Find next section (## that's not Codebase Patterns)
+        const nextSectionMatch = content.slice(sectionContentStart).match(/\n## /);
+        const sectionEnd = nextSectionMatch
+            ? sectionContentStart + nextSectionMatch.index
+            : content.length;
+        // Check if pattern already exists (avoid duplicates)
+        const existingPatterns = content.slice(sectionContentStart, sectionEnd);
+        if (!existingPatterns.includes(newPattern)) {
+            // Insert new pattern at the end of the patterns section
+            const before = content.slice(0, sectionEnd);
+            const after = content.slice(sectionEnd);
+            content = before + patternLine + after;
+            await writeFile(progressPath, content, "utf-8");
+        }
+    }
+    else {
+        // Create new Codebase Patterns section at the top
+        const newSection = patternsSectionHeader + patternLine + "\n";
+        content = newSection + content;
+        await writeFile(progressPath, content, "utf-8");
+    }
+}
 export async function update(input) {
     // Find execution by branch
     const exec = await findExecutionByBranch(input.branch);
@@ -49,6 +97,11 @@ export async function update(input) {
             const timestamp = formatDate(new Date());
             const notesContent = input.notes || story.notes || "No notes provided.";
             const entry = `## [${timestamp}] ${story.storyId}: ${story.title}\n${notesContent}\n\n`;
+            // Extract and consolidate Codebase Pattern if present
+            const pattern = extractCodebasePattern(notesContent);
+            if (pattern) {
+                await updateCodebasePatterns(progressPath, pattern);
+            }
             await appendFile(progressPath, entry, "utf-8");
         }
         catch (e) {

package/dist/utils/agent.js

@@ -57,21 +57,55 @@ ${progressLog ? `## Progress & Learnings\n${progressLog}\n` : ""}
 ## Pending User Stories
 ${storiesText}
 
+## Story Size Check (CRITICAL)
+
+Before implementing, verify the story is small enough to complete in ONE context window.
+
+**Right-sized stories:**
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+- Add a filter dropdown to a list
+
+**Too big (should have been split):**
+- "Build the entire dashboard" → schema, queries, UI components, filters
+- "Add authentication" → schema, middleware, login UI, session handling
+- "Refactor the API" → one story per endpoint
+
+**If a story seems too big:** Complete what you can, commit it, then call \`ralph_update\` with \`passes: false\` and notes explaining what remains. Do NOT produce broken code trying to finish everything.
+
 ## Instructions
 
 1. Work on ONE user story at a time, starting with the highest priority.
-2. ${progressLog ? "Review the 'Progress & Learnings' section above to understand previous decisions and context." : "Check if 'ralph-progress.md' exists and review it for context."}
+2. ${progressLog ? "Review the 'Progress & Learnings' section above - especially the 'Codebase Patterns' section at the top." : "Check if 'ralph-progress.md' exists and review it for context."}
 3. Implement the feature to satisfy all acceptance criteria.
-4. Run quality checks: \`pnpm check-types\` and \`pnpm --filter api build\` (adjust command for the specific repo structure if needed).
-5. Commit changes with message: \`feat: [${pendingStories[0].storyId}] - ${pendingStories[0].title}\`
-6. After completing a story, call \`ralph_update\` to mark it as passed:
-   \`ralph_update({ branch: "${branch}", storyId: "${pendingStories[0].storyId}", passes: true, notes: "Brief summary of implementation, key decisions, and any learnings." })\`
-7. Continue to the next story until all are complete.
-
-## Quality Requirements
-- ALL commits must pass typecheck and build
+4. Run quality checks: \`pnpm check-types\` and \`pnpm --filter api build\` (adjust for repo structure).
+5. **Browser Testing (UI stories)**: If the story changes UI, verify in browser using Chrome DevTools MCP or similar tools. A frontend story is NOT complete until visually verified.
+6. Commit changes with message: \`feat: [${pendingStories[0].storyId}] - ${pendingStories[0].title}\`
+7. **Update Directory CLAUDE.md**: If you discovered reusable patterns, add them to the CLAUDE.md in the directory you modified (create if needed). Only add genuinely reusable knowledge, not story-specific details.
+8. Call \`ralph_update\` to mark the story as passed. Include detailed notes:
+   \`ralph_update({ branch: "${branch}", storyId: "${pendingStories[0].storyId}", passes: true, notes: "..." })\`
+9. Continue to the next story until all are complete.
+
+## Notes Format for ralph_update
+
+Provide structured learnings in the \`notes\` field:
+\`\`\`
+**Implemented:** Brief summary of what was done
+**Files changed:** List key files
+**Learnings:**
+- Patterns discovered (e.g., "this codebase uses X for Y")
+- Gotchas encountered (e.g., "don't forget to update Z when changing W")
+- Useful context for future iterations
+**Codebase Pattern:** (if discovered a general pattern worth consolidating)
+\`\`\`
+
+## Quality Requirements (Feedback Loops)
+- ALL commits must pass typecheck and build - broken code compounds across iterations
 - Keep changes focused and minimal
 - Follow existing code patterns
+- UI changes must be browser-verified
+- Do NOT commit broken code - if checks fail, fix before committing
 
 ## Stop Condition
 When all stories are complete, report completion.

package/package.json

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