bmalph 2.2.1 → 2.3.0

package/dist/installer.d.ts

@@ -1,3 +1,4 @@
+import type { Platform } from "./platform/types.js";
 export declare function getPackageVersion(): string;
 export interface BundledVersions {
     bmadCommit: string;
@@ -19,10 +20,20 @@ export interface PreviewUpgradeResult {
     wouldCreate: string[];
     wouldPreserve: string[];
 }
-export declare function copyBundledAssets(projectDir: string): Promise<UpgradeResult>;
-export declare function installProject(projectDir: string): Promise<void>;
+export declare function copyBundledAssets(projectDir: string, platform?: Platform): Promise<UpgradeResult>;
+export declare function installProject(projectDir: string, platform?: Platform): Promise<void>;
 export declare function generateManifests(projectDir: string): Promise<void>;
+/**
+ * Merge the BMAD instructions snippet into the platform's instructions file.
+ * Creates the file if it doesn't exist, replaces an existing BMAD section on upgrade.
+ */
+export declare function mergeInstructionsFile(projectDir: string, platform?: Platform): Promise<void>;
+/**
+ * @deprecated Use `mergeInstructionsFile(projectDir)` instead.
+ * Kept for backward compatibility during migration.
+ */
 export declare function mergeClaudeMd(projectDir: string): Promise<void>;
 export declare function isInitialized(projectDir: string): Promise<boolean>;
-export declare function previewInstall(projectDir: string): Promise<PreviewInstallResult>;
-export declare function previewUpgrade(projectDir: string): Promise<PreviewUpgradeResult>;
+export declare function hasExistingBmadDir(projectDir: string): Promise<boolean>;
+export declare function previewInstall(projectDir: string, platform?: Platform): Promise<PreviewInstallResult>;
+export declare function previewUpgrade(projectDir: string, platform?: Platform): Promise<PreviewUpgradeResult>;

package/dist/installer.js

@@ -63,7 +63,86 @@ async function isTemplateCustomized(filePath, templateName) {
         throw err;
     }
 }
-export async function copyBundledAssets(projectDir) {
+/**
+ * Lazily loads the default (claude-code) platform to avoid circular imports
+ * and keep backward compatibility for callers that don't pass a platform.
+ */
+async function getDefaultPlatform() {
+    const { claudeCodePlatform } = await import("./platform/claude-code.js");
+    return claudeCodePlatform;
+}
+/**
+ * Deliver slash commands based on the platform's command delivery strategy.
+ *
+ * - "directory": Copy command files to a directory (e.g., .claude/commands/)
+ * - "inline": Merge command content as sections in the instructions file
+ * - "none": Skip command delivery entirely
+ */
+async function deliverCommands(projectDir, platform, slashCommandsDir) {
+    const delivery = platform.commandDelivery;
+    if (delivery.kind === "none") {
+        return [];
+    }
+    const slashFiles = await readdir(slashCommandsDir);
+    const bundledCommandNames = new Set(slashFiles.filter((f) => f.endsWith(".md")));
+    if (delivery.kind === "directory") {
+        const commandsDir = join(projectDir, delivery.dir);
+        await mkdir(commandsDir, { recursive: true });
+        // Clean stale bmalph-owned commands before copying (preserve user-created commands)
+        try {
+            const existingCommands = await readdir(commandsDir);
+            for (const file of existingCommands) {
+                if (file.endsWith(".md") && bundledCommandNames.has(file)) {
+                    await rm(join(commandsDir, file), { force: true });
+                }
+            }
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+        for (const file of bundledCommandNames) {
+            await cp(join(slashCommandsDir, file), join(commandsDir, file), { dereference: false });
+        }
+        return [`${delivery.dir}/`];
+    }
+    if (delivery.kind === "inline") {
+        // Merge command content as sections in the instructions file
+        const instructionsPath = join(projectDir, platform.instructionsFile);
+        let existing = "";
+        try {
+            existing = await readFile(instructionsPath, "utf-8");
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+        const commandSections = [];
+        for (const file of [...bundledCommandNames].sort()) {
+            const commandName = file.replace(/\.md$/, "");
+            const content = await readFile(join(slashCommandsDir, file), "utf-8");
+            commandSections.push(`### Command: ${commandName}\n\n${content.trim()}`);
+        }
+        const inlineMarker = "## BMAD Commands";
+        const commandsBlock = `\n${inlineMarker}\n\n${commandSections.join("\n\n---\n\n")}\n`;
+        if (existing.includes(inlineMarker)) {
+            // Replace existing commands section
+            const sectionStart = existing.indexOf(inlineMarker);
+            const before = existing.slice(0, sectionStart);
+            const afterSection = existing.slice(sectionStart);
+            const nextHeadingMatch = afterSection.match(/\n## (?!BMAD Commands)/);
+            const after = nextHeadingMatch ? afterSection.slice(nextHeadingMatch.index) : "";
+            await atomicWriteFile(instructionsPath, before.trimEnd() + commandsBlock + after);
+        }
+        else {
+            await atomicWriteFile(instructionsPath, existing + commandsBlock);
+        }
+        return [platform.instructionsFile];
+    }
+    return [];
+}
+export async function copyBundledAssets(projectDir, platform) {
+    const p = platform ?? (await getDefaultPlatform());
     const bmadDir = getBundledBmadDir();
     const ralphDir = getBundledRalphDir();
     const slashCommandsDir = getSlashCommandsDir();
@@ -77,32 +156,50 @@ export async function copyBundledAssets(projectDir) {
     if (!(await exists(slashCommandsDir))) {
         throw new Error(`Slash commands directory not found at ${slashCommandsDir}. Package may be corrupted.`);
     }
-    // Atomic copy: write to temp dir, then swap with old
+    // Atomic copy: rename-aside pattern to prevent data loss
     const bmadDest = join(projectDir, "_bmad");
-    const bmadTemp = join(projectDir, "_bmad.new");
-    await rm(bmadTemp, { recursive: true, force: true });
-    await cp(bmadDir, bmadTemp, { recursive: true, dereference: false });
+    const bmadOld = join(projectDir, "_bmad.old");
+    const bmadNew = join(projectDir, "_bmad.new");
+    // Clean leftover from previous failed attempt
+    await rm(bmadOld, { recursive: true, force: true });
+    // Move original aside (tolerate ENOENT on first install)
+    try {
+        await rename(bmadDest, bmadOld);
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+        debug("No existing _bmad to preserve (first install)");
+    }
+    // Stage new content
+    await rm(bmadNew, { recursive: true, force: true });
+    await cp(bmadDir, bmadNew, { recursive: true, dereference: false });
+    // Swap in
     try {
-        await rm(bmadDest, { recursive: true, force: true });
-        await rename(bmadTemp, bmadDest);
+        await rename(bmadNew, bmadDest);
     }
     catch (err) {
-        // If rename fails, attempt to restore from temp
+        // Restore original on failure
+        debug(`Rename failed, restoring original: ${formatError(err)}`);
         try {
-            await rename(bmadTemp, bmadDest);
+            await rename(bmadOld, bmadDest);
         }
-        catch {
-            // Best effort restore failed
+        catch (restoreErr) {
+            if (!isEnoent(restoreErr)) {
+                debug(`Could not restore _bmad.old: ${formatError(restoreErr)}`);
+            }
         }
         throw err;
     }
+    // Clean up backup
+    await rm(bmadOld, { recursive: true, force: true });
     // Generate combined manifest from module-help.csv files
     await generateManifests(projectDir);
-    // Generate _bmad/config.yaml
+    // Generate _bmad/config.yaml with platform-specific value
     const projectName = await deriveProjectName(projectDir);
     const escapedName = projectName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     await atomicWriteFile(join(projectDir, "_bmad/config.yaml"), `# BMAD Configuration - Generated by bmalph
-platform: claude-code
+platform: ${p.id}
 project_name: "${escapedName}"
 output_folder: _bmad-output
 user_name: BMad
@@ -136,7 +233,11 @@ modules:
     // Copy .ralphrc from template (skip if user has customized it)
     const ralphrcDest = join(projectDir, ".ralph/.ralphrc");
     if (!(await exists(ralphrcDest))) {
-        await cp(join(ralphDir, "templates/ralphrc.template"), ralphrcDest, { dereference: false });
+        // Read template and inject platform driver
+        let ralphrcContent = await readFile(join(ralphDir, "templates/ralphrc.template"), "utf-8");
+        // Replace default PLATFORM_DRIVER value with the actual platform id
+        ralphrcContent = ralphrcContent.replace(/PLATFORM_DRIVER="\$\{PLATFORM_DRIVER:-[^"]*\}"/, `PLATFORM_DRIVER="\${PLATFORM_DRIVER:-${p.id}}"`);
+        await atomicWriteFile(ralphrcDest, ralphrcContent);
     }
     // Copy Ralph loop and lib → .ralph/
     // Add version marker to ralph_loop.sh
@@ -162,27 +263,27 @@ modules:
         dereference: false,
     });
     await chmod(join(projectDir, ".ralph/ralph_monitor.sh"), 0o755);
-    // Install all slash commands → .claude/commands/
-    // Clean stale bmalph-owned commands before copying (preserve user-created commands)
-    const commandsDir = join(projectDir, ".claude/commands");
-    await mkdir(commandsDir, { recursive: true });
-    const slashFiles = await readdir(slashCommandsDir);
-    const bundledCommandNames = new Set(slashFiles.filter((f) => f.endsWith(".md")));
-    try {
-        const existingCommands = await readdir(commandsDir);
-        for (const file of existingCommands) {
-            if (file.endsWith(".md") && bundledCommandNames.has(file)) {
-                await rm(join(commandsDir, file), { force: true });
+    // Copy Ralph drivers → .ralph/drivers/
+    const driversDir = join(ralphDir, "drivers");
+    if (await exists(driversDir)) {
+        const destDriversDir = join(projectDir, ".ralph/drivers");
+        await rm(destDriversDir, { recursive: true, force: true });
+        await cp(driversDir, destDriversDir, { recursive: true, dereference: false });
+        // Make driver scripts executable
+        try {
+            const driverFiles = await readdir(destDriversDir);
+            for (const file of driverFiles) {
+                if (file.endsWith(".sh")) {
+                    await chmod(join(destDriversDir, file), 0o755);
+                }
             }
         }
+        catch {
+            // Non-fatal if chmod fails
+        }
     }
-    catch (err) {
-        if (!isEnoent(err))
-            throw err;
-    }
-    for (const file of bundledCommandNames) {
-        await cp(join(slashCommandsDir, file), join(commandsDir, file), { dereference: false });
-    }
+    // Deliver slash commands based on platform strategy
+    const commandPaths = await deliverCommands(projectDir, p, slashCommandsDir);
     // Update .gitignore
     await updateGitignore(projectDir);
     const updatedPaths = [
@@ -194,18 +295,18 @@ modules:
         ...(!promptCustomized ? [".ralph/PROMPT.md"] : []),
         ...(!agentCustomized ? [".ralph/@AGENT.md"] : []),
         ".ralph/RALPH-REFERENCE.md",
-        ".claude/commands/",
+        ...commandPaths,
         ".gitignore",
     ];
     return { updatedPaths };
 }
-export async function installProject(projectDir) {
+export async function installProject(projectDir, platform) {
     // Create user directories (not overwritten by upgrade)
     await mkdir(join(projectDir, STATE_DIR), { recursive: true });
     await mkdir(join(projectDir, ".ralph/specs"), { recursive: true });
     await mkdir(join(projectDir, ".ralph/logs"), { recursive: true });
     await mkdir(join(projectDir, ".ralph/docs/generated"), { recursive: true });
-    await copyBundledAssets(projectDir);
+    await copyBundledAssets(projectDir, platform);
 }
 async function deriveProjectName(projectDir) {
     try {
@@ -290,74 +391,54 @@ async function updateGitignore(projectDir) {
         : newEntries.join("\n") + "\n";
     await atomicWriteFile(gitignorePath, existing + suffix);
 }
-export async function mergeClaudeMd(projectDir) {
-    const claudeMdPath = join(projectDir, "CLAUDE.md");
-    const snippet = `
-## BMAD-METHOD Integration
-
-Use \`/bmalph\` to navigate phases. Use \`/bmad-help\` to discover all commands. Use \`/bmalph-status\` for a quick overview.
-
-### Phases
-
-| Phase | Focus | Key Commands |
-|-------|-------|-------------|
-| 1. Analysis | Understand the problem | \`/create-brief\`, \`/brainstorm-project\`, \`/market-research\` |
-| 2. Planning | Define the solution | \`/create-prd\`, \`/create-ux\` |
-| 3. Solutioning | Design the architecture | \`/create-architecture\`, \`/create-epics-stories\`, \`/implementation-readiness\` |
-| 4. Implementation | Build it | \`/sprint-planning\`, \`/create-story\`, then \`/bmalph-implement\` for Ralph |
-
-### Workflow
-
-1. Work through Phases 1-3 using BMAD agents and workflows (interactive, command-driven)
-2. Run \`/bmalph-implement\` to transition planning artifacts into Ralph format, then start Ralph
-
-### Management Commands
-
-| Command | Description |
-|---------|-------------|
-| \`/bmalph-status\` | Show current phase, Ralph progress, version info |
-| \`/bmalph-implement\` | Transition planning artifacts → prepare Ralph loop |
-| \`/bmalph-upgrade\` | Update bundled assets to match current bmalph version |
-| \`/bmalph-doctor\` | Check project health and report issues |
-| \`/bmalph-reset\` | Reset state (soft or hard reset with confirmation) |
-
-### Available Agents
-
-| Command | Agent | Role |
-|---------|-------|------|
-| \`/analyst\` | Analyst | Research, briefs, discovery |
-| \`/architect\` | Architect | Technical design, architecture |
-| \`/pm\` | Product Manager | PRDs, epics, stories |
-| \`/sm\` | Scrum Master | Sprint planning, status, coordination |
-| \`/dev\` | Developer | Implementation, coding |
-| \`/ux-designer\` | UX Designer | User experience, wireframes |
-| \`/qa\` | QA Engineer | Test automation, quality assurance |
-`;
+/**
+ * Merge the BMAD instructions snippet into the platform's instructions file.
+ * Creates the file if it doesn't exist, replaces an existing BMAD section on upgrade.
+ */
+export async function mergeInstructionsFile(projectDir, platform) {
+    const p = platform ?? (await getDefaultPlatform());
+    const instructionsPath = join(projectDir, p.instructionsFile);
+    const snippet = p.generateInstructionsSnippet();
+    const marker = p.instructionsSectionMarker;
+    // Ensure parent directory exists for nested paths (e.g. .cursor/rules/)
+    await mkdir(dirname(instructionsPath), { recursive: true });
     let existing = "";
     try {
-        existing = await readFile(claudeMdPath, "utf-8");
+        existing = await readFile(instructionsPath, "utf-8");
     }
     catch (err) {
         if (!isEnoent(err))
             throw err;
     }
-    if (existing.includes("## BMAD-METHOD Integration")) {
+    if (existing.includes(marker)) {
         // Replace stale section with current content, preserving content after it
-        const sectionStart = existing.indexOf("## BMAD-METHOD Integration");
+        const sectionStart = existing.indexOf(marker);
         const before = existing.slice(0, sectionStart);
         const afterSection = existing.slice(sectionStart);
-        // Find the next level-2 heading after the BMAD section start
-        const nextHeadingMatch = afterSection.match(/\n## (?!BMAD-METHOD Integration)/);
+        // Find the next level-2 heading after the section start
+        const markerEscaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const nextHeadingMatch = afterSection.match(new RegExp(`\\n## (?!${markerEscaped.slice(3)})`));
         const after = nextHeadingMatch ? afterSection.slice(nextHeadingMatch.index) : "";
-        await atomicWriteFile(claudeMdPath, before.trimEnd() + "\n" + snippet + after);
+        await atomicWriteFile(instructionsPath, before.trimEnd() + "\n" + snippet + after);
         return;
     }
-    await atomicWriteFile(claudeMdPath, existing + snippet);
+    await atomicWriteFile(instructionsPath, existing + snippet);
+}
+/**
+ * @deprecated Use `mergeInstructionsFile(projectDir)` instead.
+ * Kept for backward compatibility during migration.
+ */
+export async function mergeClaudeMd(projectDir) {
+    return mergeInstructionsFile(projectDir);
 }
 export async function isInitialized(projectDir) {
     return exists(join(projectDir, CONFIG_FILE));
 }
-export async function previewInstall(projectDir) {
+export async function hasExistingBmadDir(projectDir) {
+    return exists(join(projectDir, "_bmad"));
+}
+export async function previewInstall(projectDir, platform) {
+    const p = platform ?? (await getDefaultPlatform());
     const wouldCreate = [];
     const wouldModify = [];
     const wouldSkip = [];
@@ -368,11 +449,15 @@ export async function previewInstall(projectDir) {
         ".ralph/logs/",
         ".ralph/docs/generated/",
         "_bmad/",
-        ".claude/commands/",
     ];
+    // Add command directory only for directory-based delivery
+    if (p.commandDelivery.kind === "directory") {
+        dirsToCreate.push(`${p.commandDelivery.dir}/`);
+    }
     for (const dir of dirsToCreate) {
         if (await exists(join(projectDir, dir))) {
-            if (dir === "_bmad/" || dir === ".claude/commands/") {
+            if (dir === "_bmad/" ||
+                (p.commandDelivery.kind === "directory" && dir === `${p.commandDelivery.dir}/`)) {
                 wouldModify.push(dir);
             }
         }
@@ -404,19 +489,19 @@ export async function previewInstall(projectDir) {
     else {
         wouldCreate.push(".gitignore");
     }
-    // CLAUDE.md integration check
+    // Instructions file integration check
     try {
-        const claudeMd = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
-        if (claudeMd.includes("## BMAD-METHOD Integration")) {
-            wouldSkip.push("CLAUDE.md (already integrated)");
+        const content = await readFile(join(projectDir, p.instructionsFile), "utf-8");
+        if (content.includes(p.instructionsSectionMarker)) {
+            wouldSkip.push(`${p.instructionsFile} (already integrated)`);
         }
         else {
-            wouldModify.push("CLAUDE.md");
+            wouldModify.push(p.instructionsFile);
         }
     }
     catch (err) {
         if (isEnoent(err)) {
-            wouldCreate.push("CLAUDE.md");
+            wouldCreate.push(p.instructionsFile);
         }
         else {
             throw err;
@@ -424,7 +509,8 @@ export async function previewInstall(projectDir) {
     }
     return { wouldCreate, wouldModify, wouldSkip };
 }
-export async function previewUpgrade(projectDir) {
+export async function previewUpgrade(projectDir, platform) {
+    const p = platform ?? (await getDefaultPlatform());
     const managedPaths = [
         { path: "_bmad/", isDir: true },
         { path: ".ralph/ralph_loop.sh", isDir: false },
@@ -434,24 +520,27 @@ export async function previewUpgrade(projectDir) {
         { path: ".ralph/PROMPT.md", isDir: false, templateName: "PROMPT.md" },
         { path: ".ralph/@AGENT.md", isDir: false, templateName: "AGENT.md" },
         { path: ".ralph/RALPH-REFERENCE.md", isDir: false },
-        { path: ".claude/commands/", isDir: true },
         { path: ".gitignore", isDir: false },
     ];
+    // Add command directory only for directory-based delivery
+    if (p.commandDelivery.kind === "directory") {
+        managedPaths.push({ path: `${p.commandDelivery.dir}/`, isDir: true });
+    }
     const wouldUpdate = [];
     const wouldCreate = [];
     const wouldPreserve = [];
-    for (const { path: p, templateName } of managedPaths) {
-        const fullPath = join(projectDir, p.replace(/\/$/, ""));
+    for (const { path: pathStr, templateName } of managedPaths) {
+        const fullPath = join(projectDir, pathStr.replace(/\/$/, ""));
         if (await exists(fullPath)) {
             if (templateName && (await isTemplateCustomized(fullPath, templateName))) {
-                wouldPreserve.push(p);
+                wouldPreserve.push(pathStr);
             }
             else {
-                wouldUpdate.push(p);
+                wouldUpdate.push(pathStr);
             }
         }
         else {
-            wouldCreate.push(p);
+            wouldCreate.push(pathStr);
         }
     }
     return { wouldUpdate, wouldCreate, wouldPreserve };

package/dist/platform/aider.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from "./types.js";
+export declare const aiderPlatform: Platform;

package/dist/platform/aider.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const aiderPlatform = {
+    id: "aider",
+    displayName: "Aider",
+    tier: "instructions-only",
+    instructionsFile: "CONVENTIONS.md",
+    commandDelivery: { kind: "none" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Ask the BMAD master agent to navigate phases. Ask for help to discover all available agents and workflows.
+
+### Phases
+
+| Phase | Focus | Key Agents |
+|-------|-------|-----------|
+| 1. Analysis | Understand the problem | Analyst agent |
+| 2. Planning | Define the solution | Product Manager agent |
+| 3. Solutioning | Design the architecture | Architect agent |
+
+### Workflow
+
+Work through Phases 1-3 using BMAD agents and workflows interactively.
+
+> **Note:** Ralph (Phase 4 — autonomous implementation) is not supported on this platform.
+
+### Available Agents
+
+| Agent | Role |
+|-------|------|
+| Analyst | Research, briefs, discovery |
+| Architect | Technical design, architecture |
+| Product Manager | PRDs, epics, stories |
+| Scrum Master | Sprint planning, status, coordination |
+| Developer | Implementation, coding |
+| UX Designer | User experience, wireframes |
+| QA Engineer | Test automation, quality assurance |
+`,
+    getDoctorChecks: () => [
+        {
+            id: "instructions-file",
+            label: "CONVENTIONS.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, "CONVENTIONS.md"), "utf-8");
+                    if (content.includes("BMAD-METHOD Integration")) {
+                        return { passed: true };
+                    }
+                    return {
+                        passed: false,
+                        detail: "missing BMAD-METHOD Integration section",
+                        hint: "Run: bmalph init",
+                    };
+                }
+                catch (err) {
+                    if (isEnoent(err)) {
+                        return {
+                            passed: false,
+                            detail: "CONVENTIONS.md not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from "./types.js";
+export declare const claudeCodePlatform: Platform;

package/dist/platform/claude-code.js

@@ -0,0 +1,88 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { exists } from "../utils/file-system.js";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const claudeCodePlatform = {
+    id: "claude-code",
+    displayName: "Claude Code",
+    tier: "full",
+    instructionsFile: "CLAUDE.md",
+    commandDelivery: { kind: "directory", dir: ".claude/commands" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Use \`/bmalph\` to navigate phases. Use \`/bmad-help\` to discover all commands. Use \`/bmalph-status\` for a quick overview.
+
+### Phases
+
+| Phase | Focus | Key Commands |
+|-------|-------|-------------|
+| 1. Analysis | Understand the problem | \`/create-brief\`, \`/brainstorm-project\`, \`/market-research\` |
+| 2. Planning | Define the solution | \`/create-prd\`, \`/create-ux\` |
+| 3. Solutioning | Design the architecture | \`/create-architecture\`, \`/create-epics-stories\`, \`/implementation-readiness\` |
+| 4. Implementation | Build it | \`/sprint-planning\`, \`/create-story\`, then \`/bmalph-implement\` for Ralph |
+
+### Workflow
+
+1. Work through Phases 1-3 using BMAD agents and workflows (interactive, command-driven)
+2. Run \`/bmalph-implement\` to transition planning artifacts into Ralph format, then start Ralph
+
+### Management Commands
+
+| Command | Description |
+|---------|-------------|
+| \`/bmalph-status\` | Show current phase, Ralph progress, version info |
+| \`/bmalph-implement\` | Transition planning artifacts → prepare Ralph loop |
+| \`/bmalph-upgrade\` | Update bundled assets to match current bmalph version |
+| \`/bmalph-doctor\` | Check project health and report issues |
+| \`/bmalph-reset\` | Reset state (soft or hard reset with confirmation) |
+
+### Available Agents
+
+| Command | Agent | Role |
+|---------|-------|------|
+| \`/analyst\` | Analyst | Research, briefs, discovery |
+| \`/architect\` | Architect | Technical design, architecture |
+| \`/pm\` | Product Manager | PRDs, epics, stories |
+| \`/sm\` | Scrum Master | Sprint planning, status, coordination |
+| \`/dev\` | Developer | Implementation, coding |
+| \`/ux-designer\` | UX Designer | User experience, wireframes |
+| \`/qa\` | QA Engineer | Test automation, quality assurance |
+`,
+    getDoctorChecks: () => [
+        {
+            id: "slash-command",
+            label: ".claude/commands/bmalph.md present",
+            check: async (projectDir) => {
+                if (await exists(join(projectDir, ".claude/commands/bmalph.md"))) {
+                    return { passed: true };
+                }
+                return { passed: false, detail: "not found", hint: "Run: bmalph init" };
+            },
+        },
+        {
+            id: "instructions-file",
+            label: "CLAUDE.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
+                    if (content.includes("BMAD-METHOD Integration")) {
+                        return { passed: true };
+                    }
+                    return {
+                        passed: false,
+                        detail: "missing BMAD-METHOD Integration section",
+                        hint: "Run: bmalph init",
+                    };
+                }
+                catch (err) {
+                    if (isEnoent(err)) {
+                        return { passed: false, detail: "CLAUDE.md not found", hint: "Run: bmalph init" };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/codex.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from "./types.js";
+export declare const codexPlatform: Platform;