Update README.md for project status and to encourage contributors
This commit is contained in:
frankbria
parent
de93bc8723
commit
9ada2a5135
2 changed files with 163 additions and 29 deletions
|
|
@ -12,7 +12,8 @@
|
||||||
"Bash(git push:*)",
|
"Bash(git push:*)",
|
||||||
"Bash(npm run test:integration:*)",
|
"Bash(npm run test:integration:*)",
|
||||||
"Bash(test:*)",
|
"Bash(test:*)",
|
||||||
"Bash(awk:*)"
|
"Bash(awk:*)",
|
||||||
|
"Bash(bats:*)"
|
||||||
],
|
],
|
||||||
"deny": [],
|
"deny": [],
|
||||||
"ask": []
|
"ask": []
|
||||||
|
|
|
||||||
189
README.md
189
README.md
|
|
@ -1,11 +1,43 @@
|
||||||
# Ralph for Claude Code
|
# Ralph for Claude Code
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
> **Autonomous AI development loop with intelligent exit detection and rate limiting**
|
> **Autonomous AI development loop with intelligent exit detection and rate limiting**
|
||||||
|
|
||||||
Ralph is an implementation of the [Ralph technique](https://github.com/paul-gauthier/aider/blob/main/docs/more/aider-benchmarks.md#ralph) by Paul Gauthier, specifically adapted for [Claude Code](https://claude.ai/code). It enables continuous autonomous development cycles where Claude Code iteratively improves your project until completion, with built-in safeguards to prevent infinite loops and API overuse.
|
Ralph is an implementation of the [Ralph technique](https://github.com/paul-gauthier/aider/blob/main/docs/more/aider-benchmarks.md#ralph) by Paul Gauthier, specifically adapted for [Claude Code](https://claude.ai/code). It enables continuous autonomous development cycles where Claude Code iteratively improves your project until completion, with built-in safeguards to prevent infinite loops and API overuse.
|
||||||
|
|
||||||
**Install once, use everywhere** - Ralph becomes a global command available in any directory.
|
**Install once, use everywhere** - Ralph becomes a global command available in any directory.
|
||||||
|
|
||||||
|
## 📌 Project Status
|
||||||
|
|
||||||
|
**Version**: v0.9.0 - Active Development
|
||||||
|
**Core Features**: ✅ Working and tested
|
||||||
|
**Test Coverage**: 60% (expanding to 90%+ - see [roadmap](#-development-roadmap))
|
||||||
|
|
||||||
|
### What's Working Now ✅
|
||||||
|
- Autonomous development loops with intelligent exit detection
|
||||||
|
- Rate limiting with hourly reset (100 calls/hour, configurable)
|
||||||
|
- Circuit breaker prevents runaway loops
|
||||||
|
- Response analyzer with semantic understanding
|
||||||
|
- 5-hour API limit handling with user prompts
|
||||||
|
- tmux integration for live monitoring
|
||||||
|
- PRD import functionality
|
||||||
|
- 75 passing tests covering critical paths
|
||||||
|
|
||||||
|
### In Progress 🚧
|
||||||
|
- Expanding test coverage (60% → 90%+)
|
||||||
|
- Log rotation functionality
|
||||||
|
- Dry-run mode
|
||||||
|
- Configuration file support (.ralphrc)
|
||||||
|
- Metrics and analytics tracking
|
||||||
|
- Desktop notifications
|
||||||
|
- Git backup and rollback system
|
||||||
|
|
||||||
|
**Timeline to v1.0**: ~4 weeks • [Full roadmap](IMPLEMENTATION_PLAN.md) • **Contributions welcome!**
|
||||||
|
|
||||||
## 🌟 Features
|
## 🌟 Features
|
||||||
|
|
||||||
- **🔄 Autonomous Development Loop** - Continuously executes Claude Code with your project requirements
|
- **🔄 Autonomous Development Loop** - Continuously executes Claude Code with your project requirements
|
||||||
|
|
@ -361,22 +393,94 @@ tail -f logs/ralph.log
|
||||||
|
|
||||||
## 🤝 Contributing
|
## 🤝 Contributing
|
||||||
|
|
||||||
1. Fork the repository
|
Ralph is actively seeking contributors! We're working toward v1.0.0 with clear priorities and a detailed roadmap.
|
||||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
||||||
3. Make your changes
|
### Quick Start for Contributors
|
||||||
4. Run the test suite: `bats tests/` (ensure all tests pass)
|
|
||||||
5. Test with `./install.sh` and sample projects
|
1. **Fork and Clone**
|
||||||
6. Commit your changes (`git commit -m 'Add amazing feature'`)
|
```bash
|
||||||
7. Push to the branch (`git push origin feature/amazing-feature`)
|
git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
|
||||||
8. Open a Pull Request
|
cd ralph-claude-code
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Install Dependencies**
|
||||||
|
```bash
|
||||||
|
npm install -g bats bats-support bats-assert
|
||||||
|
./install.sh # Install Ralph globally for testing
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Run Tests**
|
||||||
|
```bash
|
||||||
|
npm test # Run all tests
|
||||||
|
npm run test:unit # Run unit tests only
|
||||||
|
npm run test:integration # Run integration tests only
|
||||||
|
```
|
||||||
|
|
||||||
|
### Priority Contribution Areas
|
||||||
|
|
||||||
|
**🔥 High Priority (Help Needed!)**
|
||||||
|
1. **Test Implementation** - We need 65+ more tests to reach 90% coverage
|
||||||
|
- See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for detailed test specifications
|
||||||
|
- Week 3-4: Installation, CLI, tmux tests (58 tests)
|
||||||
|
- Week 5-6: Features and E2E tests (42 tests)
|
||||||
|
|
||||||
|
2. **Feature Development**
|
||||||
|
- Log rotation functionality (Week 5, Day 3)
|
||||||
|
- Dry-run mode (Week 5, Day 4)
|
||||||
|
- Config file support (Week 5, Day 5)
|
||||||
|
- Metrics tracking (Week 6, Day 1)
|
||||||
|
- Notifications (Week 6, Day 2)
|
||||||
|
- Backup/rollback (Week 6, Day 3)
|
||||||
|
|
||||||
|
3. **Documentation**
|
||||||
|
- TESTING.md guide
|
||||||
|
- CONTRIBUTING.md (expand this section)
|
||||||
|
- Usage tutorials and examples
|
||||||
|
- Troubleshooting guides
|
||||||
|
|
||||||
|
4. **Real-World Testing**
|
||||||
|
- Use Ralph on your projects
|
||||||
|
- Report bugs and edge cases
|
||||||
|
- Share your experience
|
||||||
|
|
||||||
### Development Guidelines
|
### Development Guidelines
|
||||||
|
|
||||||
- All new features should include tests
|
- **Tests Required**: All new features must include tests
|
||||||
- Maintain or improve test coverage (currently 60%, target 90%+)
|
- **Coverage Goal**: Maintain or improve coverage (currently 60%, target 90%+)
|
||||||
- Follow existing code patterns and conventions
|
- **Code Style**: Follow existing bash patterns and conventions
|
||||||
- Update documentation for user-facing changes
|
- **Documentation**: Update README and relevant docs for user-facing changes
|
||||||
- See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for development roadmap
|
- **Commit Messages**: Clear, descriptive commit messages
|
||||||
|
- **Branch Naming**: `feature/feature-name` or `fix/bug-description`
|
||||||
|
|
||||||
|
### Pull Request Process
|
||||||
|
|
||||||
|
1. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||||
|
2. Make your changes with tests
|
||||||
|
3. Run full test suite: `npm test` (must pass 100%)
|
||||||
|
4. Update documentation if needed
|
||||||
|
5. Commit changes (`git commit -m 'Add amazing feature'`)
|
||||||
|
6. Push to your fork (`git push origin feature/amazing-feature`)
|
||||||
|
7. Open a Pull Request with:
|
||||||
|
- Clear description of changes
|
||||||
|
- Link to related issues
|
||||||
|
- Test results
|
||||||
|
- Screenshots (if UI/output changes)
|
||||||
|
|
||||||
|
### Development Roadmap Reference
|
||||||
|
|
||||||
|
See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete 6-week plan including:
|
||||||
|
- Detailed test specifications
|
||||||
|
- Feature implementation guides
|
||||||
|
- Code examples for new functionality
|
||||||
|
- Success metrics and milestones
|
||||||
|
|
||||||
|
### Questions or Ideas?
|
||||||
|
|
||||||
|
- Open an issue for discussion
|
||||||
|
- Check existing issues for planned work
|
||||||
|
- Join discussions on pull requests
|
||||||
|
|
||||||
|
**Every contribution matters** - from fixing typos to implementing major features. Thank you for helping make Ralph better! 🙏
|
||||||
|
|
||||||
## 📄 License
|
## 📄 License
|
||||||
|
|
||||||
|
|
@ -439,26 +543,55 @@ tmux attach -t <name> # Reattach to detached session
|
||||||
|
|
||||||
## 🗺️ Development Roadmap
|
## 🗺️ Development Roadmap
|
||||||
|
|
||||||
Ralph is under active development. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete roadmap.
|
Ralph is under active development with a clear path to v1.0.0. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete 6-week roadmap.
|
||||||
|
|
||||||
### Current Status (v0.9.0)
|
### Current Status: v0.9.0 (Week 1-2 Complete)
|
||||||
- ✅ Core loop functionality complete
|
**What's Delivered:**
|
||||||
- ✅ Rate limiting and circuit breaker
|
- ✅ Core loop functionality with intelligent exit detection
|
||||||
|
- ✅ Rate limiting (100 calls/hour) and circuit breaker pattern
|
||||||
- ✅ Response analyzer with semantic understanding
|
- ✅ Response analyzer with semantic understanding
|
||||||
- ✅ 75 tests (60% coverage)
|
- ✅ 75 comprehensive tests (100% pass rate, 60% coverage)
|
||||||
- ✅ tmux integration and monitoring
|
- ✅ tmux integration and live monitoring
|
||||||
- ✅ PRD import functionality
|
- ✅ PRD import functionality
|
||||||
|
- ✅ Installation system and project templates
|
||||||
|
- ✅ Comprehensive documentation (2,300+ lines)
|
||||||
|
|
||||||
### Planned Features (v1.0.0)
|
**Test Coverage Breakdown:**
|
||||||
- ⏳ Additional 65+ tests for 90%+ coverage
|
- Unit Tests: 35 (rate limiting, exit detection)
|
||||||
- ⏳ Log rotation functionality
|
- Integration Tests: 40 (loop execution, edge cases)
|
||||||
- ⏳ Dry-run mode
|
- Coverage: ~60% of critical code paths
|
||||||
- ⏳ Configuration file support (.ralphrc)
|
|
||||||
- ⏳ Metrics and analytics tracking
|
|
||||||
- ⏳ Desktop notifications
|
|
||||||
- ⏳ Git backup and rollback system
|
|
||||||
|
|
||||||
See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed progress tracking.
|
### Path to v1.0.0 (~4 weeks)
|
||||||
|
**Week 3-4: Enhanced Testing**
|
||||||
|
- ⏳ Installation and setup workflow tests (28 tests)
|
||||||
|
- ⏳ CLI argument parsing tests (10 tests)
|
||||||
|
- ⏳ tmux integration tests (12 tests)
|
||||||
|
- ⏳ Monitor dashboard tests (8 tests)
|
||||||
|
|
||||||
|
**Week 5: Core Features**
|
||||||
|
- ⏳ Log rotation functionality (5 tests)
|
||||||
|
- ⏳ Dry-run mode (4 tests)
|
||||||
|
- ⏳ Configuration file support - .ralphrc (6 tests)
|
||||||
|
|
||||||
|
**Week 6: Advanced Features & Polish**
|
||||||
|
- ⏳ Metrics and analytics tracking (4 tests)
|
||||||
|
- ⏳ Desktop notifications (3 tests)
|
||||||
|
- ⏳ Git backup and rollback system (5 tests)
|
||||||
|
- ⏳ End-to-end tests (10 tests)
|
||||||
|
- ⏳ Final documentation and release prep
|
||||||
|
|
||||||
|
**Target:** 140+ tests, 90%+ coverage, all planned features implemented
|
||||||
|
|
||||||
|
See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed week-by-week progress tracking.
|
||||||
|
|
||||||
|
### How to Contribute
|
||||||
|
Ralph is seeking contributors! Priority areas:
|
||||||
|
1. **Test Implementation** - Help reach 90%+ coverage ([see plan](IMPLEMENTATION_PLAN.md))
|
||||||
|
2. **Feature Development** - Log rotation, dry-run mode, config files
|
||||||
|
3. **Documentation** - Usage examples, tutorials, troubleshooting guides
|
||||||
|
4. **Bug Reports** - Real-world usage feedback and edge cases
|
||||||
|
|
||||||
|
See [Contributing](#-contributing) section below for guidelines.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue