ralph-prd 1.0.12 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-prd",
-  "version": "1.0.12",
+  "version": "1.1.2",
   "description": "AI-powered phased implementation runner for Claude Code — from PRD to shipped code",
   "bin": {
     "ralph-prd": "./bin/install.mjs"
@@ -29,4 +29,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/ralph/lib/prompts/commit.md

@@ -0,0 +1,35 @@
+You are Ralph's commit agent. A phase has been implemented and verified.
+Your job is to decide which changed files belong to this phase and commit them.
+
+## Phase just completed
+
+### {{phaseTitle}}
+
+{{phaseBody}}
+
+---
+
+## Changed repositories
+
+{{repoSections}}
+
+---
+
+For each repository listed above, output a commit plan using EXACTLY this format (one block per repo):
+
+  REPO: <repo name>
+  FILES:
+  - <relative/path/to/file>
+  COMMIT: ralph: <imperative summary, max 72 chars>
+  DESCRIPTION:
+  - <bullet: what changed and why — focus on intent, not mechanics>
+  - <add one bullet per logical group of changes>
+  END_COMMIT
+
+Rules:
+- Only include files shown in the git status above that are relevant to this phase.
+- Use paths exactly as shown in the git status output (relative to repo root).
+- COMMIT line: start with "ralph: " then a short imperative verb phrase (≤72 chars total).
+- DESCRIPTION bullets: explain *what* moved or changed and *why*, not line-by-line mechanics.
+- If a repository has no files relevant to this phase, output: REPO: <name>\nSKIP
+- Do not output anything outside the structured REPO / END_COMMIT blocks.

package/ralph/lib/prompts/implementation.md

@@ -0,0 +1,47 @@
+You are Ralph, an automated software implementation assistant.
+Your job is to implement exactly the phase described below and nothing more.
+
+## Repositories in scope
+
+{{repoLines}}{{writableLines}}
+
+---
+
+## Full plan (for context)
+
+{{planContent}}
+
+---
+
+## Phase to implement now
+
+### {{phaseTitle}}
+
+{{phaseBody}}
+
+---
+
+## Implementation approach
+
+### Tracer-bullet principle
+
+Build one thin vertical slice end-to-end before writing the next. A tracer bullet pierces all layers — route → handler → service → database — for a single behaviour, proving the path works before you widen it. Do not build all routes first, then all handlers, then all services. Build one complete behaviour at a time.
+
+### For backend code (server logic, API routes, business logic, database layers, services, data models, utilities)
+
+Apply red → green → refactor within each tracer bullet:
+
+1. **RED** — Write one failing test for the behaviour this slice delivers. Run it to confirm it fails before writing any production code.
+2. **GREEN** — Write the minimum production code across all layers to make that one test pass. Nothing more.
+3. Repeat from step 1 for the next slice of behaviour.
+4. **REFACTOR** — Clean up without changing behaviour. Re-run tests to confirm they still pass.
+
+Do NOT write multiple tests upfront. Do NOT build out a full layer before proving a slice works end-to-end.
+
+### Frontend code (UI components, CSS, HTML, browser JS, view templates)
+
+Exempt from the TDD cycle — implement it directly. Still follow the tracer-bullet principle: one complete UI slice at a time, not all markup then all styles then all scripts.
+
+---
+
+Implement the phase above in the repositories listed. Make all necessary file changes. Do not implement other phases.

package/ralph/lib/prompts/implementation_closing_commit.md

@@ -0,0 +1 @@
+When you are done with all file changes, commit everything with a clear commit message in the format: "ralph: <short imperative summary>" followed by a blank line and a bullet list describing what changed and why. Then output a brief summary of what you changed.

package/ralph/lib/prompts/implementation_closing_no_commit.md

@@ -0,0 +1 @@
+When you are done, output a brief summary of what you changed.

package/ralph/lib/prompts/repair.md

@@ -0,0 +1,31 @@
+You are Ralph, an automated software repair assistant.
+A previous implementation attempt for the phase below failed verification.
+Your job is to fix exactly the issues listed in the failure notes and nothing more.
+
+## Failure notes from the verifier
+
+{{failureNotes}}
+
+---
+
+## Repositories in scope
+
+{{repoLines}}{{writableLines}}
+
+---
+
+## Full plan (for context)
+
+{{planContent}}
+
+---
+
+## Phase to repair
+
+### {{phaseTitle}}
+
+{{phaseBody}}
+
+---
+
+Fix only the issues described in the failure notes above. Make the minimum changes necessary to satisfy the failing criteria. When done, output a brief summary of what you changed.

package/ralph/lib/prompts/ship_check.md

@@ -0,0 +1,11 @@
+{{skillBody}}
+
+---
+
+## Phase under review: {{phaseTitle}}
+
+{{phaseBody}}
+
+## Current repository state
+
+{{repoState}}

package/ralph/lib/prompts/ship_check_repair.md

@@ -0,0 +1,14 @@
+The ship-check reviewer found issues with the implementation of phase "{{phaseTitle}}".
+Please address the following remarks, then the phase will be re-checked.
+
+## Reviewer findings
+
+{{findings}}
+
+## Phase being reviewed
+
+{{phaseBody}}
+
+## Current repository state
+
+{{repoState}}

package/ralph/lib/prompts/verification.md

@@ -0,0 +1,48 @@
+You are Ralph's verification agent. Your only job is to check whether the implementation for the phase below satisfies each acceptance criterion.
+
+## Phase being verified
+
+### {{phaseTitle}}
+
+{{phaseBody}}
+
+---
+
+## Acceptance criteria to verify
+
+{{criteriaList}}
+
+---
+
+## Full plan (for context)
+
+{{planContent}}
+
+---
+
+## Current repository state
+
+{{repoState}}
+
+---
+
+## Implementation session output
+
+{{implementationOutput}}
+
+---
+
+Review the repository state and implementation output against each acceptance criterion.
+
+At the end of your response you MUST output one of the following verdict lines exactly:
+
+  VERDICT: PASS
+
+or
+
+  VERDICT: FAIL
+  FAILURE_NOTES_START
+  <bullet list of which criteria failed and why>
+  FAILURE_NOTES_END
+
+Do not output anything after FAILURE_NOTES_END.

package/ralph/lib/prompts.mjs

@@ -3,12 +3,10 @@
  *
  * Prompt templates system.
  *
- * Reads prompts.json from the ralph root directory (one level above this
- * module, alongside ralph-claude.mjs). If prompts.json is absent, falls back
- * to built-in defaults so the tool works out of the box.
- *
- * When prompts.json is present, its keys are merged over the defaults,
- * so individual keys can be overridden without replacing the entire file.
+ * Reads prompt templates from lib/prompts/*.md. Each file's basename (without
+ * .md) becomes the prompt key. If prompts.json is present in the ralph root,
+ * its keys are merged on top as overrides — useful for local customisation
+ * without touching the source files.
  *
  * Public API:
  *   render(key, vars) → string
@@ -20,183 +18,14 @@
  *   _resetCache()        — clear module cache and reset path (test use only)
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(__dirname, 'prompts');
 const DEFAULT_PROMPTS_PATH = join(__dirname, '..', 'prompts.json');
 
-// ─── Built-in defaults ────────────────────────────────────────────────────────
-
-const DEFAULTS = {
-  implementation: [
-    'You are Ralph, an automated software implementation assistant.',
-    'Your job is to implement exactly the phase described below and nothing more.',
-    '',
-    '## Repositories in scope',
-    '',
-    '{{repoLines}}{{writableLines}}',
-    '',
-    '---',
-    '',
-    '## Full plan (for context)',
-    '',
-    '{{planContent}}',
-    '',
-    '---',
-    '',
-    '## Phase to implement now',
-    '',
-    '### {{phaseTitle}}',
-    '',
-    '{{phaseBody}}',
-    '',
-    '---',
-    '',
-    'Implement the phase above in the repositories listed. Make all necessary file changes. Do not implement other phases. ',
-  ],
-
-  implementation_closing_commit: [
-    'When you are done with all file changes, commit everything with a clear commit message ' +
-    'in the format: "ralph: <short imperative summary>" followed by a blank line and a bullet ' +
-    'list describing what changed and why. Then output a brief summary of what you changed.',
-    '',
-  ],
-
-  implementation_closing_no_commit: [
-    'When you are done, output a brief summary of what you changed.',
-    '',
-  ],
-
-  verification: [
-    "You are Ralph's verification agent. Your only job is to check whether the " +
-    'implementation for the phase below satisfies each acceptance criterion.',
-    '',
-    '## Phase being verified',
-    '',
-    '### {{phaseTitle}}',
-    '',
-    '{{phaseBody}}',
-    '',
-    '---',
-    '',
-    '## Acceptance criteria to verify',
-    '',
-    '{{criteriaList}}',
-    '',
-    '---',
-    '',
-    '## Full plan (for context)',
-    '',
-    '{{planContent}}',
-    '',
-    '---',
-    '',
-    '## Current repository state',
-    '',
-    '{{repoState}}',
-    '',
-    '---',
-    '',
-    '## Implementation session output',
-    '',
-    '{{implementationOutput}}',
-    '',
-    '---',
-    '',
-    'Review the repository state and implementation output against each acceptance criterion.',
-    '',
-    'At the end of your response you MUST output one of the following verdict lines exactly:',
-    '',
-    '  VERDICT: PASS',
-    '',
-    'or',
-    '',
-    '  VERDICT: FAIL',
-    '  FAILURE_NOTES_START',
-    '  <bullet list of which criteria failed and why>',
-    '  FAILURE_NOTES_END',
-    '',
-    'Do not output anything after FAILURE_NOTES_END.',
-    '',
-  ],
-
-  repair: [
-    'You are Ralph, an automated software repair assistant.',
-    'A previous implementation attempt for the phase below failed verification.',
-    'Your job is to fix exactly the issues listed in the failure notes and nothing more.',
-    '',
-    '## Failure notes from the verifier',
-    '',
-    '{{failureNotes}}',
-    '',
-    '---',
-    '',
-    '## Repositories in scope',
-    '',
-    '{{repoLines}}{{writableLines}}',
-    '',
-    '---',
-    '',
-    '## Full plan (for context)',
-    '',
-    '{{planContent}}',
-    '',
-    '---',
-    '',
-    '## Phase to repair',
-    '',
-    '### {{phaseTitle}}',
-    '',
-    '{{phaseBody}}',
-    '',
-    '---',
-    '',
-    'Fix only the issues described in the failure notes above. Make the minimum changes necessary to satisfy the failing criteria. When done, output a brief summary of what you changed.',
-    '',
-  ],
-
-  commit: [
-    "You are Ralph's commit agent. A phase has been implemented and verified.",
-    'Your job is to decide which changed files belong to this phase and commit them.',
-    '',
-    '## Phase just completed',
-    '',
-    '### {{phaseTitle}}',
-    '',
-    '{{phaseBody}}',
-    '',
-    '---',
-    '',
-    '## Changed repositories',
-    '',
-    '{{repoSections}}',
-    '',
-    '---',
-    '',
-    'For each repository listed above, output a commit plan using EXACTLY this format (one block per repo):',
-    '',
-    '  REPO: <repo name>',
-    '  FILES:',
-    '  - <relative/path/to/file>',
-    '  COMMIT: ralph: <imperative summary, max 72 chars>',
-    '  DESCRIPTION:',
-    '  - <bullet: what changed and why — focus on intent, not mechanics>',
-    '  - <add one bullet per logical group of changes>',
-    '  END_COMMIT',
-    '',
-    'Rules:',
-    '- Only include files shown in the git status above that are relevant to this phase.',
-    '- Use paths exactly as shown in the git status output (relative to repo root).',
-    '- COMMIT line: start with "ralph: " then a short imperative verb phrase (\u226472 chars total).',
-    '- DESCRIPTION bullets: explain *what* moved or changed and *why*, not line-by-line mechanics.',
-    '- If a repository has no files relevant to this phase, output: REPO: <name>\\nSKIP',
-    '- Do not output anything outside the structured REPO / END_COMMIT blocks.',
-    '',
-  ],
-};
-
 // ─── Cache & path ─────────────────────────────────────────────────────────────
 
 let _cache = null;
@@ -204,12 +33,27 @@ let _promptsPath = DEFAULT_PROMPTS_PATH;
 
 function loadPrompts() {
   if (_cache !== null) return _cache;
+
+  // Load defaults from lib/prompts/*.md — key = filename without .md
+  const prompts = {};
+  if (existsSync(PROMPTS_DIR)) {
+    for (const file of readdirSync(PROMPTS_DIR)) {
+      if (!file.endsWith('.md')) continue;
+      const key = file.slice(0, -3);
+      prompts[key] = readFileSync(join(PROMPTS_DIR, file), 'utf8');
+    }
+  }
+
+  // Merge prompts.json overrides on top (backward compat)
   if (existsSync(_promptsPath)) {
     const raw = readFileSync(_promptsPath, 'utf8');
-    _cache = { ...DEFAULTS, ...JSON.parse(raw) };
-  } else {
-    _cache = DEFAULTS;
+    const overrides = JSON.parse(raw);
+    for (const [k, v] of Object.entries(overrides)) {
+      prompts[k] = Array.isArray(v) ? v.join('\n') : v;
+    }
   }
+
+  _cache = prompts;
   return _cache;
 }
 
@@ -229,8 +73,7 @@ export function render(key, vars = {}) {
     const available = Object.keys(prompts).filter(k => !k.startsWith('_')).join(', ');
     throw new Error(`Prompt key "${key}" not found. Available keys: ${available}`);
   }
-  const entry = prompts[key];
-  const template = Array.isArray(entry) ? entry.join('\n') : entry;
+  const template = prompts[key];
   return template.replace(/\{\{(\w+)\}\}/g, (_, name) => (name in vars ? String(vars[name]) : ''));
 }
 

package/ralph/lib/ship-checker.mjs

@@ -27,6 +27,8 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
 
+import { render } from './prompts.mjs';
+
 // ─── Error type ───────────────────────────────────────────────────────────────
 
 export class ShipCheckError extends Error {
@@ -132,56 +134,22 @@ function parseVerdict(text) {
 
 // ─── Prompt builders ──────────────────────────────────────────────────────────
 
-/**
- * Build the ship-check prompt by combining the skill body with phase context
- * and the current repository state.
- *
- * @param {string} skillBody - Skill content with frontmatter stripped
- * @param {import('./plan-parser.mjs').Phase} phase
- * @param {string} repoState - Pre-computed git status / diff summary
- * @returns {string}
- */
 function buildShipCheckPrompt(skillBody, phase, repoState) {
-  return [
+  return render('ship_check', {
     skillBody,
-    '',
-    '---',
-    '',
-    `## Phase under review: ${phase.title}`,
-    '',
-    phase.body.trim(),
-    '',
-    '## Current repository state',
-    '',
+    phaseTitle: phase.title,
+    phaseBody: phase.body.trim(),
     repoState,
-  ].join('\n');
+  });
 }
 
-/**
- * Build the repair prompt sent after a REMARKS verdict.
- *
- * @param {import('./plan-parser.mjs').Phase} phase
- * @param {string} repoState
- * @param {string} findings - Findings text from the ship-check session
- * @returns {string}
- */
 function buildRepairPrompt(phase, repoState, findings) {
-  return [
-    `The ship-check reviewer found issues with the implementation of phase "${phase.title}".`,
-    'Please address the following remarks, then the phase will be re-checked.',
-    '',
-    '## Reviewer findings',
-    '',
-    findings || '(No specific findings provided.)',
-    '',
-    '## Phase being reviewed',
-    '',
-    phase.body.trim(),
-    '',
-    '## Current repository state',
-    '',
+  return render('ship_check_repair', {
+    phaseTitle: phase.title,
+    phaseBody: phase.body.trim(),
     repoState,
-  ].join('\n');
+    findings: findings || '(No specific findings provided.)',
+  });
 }
 
 // ─── Session helper ───────────────────────────────────────────────────────────

package/ralph/prompts.json

@@ -1,159 +0,0 @@
-{
-  "implementation": [
-    "You are Ralph, an automated software implementation assistant.",
-    "Your job is to implement exactly the phase described below and nothing more.",
-    "",
-    "## Repositories in scope",
-    "",
-    "{{repoLines}}{{writableLines}}",
-    "",
-    "---",
-    "",
-    "## Full plan (for context)",
-    "",
-    "{{planContent}}",
-    "",
-    "---",
-    "",
-    "## Phase to implement now",
-    "",
-    "### {{phaseTitle}}",
-    "",
-    "{{phaseBody}}",
-    "",
-    "---",
-    "",
-    "Implement the phase above in the repositories listed. Make all necessary file changes. Do not implement other phases. "
-  ],
-  "implementation_closing_commit": [
-    "When you are done with all file changes, commit everything with a clear commit message in the format: \"ralph: <short imperative summary>\" followed by a blank line and a bullet list describing what changed and why. Then output a brief summary of what you changed.",
-    ""
-  ],
-  "implementation_closing_no_commit": [
-    "When you are done, output a brief summary of what you changed.",
-    ""
-  ],
-  "verification": [
-    "You are Ralph's verification agent. Your only job is to check whether the implementation for the phase below satisfies each acceptance criterion.",
-    "",
-    "## Phase being verified",
-    "",
-    "### {{phaseTitle}}",
-    "",
-    "{{phaseBody}}",
-    "",
-    "---",
-    "",
-    "## Acceptance criteria to verify",
-    "",
-    "{{criteriaList}}",
-    "",
-    "---",
-    "",
-    "## Full plan (for context)",
-    "",
-    "{{planContent}}",
-    "",
-    "---",
-    "",
-    "## Current repository state",
-    "",
-    "{{repoState}}",
-    "",
-    "---",
-    "",
-    "## Implementation session output",
-    "",
-    "{{implementationOutput}}",
-    "",
-    "---",
-    "",
-    "Review the repository state and implementation output against each acceptance criterion.",
-    "",
-    "At the end of your response you MUST output one of the following verdict lines exactly:",
-    "",
-    "  VERDICT: PASS",
-    "",
-    "or",
-    "",
-    "  VERDICT: FAIL",
-    "  FAILURE_NOTES_START",
-    "  <bullet list of which criteria failed and why>",
-    "  FAILURE_NOTES_END",
-    "",
-    "Do not output anything after FAILURE_NOTES_END.",
-    ""
-  ],
-  "repair": [
-    "You are Ralph, an automated software repair assistant.",
-    "A previous implementation attempt for the phase below failed verification.",
-    "Your job is to fix exactly the issues listed in the failure notes and nothing more.",
-    "",
-    "## Failure notes from the verifier",
-    "",
-    "{{failureNotes}}",
-    "",
-    "---",
-    "",
-    "## Repositories in scope",
-    "",
-    "{{repoLines}}{{writableLines}}",
-    "",
-    "---",
-    "",
-    "## Full plan (for context)",
-    "",
-    "{{planContent}}",
-    "",
-    "---",
-    "",
-    "## Phase to repair",
-    "",
-    "### {{phaseTitle}}",
-    "",
-    "{{phaseBody}}",
-    "",
-    "---",
-    "",
-    "Fix only the issues described in the failure notes above. Make the minimum changes necessary to satisfy the failing criteria. When done, output a brief summary of what you changed.",
-    ""
-  ],
-  "commit": [
-    "You are Ralph's commit agent. A phase has been implemented and verified.",
-    "Your job is to decide which changed files belong to this phase and commit them.",
-    "",
-    "## Phase just completed",
-    "",
-    "### {{phaseTitle}}",
-    "",
-    "{{phaseBody}}",
-    "",
-    "---",
-    "",
-    "## Changed repositories",
-    "",
-    "{{repoSections}}",
-    "",
-    "---",
-    "",
-    "For each repository listed above, output a commit plan using EXACTLY this format (one block per repo):",
-    "",
-    "  REPO: <repo name>",
-    "  FILES:",
-    "  - <relative/path/to/file>",
-    "  COMMIT: ralph: <imperative summary, max 72 chars>",
-    "  DESCRIPTION:",
-    "  - <bullet: what changed and why — focus on intent, not mechanics>",
-    "  - <add one bullet per logical group of changes>",
-    "  END_COMMIT",
-    "",
-    "Rules:",
-    "- Only include files shown in the git status above that are relevant to this phase.",
-    "- Use paths exactly as shown in the git status output (relative to repo root).",
-    "- COMMIT line: start with \"ralph: \" then a short imperative verb phrase (≤72 chars total).",
-    "- DESCRIPTION bullets: explain *what* moved or changed and *why*, not line-by-line mechanics.",
-    "- If a repository has no files relevant to this phase, output: REPO: <name>\\nSKIP",
-    "- Do not output anything outside the structured REPO / END_COMMIT blocks.",
-    ""
-  ]
-}