bmalph 2.2.1 → 2.3.0

package/README.md

@@ -27,11 +27,30 @@ bmalph provides:
 - `bmalph doctor` — Check installation health
 - `/bmalph-implement` — Transition from BMAD to Ralph
 
+## Supported Platforms
+
+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`                       | Inline in instructions file   |
+| Cursor         | `cursor`      | instructions-only | `.cursor/rules/bmad.mdc`          | None                          |
+| Windsurf       | `windsurf`    | instructions-only | `.windsurf/rules/bmad.md`         | None                          |
+| GitHub Copilot | `copilot`     | instructions-only | `.github/copilot-instructions.md` | None                          |
+| Aider          | `aider`       | instructions-only | `CONVENTIONS.md`                  | None                          |
+
+**Tiers:**
+
+- **full** — Phases 1-4. BMAD planning + Ralph autonomous implementation loop.
+- **instructions-only** — Phases 1-3. BMAD planning only. Ralph is not available.
+
 ## Prerequisites
 
 - Node.js 20+
 - Bash (WSL or Git Bash on Windows)
-- Claude Code (`claude` in PATH) — needed for Ralph loop
+- A supported AI coding platform (see table above)
+- For Ralph loop (Phase 4): Claude Code (`claude`) or Codex CLI (`codex`) in PATH
 
 ## Installation
 
@@ -44,9 +63,9 @@ npm install -g bmalph
 ```bash
 cd my-project
 bmalph init --name my-project
-# Use /bmalph slash command in Claude Code to navigate phases
-# ... work through BMAD phases 1-3 ...
-# Use /bmalph-implement to transition and start Ralph
+
+# To target a specific platform, add --platform (e.g. codex, cursor, windsurf)
+# Without --platform, bmalph auto-detects or prompts interactively
 ```
 
 ## Workflow
@@ -58,17 +77,27 @@ cd my-project
 bmalph init
 ```
 
+**Platform resolution:** `--platform` flag > auto-detect from project markers > interactive prompt > default `claude-code`
+
 This installs:
 
 - `_bmad/` — BMAD agents and workflows
-- `.ralph/` — Ralph loop, libs, templates
-- `bmalph/` — State management (config.json)
-- Updates `CLAUDE.md` with BMAD workflow instructions
-- Installs slash commands in `.claude/commands/`
+- `.ralph/` — Ralph loop, libs, templates (drivers for claude-code and codex only)
+- `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`)
+- Installs slash commands for supported platforms (Claude Code: `.claude/commands/` directory; Codex: inline in `AGENTS.md`; other platforms: commands not installed)
+
+### Migrating from standalone BMAD
+
+If you already have BMAD installed (a `_bmad/` directory), `bmalph init` works as a migration path:
+
+- `_bmad/` (framework files) will be replaced with the bmalph-managed version
+- `_bmad-output/` (your planning artifacts: PRDs, architecture, stories) is not touched
+- If you've customized framework files inside `_bmad/`, commit first so you can review changes with `git diff`
 
 ### Step 2: Plan with BMAD (Phases 1-3)
 
-Work interactively in Claude Code with BMAD agents. Use the `/bmalph` slash command to see your current phase, available commands, and advance phases.
+Work interactively with BMAD agents in your AI coding assistant. On Claude Code, use the `/bmalph` slash command to see your current phase and available commands. On other platforms, ask the agent about BMAD phases or run `bmalph status` in terminal.
 
 | Phase         | Agent            | Commands           |
 | ------------- | ---------------- | ------------------ |
@@ -124,7 +153,9 @@ Available in any phase for supporting tasks:
 
 ### Step 3: Implement with Ralph (Phase 4)
 
-Use the `/bmalph-implement` slash command in Claude Code.
+> **Note:** Ralph is only available on **full** tier platforms (Claude Code, OpenAI Codex). Instructions-only platforms (Cursor, Windsurf, Copilot, Aider) support Phases 1-3 only.
+
+Use the `/bmalph-implement` slash command in Claude Code, or run the transition from the BMAD agents in Codex.
 
 This transitions your BMAD artifacts into Ralph's format:
 
@@ -181,10 +212,11 @@ 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)     |
+| 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    |
 
 ### upgrade options
 
@@ -195,7 +227,13 @@ BMAD (add Epic 2) → /bmalph-implement → Ralph sees changes + picks up Epic 2
 
 ## Slash Commands
 
-bmalph installs 47 BMAD slash commands. Key commands:
+bmalph installs 47 BMAD slash commands. Command delivery varies by platform:
+
+- **Claude Code** — installed as files in `.claude/commands/` (invoke with `/command-name`)
+- **OpenAI Codex** — inlined in `AGENTS.md` (reference agents by name)
+- **Cursor, Windsurf, Copilot, Aider** — not delivered as slash commands; use agents by name in chat
+
+Key commands (Claude Code syntax):
 
 | Command                 | Description                         |
 | ----------------------- | ----------------------------------- |
@@ -239,12 +277,15 @@ project/
 │   ├── planning-artifacts/    # PRD, architecture, stories
 │   ├── implementation-artifacts/ # Sprint plans (optional)
 │   └── brainstorming/         # Brainstorm sessions (optional)
-├── .ralph/                    # Ralph autonomous loop
+├── .ralph/                    # Ralph autonomous loop (drivers for claude-code and codex only)
 │   ├── ralph_loop.sh          # Main loop script
 │   ├── ralph_import.sh        # Import requirements into Ralph
 │   ├── ralph_monitor.sh       # Monitor loop progress
 │   ├── .ralphrc               # Ralph configuration
 │   ├── RALPH-REFERENCE.md     # Ralph usage reference
+│   ├── drivers/               # Platform driver scripts
+│   │   ├── claude-code.sh     # Claude Code driver (uses `claude`)
+│   │   └── codex.sh           # OpenAI Codex driver (uses `codex exec`)
 │   ├── lib/                   # Circuit breaker, response analyzer
 │   ├── specs/                 # Copied from _bmad-output during transition
 │   ├── logs/                  # Loop execution logs
@@ -254,16 +295,23 @@ project/
 │   ├── @AGENT.md              # Agent build instructions
 │   └── @fix_plan.md           # Generated task list (after /bmalph-implement)
 ├── bmalph/                    # State management
-│   ├── config.json            # Project config (name, description)
+│   ├── config.json            # Project config (name, description, platform)
 │   └── state/                 # Phase tracking data
-├── .claude/
-│   └── commands/              # Slash commands for Claude Code
-└── CLAUDE.md                  # Updated with BMAD instructions
+├── .claude/                   # Claude Code specific
+│   └── commands/              # Slash commands (claude-code only)
+└── <instructions file>        # Varies by platform (see Supported Platforms)
 ```
 
+The instructions file and command directory depend on the configured platform. See the [Supported Platforms](#supported-platforms) table for details.
+
 ## How Ralph Works
 
-Ralph is a bash loop that spawns fresh Claude Code instances:
+Ralph is a bash loop that spawns fresh AI coding sessions using a **platform driver** matching the configured platform:
+
+- **Claude Code driver** — invokes `claude` with `--allowedTools` and session resume
+- **Codex driver** — invokes `codex exec` with `--sandbox workspace-write`
+
+Each iteration:
 
 1. Pick the next unchecked story from `@fix_plan.md`
 2. Implement with TDD (tests first, then code)
@@ -313,12 +361,14 @@ ls -la .ralph/
 
 ### Common Issues
 
-| Scenario                     | Solution                                                  |
-| ---------------------------- | --------------------------------------------------------- |
-| Commands fail before init    | Run `bmalph init` first                                   |
-| Transition finds no stories  | Create stories in Phase 3 with `/create-epics-stories`    |
-| Ralph stops mid-loop         | Circuit breaker detected stagnation. Check `.ralph/logs/` |
-| Doctor reports version drift | Run `bmalph upgrade` to update bundled assets             |
+| Scenario                      | Solution                                                       |
+| ----------------------------- | -------------------------------------------------------------- |
+| Commands fail before init     | Run `bmalph init` first                                        |
+| Transition finds no stories   | Create stories in Phase 3 with `/create-epics-stories`         |
+| 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 or codex)     |
 
 ### Reset Installation
 
@@ -326,8 +376,16 @@ If something goes wrong, you can manually reset:
 
 ```bash
 # Remove bmalph directories (preserves your project code)
-rm -rf _bmad .ralph bmalph .claude/commands/
-# Note: manually remove the bmalph section from CLAUDE.md and .gitignore entries
+rm -rf _bmad .ralph bmalph
+
+# Also remove platform-specific files:
+# Claude Code:  rm -rf .claude/commands/  and remove bmalph section from CLAUDE.md
+# Codex:        remove bmalph sections from AGENTS.md
+# Cursor:       rm .cursor/rules/bmad.mdc
+# Windsurf:     rm .windsurf/rules/bmad.md
+# Copilot:      remove bmalph sections from .github/copilot-instructions.md
+# Aider:        remove bmalph sections from CONVENTIONS.md
+# See the Supported Platforms table for your platform's files.
 
 # Reinitialize
 bmalph init
@@ -338,12 +396,17 @@ bmalph init
 ### Initialize a new project
 
 ```bash
-# Interactive mode (prompts for name/description)
+# Interactive mode (prompts for name/description, auto-detects platform)
 bmalph init
 
 # Non-interactive mode
 bmalph init --name my-app --description "My awesome app"
 
+# Specify platform explicitly
+bmalph init --name my-app --platform codex
+bmalph init --name my-app --platform cursor
+bmalph init --name my-app --platform windsurf
+
 # Preview what would be created
 bmalph init --dry-run
 ```
@@ -370,6 +433,8 @@ bmalph upgrade --dry-run
 
 ### After init: Next steps
 
+**Claude Code:**
+
 ```bash
 # 1. Open Claude Code in your project
 claude
@@ -389,6 +454,22 @@ claude
 bash .ralph/ralph_loop.sh
 ```
 
+**Other platforms:**
+
+```bash
+# 1. Open your project in your AI coding assistant
+
+# 2. Ask the agent about BMAD phases to start planning
+#    Or check status from terminal: bmalph status
+
+# 3. Reference BMAD agents by name (analyst, pm, architect)
+#    Follow phases: Analysis → Planning → Solutioning
+
+# 4. For full tier platforms (Codex), transition via BMAD agents
+#    then start Ralph:
+bash .ralph/ralph_loop.sh
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test workflow, and commit guidelines.

package/dist/cli.js

@@ -55,6 +55,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("--dry-run", "Preview changes without writing files")
     .action(async (opts) => initCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 program

package/dist/commands/doctor.d.ts

@@ -1,3 +1,4 @@
+import type { Platform } from "../platform/types.js";
 /**
  * Result of a single doctor check.
  */
@@ -32,8 +33,19 @@ interface DoctorResult {
 }
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorResult>;
 /**
- * Registry of all doctor checks in execution order.
- * Each check has a unique ID and a run function that takes a project directory.
+ * Build the full check registry for a given platform.
+ * Core checks + platform doctor checks + trailing checks.
+ */
+export declare function buildCheckRegistry(platform: Platform): CheckDefinition[];
+/**
+ * Static registry for backward compatibility with existing tests.
+ * Uses claude-code platform checks (slash-command + claude-md).
+ *
+ * Note: The check ids here ("slash-command", "claude-md") intentionally differ
+ * from the live buildCheckRegistry path which uses platform-provided ids
+ * ("instructions-file"). This is for test backward compatibility only.
+ *
+ * @deprecated Use `buildCheckRegistry(platform)` for platform-aware checks.
  */
 export declare const CHECK_REGISTRY: CheckDefinition[];
 export {};

package/dist/commands/doctor.js

@@ -9,6 +9,7 @@ import { checkUpstream, getSkipReason } from "../utils/github.js";
 import { isEnoent, formatError, withErrorHandling } from "../utils/errors.js";
 import { validateCircuitBreakerState, validateRalphSession, validateRalphApiStatus, } from "../utils/validate.js";
 import { SESSION_AGE_WARNING_MS, API_USAGE_WARNING_PERCENT, CONFIG_FILE, RALPH_STATUS_FILE, } from "../utils/constants.js";
+import { resolveProjectPlatform } from "../platform/resolve.js";
 export async function doctorCommand(options) {
     await withErrorHandling(async () => {
         const { failed } = await runDoctor(options);
@@ -19,8 +20,12 @@ export async function doctorCommand(options) {
 }
 export async function runDoctor(options) {
     const projectDir = options.projectDir;
-    // Run all checks from the registry
-    const results = await Promise.all(CHECK_REGISTRY.map((check) => check.run(projectDir)));
+    // Resolve platform for this project
+    const platform = await resolveProjectPlatform(projectDir);
+    // Build the check list: core checks + platform-specific checks
+    const checks = buildCheckRegistry(platform);
+    // Run all checks
+    const results = await Promise.all(checks.map((check) => check.run(projectDir)));
     // Output
     const passed = results.filter((r) => r.passed).length;
     const failed = results.filter((r) => !r.passed).length;
@@ -71,7 +76,7 @@ async function checkBashAvailable() {
     }
 }
 // =============================================================================
-// Check functions - each conforms to CheckFunction signature
+// Core check functions - platform-independent
 // =============================================================================
 async function checkNodeVersion(_projectDir) {
     const major = parseInt(process.versions.node.split(".")[0]);
@@ -104,9 +109,6 @@ async function checkRalphLoop(projectDir) {
 async function checkRalphLib(projectDir) {
     return checkDir(join(projectDir, ".ralph/lib"), ".ralph/lib/ directory present", "Run: bmalph upgrade");
 }
-async function checkSlashCommand(projectDir) {
-    return checkFileExists(join(projectDir, ".claude/commands/bmalph.md"), ".claude/commands/bmalph.md present", "Run: bmalph init");
-}
 async function checkConfig(projectDir) {
     const label = "bmalph/config.json exists and valid";
     const hint = "Run: bmalph init";
@@ -135,12 +137,6 @@ async function checkDir(dirPath, label, hint) {
         return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
     }
 }
-async function checkFileExists(filePath, label, hint) {
-    if (await exists(filePath)) {
-        return { label, passed: true };
-    }
-    return { label, passed: false, detail: "not found", hint };
-}
 async function checkFileHasContent(filePath, label, hint) {
     try {
         const content = await readFile(filePath, "utf-8");
@@ -153,23 +149,6 @@ async function checkFileHasContent(filePath, label, hint) {
         return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
     }
 }
-async function checkClaudeMd(projectDir) {
-    const label = "CLAUDE.md contains BMAD snippet";
-    const hint = "Run: bmalph init";
-    try {
-        const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
-        if (content.includes("BMAD-METHOD Integration")) {
-            return { label, passed: true };
-        }
-        return { label, passed: false, detail: "missing BMAD-METHOD Integration section", hint };
-    }
-    catch (err) {
-        if (isEnoent(err)) {
-            return { label, passed: false, detail: "CLAUDE.md not found", hint };
-        }
-        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
-    }
-}
 async function checkGitignore(projectDir) {
     const label = ".gitignore has required entries";
     const required = [".ralph/logs/", "_bmad-output/"];
@@ -412,21 +391,23 @@ async function checkUpstreamGitHubStatus(_projectDir) {
     }
 }
 // =============================================================================
-// Check Registry - defines all checks in execution order
+// Check Registry - core checks + platform-specific checks
 // =============================================================================
 /**
- * Registry of all doctor checks in execution order.
- * Each check has a unique ID and a run function that takes a project directory.
+ * Core checks that apply to every platform.
  */
-export const CHECK_REGISTRY = [
+const CORE_CHECKS = [
     { id: "node-version", run: checkNodeVersion },
     { id: "bash-available", run: checkBash },
     { id: "config-valid", run: checkConfig },
     { id: "bmad-dir", run: checkBmadDir },
     { id: "ralph-loop", run: checkRalphLoop },
     { id: "ralph-lib", run: checkRalphLib },
-    { id: "slash-command", run: checkSlashCommand },
-    { id: "claude-md", run: checkClaudeMd },
+];
+/**
+ * Checks that run after platform-specific checks.
+ */
+const TRAILING_CHECKS = [
     { id: "gitignore", run: checkGitignore },
     { id: "version-marker", run: checkVersionMarker },
     { id: "upstream-versions", run: checkUpstreamVersions },
@@ -435,3 +416,70 @@ export const CHECK_REGISTRY = [
     { id: "api-calls", run: checkApiCalls },
     { id: "upstream-github", run: checkUpstreamGitHubStatus },
 ];
+/**
+ * Build the full check registry for a given platform.
+ * Core checks + platform doctor checks + trailing checks.
+ */
+export function buildCheckRegistry(platform) {
+    const platformChecks = platform.getDoctorChecks().map((pc) => ({
+        id: pc.id,
+        run: async (projectDir) => {
+            const result = await pc.check(projectDir);
+            return {
+                label: pc.label,
+                passed: result.passed,
+                detail: result.detail,
+                hint: result.hint,
+            };
+        },
+    }));
+    return [...CORE_CHECKS, ...platformChecks, ...TRAILING_CHECKS];
+}
+/**
+ * Static registry for backward compatibility with existing tests.
+ * Uses claude-code platform checks (slash-command + claude-md).
+ *
+ * Note: The check ids here ("slash-command", "claude-md") intentionally differ
+ * from the live buildCheckRegistry path which uses platform-provided ids
+ * ("instructions-file"). This is for test backward compatibility only.
+ *
+ * @deprecated Use `buildCheckRegistry(platform)` for platform-aware checks.
+ */
+export const CHECK_REGISTRY = (() => {
+    // Inline claude-code platform checks to avoid async import at module level
+    const slashCommandCheck = {
+        id: "slash-command",
+        run: async (projectDir) => {
+            if (await exists(join(projectDir, ".claude/commands/bmalph.md"))) {
+                return { label: ".claude/commands/bmalph.md present", passed: true };
+            }
+            return {
+                label: ".claude/commands/bmalph.md present",
+                passed: false,
+                detail: "not found",
+                hint: "Run: bmalph init",
+            };
+        },
+    };
+    const claudeMdCheck = {
+        id: "claude-md",
+        run: async (projectDir) => {
+            const label = "CLAUDE.md contains BMAD snippet";
+            const hint = "Run: bmalph init";
+            try {
+                const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
+                if (content.includes("BMAD-METHOD Integration")) {
+                    return { label, passed: true };
+                }
+                return { label, passed: false, detail: "missing BMAD-METHOD Integration section", hint };
+            }
+            catch (err) {
+                if (isEnoent(err)) {
+                    return { label, passed: false, detail: "CLAUDE.md not found", hint };
+                }
+                return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
+            }
+        },
+    };
+    return [...CORE_CHECKS, slashCommandCheck, claudeMdCheck, ...TRAILING_CHECKS];
+})();

package/dist/commands/init.d.ts

@@ -1,6 +1,7 @@
 interface InitOptions {
     name?: string;
     description?: string;
+    platform?: string;
     dryRun?: boolean;
     projectDir: string;
 }

package/dist/commands/init.js

@@ -1,13 +1,60 @@
 import chalk from "chalk";
 import inquirer from "inquirer";
 import { writeConfig } from "../utils/config.js";
-import { installProject, mergeClaudeMd, isInitialized, previewInstall, getBundledVersions, } from "../installer.js";
+import { installProject, mergeInstructionsFile, isInitialized, hasExistingBmadDir, previewInstall, getBundledVersions, } from "../installer.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";
 import { validateProjectName } from "../utils/validate.js";
 import { withErrorHandling } from "../utils/errors.js";
+import { isPlatformId, getPlatform } from "../platform/registry.js";
+import { detectPlatform } from "../platform/detect.js";
 export async function initCommand(options) {
     await withErrorHandling(() => runInit(options));
 }
+/**
+ * Resolve which platform to use:
+ * 1. Explicit --platform flag
+ * 2. Auto-detect from filesystem markers
+ * 3. Interactive prompt (if TTY)
+ * 4. Default to claude-code (non-interactive)
+ */
+async function resolvePlatform(projectDir, explicit) {
+    // 1. Explicit flag
+    if (explicit) {
+        if (!isPlatformId(explicit)) {
+            throw new Error(`Unknown platform: "${explicit}". ` +
+                `Valid platforms: claude-code, codex, cursor, windsurf, copilot, aider`);
+        }
+        return getPlatform(explicit);
+    }
+    // 2. Auto-detect
+    const detection = await detectPlatform(projectDir);
+    if (detection.detected) {
+        return getPlatform(detection.detected);
+    }
+    // 3. Interactive prompt if multiple candidates or none detected
+    if (process.stdin.isTTY) {
+        const choices = [
+            { name: "Claude Code", value: "claude-code" },
+            { name: "OpenAI Codex", value: "codex" },
+            { name: "Cursor", value: "cursor" },
+            { name: "Windsurf", value: "windsurf" },
+            { name: "GitHub Copilot", value: "copilot" },
+            { name: "Aider", value: "aider" },
+        ];
+        const { platformId } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "platformId",
+                message: "Which platform are you using?",
+                choices,
+                default: detection.candidates[0] ?? "claude-code",
+            },
+        ]);
+        return getPlatform(platformId);
+    }
+    // 4. Non-interactive default
+    return getPlatform("claude-code");
+}
 async function runInit(options) {
     const projectDir = options.projectDir;
     if (await isInitialized(projectDir)) {
@@ -15,9 +62,16 @@ async function runInit(options) {
         console.log("Use 'bmalph upgrade' to update bundled assets to the latest version.");
         return;
     }
+    if (await hasExistingBmadDir(projectDir)) {
+        console.log(chalk.cyan("Existing BMAD installation detected."));
+        console.log("Framework files in _bmad/ will be replaced with the managed version.");
+        console.log("Planning artifacts in _bmad-output/ will not be modified.\n");
+    }
+    // Resolve platform
+    const platform = await resolvePlatform(projectDir, options.platform);
     // Handle dry-run mode
     if (options.dryRun) {
-        const preview = await previewInstall(projectDir);
+        const preview = await previewInstall(projectDir, platform);
         const actions = [
             ...preview.wouldCreate.map((p) => ({ type: "create", path: p })),
             ...preview.wouldModify.map((p) => ({ type: "modify", path: p })),
@@ -64,18 +118,19 @@ async function runInit(options) {
         throw new Error("Project name cannot be empty");
     }
     const validatedName = validateProjectName(name);
-    console.log(chalk.blue("\nInstalling BMAD + Ralph..."));
-    await installProject(projectDir);
+    console.log(chalk.blue(`\nInstalling BMAD + Ralph for ${platform.displayName}...`));
+    await installProject(projectDir, platform);
     const bundledVersions = getBundledVersions();
     const config = {
         name: validatedName,
         description: description ?? "",
         createdAt: new Date().toISOString(),
+        platform: platform.id,
         upstreamVersions: bundledVersions,
     };
     try {
         await writeConfig(projectDir, config);
-        await mergeClaudeMd(projectDir);
+        await mergeInstructionsFile(projectDir, platform);
     }
     catch (err) {
         throw new Error(`Partial installation: files were copied but configuration failed. ` +
@@ -83,11 +138,23 @@ async function runInit(options) {
     }
     console.log(chalk.green("\nbmalph initialized successfully!"));
     console.log(`\n  Project: ${chalk.bold(config.name)}`);
+    console.log(`  Platform: ${chalk.bold(platform.displayName)}`);
     console.log(`\nInstalled:`);
     console.log(`  _bmad/             BMAD agents and workflows`);
     console.log(`  .ralph/            Ralph loop and templates`);
-    console.log(`  .claude/commands/  Slash command (/bmalph)`);
+    if (platform.commandDelivery.kind === "directory") {
+        console.log(`  ${platform.commandDelivery.dir}/  Slash commands`);
+    }
     console.log(`  bmalph/            State management`);
+    // Platform-specific next step guidance
     console.log(`\nNext step:`);
-    console.log(`  Use ${chalk.cyan("/bmalph")} in Claude Code to see your current phase and commands.`);
+    if (platform.id === "claude-code") {
+        console.log(`  Use ${chalk.cyan("/bmalph")} in Claude Code to see your current phase and commands.`);
+    }
+    else if (platform.id === "codex") {
+        console.log(`  Ask Codex to ${chalk.cyan("run the BMAD master agent")} to navigate phases.`);
+    }
+    else {
+        console.log(`  Ask your AI assistant to ${chalk.cyan("use the BMAD agents")} defined in ${chalk.cyan(platform.instructionsFile)}.`);
+    }
 }

package/dist/commands/upgrade.js

@@ -1,9 +1,10 @@
 import chalk from "chalk";
 import inquirer from "inquirer";
-import { isInitialized, copyBundledAssets, mergeClaudeMd, previewUpgrade, getBundledVersions, } from "../installer.js";
+import { isInitialized, copyBundledAssets, mergeInstructionsFile, previewUpgrade, getBundledVersions, } from "../installer.js";
 import { readConfig, writeConfig } from "../utils/config.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";
 import { withErrorHandling } from "../utils/errors.js";
+import { resolveProjectPlatform } from "../platform/resolve.js";
 export async function upgradeCommand(options) {
     await withErrorHandling(() => runUpgrade(options));
 }
@@ -13,9 +14,11 @@ async function runUpgrade(options) {
         console.log(chalk.red("bmalph is not initialized. Run 'bmalph init' first."));
         return;
     }
+    // Read platform from existing config
+    const platform = await resolveProjectPlatform(projectDir);
     // Handle dry-run mode
     if (options.dryRun) {
-        const preview = await previewUpgrade(projectDir);
+        const preview = await previewUpgrade(projectDir, platform);
         const actions = [
             ...preview.wouldUpdate.map((p) => ({ type: "modify", path: p })),
             ...preview.wouldCreate.map((p) => ({ type: "create", path: p })),
@@ -41,9 +44,9 @@ async function runUpgrade(options) {
             return;
         }
     }
-    console.log(chalk.blue("Upgrading bundled assets..."));
-    const result = await copyBundledAssets(projectDir);
-    await mergeClaudeMd(projectDir);
+    console.log(chalk.blue(`Upgrading bundled assets for ${platform.displayName}...`));
+    const result = await copyBundledAssets(projectDir, platform);
+    await mergeInstructionsFile(projectDir, platform);
     // Update upstreamVersions in config to match bundled versions
     const config = await readConfig(projectDir);
     if (config) {