ralph-prd 1.1.0 → 3.0.0

package/README.md

@@ -2,44 +2,27 @@
 
 AI-powered phased implementation runner for [Claude Code](https://claude.ai/claude-code). Go from PRD to shipped code — automatically.
 
-Ralph takes a markdown plan file, breaks it into phases, and executes each one through the Claude CLI with built-in verification, repair loops, and auto-commits.
+Ralph takes a markdown plan file, breaks it into phases and tasks, and executes each one through the Claude CLI with built-in verification, repair loops, and auto-commits.
 
 ## Install
 
-One command installs Ralph and all skills into your project's `.claude/` directory:
-
 ```bash
-# Using npx (recommended)
-npx ralph-prd
-
-# Or using curl
-curl -fsSL https://raw.githubusercontent.com/tahaJemmali/ralph-prd/main/install.sh | bash
-
-# Or clone and run locally
-git clone https://github.com/tahaJemmali/ralph-prd.git
-cd your-project && ../ralph-prd/install.sh
+npx ralph-prd init
 ```
 
-This installs:
-- `.claude/ralph/` — the phased runner
-- `.claude/skills/` — 7 Claude Code skills fetched from [`tahaJemmali/skills`](https://github.com/tahaJemmali/skills) via `npx skills add`
-- On first install, adds `.claude/ralph/` and `.claude/skills/` to `.gitignore` (skipped if `.claude/` already exists, so shared setups are respected)
+This installs skills to `.claude/skills/` and scaffolds a config file. Ralph itself runs directly from the npm package — no files are copied to your project.
 
-### Updating
+Skills are fetched from [`tahaJemmali/skills`](https://github.com/tahaJemmali/skills). Installation retries automatically (3 attempts) and falls back to cached skills on network failure.
 
-To update Ralph and re-fetch skills, just re-run the install command:
+### Updating
 
 ```bash
-npx ralph-prd
+npx ralph-prd init
 ```
 
-Ralph also checks for updates automatically on every run. If a newer version is available, you'll see a notice in the console output.
+Re-running init re-fetches skills. Your `ralph.config.yaml` is preserved.
 
-To update only the skills without reinstalling:
-
-```bash
-node .claude/ralph/ralph-claude.mjs --update-skills
-```
+Ralph also checks for updates automatically on every run.
 
 ## Requirements
 
@@ -68,15 +51,21 @@ Run `/prd-to-plan`. Claude reads the PRD, identifies durable architectural decis
 ### 4. Execute with Ralph
 
 ```bash
-node .claude/ralph/ralph-claude.mjs docs/<feature>/plan.md
+npx ralph-prd run docs/<feature>/plan.md
 ```
 
 Ralph runs each phase through Claude:
-1. **Implementation** — Claude builds the phase
-2. **Verification** — checks acceptance criteria pass
-3. **Repair loop** — if verification fails, auto-repairs (up to N attempts)
-4. **Commit** — stages and commits changes
-5. **Checkpoint** — saves progress for crash recovery
+1. **Task-level implementation** — each phase is broken into individual tasks (user stories) and implemented one at a time for focused, atomic progress
+2. **Per-task commit** — every task gets its own commit with enriched messages (decisions, blockers, notes for next task)
+3. **Verification** — checks acceptance criteria pass after all tasks in the phase complete
+4. **Repair loop** — if verification fails, auto-repairs (up to N attempts)
+5. **Ship-check** — post-commit quality gate
+6. **Checkpoint** — saves progress per-task for crash recovery
+
+Each implementation session receives:
+- The **PRD** for business context (resolved from the plan's `> Source PRD:` line)
+- The **last 5 commits** per repo so tasks build on each other's work
+- The **full plan** for cross-phase awareness
 
 ### 5. Ship check
 
@@ -85,38 +74,67 @@ Run `/ship-check` to validate the final result against your project's documented
 ## CLI Reference
 
 ```bash
-node .claude/ralph/ralph-claude.mjs <plan-file.md> [OPTIONS]
-
-Options:
-  --dry-run          Preview all phases without executing
-  --reset            Delete state and restart from Phase 1
-  --only-phase N     Force re-run phase N (1-based)
-  --i-did-this       Skip Claude self-commit; run separate commit step
-  --send-it          Push branch + open PR when all phases complete
-  --wait-for-it           Pause before each commit for review
-  --skip-ship-check            Skip the post-commit ship-check step entirely
-  --ship-check-retries=N       Retry ship-check up to N times per phase before giving up (default 1)
-  --skip-on-ship-check-fail    Log and continue when all ship-check retries fail instead of hard-stopping
-  --skip-on-verify-fail        Skip verification and continue instead of hard-stopping when all repair attempts fail
-  --update-skills         Re-fetch skills from tahaJemmali/skills and exit
-  --version, -v      Print installed version and exit
+npx ralph-prd init                     Install skills and scaffold config
+npx ralph-prd run <plan.md> [OPTIONS]  Execute a plan
+npx ralph-prd --version                Print version
+
+Run options:
+  --dry-run              Preview all phases without executing
+  --reset                Delete state and restart from Phase 1
+  --only-phase N         Force re-run phase N (1-based)
+  --i-did-this           Skip Claude self-commit; run separate commit step
+  --send-it              Push branch + open PR when all phases complete
+  --wait-for-it          Pause before each commit for review
+  --skip-ship-check      Skip the post-commit ship-check step entirely
+  --ship-check-retries=N Retry ship-check up to N times (default 1)
+  --skip-on-ship-check-fail  Log and continue when ship-check fails
+  --skip-on-verify-fail  Skip verification when all repair attempts fail
+  --log-level=LEVEL      none | necessary | dump (default: necessary)
+  --update-skills        Re-fetch skills and exit
 ```
 
 ### Examples
 
 ```bash
 # Resume from last incomplete phase
-node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md
+npx ralph-prd run docs/auth-rework/plan.md
 
 # Preview the plan
-node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md --dry-run
+npx ralph-prd run docs/auth-rework/plan.md --dry-run
 
 # Re-run only Phase 3
-node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md --only-phase 3
+npx ralph-prd run docs/auth-rework/plan.md --only-phase 3
 
 # Ship it: run all phases, push, open PR
-node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md --send-it
+npx ralph-prd run docs/auth-rework/plan.md --send-it
+
+# Legacy invocation (still works)
+npx ralph-prd docs/auth-rework/plan.md
+```
+
+## Commit Messages
+
+Ralph produces enriched commit messages with context that carries forward between tasks:
+
 ```
+ralph: add user authentication endpoint
+
+- Added POST /auth/login route with JWT response
+- Created JWT token generation utility
+
+Decisions:
+- Chose bcrypt over argon2 for password hashing (broader ecosystem support)
+- Used 15-minute JWT expiry with refresh token pattern per PRD requirement
+
+Blockers:
+- Redis session store not available yet (Phase 3) — using in-memory Map
+
+Next:
+- Token refresh endpoint needs the auth middleware created here
+- Rate limiting should be added before login goes to production
+```
+
+The **Decisions**, **Blockers**, and **Next** sections are optional — included only when relevant.
 
 ## Included Skills
 
@@ -132,9 +150,9 @@ node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md --send-it
 
 Skills are fetched from [`tahaJemmali/skills`](https://github.com/tahaJemmali/skills) during install. You can also install or update them independently with `npx skills add tahaJemmali/skills`.
 
-## Multi-Repo Support
+## Configuration
 
-Create `ralph.config.yaml` in `.claude/ralph/` for monorepo setups:
+Create `.claude/ralph.config.yaml` for multi-repo setups or to customize flags:
 
 ```yaml
 repos:
@@ -158,6 +176,8 @@ hooks:
   afterCommit: npm test
 ```
 
+Config lookup order: `.claude/ralph.config.yaml` (canonical) → `.claude/ralph/ralph.config.yaml` (legacy). If no config exists, Ralph uses the current directory as the single repo.
+
 ## Plan File Format
 
 Plans must follow the template produced by `/prd-to-plan`:
@@ -180,7 +200,9 @@ Plans must follow the template produced by `/prd-to-plan`:
 
 ### What to build
 
-Description of the vertical slice.
+1. First task — implement the login endpoint
+2. Second task — add JWT token generation
+3. Third task — wire up password hashing
 
 ### Acceptance criteria
 
@@ -190,15 +212,31 @@ Description of the vertical slice.
 
 Ralph validates the plan structure before execution and checks off criteria as phases complete.
 
+The "What to build" section is parsed into individual tasks. Numbered items (`1.`, `2.`) or bullet items (`-`, `*`) each become a separate implementation session with its own commit. If the section is a single paragraph, the entire phase runs as one task.
+
 ## How It Works
 
 - **Zero dependencies** — pure Node.js, no npm packages
-- **Crash recovery** — checkpoints after each step; resume where you left off
+- **Runs from package** — no files copied to your project (only skills + config)
+- **Task-level execution** — phases are broken into focused tasks, each with its own implementation + commit cycle
+- **PRD context** — every session gets the source PRD and recent git history
+- **Enriched commits** — decisions, blockers, and notes carry knowledge between tasks
+- **Crash recovery** — checkpoints after each task; resume where you left off
+- **Atomic state writes** — write-then-rename prevents corruption on crash
 - **Live streaming** — see Claude's tool calls, thinking, and output in real-time
 - **Full logging** — JSONL logs of every Claude CLI event per phase
-- **macOS notifications** — get notified when phases complete or fail
+- **Cross-platform notifications** — macOS, Linux (notify-send), and terminal bell fallback
+- **Resilient installs** — retries skill installation, falls back to cached skills on network failure
 - **Safety** — optional `blocked-commands.txt` and `blocked-paths.txt` restrict what Claude can do
 
+## Public API
+
+ralph-prd exports a stable API for use by orchestrators like [ralph-prd-afk](https://github.com/tahaJemmali/ralph-prd-afk):
+
+```javascript
+import { send, preflight, getCumulativeCost } from 'ralph-prd/transport';
+```
+
 ## Acknowledgments
 
 Three of the skills in this repo — [`/grill-me`](https://skills.sh/mattpocock/skills/grill-me), [`/write-a-prd`](https://skills.sh/mattpocock/skills/write-a-prd), and [`/prd-to-plan`](https://skills.sh/mattpocock/skills/prd-to-plan) — are based on [Matt Pocock](https://github.com/mattpocock)'s work. Matt generously gave his blessing to include them here. If you find these useful, go check out his cohort and give him a star.

package/bin/cli.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * bin/cli.mjs — ralph-prd CLI router
+ *
+ * Usage:
+ *   npx ralph-prd init            Install skills and scaffold config
+ *   npx ralph-prd run <plan.md>   Execute a plan
+ *   npx ralph-prd --version       Print version
+ *
+ * The `init` subcommand installs skills to .claude/skills/ and scaffolds
+ * ralph.config.yaml. It does NOT copy the runner — ralph-prd executes
+ * directly from the npm package.
+ *
+ * For backward compatibility, running `npx ralph-prd` without a subcommand
+ * still triggers init (legacy behavior).
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+// ─── Version ─────────────────────────────────────────────────────────────────
+
+const pkg = JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8'));
+const VERSION = pkg.version;
+
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(`ralph-prd v${VERSION}`);
+  process.exit(0);
+}
+
+// ─── Subcommand routing ──────────────────────────────────────────────────────
+
+const subcommand = args.find(a => !a.startsWith('--'));
+
+if (subcommand === 'run') {
+  // npx ralph-prd run <plan.md> [flags]
+  const runArgs = args.filter(a => a !== 'run');
+  const planArg = runArgs.find(a => !a.startsWith('--'));
+
+  if (!planArg) {
+    console.error('Usage: npx ralph-prd run <plan-file.md> [OPTIONS]');
+    process.exit(1);
+  }
+
+  // Import and run ralph-claude.mjs directly from the package
+  // Override process.argv so ralph-claude.mjs sees the correct args
+  process.argv = [process.argv[0], resolve(PKG_ROOT, 'ralph', 'ralph-claude.mjs'), ...runArgs];
+
+  await import(resolve(PKG_ROOT, 'ralph', 'ralph-claude.mjs'));
+
+} else if (subcommand === 'init' || !subcommand) {
+  // npx ralph-prd init  OR  npx ralph-prd (legacy: bare invocation = init)
+  const { install } = await import('./install.mjs');
+  await install();
+
+} else if (subcommand === '--update-skills') {
+  // npx ralph-prd --update-skills
+  process.argv = [process.argv[0], 'ralph-claude.mjs', '--update-skills'];
+  await import(resolve(PKG_ROOT, 'ralph', 'ralph-claude.mjs'));
+
+} else {
+  // Assume it's a plan file path (legacy: npx ralph-prd docs/feature/plan.md)
+  // Treat bare arguments as plan files for backward compat
+  process.argv = [process.argv[0], resolve(PKG_ROOT, 'ralph', 'ralph-claude.mjs'), ...args];
+  await import(resolve(PKG_ROOT, 'ralph', 'ralph-claude.mjs'));
+}

package/bin/install.mjs

@@ -48,6 +48,13 @@ mkdirSync(claudeDir, { recursive: true });
 // Copy ralph runner
 const ralphSrc = resolve(PKG_ROOT, 'ralph');
 const ralphDst = resolve(claudeDir, 'ralph');
+// Preserve user config across updates
+const configDst = resolve(ralphDst, 'ralph.config.yaml');
+let savedConfig = null;
+if (existsSync(configDst)) {
+  savedConfig = readFileSync(configDst, 'utf8');
+}
+
 if (existsSync(ralphDst)) {
   info('Updating existing .claude/ralph/');
   rmSync(ralphDst, { recursive: true });
@@ -62,16 +69,19 @@ const pkg = JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8'));
 writeFileSync(resolve(ralphDst, '.ralph-version'), pkg.version + '\n', 'utf8');
 ok(`Installed ralph runner v${pkg.version} -> .claude/ralph/`);
 
-// Create default ralph.config.yaml if it doesn't exist yet
-const configDst = resolve(ralphDst, 'ralph.config.yaml');
-const configSrc = resolve(ralphDst, 'ralph.config.sample.yaml');
-if (!existsSync(configDst) && existsSync(configSrc)) {
-  copyFileSync(configSrc, configDst);
-  ok('Created default ralph.config.yaml -> .claude/ralph/ralph.config.yaml');
+// Restore saved config or create default from sample
+if (savedConfig !== null) {
+  writeFileSync(configDst, savedConfig, 'utf8');
+  ok('Restored existing ralph.config.yaml');
+} else {
+  const configSrc = resolve(ralphDst, 'ralph.config.sample.yaml');
+  if (existsSync(configSrc)) {
+    copyFileSync(configSrc, configDst);
+    ok('Created default ralph.config.yaml -> .claude/ralph/ralph.config.yaml');
+  }
 }
 
 // Install skills via skills.sh
-info('Installing skills from tahaJemmali/skills…');
 const REQUIRED_SKILLS = [
   'grill-me',
   'write-a-prd',
@@ -81,15 +91,39 @@ const REQUIRED_SKILLS = [
   'review-changes',
   'repo-doc-maintainer',
 ];
-const skillsResult = spawnSync(
-  'npx',
-  ['skills', 'add', 'tahaJemmali/skills', ...REQUIRED_SKILLS.flatMap(s => ['--skill', s]), '-a', 'claude-code', '-y'],
-  { cwd: projectRoot, stdio: 'inherit', encoding: 'utf8' },
-);
-if (skillsResult.status !== 0) {
-  fail('Skills installation failed — aborting. ralph-prd requires all skills to be installed.\n  Retry by running: npx ralph-prd');
+
+info('Installing skills from tahaJemmali/skills…');
+let skillsOk = false;
+for (let attempt = 1; attempt <= 3; attempt++) {
+  const skillsResult = spawnSync(
+    'npx',
+    ['skills', 'add', 'tahaJemmali/skills', ...REQUIRED_SKILLS.flatMap(s => ['--skill', s]), '-a', 'claude-code', '-y'],
+    { cwd: projectRoot, stdio: 'inherit', encoding: 'utf8' },
+  );
+  if (skillsResult.status === 0) {
+    skillsOk = true;
+    break;
+  }
+  if (attempt < 3) {
+    info(`Skills install attempt ${attempt} failed, retrying in 2s…`);
+    spawnSync('sleep', ['2']);
+  }
+}
+
+if (skillsOk) {
+  ok('Installed skills -> .claude/skills/');
+} else {
+  // Check if skills already exist from a previous install
+  const skillsDir = resolve(projectRoot, '.claude', 'skills');
+  const allPresent = REQUIRED_SKILLS.every(s =>
+    existsSync(resolve(skillsDir, s, 'SKILL.md'))
+  );
+  if (allPresent) {
+    info('Skills install failed but existing skills found — continuing with cached skills.');
+  } else {
+    fail('Skills installation failed after 3 attempts — aborting.\n  Retry: npx ralph-prd');
+  }
 }
-ok('Installed skills -> .claude/skills/');
 
 const gitignorePath = resolve(projectRoot, '.gitignore');
 let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "ralph-prd",
-  "version": "1.1.0",
+  "version": "3.0.0",
+  "type": "module",
   "description": "AI-powered phased implementation runner for Claude Code — from PRD to shipped code",
   "bin": {
-    "ralph-prd": "./bin/install.mjs"
+    "ralph-prd": "./bin/cli.mjs"
+  },
+  "exports": {
+    ".": "./ralph/index.mjs",
+    "./transport": "./ralph/lib/transport.mjs"
   },
   "keywords": [
     "claude",

package/ralph/index.mjs

@@ -0,0 +1,10 @@
+/**
+ * ralph-prd public API
+ *
+ * Stable exports for use by ralph-prd-afk and other consumers.
+ * Import via: import { send, preflight } from 'ralph-prd/transport'
+ * Or:         import { send, preflight } from 'ralph-prd'
+ */
+
+export { send, preflight, getCumulativeCost, TransportError } from './lib/transport.mjs';
+export { resolveRepos } from './lib/config.mjs';

package/ralph/lib/committer.mjs

@@ -166,14 +166,36 @@ function parseCommitPlan(text) {
     const commitLine = lines.find(l => l.startsWith('COMMIT:'));
     const commitSubject = commitLine ? commitLine.slice('COMMIT:'.length).trim() : '';
 
-    // DESCRIPTION bullets → body paragraphs
-    const bodyLines = [];
-    let inDesc = false;
+    // Parse sectioned body: DESCRIPTION, DECISIONS, BLOCKERS, NEXT
+    const sections = { DESCRIPTION: [], DECISIONS: [], BLOCKERS: [], NEXT: [] };
+    let currentSection = null;
     for (const line of lines) {
-      if (line === 'DESCRIPTION:') { inDesc = true; continue; }
-      if (inDesc) bodyLines.push(line);
+      if (line === 'DESCRIPTION:') { currentSection = 'DESCRIPTION'; continue; }
+      if (line === 'DECISIONS:')   { currentSection = 'DECISIONS';   continue; }
+      if (line === 'BLOCKERS:')    { currentSection = 'BLOCKERS';    continue; }
+      if (line === 'NEXT:')        { currentSection = 'NEXT';        continue; }
+      // Stop collecting on known non-body headers
+      if (line === 'FILES:' || line.startsWith('COMMIT:') || line.startsWith('REPO:')) {
+        currentSection = null; continue;
+      }
+      if (currentSection) sections[currentSection].push(line);
+    }
+
+    // Build commit body: description bullets, then optional enrichment sections
+    const bodyParts = [];
+    if (sections.DESCRIPTION.length > 0) {
+      bodyParts.push(sections.DESCRIPTION.join('\n'));
+    }
+    if (sections.DECISIONS.length > 0) {
+      bodyParts.push('Decisions:\n' + sections.DECISIONS.join('\n'));
+    }
+    if (sections.BLOCKERS.length > 0) {
+      bodyParts.push('Blockers:\n' + sections.BLOCKERS.join('\n'));
+    }
+    if (sections.NEXT.length > 0) {
+      bodyParts.push('Next:\n' + sections.NEXT.join('\n'));
     }
-    const commitBody = bodyLines.join('\n').trim();
+    const commitBody = bodyParts.join('\n\n').trim();
 
     plans.push({ name, files, commitSubject, commitBody, skip: false });
   }
@@ -325,7 +347,7 @@ export async function runCommitStep({
   const changedRepos = await scanChangedRepos(repos);
 
   if (changedRepos.length === 0) {
-    return { nextStepIndex: si, anyCommitted: false };
+    return { nextTaskNum: si, anyCommitted: false };
   }
 
   // Build and run the commit session

package/ralph/lib/config.mjs

@@ -158,16 +158,28 @@ function parseConfigYaml(content) {
  * Throws an Error with a human-readable message on any validation failure so
  * the caller can print it and exit before any phase begins.
  *
- * @param {string} runnerDir - Absolute path of the directory containing ralph-claude.mjs
+ * @param {string} runnerDir - Absolute path of the directory containing ralph-claude.mjs.
+ *   Also searches process.cwd()/.claude/ for config (new canonical location).
  * @returns {{ repos: Repo[], flags: RalphFlags, hooks: RalphHooks }}
  */
 export function resolveRepos(runnerDir) {
-  const configPath = join(runnerDir, CONFIG_FILENAME);
+  // Config lookup chain: new canonical path → legacy path → no config
+  const cwd = process.cwd();
+  const canonicalPath = join(cwd, '.claude', CONFIG_FILENAME);
+  const legacyPath = join(runnerDir, CONFIG_FILENAME);
+  const configPath = existsSync(canonicalPath) ? canonicalPath
+    : existsSync(legacyPath) ? legacyPath
+    : null;
+
+  if (configPath === legacyPath && existsSync(legacyPath)) {
+    console.log(`[ralph] Config loaded from legacy path: ${legacyPath}`);
+    console.log('[ralph] Move to .claude/ralph.config.yaml for the new canonical location.');
+  }
+
   const defaultFlags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, skipShipCheck: false, shipCheckRetries: 1, skipOnShipCheckFail: true, skipOnVerifyFail: false };
   const defaultHooks = { afterCommit: null };
 
-  if (!existsSync(configPath)) {
-    const cwd = process.cwd();
+  if (!configPath) {
     if (!existsSync(cwd)) {
       throw new Error(`Default repo (cwd) does not exist: ${cwd}`);
     }
@@ -182,7 +194,16 @@ export function resolveRepos(runnerDir) {
   const configDir = dirname(configPath);
 
   if (parsed.repos.length === 0) {
-    throw new Error(`${configPath}: no repos defined`);
+    // No repos defined — fall back to cwd (same as no-config-file behavior),
+    // but still respect flags and hooks from the config.
+    const cwd = process.cwd();
+    if (!existsSync(cwd)) {
+      throw new Error(`Default repo (cwd) does not exist: ${cwd}`);
+    }
+    if (!isGitRepo(cwd)) {
+      throw new Error(`Default repo (cwd) is not a git repository: ${cwd}`);
+    }
+    return { repos: [{ name: basename(cwd), path: cwd }], flags: parsed.flags, hooks: parsed.hooks };
   }
 
   const errors = [];

package/ralph/lib/phase-executor.mjs

@@ -59,7 +59,7 @@ export class PhaseExecutorError extends Error {
  * @param {string}   opts.safetyHeader  - May be empty string
  * @returns {string}
  */
-export function buildImplementationPrompt({ planContent, phase, repos, safetyHeader, selfCommit = true }) {
+export function buildImplementationPrompt({ planContent, phase, repos, safetyHeader, selfCommit = true, prdContent = '', recentCommits = '' }) {
   const primaryRepos = repos.filter(r => !r.writableOnly);
   const writableDirs = repos.filter(r => r.writableOnly);
 
@@ -71,6 +71,16 @@ export function buildImplementationPrompt({ planContent, phase, repos, safetyHea
       writableDirs.map(r => `  - ${r.path}`).join('\n')
     : '';
 
+  // Build recent commits section (shows what prior phases/tasks already built)
+  const recentCommitsSection = recentCommits
+    ? `\n## Recent commits (for context — do NOT redo this work)\n\n${recentCommits}\n\n`
+    : '';
+
+  // Build PRD section (business context for the implementation)
+  const prdSection = prdContent
+    ? `## Source PRD (business context — understand the WHY behind the plan)\n\n${prdContent.trim()}\n\n---\n\n`
+    : '';
+
   const closingKey = selfCommit ? 'implementation_closing_commit' : 'implementation_closing_no_commit';
 
   return (
@@ -78,6 +88,8 @@ export function buildImplementationPrompt({ planContent, phase, repos, safetyHea
     render('implementation', {
       repoLines,
       writableLines,
+      recentCommits: recentCommitsSection,
+      prdSection,
       planContent: planContent.trim(),
       phaseTitle: phase.title,
       phaseBody: phase.body.trim(),
@@ -118,8 +130,10 @@ export async function runImplementation({
   send,
   isDryRun,
   selfCommit = true,
+  prdContent = '',
+  recentCommits = '',
 }) {
-  const prompt = buildImplementationPrompt({ planContent, phase, repos, safetyHeader, selfCommit });
+  const prompt = buildImplementationPrompt({ planContent, phase, repos, safetyHeader, selfCommit, prdContent, recentCommits });
   const step = logWriter.openStep(phaseNum, taskNum, 'implementation', phase.title);
 
   step.writeHeader();