bmalph 2.2.1 → 2.4.0

package/dist/commands/implement.js

@@ -0,0 +1,82 @@
+import chalk from "chalk";
+import { access } from "fs/promises";
+import { join } from "path";
+import { runTransition } from "../transition/orchestration.js";
+import { withErrorHandling } from "../utils/errors.js";
+import { resolveProjectPlatform } from "../platform/resolve.js";
+export async function implementCommand(options) {
+    await withErrorHandling(() => runImplement(options));
+}
+async function runImplement(options) {
+    const { projectDir, force } = options;
+    // Re-run protection: warn if implement was already run
+    try {
+        await access(join(projectDir, ".ralph/@fix_plan.md"));
+        if (!force) {
+            console.log(chalk.yellow("Warning: bmalph implement has already been run."));
+            console.log("Re-running will overwrite PROMPT.md, PROJECT_CONTEXT.md, @AGENT.md, and SPECS_INDEX.md.");
+            console.log("Fix plan progress will be preserved.\n");
+            console.log(`Use ${chalk.bold("--force")} to proceed anyway.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch {
+        // fix_plan doesn't exist — first run, proceed
+    }
+    const platform = await resolveProjectPlatform(projectDir);
+    const result = await runTransition(projectDir, { force });
+    // Print preflight issues with severity icons
+    if (result.preflightIssues && result.preflightIssues.length > 0) {
+        console.log(chalk.bold("\nPre-flight checks\n"));
+        for (const issue of result.preflightIssues) {
+            console.log(`  ${severityIcon(issue)} ${issue.message}`);
+            if (issue.suggestion) {
+                console.log(chalk.dim(`     ${issue.suggestion}`));
+            }
+        }
+        console.log("");
+    }
+    // Print warnings
+    if (result.warnings.length > 0) {
+        for (const warning of result.warnings) {
+            console.log(chalk.yellow(`  ! ${warning}`));
+        }
+        console.log("");
+    }
+    // Generated files summary
+    if (result.generatedFiles.length > 0) {
+        console.log(chalk.bold("\nGenerated files\n"));
+        for (const file of result.generatedFiles) {
+            const icon = file.action === "created" ? chalk.green("+") : chalk.cyan("~");
+            console.log(`  ${icon} ${file.path}`);
+        }
+        console.log("");
+    }
+    // Summary
+    const preserved = result.fixPlanPreserved ? chalk.dim(" (progress preserved)") : "";
+    console.log(chalk.green(`Transition complete: ${result.storiesCount} stories`) + preserved);
+    if (result.warnings.length > 0) {
+        console.log(chalk.yellow(`  ${result.warnings.length} warning(s)`));
+    }
+    // Driver instructions
+    console.log("");
+    if (platform.tier === "full") {
+        console.log(`Start the Ralph loop:\n`);
+        console.log(`    bash .ralph/drivers/${platform.id}.sh`);
+    }
+    else {
+        console.log(`Ralph requires a full-tier platform (claude-code or codex). ` +
+            `Current platform: ${platform.displayName}`);
+    }
+}
+function severityIcon(issue) {
+    switch (issue.severity) {
+        case "error":
+            return chalk.red("\u2717");
+        case "warning":
+            return chalk.yellow("!");
+        case "info":
+            return chalk.dim("i");
+    }
+}

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/reset.d.ts

@@ -0,0 +1,7 @@
+interface ResetOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    projectDir: string;
+}
+export declare function resetCommand(options: ResetOptions): Promise<void>;
+export {};

package/dist/commands/reset.js

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { isInitialized } from "../installer.js";
+import { buildResetPlan, executeResetPlan, planToDryRunActions } from "../reset.js";
+import { formatDryRunSummary } from "../utils/dryrun.js";
+import { withErrorHandling } from "../utils/errors.js";
+import { resolveProjectPlatform } from "../platform/resolve.js";
+export async function resetCommand(options) {
+    await withErrorHandling(() => runReset(options));
+}
+async function runReset(options) {
+    const projectDir = options.projectDir;
+    if (!(await isInitialized(projectDir))) {
+        console.log(chalk.red("bmalph is not initialized. Nothing to reset."));
+        return;
+    }
+    const platform = await resolveProjectPlatform(projectDir);
+    const plan = await buildResetPlan(projectDir, platform);
+    // Preview
+    const actions = planToDryRunActions(plan);
+    if (actions.length === 0) {
+        console.log(chalk.dim("Nothing to reset."));
+        return;
+    }
+    // Dry-run mode
+    if (options.dryRun) {
+        console.log(formatDryRunSummary(actions));
+        return;
+    }
+    // Show preview before confirmation
+    for (const action of actions) {
+        if (action.type === "delete") {
+            console.log(`  ${chalk.red("delete")} ${action.path}`);
+        }
+        else if (action.type === "modify") {
+            console.log(`  ${chalk.yellow("modify")} ${action.path}`);
+        }
+        else if (action.type === "warn") {
+            console.log(`  ${chalk.yellow("warn")}   ${action.path}${action.reason ? ` (${action.reason})` : ""}`);
+        }
+    }
+    // Confirm unless --force or non-interactive
+    if (!options.force) {
+        if (!process.stdin.isTTY) {
+            throw new Error("Non-interactive mode requires --force flag for reset");
+        }
+        const { confirm } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirm",
+                message: "This will remove all bmalph files from the project. Continue?",
+                default: false,
+            },
+        ]);
+        if (!confirm) {
+            console.log("Aborted.");
+            return;
+        }
+    }
+    // Execute
+    console.log("\nResetting...");
+    await executeResetPlan(projectDir, plan);
+    // Summary
+    console.log(chalk.green("\nReset complete."));
+    if (plan.directories.length > 0) {
+        console.log(chalk.dim("\nRemoved:"));
+        for (const dir of plan.directories) {
+            console.log(`  ${dir}/`);
+        }
+    }
+    if (plan.commandFiles.length > 0) {
+        console.log(chalk.dim("\nRemoved commands:"));
+        for (const file of plan.commandFiles) {
+            console.log(`  ${file}`);
+        }
+    }
+    // Show warnings
+    for (const warning of plan.warnings) {
+        console.log(chalk.yellow(`\nNote: ${warning.path} ${warning.message}`));
+    }
+}

package/dist/commands/status.js

@@ -2,6 +2,8 @@ import chalk from "chalk";
 import { readConfig } from "../utils/config.js";
 import { readState, readRalphStatus, getPhaseLabel, getPhaseInfo } from "../utils/state.js";
 import { withErrorHandling } from "../utils/errors.js";
+import { resolveProjectPlatform } from "../platform/resolve.js";
+import { scanProjectArtifacts } from "../transition/artifact-scan.js";
 export async function statusCommand(options) {
     await withErrorHandling(() => runStatus(options));
 }
@@ -15,17 +17,32 @@ export async function runStatus(options) {
     }
     // Read current state
     const state = await readState(projectDir);
-    const phase = state?.currentPhase ?? 1;
+    const storedPhase = state?.currentPhase ?? 1;
     const status = state?.status ?? "planning";
-    const phaseName = getPhaseLabel(phase);
-    const phaseInfo = getPhaseInfo(phase);
     // Read Ralph status if in implementation phase
     let ralphStatus = null;
-    if (phase === 4) {
+    if (storedPhase === 4) {
         ralphStatus = await readRalphStatus(projectDir);
     }
-    // Determine next action
-    const nextAction = getNextAction(phase, status, ralphStatus);
+    // Scan artifacts for phases 1-3 to detect actual progress
+    let artifactScan = null;
+    let phase = storedPhase;
+    let phaseDetected = false;
+    if (phase < 4) {
+        artifactScan = await scanProjectArtifacts(projectDir);
+        if (artifactScan && artifactScan.detectedPhase > phase) {
+            phase = artifactScan.detectedPhase;
+            phaseDetected = true;
+        }
+    }
+    const phaseName = getPhaseLabel(phase);
+    const phaseInfo = getPhaseInfo(phase);
+    // Resolve platform for next action hints
+    const platform = await resolveProjectPlatform(projectDir);
+    // Determine next action — use artifact-based suggestion when available
+    const nextAction = artifactScan && phaseDetected
+        ? artifactScan.nextAction
+        : getNextAction(phase, status, ralphStatus, platform);
     if (options.json) {
         const output = {
             phase,
@@ -40,6 +57,14 @@ export async function runStatus(options) {
                 tasksTotal: ralphStatus.tasksTotal,
             };
         }
+        if (artifactScan) {
+            output.artifacts = {
+                directory: artifactScan.directory,
+                found: artifactScan.found,
+                detectedPhase: artifactScan.detectedPhase,
+                missing: artifactScan.missing,
+            };
+        }
         if (nextAction) {
             output.nextAction = nextAction;
         }
@@ -48,9 +73,18 @@ export async function runStatus(options) {
     }
     // Human-readable output
     console.log(chalk.bold("bmalph status\n"));
-    console.log(`  ${chalk.cyan("Phase:")} ${phase} - ${phaseName}`);
+    const phaseLabel = phaseDetected
+        ? `${phase} - ${phaseName} (detected from artifacts)`
+        : `${phase} - ${phaseName}`;
+    console.log(`  ${chalk.cyan("Phase:")} ${phaseLabel}`);
     console.log(`  ${chalk.cyan("Agent:")} ${phaseInfo.agent}`);
     console.log(`  ${chalk.cyan("Status:")} ${formatStatus(status)}`);
+    // Show artifact checklist for phases 1-3
+    if (artifactScan) {
+        console.log("");
+        console.log(chalk.bold(`  Artifacts (${artifactScan.directory})`));
+        printArtifactChecklist(artifactScan);
+    }
     if (phase === 4 && ralphStatus) {
         console.log("");
         console.log(chalk.bold("  Ralph Loop"));
@@ -68,6 +102,45 @@ export async function runStatus(options) {
         console.log(`  ${chalk.cyan("Next:")} ${nextAction}`);
     }
 }
+const ARTIFACT_DEFINITIONS = [
+    { phase: 1, name: "Product Brief", required: false },
+    { phase: 1, name: "Market Research", required: false },
+    { phase: 1, name: "Domain Research", required: false },
+    { phase: 1, name: "Technical Research", required: false },
+    { phase: 2, name: "PRD", required: true },
+    { phase: 2, name: "UX Design", required: false },
+    { phase: 3, name: "Architecture", required: true },
+    { phase: 3, name: "Epics & Stories", required: true },
+    { phase: 3, name: "Readiness Report", required: true },
+];
+const PHASE_LABELS = {
+    1: "Phase 1 - Analysis",
+    2: "Phase 2 - Planning",
+    3: "Phase 3 - Solutioning",
+};
+function printArtifactChecklist(scan) {
+    const foundByName = new Map();
+    for (const artifacts of [scan.phases[1], scan.phases[2], scan.phases[3]]) {
+        for (const artifact of artifacts) {
+            foundByName.set(artifact.name, artifact);
+        }
+    }
+    let currentPhase = 0;
+    for (const def of ARTIFACT_DEFINITIONS) {
+        if (def.phase !== currentPhase) {
+            currentPhase = def.phase;
+            console.log(`    ${PHASE_LABELS[currentPhase]}`);
+        }
+        const found = foundByName.get(def.name);
+        if (found) {
+            console.log(`      ${chalk.green("*")} ${def.name} (${found.filename})`);
+        }
+        else {
+            const suffix = def.required ? " (required)" : "";
+            console.log(`      ${chalk.dim("-")} ${def.name}${suffix}`);
+        }
+    }
+}
 function formatStatus(status) {
     switch (status) {
         case "planning":
@@ -94,7 +167,7 @@ function formatRalphStatus(status) {
             return status;
     }
 }
-function getNextAction(phase, status, ralphStatus) {
+function getNextAction(phase, status, ralphStatus, platform) {
     if (status === "completed") {
         return null;
     }
@@ -104,10 +177,13 @@ function getNextAction(phase, status, ralphStatus) {
         case 2:
             return "Run /pm to create PRD";
         case 3:
-            return "Run /bmalph-implement when ready for implementation";
+            return "Run: bmalph implement";
         case 4:
             if (!ralphStatus || ralphStatus.status === "not_started") {
-                return "Start Ralph loop with: bash .ralph/ralph_loop.sh";
+                if (platform.tier === "full") {
+                    return `Start Ralph loop with: bash .ralph/drivers/${platform.id}.sh`;
+                }
+                return "Ralph requires a full-tier platform (Claude Code or Codex)";
             }
             if (ralphStatus.status === "blocked") {
                 return "Review Ralph logs: bmalph doctor";

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) {

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>;