its-consulting/ralph-claude-code
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(structure): migrate Ralph files to .ralph/ subfolder (#109)

Browse source 
* 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>
This commit is contained in:
Frank Bria 2026-01-20 23:22:30 -07:00 • committed by GitHub
parent 0e95f67318
commit 9b19d70e35
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
27 changed files with 1126 additions and 585 deletions
Download patch file Download diff file Expand all files Collapse all files

79
README.md
View file

@ -2,7 +2,7 @@
[![CI](https://github.com/frankbria/ralph-claude-code/actions/workflows/test.yml/badge.svg)](https://github.com/frankbria/ralph-claude-code/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Version](https://img.shields.io/badge/version-0.9.9-blue)
![Version](https://img.shields.io/badge/version-0.10.0-blue)
![Tests](https://img.shields.io/badge/tests-308%20passing-green)
[![GitHub Issues](https://img.shields.io/github/issues/frankbria/ralph-claude-code)](https://github.com/frankbria/ralph-claude-code/issues)
[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
@ -16,7 +16,7 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
## Project Status
**Version**: v0.9.9 - Active Development
**Version**: v0.10.0 - Active Development
**Core Features**: Working and tested
**Test Coverage**: 308 tests, 100% pass rate
@ -40,6 +40,15 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t
### Recent Improvements
**v0.10.0 - .ralph/ Subfolder Structure (BREAKING CHANGE)**
- **Breaking**: Moved all Ralph-specific files to `.ralph/` subfolder
- Project root stays clean: only `src/`, `README.md`, and user files remain
- Added `ralph-migrate` command for upgrading existing projects
- Migration script creates backup before moving files
- Fail-safe migration: preserves dotfiles with `cp -a source/. dest/` pattern
- Auto-detection of old structure with helpful upgrade guidance
- Updated all tests for new structure (310 tests)
**v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script**
- Fixed premature exit bug: completion indicators now require Claude's explicit `EXIT_SIGNAL: true`
- Added dual-condition check preventing exits when Claude reports work in progress
@ -152,7 +161,7 @@ cd ralph-claude-code
./install.sh
```
This adds `ralph`, `ralph-monitor`, and `ralph-setup` commands to your PATH.
This adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, and `ralph-migrate` commands to your PATH.
> **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired.
@ -167,9 +176,9 @@ ralph-import my-requirements.md my-project
cd my-project
# Review and adjust the generated files:
# - PROMPT.md (Ralph instructions)
# - @fix_plan.md (task priorities)
# - specs/requirements.md (technical specs)
# - .ralph/PROMPT.md (Ralph instructions)
# - .ralph/@fix_plan.md (task priorities)
# - .ralph/specs/requirements.md (technical specs)
# Start autonomous development
ralph --monitor
@ -182,9 +191,9 @@ ralph-setup my-awesome-project
cd my-awesome-project
# Configure your project requirements manually
# Edit PROMPT.md with your project goals
# Edit specs/ with detailed specifications
# Edit @fix_plan.md with initial priorities
# Edit .ralph/PROMPT.md with your project goals
# Edit .ralph/specs/ with detailed specifications
# Edit .ralph/@fix_plan.md with initial priorities
# Start autonomous development
ralph --monitor
@ -247,7 +256,7 @@ Loop 8: Claude outputs "All tasks complete, project ready"
```
**Other exit conditions:**
- All tasks in `@fix_plan.md` marked complete
- All tasks in `.ralph/@fix_plan.md` marked complete
- Multiple consecutive "done" signals from Claude Code
- Too many test-focused loops (indicating feature completeness)
- Claude API 5-hour usage limit reached (with user prompt to wait or exit)
@ -284,10 +293,10 @@ ralph-import design-doc.pdf
Ralph-import creates a complete project with:
- **PROMPT.md** - Converted into Ralph development instructions
- **@fix_plan.md** - Requirements broken down into prioritized tasks
- **specs/requirements.md** - Technical specifications extracted from your document
- **Standard Ralph structure** - All necessary directories and template files
- **.ralph/PROMPT.md** - Converted into Ralph development instructions
- **.ralph/@fix_plan.md** - Requirements broken down into prioritized tasks
- **.ralph/specs/requirements.md** - Technical specifications extracted from your document
- **Standard Ralph structure** - All necessary directories and template files in `.ralph/`
The conversion is intelligent and preserves your original requirements while making them actionable for autonomous development.
@ -384,8 +393,8 @@ ralph --no-continue # Isolated iterations
ralph --reset-session # Clears current session
# Check session status
cat .ralph_session # View current session file
cat .ralph_session_history # View session transition history
cat .ralph/.ralph_session # View current session file
cat .ralph/.ralph_session_history # View session transition history
```
**Session Auto-Reset Triggers:**
@ -395,7 +404,7 @@ cat .ralph_session_history # View session transition history
- Manual circuit breaker reset (`--reset-circuit`)
- Session expiration (default: 24 hours)
Sessions are persisted to `.ralph_session` with a configurable expiration (default: 24 hours). The last 50 session transitions are logged to `.ralph_session_history` for debugging.
Sessions are persisted to `.ralph/.ralph_session` with a configurable expiration (default: 24 hours). The last 50 session transitions are logged to `.ralph/.ralph_session_history` for debugging.
### Exit Thresholds
@ -426,42 +435,45 @@ CB_OUTPUT_DECLINE_THRESHOLD=70 # Open circuit if output declines by >70%
## Project Structure
Ralph creates a standardized structure for each project:
Ralph creates a standardized structure for each project with a `.ralph/` subfolder for configuration:
```
my-project/
├── PROMPT.md # Main development instructions for Ralph
├── @fix_plan.md # Prioritized task list (@ prefix = Ralph control file)
├── @AGENT.md # Build and run instructions
├── specs/ # Project specifications and requirements
│ └── stdlib/ # Standard library specifications
├── src/ # Source code implementation
├── examples/ # Usage examples and test cases
├── logs/ # Ralph execution logs
└── docs/generated/ # Auto-generated documentation
├── .ralph/ # Ralph configuration and state (hidden folder)
│ ├── PROMPT.md # Main development instructions for Ralph
│ ├── @fix_plan.md # Prioritized task list (@ prefix = Ralph control file)
│ ├── @AGENT.md # Build and run instructions
│ ├── specs/ # Project specifications and requirements
│ │ └── stdlib/ # Standard library specifications
│ ├── examples/ # Usage examples and test cases
│ ├── logs/ # Ralph execution logs
│ └── docs/generated/ # Auto-generated documentation
└── src/ # Source code implementation (at project root)
```
> **Migration**: If you have existing Ralph projects using the old flat structure, run `ralph-migrate` to automatically move files to the `.ralph/` subfolder.
## Best Practices
### Writing Effective Prompts
1. **Be Specific** - Clear requirements lead to better results
2. **Prioritize** - Use `@fix_plan.md` to guide Ralph's focus
2. **Prioritize** - Use `.ralph/@fix_plan.md` to guide Ralph's focus
3. **Set Boundaries** - Define what's in/out of scope
4. **Include Examples** - Show expected inputs/outputs
### Project Specifications
- Place detailed requirements in `specs/`
- Use `@fix_plan.md` for prioritized task tracking
- Keep `@AGENT.md` updated with build instructions
- Place detailed requirements in `.ralph/specs/`
- Use `.ralph/@fix_plan.md` for prioritized task tracking
- Keep `.ralph/@AGENT.md` updated with build instructions
- Document key decisions and architecture
### Monitoring Progress
- Use `ralph-monitor` for live status updates
- Check logs in `logs/` for detailed execution history
- Monitor `status.json` for programmatic access
- Check logs in `.ralph/logs/` for detailed execution history
- Monitor `.ralph/status.json` for programmatic access
- Watch for exit condition signals
## System Requirements
@ -646,6 +658,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
./uninstall.sh # Remove Ralph from system (dedicated script)
./install.sh uninstall # Alternative: Remove Ralph from system
./install.sh --help # Show installation help
ralph-migrate # Migrate existing project to .ralph/ structure
```
### Ralph Loop Options