bmalph 2.2.1 → 2.3.0

package/dist/platform/codex.js

@@ -0,0 +1,67 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const codexPlatform = {
+    id: "codex",
+    displayName: "OpenAI Codex",
+    tier: "full",
+    instructionsFile: "AGENTS.md",
+    commandDelivery: { kind: "inline" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Run 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 |
+| 4. Implementation | Build it | Developer agent, then Ralph autonomous loop |
+
+### Workflow
+
+1. Work through Phases 1-3 using BMAD agents and workflows
+2. Use the bmalph-implement transition to prepare Ralph format, then start Ralph
+
+### 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: "AGENTS.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, "AGENTS.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: "AGENTS.md not found", hint: "Run: bmalph init" };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/copilot.d.ts

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

package/dist/platform/copilot.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const copilotPlatform = {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    tier: "instructions-only",
+    instructionsFile: ".github/copilot-instructions.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: ".github/copilot-instructions.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".github/copilot-instructions.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: ".github/copilot-instructions.md not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/cursor.d.ts

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

package/dist/platform/cursor.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const cursorPlatform = {
+    id: "cursor",
+    displayName: "Cursor",
+    tier: "instructions-only",
+    instructionsFile: ".cursor/rules/bmad.mdc",
+    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: ".cursor/rules/bmad.mdc contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".cursor/rules/bmad.mdc"), "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: ".cursor/rules/bmad.mdc not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/detect.d.ts

@@ -0,0 +1,7 @@
+import type { PlatformId } from "./types.js";
+interface DetectionResult {
+    detected: PlatformId | null;
+    candidates: PlatformId[];
+}
+export declare function detectPlatform(projectDir: string): Promise<DetectionResult>;
+export {};

package/dist/platform/detect.js

@@ -0,0 +1,23 @@
+import { exists } from "../utils/file-system.js";
+import { join } from "path";
+const DETECTION_MARKERS = [
+    { platform: "claude-code", markers: [".claude"] },
+    { platform: "codex", markers: ["AGENTS.md"] },
+    { platform: "cursor", markers: [".cursor"] },
+    { platform: "windsurf", markers: [".windsurf"] },
+    { platform: "copilot", markers: [".github/copilot-instructions.md"] },
+    { platform: "aider", markers: [".aider.conf.yml"] },
+];
+export async function detectPlatform(projectDir) {
+    const candidates = [];
+    for (const { platform, markers } of DETECTION_MARKERS) {
+        for (const marker of markers) {
+            if (await exists(join(projectDir, marker))) {
+                candidates.push(platform);
+                break;
+            }
+        }
+    }
+    const detected = candidates.length === 1 ? (candidates[0] ?? null) : null;
+    return { detected, candidates };
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,4 @@
+export type { Platform, PlatformId, PlatformTier, CommandDelivery, PlatformDoctorCheck, } from "./types.js";
+export { getPlatform, getAllPlatforms, isPlatformId } from "./registry.js";
+export { resolveProjectPlatform } from "./resolve.js";
+export { detectPlatform } from "./detect.js";

package/dist/platform/index.js

@@ -0,0 +1,3 @@
+export { getPlatform, getAllPlatforms, isPlatformId } from "./registry.js";
+export { resolveProjectPlatform } from "./resolve.js";
+export { detectPlatform } from "./detect.js";

package/dist/platform/registry.d.ts

@@ -0,0 +1,4 @@
+import type { Platform, PlatformId } from "./types.js";
+export declare function getPlatform(id: PlatformId): Platform;
+export declare function getAllPlatforms(): Platform[];
+export declare function isPlatformId(value: string): value is PlatformId;

package/dist/platform/registry.js

@@ -0,0 +1,27 @@
+import { claudeCodePlatform } from "./claude-code.js";
+import { codexPlatform } from "./codex.js";
+import { cursorPlatform } from "./cursor.js";
+import { windsurfPlatform } from "./windsurf.js";
+import { copilotPlatform } from "./copilot.js";
+import { aiderPlatform } from "./aider.js";
+const PLATFORMS = new Map([
+    ["claude-code", claudeCodePlatform],
+    ["codex", codexPlatform],
+    ["cursor", cursorPlatform],
+    ["windsurf", windsurfPlatform],
+    ["copilot", copilotPlatform],
+    ["aider", aiderPlatform],
+]);
+export function getPlatform(id) {
+    const platform = PLATFORMS.get(id);
+    if (!platform) {
+        throw new Error(`Unknown platform: ${id}`);
+    }
+    return platform;
+}
+export function getAllPlatforms() {
+    return [...PLATFORMS.values()];
+}
+export function isPlatformId(value) {
+    return PLATFORMS.has(value);
+}

package/dist/platform/resolve.d.ts

@@ -0,0 +1,8 @@
+import type { Platform } from "./types.js";
+/**
+ * Resolve the platform for a project from its config, defaulting to claude-code.
+ *
+ * Used by doctor and upgrade commands to determine which platform checks and
+ * assets to use. Falls back to claude-code when config is missing or unreadable.
+ */
+export declare function resolveProjectPlatform(projectDir: string): Promise<Platform>;

package/dist/platform/resolve.js

@@ -0,0 +1,24 @@
+import { readConfig } from "../utils/config.js";
+import { isEnoent, formatError } from "../utils/errors.js";
+import { warn } from "../utils/logger.js";
+import { getPlatform } from "./registry.js";
+/**
+ * Resolve the platform for a project from its config, defaulting to claude-code.
+ *
+ * Used by doctor and upgrade commands to determine which platform checks and
+ * assets to use. Falls back to claude-code when config is missing or unreadable.
+ */
+export async function resolveProjectPlatform(projectDir) {
+    try {
+        const config = await readConfig(projectDir);
+        if (config?.platform) {
+            return getPlatform(config.platform);
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            warn(`Failed to read project config: ${formatError(err)}`);
+        }
+    }
+    return getPlatform("claude-code");
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Platform abstraction layer for bmalph.
+ *
+ * Controls how `bmalph init/upgrade/doctor` install instruction files,
+ * deliver slash commands, and run health checks per platform.
+ */
+/** Supported platform identifiers. */
+export type PlatformId = "claude-code" | "codex" | "cursor" | "windsurf" | "copilot" | "aider";
+/** Full platforms support Phases 1-4 (planning + Ralph implementation). */
+/** Instructions-only platforms support Phases 1-3 (planning only). */
+export type PlatformTier = "full" | "instructions-only";
+/** How slash commands are delivered to the platform. */
+export type CommandDelivery = {
+    kind: "directory";
+    dir: string;
+} | {
+    kind: "inline";
+} | {
+    kind: "none";
+};
+/** Result of a single platform-specific doctor check. */
+export interface PlatformDoctorCheck {
+    id: string;
+    label: string;
+    check: (projectDir: string) => Promise<{
+        passed: boolean;
+        detail?: string;
+        hint?: string;
+    }>;
+}
+/** Platform definition controlling install, upgrade, and doctor behavior. */
+export interface Platform {
+    readonly id: PlatformId;
+    readonly displayName: string;
+    readonly tier: PlatformTier;
+    readonly instructionsFile: string;
+    readonly commandDelivery: CommandDelivery;
+    readonly instructionsSectionMarker: string;
+    readonly generateInstructionsSnippet: () => string;
+    readonly getDoctorChecks: () => PlatformDoctorCheck[];
+}

package/dist/platform/types.js

@@ -0,0 +1,7 @@
+/**
+ * Platform abstraction layer for bmalph.
+ *
+ * Controls how `bmalph init/upgrade/doctor` install instruction files,
+ * deliver slash commands, and run health checks per platform.
+ */
+export {};

package/dist/platform/windsurf.d.ts

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

package/dist/platform/windsurf.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const windsurfPlatform = {
+    id: "windsurf",
+    displayName: "Windsurf",
+    tier: "instructions-only",
+    instructionsFile: ".windsurf/rules/bmad.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: ".windsurf/rules/bmad.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".windsurf/rules/bmad.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: ".windsurf/rules/bmad.md not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/transition/artifacts.js

@@ -39,7 +39,7 @@ export async function validateArtifacts(files, artifactsDir) {
             }
         }
         catch {
-            // Cannot read readiness file, skip
+            warnings.push("Could not read readiness report — NO-GO status unverified");
         }
     }
     return warnings;

package/dist/transition/specs-changelog.js

@@ -36,7 +36,10 @@ export async function generateSpecsChangelog(oldSpecsDir, newSourceDir) {
                 debug(`Could not read old spec file ${file}: ${formatError(err)}`);
                 return "";
             });
-            const newContent = await readFile(join(newSourceDir, file), "utf-8");
+            const newContent = await readFile(join(newSourceDir, file), "utf-8").catch((err) => {
+                debug(`Could not read new spec file ${file}: ${formatError(err)}`);
+                return "";
+            });
             if (oldContent !== newContent) {
                 changes.push({
                     file,

package/dist/utils/config.d.ts

@@ -1,3 +1,4 @@
+import type { PlatformId } from "../platform/types.js";
 export interface UpstreamVersions {
     bmadCommit: string;
 }
@@ -5,6 +6,7 @@ export interface BmalphConfig {
     name: string;
     description: string;
     createdAt: string;
+    platform?: PlatformId;
     upstreamVersions?: UpstreamVersions;
 }
 export declare function readConfig(projectDir: string): Promise<BmalphConfig | null>;

package/dist/utils/validate.js

@@ -1,4 +1,12 @@
 import { MAX_PROJECT_NAME_LENGTH } from "./constants.js";
+const VALID_PLATFORM_IDS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "aider",
+];
 const VALID_STATUSES = ["planning", "implementing", "completed"];
 // Invalid filesystem characters (Windows + POSIX)
 const INVALID_FS_CHARS = /[<>:"/\\|?*]/;
@@ -50,6 +58,13 @@ export function validateConfig(data) {
         throw new Error("config.createdAt must be a string");
     }
     const description = typeof data.description === "string" ? data.description : "";
+    let platform;
+    if (data.platform !== undefined) {
+        if (typeof data.platform !== "string" || !VALID_PLATFORM_IDS.includes(data.platform)) {
+            throw new Error(`config.platform must be one of: ${VALID_PLATFORM_IDS.join(", ")}`);
+        }
+        platform = data.platform;
+    }
     const upstreamVersions = data.upstreamVersions !== undefined
         ? validateUpstreamVersions(data.upstreamVersions)
         : undefined;
@@ -57,6 +72,7 @@ export function validateConfig(data) {
         name: data.name,
         description,
         createdAt: data.createdAt,
+        ...(platform !== undefined && { platform }),
         upstreamVersions,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
   "type": "module",
   "bin": {

package/ralph/drivers/claude-code.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Claude Code driver for Ralph
+# Provides platform-specific CLI invocation logic
+
+# Driver identification
+driver_name() {
+    echo "claude-code"
+}
+
+driver_display_name() {
+    echo "Claude Code"
+}
+
+driver_cli_binary() {
+    echo "claude"
+}
+
+driver_min_version() {
+    echo "2.0.76"
+}
+
+# Check if the CLI binary is available
+driver_check_available() {
+    command -v "$(driver_cli_binary)" &>/dev/null
+}
+
+# Valid tool patterns for --allowedTools validation
+# Sets the global VALID_TOOL_PATTERNS array
+driver_valid_tools() {
+    VALID_TOOL_PATTERNS=(
+        "Write"
+        "Read"
+        "Edit"
+        "MultiEdit"
+        "Glob"
+        "Grep"
+        "Task"
+        "TodoWrite"
+        "WebFetch"
+        "WebSearch"
+        "Bash"
+        "Bash(git *)"
+        "Bash(npm *)"
+        "Bash(bats *)"
+        "Bash(python *)"
+        "Bash(node *)"
+        "NotebookEdit"
+    )
+}
+
+# Build the CLI command arguments
+# Populates global CLAUDE_CMD_ARGS array
+# Parameters:
+#   $1 - prompt_file: path to the prompt file
+#   $2 - loop_context: context string for session continuity
+#   $3 - session_id: session ID for resume (empty for new session)
+driver_build_command() {
+    local prompt_file=$1
+    local loop_context=$2
+    local session_id=$3
+
+    # Note: We do NOT use --dangerously-skip-permissions here. Tool permissions
+    # are controlled via --allowedTools from CLAUDE_ALLOWED_TOOLS in .ralphrc.
+    # This preserves the permission denial circuit breaker (Issue #101).
+    CLAUDE_CMD_ARGS=("$(driver_cli_binary)")
+
+    if [[ ! -f "$prompt_file" ]]; then
+        echo "ERROR: Prompt file not found: $prompt_file" >&2
+        return 1
+    fi
+
+    # Output format
+    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
+        CLAUDE_CMD_ARGS+=("--output-format" "json")
+    fi
+
+    # Allowed tools
+    if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
+        CLAUDE_CMD_ARGS+=("--allowedTools")
+        local IFS=','
+        read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
+        for tool in "${tools_array[@]}"; do
+            tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            if [[ -n "$tool" ]]; then
+                CLAUDE_CMD_ARGS+=("$tool")
+            fi
+        done
+    fi
+
+    # Session resume
+    # IMPORTANT: Use --resume with explicit session ID instead of --continue.
+    # --continue resumes the "most recent session in current directory" which
+    # can hijack active Claude Code sessions. --resume with a specific session ID
+    # ensures we only resume Ralph's own sessions. (Issue #151)
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
+
+    # Loop context as system prompt
+    if [[ -n "$loop_context" ]]; then
+        CLAUDE_CMD_ARGS+=("--append-system-prompt" "$loop_context")
+    fi
+
+    # Prompt content
+    local prompt_content
+    prompt_content=$(cat "$prompt_file")
+    CLAUDE_CMD_ARGS+=("-p" "$prompt_content")
+}
+
+# Whether this driver supports session continuity
+driver_supports_sessions() {
+    return 0  # true
+}
+
+# Stream filter for live output (jq filter for JSON streaming)
+driver_stream_filter() {
+    echo '.content // empty | select(type == "string")'
+}