Add ralph-claude-code integration and agent documentation

.gitignore

@@ -173,3 +173,20 @@ test_suite_analysis/metadata.json
 
 .devpod/
 .devpod-internal/
+
+# Claude Code local settings (personal, not shared)
+.claude/settings.local.json
+
+# Ralph autonomous agent state files
+.call_count
+.circuit_breaker_history
+.circuit_breaker_state
+.exit_signals
+.last_reset
+.ralph_session
+.ralph_session_history
+.response_analysis
+.claude_session_id
+progress.json
+status.json
+logs/

@AGENT.md

@@ -0,0 +1,175 @@
+# Agent Build Instructions
+
+## Project Setup
+
+This project uses **pixi** for environment and dependency management. All commands should be run from the project root.
+
+```bash
+# Install dependencies (pixi handles everything)
+pixi install
+
+# Activate the environment (optional, pixi run handles this automatically)
+pixi shell
+```
+
+## Running Tests
+```bash
+# Run tests
+pixi run test
+
+# Run tests with coverage
+pixi run coverage
+pixi run coverage-report
+```
+
+## Linting and Formatting
+```bash
+# Format code with ruff
+pixi run format
+
+# Run all linters (ruff, ty, pylint)
+pixi run lint
+
+# Run both format and lint
+pixi run style
+
+# Run full CI checks
+pixi run ci
+```
+
+## Available Pixi Tasks
+```bash
+# View all available tasks
+pixi task list
+
+# Common tasks:
+pixi run test           # Run pytest
+pixi run coverage       # Run tests with coverage
+pixi run format         # Format code with ruff
+pixi run lint           # Run all linters
+pixi run style          # Format + lint
+pixi run ci             # Full CI pipeline
+pixi run fix            # Auto-fix common issues
+```
+
+## GitHub CLI
+```bash
+# GitHub CLI is available via pixi
+pixi run gh <command>
+```
+
+## 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
+  # Using pixi tasks
+  pixi run coverage         # Runs pytest with coverage
+  pixi run coverage-report  # Shows coverage report
+  ```
+- **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 @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.

@fix_plan.md

@@ -0,0 +1,19 @@
+# Ralph Fix Plan
+
+## High Priority
+<!-- Add high priority tasks here when working on a specific project -->
+
+## Medium Priority
+<!-- Add medium priority tasks here -->
+
+## Low Priority
+<!-- Add low priority tasks here -->
+
+## Completed
+- [x] Initial Ralph setup
+- [x] Add Ralph state files to .gitignore to prevent dirty repo state
+
+## Notes
+- This is a template project - update this file with project-specific tasks after cloning
+- For template improvements, add tasks here as needed
+- Use `pixi run ci` to verify changes pass all checks