bmalph 2.8.0 → 2.9.0

package/README.md

@@ -10,7 +10,7 @@
 [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) planning + [Ralph](https://github.com/snarktank/ralph) autonomous implementation, wired through platform-specific instructions, skills, and command indexes.
 
 <p align="center">
-  <img src="docs/bmalph-diagram-light.svg" alt="bmalph workflow diagram" width="800" />
+  <img src="docs/bmalph-diagram.png" alt="bmalph workflow diagram" width="800" />
 </p>
 
 ## What is bmalph?
@@ -36,14 +36,15 @@ bmalph provides:
 
 bmalph works with multiple AI coding assistants. Each platform gets BMAD planning (Phases 1-3). The Ralph autonomous loop (Phase 4) requires a CLI-based platform.
 
-| Platform       | ID            | Tier                | Instructions File                 | Commands                         |
-| -------------- | ------------- | ------------------- | --------------------------------- | -------------------------------- |
-| Claude Code    | `claude-code` | full                | `CLAUDE.md`                       | `.claude/commands/` directory    |
-| OpenAI Codex   | `codex`       | full                | `AGENTS.md`                       | Codex Skills (`.agents/skills/`) |
-| Cursor         | `cursor`      | full (experimental) | `.cursor/rules/bmad.mdc`          | `_bmad/COMMANDS.md`              |
-| Windsurf       | `windsurf`    | instructions-only   | `.windsurf/rules/bmad.md`         | `_bmad/COMMANDS.md`              |
-| GitHub Copilot | `copilot`     | full (experimental) | `.github/copilot-instructions.md` | `_bmad/COMMANDS.md`              |
-| Aider          | `aider`       | instructions-only   | `CONVENTIONS.md`                  | `_bmad/COMMANDS.md`              |
+| Platform       | ID            | Tier                | Instructions File                 | Commands                              |
+| -------------- | ------------- | ------------------- | --------------------------------- | ------------------------------------- |
+| Claude Code    | `claude-code` | full                | `CLAUDE.md`                       | `.claude/commands/` directory         |
+| OpenAI Codex   | `codex`       | full                | `AGENTS.md`                       | Codex Skills (`.agents/skills/`)      |
+| OpenCode       | `opencode`    | full                | `AGENTS.md`                       | OpenCode Skills (`.opencode/skills/`) |
+| Cursor         | `cursor`      | full (experimental) | `.cursor/rules/bmad.mdc`          | `_bmad/COMMANDS.md`                   |
+| Windsurf       | `windsurf`    | instructions-only   | `.windsurf/rules/bmad.md`         | `_bmad/COMMANDS.md`                   |
+| GitHub Copilot | `copilot`     | full (experimental) | `.github/copilot-instructions.md` | `_bmad/COMMANDS.md`                   |
+| Aider          | `aider`       | instructions-only   | `CONVENTIONS.md`                  | `_bmad/COMMANDS.md`                   |
 
 **Tiers:**
 
@@ -55,7 +56,7 @@ bmalph works with multiple AI coding assistants. Each platform gets BMAD plannin
 - Node.js 20+
 - Bash (WSL or Git Bash on Windows)
 - A supported AI coding platform (see table above)
-- For Ralph loop (Phase 4): Claude Code (`claude`), Codex CLI (`codex`), Copilot CLI (`copilot`), or Cursor CLI (`cursor-agent`; older `agent` installs are also supported)
+- For Ralph loop (Phase 4): Claude Code (`claude`), Codex CLI (`codex`), OpenCode (`opencode`), Copilot CLI (`copilot`), or Cursor CLI (`cursor-agent`; older `agent` installs are also supported)
 
 ## Installation
 
@@ -85,15 +86,15 @@ bmalph init
 
 **Platform resolution:** `--platform` flag > auto-detect from project markers > interactive prompt > default `claude-code`
 
-Strong markers such as `.cursor/`, `.claude/`, `.windsurf/`, `.github/copilot-instructions.md`, and `.aider.conf.yml` are auto-detected directly. Root-only `AGENTS.md` and `CLAUDE.md` are treated as weak hints and may still trigger the interactive platform prompt.
+Strong markers such as `.cursor/`, `.claude/`, `.opencode/`, `.windsurf/`, `.github/copilot-instructions.md`, and `.aider.conf.yml` are auto-detected directly. Root-only `AGENTS.md` and `CLAUDE.md` are treated as weak hints and may still trigger the interactive platform prompt.
 
 This installs:
 
 - `_bmad/` — BMAD agents and workflows
-- `.ralph/` — Ralph loop, libs, templates (drivers for claude-code, codex, copilot, and cursor)
+- `.ralph/` — Ralph loop, libs, templates (drivers for claude-code, codex, opencode, copilot, and cursor)
 - `bmalph/` — State management (config.json, stores selected platform)
 - Updates the platform's instructions file with BMAD workflow instructions (e.g. `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/bmad.mdc`)
-- Delivers BMAD commands using the platform's native mechanism (Claude Code: `.claude/commands/`; Codex: `.agents/skills/`; Cursor, Windsurf, Copilot, and Aider: `_bmad/COMMANDS.md`)
+- Delivers BMAD commands using the platform's native mechanism (Claude Code: `.claude/commands/`; Codex: `.agents/skills/`; OpenCode: `.opencode/skills/`; Cursor, Windsurf, Copilot, and Aider: `_bmad/COMMANDS.md`)
 
 ### Migrating from standalone BMAD
 
@@ -166,7 +167,7 @@ Available in any phase for supporting tasks:
 
 ### Step 3: Implement with Ralph (Phase 4)
 
-> **Note:** Ralph is only available on **full** tier platforms (Claude Code, OpenAI Codex, GitHub Copilot, Cursor). Instructions-only platforms (Windsurf, Aider) support Phases 1-3 only. GitHub Copilot and Cursor support is experimental.
+> **Note:** Ralph is only available on **full** tier platforms (Claude Code, OpenAI Codex, OpenCode, GitHub Copilot, Cursor). Instructions-only platforms (Windsurf, Aider) support Phases 1-3 only. GitHub Copilot and Cursor support is experimental.
 
 Run `bmalph implement` from the terminal, or use the `/bmalph-implement` slash command in Claude Code.
 
@@ -231,12 +232,12 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 
 ### init options
 
-| Flag                       | Description                                                                        | Default        |
-| -------------------------- | ---------------------------------------------------------------------------------- | -------------- |
-| `-n, --name <name>`        | Project name                                                                       | directory name |
-| `-d, --description <desc>` | Project description                                                                | (prompted)     |
-| `--platform <id>`          | Target platform (`claude-code`, `codex`, `cursor`, `windsurf`, `copilot`, `aider`) | auto-detect    |
-| `--dry-run`                | Preview changes without writing files                                              |                |
+| Flag                       | Description                                                                                    | Default        |
+| -------------------------- | ---------------------------------------------------------------------------------------------- | -------------- |
+| `-n, --name <name>`        | Project name                                                                                   | directory name |
+| `-d, --description <desc>` | Project description                                                                            | (prompted)     |
+| `--platform <id>`          | Target platform (`claude-code`, `codex`, `opencode`, `cursor`, `windsurf`, `copilot`, `aider`) | auto-detect    |
+| `--dry-run`                | Preview changes without writing files                                                          |                |
 
 ### implement options
 
@@ -278,11 +279,12 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 
 ### run options
 
-| Flag                  | Description                                                    |
-| --------------------- | -------------------------------------------------------------- |
-| `--driver <platform>` | Override platform driver (claude-code, codex, copilot, cursor) |
-| `--interval <ms>`     | Dashboard refresh interval in milliseconds (default: 2000)     |
-| `--no-dashboard`      | Run Ralph without the dashboard overlay                        |
+| Flag                   | Description                                                                 |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `--driver <platform>`  | Override platform driver (claude-code, codex, opencode, copilot, cursor)    |
+| `--review/--no-review` | Enable/disable periodic code review (Claude Code only, prompted by default) |
+| `--interval <ms>`      | Dashboard refresh interval in milliseconds (default: 2000)                  |
+| `--no-dashboard`       | Run Ralph without the dashboard overlay                                     |
 
 ### watch options
 
@@ -294,10 +296,11 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 
 ## Command Delivery
 
-bmalph bundles 51 BMAD and bmalph command definitions. Delivery varies by platform:
+bmalph bundles 54 BMAD and bmalph command definitions. Delivery varies by platform:
 
 - **Claude Code** — installed as files in `.claude/commands/` (invoke with `/command-name`)
 - **OpenAI Codex** — delivered as Codex Skills in `.agents/skills/` (invoke with `$command-name`)
+- **OpenCode** — delivered as OpenCode Skills in `.opencode/skills/`
 - **Cursor** — discoverable via `_bmad/COMMANDS.md`; ask Cursor to run the BMAD master agent
 - **Windsurf, Copilot, Aider** — discoverable via `_bmad/COMMANDS.md` reference index
 
@@ -324,6 +327,7 @@ For the full list:
 
 - Claude Code: run `/bmad-help`
 - OpenAI Codex: inspect `.agents/skills/`
+- OpenCode: inspect `.opencode/skills/`
 - Cursor, Windsurf, Copilot, Aider: open `_bmad/COMMANDS.md`
 
 ### Transition to Ralph
@@ -358,7 +362,7 @@ project/
 │   ├── planning-artifacts/    # PRD, architecture, stories
 │   ├── implementation-artifacts/ # Sprint plans (optional)
 │   └── brainstorming/         # Brainstorm sessions (optional)
-├── .ralph/                    # Ralph autonomous loop (drivers for claude-code, codex, copilot, and cursor)
+├── .ralph/                    # Ralph autonomous loop (drivers for claude-code, codex, opencode, copilot, and cursor)
 │   ├── ralph_loop.sh          # Main loop script
 │   ├── ralph_import.sh        # Import requirements into Ralph
 │   ├── ralph_monitor.sh       # Monitor loop progress
@@ -367,6 +371,7 @@ project/
 │   ├── drivers/               # Platform driver scripts
 │   │   ├── claude-code.sh     # Claude Code driver (uses `claude`)
 │   │   ├── codex.sh           # OpenAI Codex driver (uses `codex exec`)
+│   │   ├── opencode.sh        # OpenCode driver (uses `opencode run`)
 │   │   ├── copilot.sh         # GitHub Copilot driver (uses `copilot`, experimental)
 │   │   ├── cursor.sh          # Cursor driver (uses `cursor-agent`/`agent`, experimental)
 │   │   └── cursor-agent-wrapper.sh # Wrapper for Windows .cmd Cursor installs
@@ -396,6 +401,7 @@ Ralph is a bash loop that spawns fresh AI coding sessions using a **platform dri
 
 - **Claude Code driver** — invokes `claude` with `--output-format json`, `--permission-mode bypassPermissions`, `--allowedTools`, and explicit `--resume <session_id>`
 - **Codex driver** — invokes `codex exec --json --sandbox workspace-write` with explicit `--resume <session_id>`
+- **OpenCode driver** — invokes `opencode run --agent build --format json` with optional `--continue --session <session_id>`
 - **Copilot driver** _(experimental)_ — invokes `copilot --autopilot --yolo` with plain-text output
 - **Cursor driver** _(experimental)_ — invokes `cursor-agent -p --force --output-format json`, persists `session_id` for `--resume`, and switches to `stream-json` only for live output
 
@@ -410,6 +416,7 @@ Safety mechanisms:
 
 - **Circuit breaker** — prevents infinite loops on failing stories
 - **Response analyzer** — detects stuck or repeating outputs
+- **Code review** — optional periodic review every 5 loops (`--review`, Claude Code only). A read-only session analyzes git diffs and feeds structured findings into the next implementation loop
 - **Completion** — loop exits when all `@fix_plan.md` items are checked off
 
 Cursor-specific runtime checks:
@@ -478,7 +485,7 @@ Notes:
 | Ralph stops mid-loop          | Circuit breaker detected stagnation. Check `.ralph/logs/`                                                          |
 | Doctor reports version drift  | Run `bmalph upgrade` to update bundled assets                                                                      |
 | Wrong platform detected       | Re-run `bmalph init --platform <id>` with the correct platform                                                     |
-| Ralph unavailable on platform | Ralph requires a full tier platform (claude-code, codex, copilot, or cursor)                                       |
+| Ralph unavailable on platform | Ralph requires a full tier platform (claude-code, codex, opencode, copilot, or cursor)                             |
 
 ### Windows: Cursor Driver
 
@@ -513,6 +520,7 @@ Then remove the bmalph-managed sections from your instructions file. The file de
 
 - **Claude Code** — remove `.claude/commands/` and bmalph section from `CLAUDE.md`
 - **Codex** — remove bmalph sections from `AGENTS.md`
+- **OpenCode** — remove `.opencode/skills/bmad-*/` and bmalph sections from `AGENTS.md`
 - **Cursor** — remove `.cursor/rules/bmad.mdc`
 - **Windsurf** — remove `.windsurf/rules/bmad.md`
 - **Copilot** — remove bmalph sections from `.github/copilot-instructions.md`
@@ -598,6 +606,21 @@ bmalph run
 #    Then: bmalph run
 ```
 
+**OpenCode:**
+
+```bash
+# 1. Open your project in your AI coding assistant
+
+# 2. Use OpenCode Skills such as $analyst, $create-prd, and $architect
+#    See .opencode/skills/ and _bmad/COMMANDS.md for the full catalog
+
+# 3. Follow phases: Analysis -> Planning -> Solutioning
+
+# 4. Transition to Ralph
+#    Run: bmalph implement
+#    Then: bmalph run
+```
+
 **Cursor, Copilot, Windsurf, Aider:**
 
 ```bash

package/dist/cli.js

@@ -59,7 +59,7 @@ program
     .description("Initialize bmalph in the current project")
     .option("-n, --name <name>", "Project name")
     .option("-d, --description <desc>", "Project description")
-    .option("--platform <id>", "Target platform (claude-code, codex, cursor, windsurf, copilot, aider)")
+    .option("--platform <id>", "Target platform (claude-code, codex, opencode, cursor, windsurf, copilot, aider)")
     .option("--dry-run", "Preview changes without writing files")
     .action(async (opts) => initCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 program
@@ -102,9 +102,10 @@ program
 program
     .command("run")
     .description("Start Ralph loop with live dashboard")
-    .option("--driver <platform>", "Override platform driver (claude-code, codex, copilot, cursor)")
+    .option("--driver <platform>", "Override platform driver (claude-code, codex, opencode, copilot, cursor)")
     .option("--interval <ms>", "Dashboard refresh interval in milliseconds (default: 2000)")
     .option("--no-dashboard", "Run Ralph without the dashboard overlay")
+    .option("--review", "Enable periodic code review loop (~10-14% more tokens)")
     .action(async (opts) => runCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 void program.parseAsync();
 //# sourceMappingURL=cli.js.map

package/dist/commands/doctor-checks.js

@@ -15,7 +15,7 @@ export async function checkCommandAvailable(command) {
         return false;
     }
 }
-export async function checkNodeVersion(_projectDir) {
+export function checkNodeVersion(_projectDir) {
     const major = parseInt(process.versions.node.split(".")[0]);
     return {
         label: "Node version >= 20",

package/dist/commands/doctor-health-checks.js

@@ -4,9 +4,10 @@ import { readConfig } from "../utils/config.js";
 import { parseGitignoreLines } from "../utils/file-system.js";
 import { getBundledVersions } from "../installer.js";
 import { isEnoent, formatError } from "../utils/errors.js";
+import { GITIGNORE_ENTRIES } from "../utils/constants.js";
 export async function checkGitignore(projectDir) {
     const label = ".gitignore has required entries";
-    const required = [".ralph/logs/", "_bmad-output/"];
+    const required = [...GITIGNORE_ENTRIES];
     try {
         const content = await readFile(join(projectDir, ".gitignore"), "utf-8");
         const existingLines = parseGitignoreLines(content);

package/dist/commands/init.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
-import { select, input } from "@inquirer/prompts";
+import select from "@inquirer/select";
+import input from "@inquirer/input";
 import { writeConfig } from "../utils/config.js";
 import { installProject, mergeInstructionsFile, isInitialized, previewInstall, getBundledVersions, } from "../installer.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";
@@ -101,6 +102,7 @@ async function runInit(options) {
     const bundledVersions = await getBundledVersions();
     const config = {
         name: validatedName,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive against future refactors
         description: description ?? "",
         createdAt: new Date().toISOString(),
         platform: platform.id,

package/dist/commands/reset.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { confirm } from "@inquirer/prompts";
+import confirm from "@inquirer/confirm";
 import { isInitialized } from "../installer.js";
 import { buildResetPlan, executeResetPlan, planToDryRunActions } from "../reset.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";

package/dist/commands/run.js

@@ -24,6 +24,10 @@ async function executeRun(options) {
     if (platform.experimental) {
         console.log(chalk.yellow(`Warning: ${platform.displayName} support is experimental`));
     }
+    const reviewEnabled = await resolveReviewMode(options.review, platform);
+    if (reviewEnabled) {
+        console.log(chalk.cyan("Enhanced mode: code review every 5 implementation loops"));
+    }
     const interval = parseInterval(options.interval);
     let useDashboard = dashboard;
     if (useDashboard) {
@@ -39,9 +43,10 @@ async function executeRun(options) {
     }
     const ralph = spawnRalphLoop(projectDir, platform.id, {
         inheritStdio: !useDashboard,
+        ...(reviewEnabled && { reviewEnabled }),
     });
     if (useDashboard) {
-        await startRunDashboard({ projectDir, interval, ralph });
+        await startRunDashboard({ projectDir, interval, ralph, reviewEnabled });
         if (ralph.state === "stopped") {
             applyRalphExitCode(ralph.exitCode);
         }
@@ -65,4 +70,34 @@ function resolvePlatform(driverOverride, configPlatform) {
     }
     return getPlatform(id);
 }
+async function resolveReviewMode(reviewFlag, platform) {
+    if (reviewFlag === true) {
+        if (platform.id !== "claude-code") {
+            throw new Error("--review requires Claude Code (other drivers lack read-only enforcement)");
+        }
+        return true;
+    }
+    if (reviewFlag === false) {
+        return false;
+    }
+    if (platform.id !== "claude-code") {
+        return false;
+    }
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    const { default: select } = await import("@inquirer/select");
+    const mode = await select({
+        message: "Quality mode:",
+        choices: [
+            { name: "Standard — current behavior (no extra cost)", value: "standard" },
+            {
+                name: "Enhanced — periodic code review every 5 loops (~10-14% more tokens)",
+                value: "enhanced",
+            },
+        ],
+        default: "standard",
+    });
+    return mode === "enhanced";
+}
 //# sourceMappingURL=run.js.map

package/dist/commands/status.js

@@ -8,9 +8,6 @@ import { resolveProjectPlatform } from "../platform/resolve.js";
 import { getFullTierPlatformNames } from "../platform/registry.js";
 import { getPlatformAnalysisHint, getPlatformPrdHint } from "../platform/guidance.js";
 import { scanProjectArtifacts } from "../transition/artifact-scan.js";
-function getCursorNextAction() {
-    return "Read _bmad/COMMANDS.md and ask Cursor to run the BMAD master agent";
-}
 export async function statusCommand(options) {
     await withErrorHandling(() => runStatus(options));
 }
@@ -151,14 +148,8 @@ function getNextAction(phase, status, ralphStatus, platform) {
     }
     switch (phase) {
         case 1:
-            if (platform.id === "cursor") {
-                return getCursorNextAction();
-            }
             return getPlatformAnalysisHint(platform);
         case 2:
-            if (platform.id === "cursor") {
-                return getCursorNextAction();
-            }
             return getPlatformPrdHint(platform);
         case 3:
             return "Run: bmalph implement";

package/dist/commands/upgrade.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { confirm } from "@inquirer/prompts";
+import confirm from "@inquirer/confirm";
 import { isInitialized, copyBundledAssets, mergeInstructionsFile, previewUpgrade, getBundledVersions, } from "../installer.js";
 import { readConfig, writeConfig } from "../utils/config.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";

package/dist/installer/metadata.js

@@ -22,7 +22,7 @@ export async function getBundledVersions() {
     const versionsPath = join(__dirname, "..", "..", "bundled-versions.json");
     try {
         const versions = JSON.parse(await readFile(versionsPath, "utf-8"));
-        if (!versions || typeof versions.bmadCommit !== "string") {
+        if (typeof versions.bmadCommit !== "string") {
             throw new Error("Invalid bundled-versions.json structure: missing bmadCommit");
         }
         return {

package/dist/installer/project-files.js

@@ -2,7 +2,7 @@ import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { atomicWriteFile, exists, parseGitignoreLines, replaceSection, } from "../utils/file-system.js";
 import { isEnoent } from "../utils/errors.js";
-import { CONFIG_FILE, STATE_DIR } from "../utils/constants.js";
+import { CONFIG_FILE, GITIGNORE_ENTRIES, STATE_DIR } from "../utils/constants.js";
 import { getDefaultPlatform } from "./metadata.js";
 import { isTemplateCustomized } from "./template-files.js";
 export async function updateGitignore(projectDir) {
@@ -16,8 +16,7 @@ export async function updateGitignore(projectDir) {
             throw err;
     }
     const existingLines = parseGitignoreLines(existing);
-    const entries = [".ralph/logs/", "_bmad-output/"];
-    const newEntries = entries.filter((e) => !existingLines.has(e));
+    const newEntries = GITIGNORE_ENTRIES.filter((e) => !existingLines.has(e));
     if (newEntries.length === 0)
         return;
     const suffix = existing.length > 0 && !existing.endsWith("\n")

package/dist/installer/ralph-assets.js

@@ -8,8 +8,10 @@ export async function installRalphAssets(projectDir, ralphDir, platform, package
     await mkdir(join(projectDir, ".ralph"), { recursive: true });
     const promptPath = join(projectDir, ".ralph/PROMPT.md");
     const agentPath = join(projectDir, ".ralph/@AGENT.md");
+    const reviewPromptPath = join(projectDir, ".ralph/REVIEW_PROMPT.md");
     const promptCustomized = await isTemplateCustomized(promptPath, "PROMPT.md");
     const agentCustomized = await isTemplateCustomized(agentPath, "AGENT.md");
+    const reviewPromptCustomized = await isTemplateCustomized(reviewPromptPath, "REVIEW_PROMPT.md");
     if (!promptCustomized) {
         await cp(join(ralphDir, "templates/PROMPT.md"), promptPath, {
             dereference: false,
@@ -20,6 +22,11 @@ export async function installRalphAssets(projectDir, ralphDir, platform, package
             dereference: false,
         });
     }
+    if (!reviewPromptCustomized) {
+        await cp(join(ralphDir, "templates/REVIEW_PROMPT.md"), reviewPromptPath, {
+            dereference: false,
+        });
+    }
     await cp(join(ralphDir, "RALPH-REFERENCE.md"), join(projectDir, ".ralph/RALPH-REFERENCE.md"), {
         dereference: false,
     });
@@ -83,6 +90,7 @@ export async function installRalphAssets(projectDir, ralphDir, platform, package
             ".ralph/lib/",
             ...(!promptCustomized ? [".ralph/PROMPT.md"] : []),
             ...(!agentCustomized ? [".ralph/@AGENT.md"] : []),
+            ...(!reviewPromptCustomized ? [".ralph/REVIEW_PROMPT.md"] : []),
             ...(!ralphrcCustomized && currentRalphrc !== renderedRalphrc ? [".ralph/.ralphrc"] : []),
             ".ralph/RALPH-REFERENCE.md",
         ],

package/dist/installer/template-files.js

@@ -5,6 +5,7 @@ import { getBundledRalphDir } from "./metadata.js";
 const TEMPLATE_PLACEHOLDERS = {
     "PROMPT.md": "[YOUR PROJECT NAME]",
     "AGENT.md": "pip install -r requirements.txt",
+    "REVIEW_PROMPT.md": "[YOUR PROJECT NAME]",
 };
 const RALPHRC_TEMPLATE_NAME = "RALPHRC";
 const CLAUDE_ALLOWED_TOOLS_TEMPLATE_LINE = 'ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,EnterPlanMode,ExitPlanMode,NotebookEdit,Bash"';
@@ -49,6 +50,20 @@ QUALITY_GATE_TIMEOUT="\${QUALITY_GATE_TIMEOUT:-120}"
 # Only run gates when the agent signals completion (EXIT_SIGNAL=true)
 QUALITY_GATE_ON_COMPLETION_ONLY="\${QUALITY_GATE_ON_COMPLETION_ONLY:-false}"
 
+`;
+const REVIEW_TEMPLATE_BLOCK = `# =============================================================================
+# PERIODIC CODE REVIEW
+# =============================================================================
+
+# Enable periodic code review loops (set via 'bmalph run --review' or manually)
+# When enabled, Ralph runs a read-only review session every REVIEW_INTERVAL loops.
+# The review agent analyzes git diffs and outputs findings for the next implementation loop.
+# Currently supported on Claude Code only.
+REVIEW_ENABLED="\${REVIEW_ENABLED:-false}"
+
+# Number of implementation loops between review sessions (default: 5)
+REVIEW_INTERVAL="\${REVIEW_INTERVAL:-5}"
+
 `;
 const LEGACY_RALPHRC_TEMPLATE = `# .ralphrc - Ralph project configuration
 # Generated by: ralph enable
@@ -209,6 +224,16 @@ async function isRalphrcCustomized(filePath, platformId) {
     if (matchesManagedPermissionVariants(content, templateWithoutQG)) {
         return false;
     }
+    // Check variants without review block (pre-review installs)
+    const templateWithoutReview = currentTemplate.replace(REVIEW_TEMPLATE_BLOCK, "");
+    if (matchesManagedPermissionVariants(content, templateWithoutReview)) {
+        return false;
+    }
+    // Check variants without both quality gates and review blocks
+    const templateWithoutQGAndReview = templateWithoutQG.replace(REVIEW_TEMPLATE_BLOCK, "");
+    if (matchesManagedPermissionVariants(content, templateWithoutQGAndReview)) {
+        return false;
+    }
     const legacyTemplate = normalizeManagedRalphrcContent(renderLegacyRalphrcTemplate(platformId));
     return content !== legacyTemplate;
 }

package/dist/reset.js

@@ -3,7 +3,7 @@ import { join, posix } from "node:path";
 import { getSlashCommandsDir } from "./installer.js";
 import { exists, atomicWriteFile, parseGitignoreLines, replaceSection, } from "./utils/file-system.js";
 import { isEnoent } from "./utils/errors.js";
-import { BMAD_DIR, RALPH_DIR, BMALPH_DIR, BMAD_OUTPUT_DIR, SKILLS_PREFIX, } from "./utils/constants.js";
+import { BMAD_DIR, RALPH_DIR, BMALPH_DIR, BMAD_OUTPUT_DIR, GITIGNORE_ENTRIES, SKILLS_PREFIX, } from "./utils/constants.js";
 export async function buildResetPlan(projectDir, platform) {
     const plan = {
         directories: [],
@@ -74,8 +74,7 @@ export async function buildResetPlan(projectDir, platform) {
     try {
         const content = await readFile(join(projectDir, ".gitignore"), "utf-8");
         const existingLines = parseGitignoreLines(content);
-        const bmalpEntries = [".ralph/logs/", "_bmad-output/"];
-        for (const entry of bmalpEntries) {
+        for (const entry of GITIGNORE_ENTRIES) {
             if (existingLines.has(entry)) {
                 plan.gitignoreLines.push(entry);
             }

package/dist/run/ralph-process.js

@@ -74,10 +74,10 @@ export async function runBashCommand(command, options = {}) {
             }
             finish(() => reject(new Error(`bash command timed out: ${command}`)));
         }, timeoutMs);
-        child.stdout?.on("data", (chunk) => {
+        child.stdout.on("data", (chunk) => {
             stdout += chunk.toString();
         });
-        child.stderr?.on("data", (chunk) => {
+        child.stderr.on("data", (chunk) => {
             stderr += chunk.toString();
         });
         child.on("close", (exitCode) => finish(() => resolve({
@@ -124,9 +124,14 @@ export async function validateRalphLoop(projectDir) {
     }
 }
 export function spawnRalphLoop(projectDir, platformId, options) {
+    const env = { ...process.env, PLATFORM_DRIVER: platformId };
+    if (options.reviewEnabled) {
+        env.REVIEW_ENABLED = "true";
+        env.REVIEW_INTERVAL = "5";
+    }
     const child = spawn(cachedBashCommand ?? "bash", [BASH_RALPH_LOOP_PATH], {
         cwd: projectDir,
-        env: { ...process.env, PLATFORM_DRIVER: platformId },
+        env,
         stdio: options.inheritStdio ? "inherit" : ["ignore", "pipe", "pipe"],
         detached: process.platform !== "win32",
         windowsHide: true,

package/dist/run/run-dashboard.js

@@ -2,11 +2,12 @@ import { createRefreshCallback } from "../watch/dashboard.js";
 import { createTerminalFrameWriter } from "../watch/frame-writer.js";
 import { FileWatcher } from "../watch/file-watcher.js";
 import { renderFooterLine } from "../watch/renderer.js";
-export function renderStatusBar(ralph) {
+export function renderStatusBar(ralph, reviewEnabled) {
     const pid = ralph.child.pid ?? "?";
+    const badge = reviewEnabled ? " [review]" : "";
     switch (ralph.state) {
         case "running":
-            return `Ralph: running (PID ${pid}) | q: stop/detach`;
+            return `Ralph: running (PID ${pid})${badge} | q: stop/detach`;
         case "stopped":
             return `Ralph: stopped (exit ${ralph.exitCode ?? "?"}) | q: quit`;
         case "detached":
@@ -17,12 +18,12 @@ export function renderQuitPrompt() {
     return "Stop (s) | Detach (d) | Cancel (c)";
 }
 export async function startRunDashboard(options) {
-    const { projectDir, interval, ralph } = options;
+    const { projectDir, interval, ralph, reviewEnabled } = options;
     const frameWriter = createTerminalFrameWriter();
     let showingPrompt = false;
     let stopped = false;
     const footerRenderer = (lastUpdated, cols) => {
-        const leftText = showingPrompt ? renderQuitPrompt() : renderStatusBar(ralph);
+        const leftText = showingPrompt ? renderQuitPrompt() : renderStatusBar(ralph, reviewEnabled);
         return renderFooterLine(leftText, `Updated: ${lastUpdated.toISOString().slice(11, 19)}`, cols);
     };
     const refresh = createRefreshCallback(projectDir, (frame) => {
@@ -100,6 +101,7 @@ export async function startRunDashboard(options) {
             }
             resolve();
         };
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- setRawMode absent in pseudo-TTY
         if (process.stdin.isTTY && process.stdin.setRawMode) {
             process.stdin.setRawMode(true);
             process.stdin.resume();

package/dist/transition/artifact-scan.js

@@ -3,10 +3,7 @@ import { relative } from "node:path";
 import { findArtifactsDir } from "./artifacts.js";
 import { ARTIFACT_DEFINITIONS } from "../utils/artifact-definitions.js";
 import { getPlatform } from "../platform/registry.js";
-import { getPlatformAnalysisHint, getPlatformArchitectureHint, getPlatformEpicsStoriesHint, getPlatformPrdHint, getPlatformReadinessHint, } from "../platform/guidance.js";
-function getCursorNextAction() {
-    return "Read _bmad/COMMANDS.md and ask Cursor to run the BMAD master agent for the next BMAD workflow";
-}
+import { getPlatformAnalysisHint, getPlatformArchitectureHint, getPlatformEpicsStoriesHint, getPlatformMasterAgentHint, getPlatformPrdHint, getPlatformReadinessHint, } from "../platform/guidance.js";
 export function classifyArtifact(filename) {
     for (const rule of ARTIFACT_DEFINITIONS) {
         if (rule.pattern.test(filename)) {
@@ -47,13 +44,13 @@ export function getMissing(phases) {
 export function suggestNext(phases, detectedPhase, platformId) {
     const foundNames = new Set([...phases[1], ...phases[2], ...phases[3]].map((a) => a.name));
     const platform = platformId ? getPlatform(platformId) : null;
-    if (platformId === "cursor") {
+    if (platform && platform.commandDelivery.kind === "index") {
         const allPlanningArtifactsPresent = foundNames.has("PRD") &&
             foundNames.has("Architecture") &&
             foundNames.has("Epics & Stories") &&
             foundNames.has("Readiness Report");
         if (!allPlanningArtifactsPresent) {
-            return getCursorNextAction();
+            return getPlatformMasterAgentHint(platform);
         }
     }
     if (detectedPhase <= 1 && phases[1].length === 0) {

package/dist/transition/context.js

@@ -11,7 +11,7 @@ export function extractSectionWithInfo(content, headingPattern, maxLength = SECT
     // Determine heading level from the match
     const headingLevelMatch = match[0].match(/^(#{1,6})\s/);
     const level = headingLevelMatch ? headingLevelMatch[1].length : 2;
-    const startIndex = (match.index ?? 0) + match[0].length;
+    const startIndex = match.index + match[0].length;
     const rest = content.slice(startIndex);
     // Find next heading of same or higher level
     const nextHeadingPattern = new RegExp(`^#{1,${level}}\\s`, "m");

package/dist/utils/constants.js

@@ -53,6 +53,28 @@ export const CONFIG_FILE = "bmalph/config.json";
 /** Ralph status file path */
 export const RALPH_STATUS_FILE = ".ralph/status.json";
 // =============================================================================
+// Ralph status mapping
+// =============================================================================
+/**
+ * Maps raw Ralph bash status strings to normalized status values.
+ * Single source of truth — used by both validate.ts and ralph-runtime-state.ts.
+ */
+export const RALPH_STATUS_MAP = {
+    running: "running",
+    halted: "blocked",
+    stopped: "blocked",
+    completed: "completed",
+    success: "completed",
+    graceful_exit: "completed",
+    paused: "blocked",
+    error: "blocked",
+};
+// =============================================================================
+// Gitignore entries managed by bmalph
+// =============================================================================
+/** Entries bmalph adds to .gitignore during init and checks during doctor */
+export const GITIGNORE_ENTRIES = [".ralph/logs/", "_bmad-output/"];
+// =============================================================================
 // Dashboard constants
 // =============================================================================
 /** Default dashboard refresh interval in milliseconds */

package/dist/utils/github.js

@@ -132,9 +132,10 @@ export class GitHubClient {
                 typeof data.sha !== "string" ||
                 !("commit" in data) ||
                 !data.commit ||
-                typeof data.commit?.message !== "string" ||
-                !data.commit?.author ||
-                typeof data.commit?.author?.date !== "string") {
+                typeof data.commit.message !==
+                    "string" ||
+                !data.commit.author ||
+                typeof data.commit.author.date !== "string") {
                 return {
                     success: false,
                     error: {