bmalph 2.2.1 → 2.4.0

package/ralph/ralph_loop.sh

@@ -66,7 +66,8 @@ RALPH_SESSION_HISTORY_FILE="$RALPH_DIR/.ralph_session_history"  # Session transi
 CLAUDE_SESSION_EXPIRY_HOURS=${CLAUDE_SESSION_EXPIRY_HOURS:-24}
 
 # Valid tool patterns for --allowed-tools validation
-# Tools can be exact matches or pattern matches with wildcards in parentheses
+# Default: Claude Code tools. Platform driver overwrites via driver_valid_tools() in main().
+# Validation runs in main() after load_platform_driver so the correct patterns are in effect.
 VALID_TOOL_PATTERNS=(
     "Write"
     "Read"
@@ -98,6 +99,9 @@ TEST_PERCENTAGE_THRESHOLD=30  # If more than 30% of recent loops are test-only,
 RALPHRC_FILE=".ralphrc"
 RALPHRC_LOADED=false
 
+# Platform driver (set from .ralphrc or environment)
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
 # load_ralphrc - Load project-specific configuration from .ralphrc
 #
 # This function sources .ralphrc if it exists, applying project-specific
@@ -155,6 +159,26 @@ load_ralphrc() {
     return 0
 }
 
+# Source platform driver
+load_platform_driver() {
+    local driver_file="$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh"
+    if [[ ! -f "$driver_file" ]]; then
+        log_status "ERROR" "Platform driver not found: $driver_file"
+        log_status "ERROR" "Available drivers: $(ls "$SCRIPT_DIR/drivers/"*.sh 2>/dev/null | xargs -n1 basename | sed 's/.sh$//' | tr '\n' ' ')"
+        exit 1
+    fi
+    # shellcheck source=/dev/null
+    source "$driver_file"
+
+    # Initialize driver-specific tool patterns
+    driver_valid_tools
+
+    # Set CLI binary from driver
+    CLAUDE_CODE_CMD="$(driver_cli_binary)"
+
+    log_status "INFO" "Platform driver: $(driver_display_name) ($(driver_cli_binary))"
+}
+
 # Colors for terminal output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -949,68 +973,11 @@ update_session_last_used() {
 # Global array for Claude command arguments (avoids shell injection)
 declare -a CLAUDE_CMD_ARGS=()
 
-# Build Claude CLI command with modern flags using array (shell-injection safe)
+# Build CLI command with platform driver (shell-injection safe)
+# Delegates to the active platform driver's driver_build_command()
 # Populates global CLAUDE_CMD_ARGS array for direct execution
-# Uses -p flag with prompt content (Claude CLI does not have --prompt-file)
 build_claude_command() {
-    local prompt_file=$1
-    local loop_context=$2
-    local session_id=$3
-
-    # Reset global array
-    # 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=("$CLAUDE_CODE_CMD")
-
-    # Check if prompt file exists
-    if [[ ! -f "$prompt_file" ]]; then
-        log_status "ERROR" "Prompt file not found: $prompt_file"
-        return 1
-    fi
-
-    # Add output format flag
-    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
-        CLAUDE_CMD_ARGS+=("--output-format" "json")
-    fi
-
-    # Add allowed tools (each tool as separate array element)
-    if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
-        CLAUDE_CMD_ARGS+=("--allowedTools")
-        # Split by comma and add each tool
-        local IFS=','
-        read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
-        for tool in "${tools_array[@]}"; do
-            # Trim whitespace
-            tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-            if [[ -n "$tool" ]]; then
-                CLAUDE_CMD_ARGS+=("$tool")
-            fi
-        done
-    fi
-
-    # Add session continuity flag
-    # 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
-    # If no session_id, start fresh - Claude will generate a new session ID
-    # which we'll capture via save_claude_session() for future loops
-
-    # Add loop context as system prompt (no escaping needed - array handles it)
-    if [[ -n "$loop_context" ]]; then
-        CLAUDE_CMD_ARGS+=("--append-system-prompt" "$loop_context")
-    fi
-
-    # Read prompt file content and use -p flag
-    # Note: Claude CLI uses -p for prompts, not --prompt-file (which doesn't exist)
-    # Array-based approach maintains shell injection safety
-    local prompt_content
-    prompt_content=$(cat "$prompt_file")
-    CLAUDE_CMD_ARGS+=("-p" "$prompt_content")
+    driver_build_command "$@"
 }
 
 # Main execution function
@@ -1418,6 +1385,14 @@ main() {
         fi
     fi
 
+    # Load platform driver (after .ralphrc so PLATFORM_DRIVER can be overridden)
+    load_platform_driver
+
+    # Validate --allowed-tools now that platform-specific VALID_TOOL_PATTERNS are loaded
+    if [[ "${_CLI_ALLOWED_TOOLS:-}" == "true" ]] && ! validate_allowed_tools "$CLAUDE_ALLOWED_TOOLS"; then
+        exit 1
+    fi
+
     log_status "SUCCESS" "🚀 Ralph loop starting with Claude Code"
     log_status "INFO" "Max calls per hour: $MAX_CALLS_PER_HOUR"
     log_status "INFO" "Logs: $LOG_DIR/ | Docs: $DOCS_DIR/ | Status: $STATUS_FILE"
@@ -1461,6 +1436,21 @@ main() {
         exit 1
     fi
 
+    # Check required dependencies
+    if ! command -v jq &> /dev/null; then
+        log_status "ERROR" "Required dependency 'jq' is not installed."
+        echo ""
+        echo "jq is required for JSON processing in the Ralph loop."
+        echo ""
+        echo "Install jq:"
+        echo "  macOS:   brew install jq"
+        echo "  Ubuntu:  sudo apt-get install jq"
+        echo "  Windows: choco install jq  (or: winget install jqlang.jq)"
+        echo ""
+        echo "After installing, run this command again."
+        exit 1
+    fi
+
     # Initialize session tracking before entering the loop
     init_session_tracking
 
@@ -1750,10 +1740,8 @@ while [[ $# -gt 0 ]]; do
             shift 2
             ;;
         --allowed-tools)
-            if ! validate_allowed_tools "$2"; then
-                exit 1
-            fi
             CLAUDE_ALLOWED_TOOLS="$2"
+            _CLI_ALLOWED_TOOLS=true
             shift 2
             ;;
         --no-continue)

package/ralph/templates/ralphrc.template

@@ -6,6 +6,13 @@
 # Values here override global Ralph defaults.
 # Environment variables override values in this file.
 
+# =============================================================================
+# PLATFORM DRIVER
+# =============================================================================
+
+# Platform driver for Ralph loop (claude-code or codex)
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
 # =============================================================================
 # PROJECT IDENTIFICATION
 # =============================================================================

package/slash-commands/bmalph-doctor.md

@@ -0,0 +1,16 @@
+# Check Project Health
+
+Run diagnostic checks on the bmalph installation and report any issues.
+
+## How to Run
+
+Execute the CLI command:
+    bmalph doctor
+
+## What It Does
+
+- Verifies required directories exist (`_bmad/`, `.ralph/`, `bmalph/`)
+- Checks that slash commands are installed correctly
+- Validates the instructions file contains the BMAD snippet
+- Reports version mismatches between installed and bundled assets
+- Suggests remediation steps for any issues found

package/slash-commands/bmalph-implement.md

@@ -2,151 +2,28 @@
 
 Transition from BMAD planning (Phase 3) to Ralph implementation (Phase 4).
 
-## Prerequisites
+## How to Run
 
-- bmalph must be initialized (`bmalph/config.json` must exist)
-- Stories must exist in `_bmad-output/planning-artifacts/`
+Execute the CLI command:
+    bmalph implement
 
-## Steps
+If pre-flight validation fails and you want to proceed anyway:
+    bmalph implement --force
 
-### 1. Validate Prerequisites
+## What It Does
 
-Check that:
-- `bmalph/config.json` exists
-- `.ralph/ralph_loop.sh` exists
-- `_bmad-output/planning-artifacts/` exists with story files
+- Validates planning artifacts (PRD, architecture, readiness report)
+- Parses epics and stories into `.ralph/@fix_plan.md`
+- Copies specs to `.ralph/specs/`
+- Generates PROJECT_CONTEXT.md, PROMPT.md, SPECS_INDEX.md
+- Customizes @AGENT.md based on detected tech stack
+- Updates phase state to 4 (implementing)
 
-If any are missing, report the error and suggest running the required commands.
+## After Running
 
-### 2. Parse Stories
+Review the CLI output for:
+- **Pre-flight warnings**: Address any issues or acknowledge them
+- **Story count**: Verify all expected stories were parsed
+- **Driver instructions**: Follow the displayed command to start the Ralph loop
 
-Read `_bmad-output/planning-artifacts/stories.md` (or any file matching `*stor*.md` or `*epic*.md`):
-- Extract epics: `## Epic N: Title`
-- Extract stories: `### Story N.M: Title`
-- Parse acceptance criteria (Given/When/Then blocks)
-
-### 3. Generate `.ralph/@fix_plan.md`
-
-Create an ordered list of stories as checkboxes:
-
-```markdown
-# Ralph Fix Plan
-
-## Stories to Implement
-
-### [Epic Title]
-> Goal: [Epic description]
-
-- [ ] Story 1.1: [Title]
-  > [Description line 1]
-  > AC: Given..., When..., Then...
-
-## Completed
-
-## Notes
-- Follow TDD methodology (red-green-refactor)
-- One story per Ralph loop iteration
-- Update this file after completing each story
-```
-
-**Important:** If existing `@fix_plan.md` has completed items `[x]`, preserve their completion status in the new file.
-
-### 4. Generate `.ralph/PROJECT_CONTEXT.md`
-
-Extract from planning artifacts:
-- Project goals from PRD (Executive Summary, Vision, Goals sections)
-- Success metrics from PRD
-- Architecture constraints from architecture document
-- Technical risks from architecture document
-- Scope boundaries from PRD
-- Target users from PRD
-- Non-functional requirements from PRD
-
-Format as:
-
-```markdown
-# [Project Name] — Project Context
-
-## Project Goals
-[extracted content]
-
-## Success Metrics
-[extracted content]
-
-## Architecture Constraints
-[extracted content]
-
-## Technical Risks
-[extracted content]
-
-## Scope Boundaries
-[extracted content]
-
-## Target Users
-[extracted content]
-
-## Non-Functional Requirements
-[extracted content]
-```
-
-### 5. Copy Specs to `.ralph/specs/`
-
-Copy the entire `_bmad-output/` tree to `.ralph/specs/`:
-- This includes `planning-artifacts/`, `implementation-artifacts/`, etc.
-- Preserve directory structure
-
-If specs existed before, generate `SPECS_CHANGELOG.md`:
-```markdown
-# Specs Changelog
-
-Last updated: [timestamp]
-
-## Added
-- [new files]
-
-## Modified
-- [changed files]
-
-## Removed
-- [deleted files]
-```
-
-### 6. Update State
-
-Update `bmalph/state/current-phase.json`:
-```json
-{
-  "currentPhase": 4,
-  "status": "implementing",
-  "startedAt": "[original or now]",
-  "lastUpdated": "[now]"
-}
-```
-
-### 7. Report Results
-
-Output:
-- Number of stories found
-- Any warnings (missing PRD, architecture, NO-GO status in readiness report)
-- Whether fix_plan progress was preserved
-
-### 8. Instruct User
-
-Display:
-
-```
-Transition complete. To start the Ralph autonomous loop:
-
-    bash .ralph/ralph_loop.sh
-
-Or in a separate terminal for background execution:
-
-    nohup bash .ralph/ralph_loop.sh > .ralph/logs/ralph.log 2>&1 &
-```
-
-## Warnings to Check
-
-- No PRD document found
-- No architecture document found
-- Readiness report indicates NO-GO status
-- No stories parsed from the epics file
+If there are errors, fix the underlying planning artifacts and re-run.

package/slash-commands/bmalph-status.md

@@ -0,0 +1,15 @@
+# Project Status
+
+Show the current bmalph project status, including phase, Ralph progress, and version info.
+
+## How to Run
+
+Execute the CLI command:
+    bmalph status
+
+## What It Does
+
+- Shows current phase (1-4) and status (planning, implementing, completed)
+- Displays Ralph loop progress (tasks completed / total)
+- Reports installed bmalph version and bundled asset versions
+- Indicates whether updates are available

package/slash-commands/bmalph-upgrade.md

@@ -0,0 +1,15 @@
+# Upgrade Bundled Assets
+
+Update BMAD and Ralph assets to match the currently installed bmalph version.
+
+## How to Run
+
+Execute the CLI command:
+    bmalph upgrade
+
+## What It Does
+
+- Overwrites `_bmad/` with the latest bundled BMAD agents and workflows
+- Overwrites `.ralph/` base files with the latest bundled Ralph loop and libraries
+- Preserves project-specific state (config, fix plan progress, specs)
+- Reports which files were updated