Initial Ralph project setup
This commit is contained in:
debian
47
.gitignore
vendored
Normal file
47
.gitignore
vendored
Normal file
@@ -0,0 +1,47 @@
|
||||
# Ralph generated files (inside .ralph/ subfolder)
|
||||
.ralph/.call_count
|
||||
.ralph/.last_reset
|
||||
.ralph/.exit_signals
|
||||
.ralph/status.json
|
||||
.ralph/.ralph_session
|
||||
.ralph/.ralph_session_history
|
||||
.ralph/.claude_session_id
|
||||
.ralph/.response_analysis
|
||||
.ralph/.circuit_breaker_state
|
||||
.ralph/.circuit_breaker_history
|
||||
|
||||
# Ralph logs and generated docs
|
||||
.ralph/logs/*
|
||||
!.ralph/logs/.gitkeep
|
||||
.ralph/docs/generated/*
|
||||
!.ralph/docs/generated/.gitkeep
|
||||
|
||||
# General logs
|
||||
*.log
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Temporary files
|
||||
*.tmp
|
||||
.temp/
|
||||
|
||||
# Node modules (if using Node.js projects)
|
||||
node_modules/
|
||||
|
||||
# Python cache (if using Python projects)
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Rust build (if using Rust projects)
|
||||
target/
|
||||
|
||||
# IDE files
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# Ralph backup directories (created by migration)
|
||||
.ralph_backup_*
|
||||
158
.ralph/AGENT.md
Normal file
158
.ralph/AGENT.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Agent Build Instructions
|
||||
|
||||
## Project Setup
|
||||
```bash
|
||||
# Install dependencies (example for Node.js project)
|
||||
npm install
|
||||
|
||||
# Or for Python project
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Or for Rust project
|
||||
cargo build
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
```bash
|
||||
# Node.js
|
||||
npm test
|
||||
|
||||
# Python
|
||||
pytest
|
||||
|
||||
# Rust
|
||||
cargo test
|
||||
```
|
||||
|
||||
## Build Commands
|
||||
```bash
|
||||
# Production build
|
||||
npm run build
|
||||
# or
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
## Development Server
|
||||
```bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
# or
|
||||
cargo run
|
||||
```
|
||||
|
||||
## Key Learnings
|
||||
- Update this section when you learn new build optimizations
|
||||
- Document any gotchas or special setup requirements
|
||||
- Keep track of the fastest test/build cycle
|
||||
|
||||
## Feature Development Quality Standards
|
||||
|
||||
**CRITICAL**: All new features MUST meet the following mandatory requirements before being considered complete.
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- **Minimum Coverage**: 85% code coverage ratio required for all new code
|
||||
- **Test Pass Rate**: 100% - all tests must pass, no exceptions
|
||||
- **Test Types Required**:
|
||||
- Unit tests for all business logic and services
|
||||
- Integration tests for API endpoints or main functionality
|
||||
- End-to-end tests for critical user workflows
|
||||
- **Coverage Validation**: Run coverage reports before marking features complete:
|
||||
```bash
|
||||
# Examples by language/framework
|
||||
npm run test:coverage
|
||||
pytest --cov=src tests/ --cov-report=term-missing
|
||||
cargo tarpaulin --out Html
|
||||
```
|
||||
- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
|
||||
- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
|
||||
|
||||
### Git Workflow Requirements
|
||||
|
||||
Before moving to the next feature, ALL changes must be:
|
||||
|
||||
1. **Committed with Clear Messages**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat(module): descriptive message following conventional commits"
|
||||
```
|
||||
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
|
||||
- Include scope when applicable: `feat(api):`, `fix(ui):`, `test(auth):`
|
||||
- Write descriptive messages that explain WHAT changed and WHY
|
||||
|
||||
2. **Pushed to Remote Repository**:
|
||||
```bash
|
||||
git push origin <branch-name>
|
||||
```
|
||||
- Never leave completed features uncommitted
|
||||
- Push regularly to maintain backup and enable collaboration
|
||||
- Ensure CI/CD pipelines pass before considering feature complete
|
||||
|
||||
3. **Branch Hygiene**:
|
||||
- Work on feature branches, never directly on `main`
|
||||
- Branch naming convention: `feature/<feature-name>`, `fix/<issue-name>`, `docs/<doc-update>`
|
||||
- Create pull requests for all significant changes
|
||||
|
||||
4. **Ralph Integration**:
|
||||
- Update .ralph/fix_plan.md with new tasks before starting work
|
||||
- Mark items complete in .ralph/fix_plan.md upon completion
|
||||
- Update .ralph/PROMPT.md if development patterns change
|
||||
- Test features work within Ralph's autonomous loop
|
||||
|
||||
### Documentation Requirements
|
||||
|
||||
**ALL implementation documentation MUST remain synchronized with the codebase**:
|
||||
|
||||
1. **Code Documentation**:
|
||||
- Language-appropriate documentation (JSDoc, docstrings, etc.)
|
||||
- Update inline comments when implementation changes
|
||||
- Remove outdated comments immediately
|
||||
|
||||
2. **Implementation Documentation**:
|
||||
- Update relevant sections in this AGENT.md file
|
||||
- Keep build and test commands current
|
||||
- Update configuration examples when defaults change
|
||||
- Document breaking changes prominently
|
||||
|
||||
3. **README Updates**:
|
||||
- Keep feature lists current
|
||||
- Update setup instructions when dependencies change
|
||||
- Maintain accurate command examples
|
||||
- Update version compatibility information
|
||||
|
||||
4. **AGENT.md Maintenance**:
|
||||
- Add new build patterns to relevant sections
|
||||
- Update "Key Learnings" with new insights
|
||||
- Keep command examples accurate and tested
|
||||
- Document new testing patterns or quality gates
|
||||
|
||||
### Feature Completion Checklist
|
||||
|
||||
Before marking ANY feature as complete, verify:
|
||||
|
||||
- [ ] All tests pass with appropriate framework command
|
||||
- [ ] Code coverage meets 85% minimum threshold
|
||||
- [ ] Coverage report reviewed for meaningful test quality
|
||||
- [ ] Code formatted according to project standards
|
||||
- [ ] Type checking passes (if applicable)
|
||||
- [ ] All changes committed with conventional commit messages
|
||||
- [ ] All commits pushed to remote repository
|
||||
- [ ] .ralph/fix_plan.md task marked as complete
|
||||
- [ ] Implementation documentation updated
|
||||
- [ ] Inline code comments updated or added
|
||||
- [ ] .ralph/AGENT.md updated (if new patterns introduced)
|
||||
- [ ] Breaking changes documented
|
||||
- [ ] Features tested within Ralph loop (if applicable)
|
||||
- [ ] CI/CD pipeline passes
|
||||
|
||||
### Rationale
|
||||
|
||||
These standards ensure:
|
||||
- **Quality**: High test coverage and pass rates prevent regressions
|
||||
- **Traceability**: Git commits and .ralph/fix_plan.md provide clear history of changes
|
||||
- **Maintainability**: Current documentation reduces onboarding time and prevents knowledge loss
|
||||
- **Collaboration**: Pushed changes enable team visibility and code review
|
||||
- **Reliability**: Consistent quality gates maintain production stability
|
||||
- **Automation**: Ralph integration ensures continuous development practices
|
||||
|
||||
**Enforcement**: AI agents should automatically apply these standards to all feature development tasks without requiring explicit instruction for each task.
|
||||
296
.ralph/PROMPT.md
Normal file
296
.ralph/PROMPT.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Ralph Development Instructions
|
||||
|
||||
## Context
|
||||
You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.
|
||||
|
||||
## Current Objectives
|
||||
1. Study .ralph/specs/* to learn about the project specifications
|
||||
2. Review .ralph/fix_plan.md for current priorities
|
||||
3. Implement the highest priority item using best practices
|
||||
4. Use parallel subagents for complex tasks (max 100 concurrent)
|
||||
5. Run tests after each implementation
|
||||
6. Update documentation and fix_plan.md
|
||||
|
||||
## Key Principles
|
||||
- ONE task per loop - focus on the most important thing
|
||||
- Search the codebase before assuming something isn't implemented
|
||||
- Use subagents for expensive operations (file searching, analysis)
|
||||
- Write comprehensive tests with clear documentation
|
||||
- Update .ralph/fix_plan.md with your learnings
|
||||
- Commit working changes with descriptive messages
|
||||
|
||||
## Protected Files (DO NOT MODIFY)
|
||||
The following files and directories are part of Ralph's infrastructure.
|
||||
NEVER delete, move, rename, or overwrite these under any circumstances:
|
||||
- .ralph/ (entire directory and all contents)
|
||||
- .ralphrc (project configuration)
|
||||
|
||||
When performing cleanup, refactoring, or restructuring tasks:
|
||||
- These files are NOT part of your project code
|
||||
- They are Ralph's internal control files that keep the development loop running
|
||||
- Deleting them will break Ralph and halt all autonomous development
|
||||
|
||||
## 🧪 Testing Guidelines (CRITICAL)
|
||||
- LIMIT testing to ~20% of your total effort per loop
|
||||
- PRIORITIZE: Implementation > Documentation > Tests
|
||||
- Only write tests for NEW functionality you implement
|
||||
- Do NOT refactor existing tests unless broken
|
||||
- Do NOT add "additional test coverage" as busy work
|
||||
- Focus on CORE functionality first, comprehensive testing later
|
||||
|
||||
## Execution Guidelines
|
||||
- Before making changes: search codebase using subagents
|
||||
- After implementation: run ESSENTIAL tests for the modified code only
|
||||
- If tests fail: fix them as part of your current work
|
||||
- Keep .ralph/AGENT.md updated with build/run instructions
|
||||
- Document the WHY behind tests and implementations
|
||||
- No placeholder implementations - build it properly
|
||||
|
||||
## 🎯 Status Reporting (CRITICAL - Ralph needs this!)
|
||||
|
||||
**IMPORTANT**: At the end of your response, ALWAYS include this status block:
|
||||
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
|
||||
TASKS_COMPLETED_THIS_LOOP: <number>
|
||||
FILES_MODIFIED: <number>
|
||||
TESTS_STATUS: PASSING | FAILING | NOT_RUN
|
||||
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
|
||||
EXIT_SIGNAL: false | true
|
||||
RECOMMENDATION: <one line summary of what to do next>
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
### When to set EXIT_SIGNAL: true
|
||||
|
||||
Set EXIT_SIGNAL to **true** when ALL of these conditions are met:
|
||||
1. ✅ All items in fix_plan.md are marked [x]
|
||||
2. ✅ All tests are passing (or no tests exist for valid reasons)
|
||||
3. ✅ No errors or warnings in the last execution
|
||||
4. ✅ All requirements from specs/ are implemented
|
||||
5. ✅ You have nothing meaningful left to implement
|
||||
|
||||
### Examples of proper status reporting:
|
||||
|
||||
**Example 1: Work in progress**
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: IN_PROGRESS
|
||||
TASKS_COMPLETED_THIS_LOOP: 2
|
||||
FILES_MODIFIED: 5
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: IMPLEMENTATION
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: Continue with next priority task from fix_plan.md
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Example 2: Project complete**
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: COMPLETE
|
||||
TASKS_COMPLETED_THIS_LOOP: 1
|
||||
FILES_MODIFIED: 1
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: DOCUMENTATION
|
||||
EXIT_SIGNAL: true
|
||||
RECOMMENDATION: All requirements met, project ready for review
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Example 3: Stuck/blocked**
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: BLOCKED
|
||||
TASKS_COMPLETED_THIS_LOOP: 0
|
||||
FILES_MODIFIED: 0
|
||||
TESTS_STATUS: FAILING
|
||||
WORK_TYPE: DEBUGGING
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: Need human help - same error for 3 loops
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
### What NOT to do:
|
||||
- ❌ Do NOT continue with busy work when EXIT_SIGNAL should be true
|
||||
- ❌ Do NOT run tests repeatedly without implementing new features
|
||||
- ❌ Do NOT refactor code that is already working fine
|
||||
- ❌ Do NOT add features not in the specifications
|
||||
- ❌ Do NOT forget to include the status block (Ralph depends on it!)
|
||||
|
||||
## 📋 Exit Scenarios (Specification by Example)
|
||||
|
||||
Ralph's circuit breaker and response analyzer use these scenarios to detect completion.
|
||||
Each scenario shows the exact conditions and expected behavior.
|
||||
|
||||
### Scenario 1: Successful Project Completion
|
||||
**Given**:
|
||||
- All items in .ralph/fix_plan.md are marked [x]
|
||||
- Last test run shows all tests passing
|
||||
- No errors in recent logs/
|
||||
- All requirements from .ralph/specs/ are implemented
|
||||
|
||||
**When**: You evaluate project status at end of loop
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: COMPLETE
|
||||
TASKS_COMPLETED_THIS_LOOP: 1
|
||||
FILES_MODIFIED: 1
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: DOCUMENTATION
|
||||
EXIT_SIGNAL: true
|
||||
RECOMMENDATION: All requirements met, project ready for review
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Detects EXIT_SIGNAL=true, gracefully exits loop with success message
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Test-Only Loop Detected
|
||||
**Given**:
|
||||
- Last 3 loops only executed tests (npm test, bats, pytest, etc.)
|
||||
- No new files were created
|
||||
- No existing files were modified
|
||||
- No implementation work was performed
|
||||
|
||||
**When**: You start a new loop iteration
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: IN_PROGRESS
|
||||
TASKS_COMPLETED_THIS_LOOP: 0
|
||||
FILES_MODIFIED: 0
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: TESTING
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: All tests passing, no implementation needed
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Increments test_only_loops counter, exits after 3 consecutive test-only loops
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Stuck on Recurring Error
|
||||
**Given**:
|
||||
- Same error appears in last 5 consecutive loops
|
||||
- No progress on fixing the error
|
||||
- Error message is identical or very similar
|
||||
|
||||
**When**: You encounter the same error again
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: BLOCKED
|
||||
TASKS_COMPLETED_THIS_LOOP: 0
|
||||
FILES_MODIFIED: 2
|
||||
TESTS_STATUS: FAILING
|
||||
WORK_TYPE: DEBUGGING
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: Stuck on [error description] - human intervention needed
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Circuit breaker detects repeated errors, opens circuit after 5 loops
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: No Work Remaining
|
||||
**Given**:
|
||||
- All tasks in fix_plan.md are complete
|
||||
- You analyze .ralph/specs/ and find nothing new to implement
|
||||
- Code quality is acceptable
|
||||
- Tests are passing
|
||||
|
||||
**When**: You search for work to do and find none
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: COMPLETE
|
||||
TASKS_COMPLETED_THIS_LOOP: 0
|
||||
FILES_MODIFIED: 0
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: DOCUMENTATION
|
||||
EXIT_SIGNAL: true
|
||||
RECOMMENDATION: No remaining work, all .ralph/specs implemented
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Detects completion signal, exits loop immediately
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Making Progress
|
||||
**Given**:
|
||||
- Tasks remain in .ralph/fix_plan.md
|
||||
- Implementation is underway
|
||||
- Files are being modified
|
||||
- Tests are passing or being fixed
|
||||
|
||||
**When**: You complete a task successfully
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: IN_PROGRESS
|
||||
TASKS_COMPLETED_THIS_LOOP: 3
|
||||
FILES_MODIFIED: 7
|
||||
TESTS_STATUS: PASSING
|
||||
WORK_TYPE: IMPLEMENTATION
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: Continue with next task from .ralph/fix_plan.md
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Continues loop, circuit breaker stays CLOSED (normal operation)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 6: Blocked on External Dependency
|
||||
**Given**:
|
||||
- Task requires external API, library, or human decision
|
||||
- Cannot proceed without missing information
|
||||
- Have tried reasonable workarounds
|
||||
|
||||
**When**: You identify the blocker
|
||||
|
||||
**Then**: You must output:
|
||||
```
|
||||
---RALPH_STATUS---
|
||||
STATUS: BLOCKED
|
||||
TASKS_COMPLETED_THIS_LOOP: 0
|
||||
FILES_MODIFIED: 0
|
||||
TESTS_STATUS: NOT_RUN
|
||||
WORK_TYPE: IMPLEMENTATION
|
||||
EXIT_SIGNAL: false
|
||||
RECOMMENDATION: Blocked on [specific dependency] - need [what's needed]
|
||||
---END_RALPH_STATUS---
|
||||
```
|
||||
|
||||
**Ralph's Action**: Logs blocker, may exit after multiple blocked loops
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
- .ralph/: Ralph-specific configuration and documentation
|
||||
- specs/: Project specifications and requirements
|
||||
- fix_plan.md: Prioritized TODO list
|
||||
- AGENT.md: Project build and run instructions
|
||||
- PROMPT.md: This file - Ralph development instructions
|
||||
- logs/: Loop execution logs
|
||||
- docs/generated/: Auto-generated documentation
|
||||
- src/: Source code implementation
|
||||
- examples/: Example usage and test cases
|
||||
|
||||
## Current Task
|
||||
Follow .ralph/fix_plan.md and choose the most important item to implement next.
|
||||
Use your judgment to prioritize what will have the biggest impact on project progress.
|
||||
|
||||
Remember: Quality over speed. Build it right the first time. Know when you're done.
|
||||
27
.ralph/fix_plan.md
Normal file
27
.ralph/fix_plan.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Ralph Fix Plan
|
||||
|
||||
## High Priority
|
||||
- [ ] Set up basic project structure and build system
|
||||
- [ ] Define core data structures and types
|
||||
- [ ] Implement basic input/output handling
|
||||
- [ ] Create test framework and initial tests
|
||||
|
||||
## Medium Priority
|
||||
- [ ] Add error handling and validation
|
||||
- [ ] Implement core business logic
|
||||
- [ ] Add configuration management
|
||||
- [ ] Create user documentation
|
||||
|
||||
## Low Priority
|
||||
- [ ] Performance optimization
|
||||
- [ ] Extended feature set
|
||||
- [ ] Integration with external services
|
||||
- [ ] Advanced error recovery
|
||||
|
||||
## Completed
|
||||
- [x] Project initialization
|
||||
|
||||
## Notes
|
||||
- Focus on MVP functionality first
|
||||
- Ensure each feature is properly tested
|
||||
- Update this file after each major milestone
|
||||
38
.ralphrc
Normal file
38
.ralphrc
Normal file
@@ -0,0 +1,38 @@
|
||||
# .ralphrc - Ralph project configuration
|
||||
# Generated by: ralph-setup
|
||||
# Documentation: https://github.com/frankbria/ralph-claude-code
|
||||
|
||||
# Project identification
|
||||
PROJECT_NAME="abe"
|
||||
PROJECT_TYPE="generic"
|
||||
|
||||
# Claude Code CLI command
|
||||
# If "claude" is not in your PATH, set to your installation:
|
||||
# "npx @anthropic-ai/claude-code" (uses npx, no global install needed)
|
||||
# "/path/to/claude" (custom path)
|
||||
CLAUDE_CODE_CMD="claude"
|
||||
|
||||
# Loop settings
|
||||
MAX_CALLS_PER_HOUR=100
|
||||
CLAUDE_TIMEOUT_MINUTES=15
|
||||
CLAUDE_OUTPUT_FORMAT="json"
|
||||
|
||||
# Tool permissions
|
||||
# Comma-separated list of allowed tools
|
||||
# Safe git subcommands only - broad Bash(git *) allows destructive commands like git clean/git rm (Issue #149)
|
||||
ALLOWED_TOOLS="Write,Read,Edit,Bash(git add *),Bash(git commit *),Bash(git diff *),Bash(git log *),Bash(git status),Bash(git status *),Bash(git push *),Bash(git pull *),Bash(git fetch *),Bash(git checkout *),Bash(git branch *),Bash(git stash *),Bash(git merge *),Bash(git tag *),Bash(npm *),Bash(pytest)"
|
||||
|
||||
# Session management
|
||||
SESSION_CONTINUITY=true
|
||||
SESSION_EXPIRY_HOURS=24
|
||||
|
||||
# Task sources (for ralph enable --sync)
|
||||
# Options: local, beads, github (comma-separated for multiple)
|
||||
TASK_SOURCES="local"
|
||||
GITHUB_TASK_LABEL="ralph-task"
|
||||
BEADS_FILTER="status:open"
|
||||
|
||||
# Circuit breaker thresholds
|
||||
CB_NO_PROGRESS_THRESHOLD=3
|
||||
CB_SAME_ERROR_THRESHOLD=5
|
||||
CB_OUTPUT_DECLINE_THRESHOLD=70
|
||||
Reference in New Issue
Block a user