diff --git a/CLAUDE.md b/CLAUDE.md index 00f7386..7b72417 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -133,4 +133,122 @@ Ralph integrates with: - `MAX_CONSECUTIVE_TEST_LOOPS=3` - Exit if too many test-only iterations - `MAX_CONSECUTIVE_DONE_SIGNALS=2` - Exit on repeated completion signals - `TEST_PERCENTAGE_THRESHOLD=30%` - Flag if testing dominates recent loops -- Completion detection via @fix_plan.md checklist items \ No newline at end of file +- Completion detection via @fix_plan.md checklist items + +## 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 bash script functions (if applicable) + - Integration tests for Ralph loop behavior + - End-to-end tests for full development cycles +- **Coverage Validation**: Run coverage reports before marking features complete: + ```bash + # For projects with test suites + ./test.sh --coverage + + # Manual testing of Ralph loop + ralph --monitor --calls 5 + ``` +- **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(loop):`, `fix(monitor):`, `test(setup):` + - Write descriptive messages that explain WHAT changed and WHY + +2. **Pushed to Remote Repository**: + ```bash + git push origin + ``` + - 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/`, `fix/`, `docs/` + - Create pull requests for all significant changes + +4. **Ralph Integration**: + - Update @fix_plan.md with new tasks before starting work + - Mark items complete in @fix_plan.md upon completion + - Update PROMPT.md if Ralph's behavior needs modification + - Test Ralph loop with new features before completion + +### Documentation Requirements + +**ALL implementation documentation MUST remain synchronized with the codebase**: + +1. **Script Documentation**: + - Bash: Comments for all functions and complex logic + - Update inline comments when implementation changes + - Remove outdated comments immediately + +2. **Implementation Documentation**: + - Update relevant sections in this CLAUDE.md file + - Keep template files in `templates/` current + - Update configuration examples when defaults change + - Document breaking changes prominently + +3. **README Updates**: + - Keep feature lists current + - Update setup instructions when commands change + - Maintain accurate command examples + - Update version compatibility information + +4. **Template Maintenance**: + - Update template files when new patterns are introduced + - Keep PROMPT.md template current with best practices + - Update @AGENT.md template with new build patterns + - Document new Ralph configuration options + +5. **CLAUDE.md Maintenance**: + - Add new commands to "Key Commands" section + - Update "Exit Conditions and Thresholds" when logic changes + - Keep installation instructions accurate and tested + - Document new Ralph loop behaviors or quality gates + +### Feature Completion Checklist + +Before marking ANY feature as complete, verify: + +- [ ] All tests pass (if applicable) +- [ ] Code coverage meets 85% minimum threshold (if applicable) +- [ ] Script functionality manually tested +- [ ] All changes committed with conventional commit messages +- [ ] All commits pushed to remote repository +- [ ] @fix_plan.md task marked as complete +- [ ] Implementation documentation updated +- [ ] Inline code comments updated or added +- [ ] CLAUDE.md updated (if new patterns introduced) +- [ ] Template files updated (if applicable) +- [ ] Breaking changes documented +- [ ] Ralph loop tested with new features +- [ ] Installation process verified (if applicable) + +### Rationale + +These standards ensure: +- **Quality**: Thorough testing prevents regressions in Ralph's autonomous behavior +- **Traceability**: Git commits and @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 Ralph loop 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. diff --git a/templates/AGENT.md b/templates/AGENT.md index b3b3c62..ab4e07e 100644 --- a/templates/AGENT.md +++ b/templates/AGENT.md @@ -44,3 +44,115 @@ cargo run - 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 + ``` + - 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/`, `fix/`, `docs/` + - Create pull requests for all significant changes + +4. **Ralph Integration**: + - Update @fix_plan.md with new tasks before starting work + - Mark items complete in @fix_plan.md upon completion + - Update 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 +- [ ] @fix_plan.md task marked as complete +- [ ] Implementation documentation updated +- [ ] Inline code comments updated or added +- [ ] 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 @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.