* refactor(naming): remove @ prefix from on-disk filenames
BREAKING CHANGE: Renames @fix_plan.md → fix_plan.md and @AGENT.md → AGENT.md
This change improves POSIX compliance and compatibility with command-line tools.
The @ prefix was originally used to avoid naming conflicts, but with the .ralph/
folder structure introduced in v0.10.0, this convention is no longer necessary.
Changes:
- Update all scripts to use new naming (fix_plan.md, AGENT.md)
- Update migration script to handle both old and new naming conventions
- Update templates to use new naming
- Update all documentation references
- Update all 420 tests to expect new naming (TDD approach)
Migration:
- Existing projects with @-prefixed files will be automatically renamed
when running ralph-migrate
- Projects already using the new naming will continue to work unchanged
* docs(claude): update file naming conventions section
* fix(migrate): prevent orphaned @-prefixed files during migration
When both root/@fix_plan.md and .ralph/@fix_plan.md exist, the root file
now takes priority and the .ralph/@fix_plan.md is removed (backup exists).
This prevents orphaned legacy files after migration.
---------
Co-authored-by: Test User <test@example.com>
* feat(enable): add ralph-enable wizard for existing projects (v0.11.0)
Add interactive wizard and CI version for enabling Ralph in existing projects.
New commands:
- ralph-enable: Interactive 5-phase wizard for humans
- ralph-enable-ci: Non-interactive version with JSON output for CI/automation
New library components:
- lib/enable_core.sh: Shared logic for idempotency, project detection, templates
- lib/wizard_utils.sh: Interactive prompt utilities
- lib/task_sources.sh: Task import from beads, GitHub Issues, PRD documents
Features:
- Auto-detects project type (TypeScript, Python, Rust, Go)
- Auto-detects framework (Next.js, FastAPI, Django, Express)
- Imports tasks from beads, GitHub Issues, or PRD documents
- Generates .ralphrc project configuration file
- Idempotent: safe to run multiple times, respects existing files
- Exit codes: 0 (success), 1 (error), 2 (already enabled)
Updated:
- install.sh: Added new commands to global installation
- ralph_loop.sh: Loads .ralphrc configuration at startup
Tests: 75 new tests (30 enable_core + 23 task_sources + 22 integration)
Total: 396 tests passing (100% pass rate)
Closes#85, #121, #64, #87, #99
* fix(enable): address code review feedback
Fixes from PR #124 review:
1. sed -i portability (ralph_enable.sh:456)
- Use portable sed + mv pattern instead of GNU-only sed -i
2. sed regex portability (lib/task_sources.sh)
- Replace \s with POSIX [[:space:]] character class
- Add sed -E flag for extended regex
3. jq availability check (ralph_enable_ci.sh:177)
- Add check for jq when --json flag is used
4. Unused filter parameter (lib/task_sources.sh:44)
- Pass filter to bd list --filter command
5. Word-splitting in select_multiple (ralph_enable.sh:322)
- Return comma-separated indices instead of space-separated text
- Update caller to parse indices correctly
6. Missing || true for check_existing_ralph (ralph_enable.sh:185)
- Prevent set -e from exiting on non-zero return
7. select_multiple stdout corruption (lib/wizard_utils.sh)
- Redirect interactive output to stderr
- Only final result goes to stdout
8. Color variables not exported (lib/wizard_utils.sh:12)
- Export WIZARD_* color variables for subshells
9. select_option infinite loop (lib/wizard_utils.sh:179)
- Add guard for empty options array
* fix(tests): add missing mocks and exports for new enable feature
- Add RESPONSE_ANALYSIS_FILE export to test_session_continuity.bats setup
- Add mock ralph_enable.sh and ralph_enable_ci.sh to test_installation.bats
- Add mock lib files: enable_core.sh, wizard_utils.sh, task_sources.sh, timeout_utils.sh
All 396 tests now pass.
* fix(config): fix critical issues from PR review
1. .ralphrc Configuration Loading Fix:
- Captured env var state BEFORE setting defaults with _env_* variables
- load_ralphrc now only restores values explicitly set by environment
- .ralphrc settings are now properly applied (not overwritten by defaults)
2. sed Command Injection Fix:
- Replaced sed with awk for .ralphrc updates in ralph_enable.sh
- awk -v pattern safely handles user input without shell injection risk
3. Shell Injection Fix in safe_create_file():
- Replaced echo with printf '%s\n' for safer content handling
- Prevents issues with backslashes, -n, and special characters
4. Specific Error Codes:
- Added ENABLE_INVALID_ARGS=3 for argument errors
- Added ENABLE_FILE_NOT_FOUND=4 for missing files
- Added ENABLE_DEPENDENCY_MISSING=5 for missing deps (e.g., jq)
- Added ENABLE_PERMISSION_DENIED=6 for permission errors
- Updated ralph_enable.sh and ralph_enable_ci.sh to use specific codes
5. Added tests for .ralphrc loading pattern verification
Test count: 398 (up from 396)
* fix(enable): make --force flag actually overwrite existing files
The --force flag was accepted but safe_create_file() always skipped
existing files regardless of ENABLE_FORCE value.
Changes:
- safe_create_file() now checks ENABLE_FORCE environment variable
- When ENABLE_FORCE="true", overwrites existing files instead of skipping
- Added proper logging for overwrite operations
Added tests:
- Verify enable_ralph_in_directory actually changes file contents with --force
- Test safe_create_file overwrites when ENABLE_FORCE is true
- Test safe_create_file skips when ENABLE_FORCE is false
Test count: 400 (up from 398)
---------
Co-authored-by: Test User <test@example.com>
* feat(structure): migrate Ralph files to .ralph/ subfolder
BREAKING CHANGE: Ralph configuration files now live in .ralph/ subfolder
This refactoring moves all Ralph-specific files into a hidden .ralph/
directory while keeping src/ at the project root. This improves
compatibility with existing tooling and keeps the project root clean.
Changes:
- Move PROMPT.md, @fix_plan.md, @AGENT.md to .ralph/
- Move specs/, logs/, docs/generated/, examples/ to .ralph/
- Move state files (.response_analysis, .circuit_breaker_state, etc.) to .ralph/
- Keep src/ at project root (unchanged)
- Add RALPH_DIR=".ralph" configuration variable
- Add ralph-migrate command for existing projects
- Create migrate_to_ralph_folder.sh migration script
- Update all path references in scripts and tests
- Update documentation (README.md, CLAUDE.md)
New project structure:
project/
├── .ralph/ # Ralph configuration
│ ├── PROMPT.md
│ ├── @fix_plan.md
│ ├── @AGENT.md
│ ├── specs/
│ ├── logs/
│ └── docs/generated/
└── src/ # Source code (unchanged)
Migration: Run `ralph-migrate` in existing projects to upgrade.
All 310 tests pass (100% pass rate).
* chore: add .claude/settings.local.json to .gitignore
* fix: address code review feedback for .ralph/ subfolder structure
Fixes multiple path-related issues identified in code review:
Test fixes:
- Fix create_sample_prompt to use $RALPH_DIR/PROMPT.md in test_session_continuity.bats
- Fix result_file path to use $RALPH_DIR/.json_parse_result in test_json_parsing.bats
- Fix @fix_plan.md and .response_analysis paths in test_cli_modern.bats
- Update templates directory missing test to account for global fallback
Template fix:
- Fix @fix_plan.md reference in templates/PROMPT.md to use .ralph/ prefix
Script fixes:
- Fix PROMPT_FILE comparison in ralph_loop.sh to use $RALPH_DIR/PROMPT.md
- Fix examples migration logic in migrate_to_ralph_folder.sh (remove premature mkdir)
- Move templates directory check AFTER cd in setup.sh (was checking wrong location)
- Add template directory validation with fallback to global templates
All 310 tests pass.
* Update migrate_to_ralph_folder.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* fix: address code review feedback for .ralph/ subfolder structure
Code Review Fixes:
- Fix test_json_parsing.bats: all result_file and session file paths now use $RALPH_DIR prefix
- Fix ralph_loop.sh help text: paths now show .ralph/.ralph_session, .ralph/.call_count, etc.
- Fix migrate_to_ralph_folder.sh:
- Proper error handling for date command (separate local declaration)
- Use cp -a source/. dest/ pattern to preserve dotfiles and attributes
- Remove 2>/dev/null suppression to surface copy errors
- Update create_files.sh to use .ralph/ structure for embedded scripts
- Update .gitignore with all .ralph/ state file paths
- Add old structure detection in ralph_loop.sh with helpful migration message
Version Update:
- Bump to v0.10.0 (breaking change: structural reorganization)
- Update README.md and CLAUDE.md with new version and release notes
- Add ralph-migrate documentation to Key Commands section
All 310 tests pass.
---------
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* feat(timeout): add cross-platform timeout support for macOS
Add portable timeout wrapper that automatically detects and uses the
appropriate timeout command based on the platform:
- Linux: Uses standard GNU `timeout` from coreutils
- macOS: Uses `gtimeout` from Homebrew coreutils
Changes:
- Add lib/timeout_utils.sh with detect_timeout_command() and
portable_timeout() functions
- Update ralph_loop.sh to source timeout_utils.sh and use
portable_timeout for Claude Code execution
- Update install.sh to check for coreutils on macOS and provide
installation instructions
- Update test mocks to include gtimeout and portable_timeout
- Update README.md with macOS coreutils installation instructions
- Update CLAUDE.md with timeout_utils.sh documentation
Users on macOS now need to install coreutils: brew install coreutils
* Update model reference in opencode-review workflow
* Update model name in opencode-review workflow
* Update model version in opencode-review workflow
* Update model version in opencode-review workflow
* Update lib/timeout_utils.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* Update opencode-review.yml
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
The install.sh was missing the lib/ directory copy, causing ralph_loop.sh
to fail when sourcing response_analyzer.sh and circuit_breaker.sh.
Changes:
- Add mkdir -p "$RALPH_HOME/lib" to create_install_dirs()
- Add cp -r "$SCRIPT_DIR/lib/"* "$RALPH_HOME/lib/" to install_scripts()
- Add chmod +x for lib/*.sh scripts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Removed npx @anthropic-ai/claude-code --version check during install
- This was causing the install script to hang due to network/auth delays
- Claude Code will be downloaded automatically when first used by Ralph
- Installation should now complete quickly without hanging
- Updated from @anthropic/claude-code to @anthropic-ai/claude-code
- This was causing npm 404 errors when trying to execute Claude Code
- Fixed in ralph_loop.sh, ralph_import.sh, install.sh, and README.md
- Ralph should now be able to successfully execute Claude Code commands
🚀 New Feature: ralph-import
- Converts existing PRDs/specs to Ralph format using Claude Code intelligence
- Supports multiple formats: Markdown, text, JSON, Word docs, PDFs
- Creates complete Ralph project with PROMPT.md, @fix_plan.md, specs/
- Leverages Claude Code for intelligent requirement parsing and conversion
🔧 Implementation:
- ralph_import.sh: Core conversion script with Claude Code integration
- Global installation: ralph-import command available system-wide
- Smart conversion prompt that extracts goals, priorities, and technical specs
- Auto-generates proper Ralph project structure from any source format
📚 Enhanced Documentation:
- New "Importing Existing Requirements" section in README
- Option A (import PRD) vs Option B (manual setup) in Quick Start
- Comprehensive format support and usage examples
- Command reference updated with ralph-import
🎯 Benefits:
- Eliminates manual conversion from PRDs to Ralph format
- Leverages Claude Code's intelligence for requirement interpretation
- Dramatically reduces onboarding friction for existing projects
- Maintains all original requirement context while making it actionable
Sample PRD included for testing and demonstration purposes.
Major architectural change to make Ralph available as global commands:
🌟 New Global Installation System:
- Add install.sh script for global installation to ~/.local/bin
- Creates ralph, ralph-monitor, ralph-setup global commands
- Installs templates and scripts to ~/.ralph/ directory
- Automatic dependency checking and PATH configuration
🚀 Enhanced User Experience:
- ralph-setup my-project (run from anywhere, no directory constraints)
- ralph --monitor (start from any project directory)
- ralph-monitor (global monitoring command)
- No more ../ralph_loop.sh relative path requirements
🔧 Improved Architecture:
- Global template system in ~/.ralph/templates/
- Smart path detection (global commands vs local scripts)
- Maintains backward compatibility during transition
- Clean separation of installation vs project files
📚 Updated Documentation:
- All examples now use global commands (ralph vs ../ralph_loop.sh)
- Clear installation instructions with ./install.sh
- Global command reference in CLAUDE.md
- Streamlined Quick Start workflow
This makes Ralph much more professional and user-friendly by eliminating
directory structure requirements and providing standard Unix command experience.
