Skip to content

Commit 24e50b0

Browse files
blooopblooop
authored
Merge branch 'main' into claude/fix-pixi-tasks-3eqAA
2 parents 7ab1ba8 + 77e3531 commit 24e50b0

File tree

6 files changed

+800
-10
lines changed

6 files changed

+800
-10
lines changed

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,3 +173,20 @@ test_suite_analysis/metadata.json
173173

174174
.devpod/
175175
.devpod-internal/
176+
177+
# Claude Code local settings (personal, not shared)
178+
.claude/settings.local.json
179+
180+
# Ralph autonomous agent state files
181+
.call_count
182+
.circuit_breaker_history
183+
.circuit_breaker_state
184+
.exit_signals
185+
.last_reset
186+
.ralph_session
187+
.ralph_session_history
188+
.response_analysis
189+
.claude_session_id
190+
progress.json
191+
status.json
192+
logs/

‎@AGENT.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Agent Build Instructions
2+
3+
## Project Setup
4+
5+
This project uses **pixi** for environment and dependency management. All commands should be run from the project root.
6+
7+
```bash
8+
# Install dependencies (pixi handles everything)
9+
pixi install
10+
11+
# Activate the environment (optional, pixi run handles this automatically)
12+
pixi shell
13+
```
14+
15+
## Running Tests
16+
```bash
17+
# Run tests
18+
pixi run test
19+
20+
# Run tests with coverage
21+
pixi run coverage
22+
pixi run coverage-report
23+
```
24+
25+
## Linting and Formatting
26+
```bash
27+
# Format code with ruff
28+
pixi run format
29+
30+
# Run all linters (ruff, ty, pylint)
31+
pixi run lint
32+
33+
# Run both format and lint
34+
pixi run style
35+
36+
# Run full CI checks
37+
pixi run ci
38+
```
39+
40+
## Available Pixi Tasks
41+
```bash
42+
# View all available tasks
43+
pixi task list
44+
45+
# Common tasks:
46+
pixi run test # Run pytest
47+
pixi run coverage # Run tests with coverage
48+
pixi run format # Format code with ruff
49+
pixi run lint # Run all linters
50+
pixi run style # Format + lint
51+
pixi run ci # Full CI pipeline
52+
pixi run fix # Auto-fix common issues
53+
```
54+
55+
## GitHub CLI
56+
```bash
57+
# GitHub CLI is available via pixi
58+
pixi run gh <command>
59+
```
60+
61+
## Key Learnings
62+
- Update this section when you learn new build optimizations
63+
- Document any gotchas or special setup requirements
64+
- Keep track of the fastest test/build cycle
65+
66+
## Feature Development Quality Standards
67+
68+
**CRITICAL**: All new features MUST meet the following mandatory requirements before being considered complete.
69+
70+
### Testing Requirements
71+
72+
- **Minimum Coverage**: 85% code coverage ratio required for all new code
73+
- **Test Pass Rate**: 100% - all tests must pass, no exceptions
74+
- **Test Types Required**:
75+
- Unit tests for all business logic and services
76+
- Integration tests for API endpoints or main functionality
77+
- End-to-end tests for critical user workflows
78+
- **Coverage Validation**: Run coverage reports before marking features complete:
79+
```bash
80+
# Using pixi tasks
81+
pixi run coverage # Runs pytest with coverage
82+
pixi run coverage-report # Shows coverage report
83+
```
84+
- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
85+
- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
86+
87+
### Git Workflow Requirements
88+
89+
Before moving to the next feature, ALL changes must be:
90+
91+
1. **Committed with Clear Messages**:
92+
```bash
93+
git add .
94+
git commit -m "feat(module): descriptive message following conventional commits"
95+
```
96+
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
97+
- Include scope when applicable: `feat(api):`, `fix(ui):`, `test(auth):`
98+
- Write descriptive messages that explain WHAT changed and WHY
99+
100+
2. **Pushed to Remote Repository**:
101+
```bash
102+
git push origin <branch-name>
103+
```
104+
- Never leave completed features uncommitted
105+
- Push regularly to maintain backup and enable collaboration
106+
- Ensure CI/CD pipelines pass before considering feature complete
107+
108+
3. **Branch Hygiene**:
109+
- Work on feature branches, never directly on `main`
110+
- Branch naming convention: `feature/<feature-name>`, `fix/<issue-name>`, `docs/<doc-update>`
111+
- Create pull requests for all significant changes
112+
113+
4. **Ralph Integration**:
114+
- Update @fix_plan.md with new tasks before starting work
115+
- Mark items complete in @fix_plan.md upon completion
116+
- Update PROMPT.md if development patterns change
117+
- Test features work within Ralph's autonomous loop
118+
119+
### Documentation Requirements
120+
121+
**ALL implementation documentation MUST remain synchronized with the codebase**:
122+
123+
1. **Code Documentation**:
124+
- Language-appropriate documentation (JSDoc, docstrings, etc.)
125+
- Update inline comments when implementation changes
126+
- Remove outdated comments immediately
127+
128+
2. **Implementation Documentation**:
129+
- Update relevant sections in this AGENT.md file
130+
- Keep build and test commands current
131+
- Update configuration examples when defaults change
132+
- Document breaking changes prominently
133+
134+
3. **README Updates**:
135+
- Keep feature lists current
136+
- Update setup instructions when dependencies change
137+
- Maintain accurate command examples
138+
- Update version compatibility information
139+
140+
4. **AGENT.md Maintenance**:
141+
- Add new build patterns to relevant sections
142+
- Update "Key Learnings" with new insights
143+
- Keep command examples accurate and tested
144+
- Document new testing patterns or quality gates
145+
146+
### Feature Completion Checklist
147+
148+
Before marking ANY feature as complete, verify:
149+
150+
- [ ] All tests pass with appropriate framework command
151+
- [ ] Code coverage meets 85% minimum threshold
152+
- [ ] Coverage report reviewed for meaningful test quality
153+
- [ ] Code formatted according to project standards
154+
- [ ] Type checking passes (if applicable)
155+
- [ ] All changes committed with conventional commit messages
156+
- [ ] All commits pushed to remote repository
157+
- [ ] @fix_plan.md task marked as complete
158+
- [ ] Implementation documentation updated
159+
- [ ] Inline code comments updated or added
160+
- [ ] AGENT.md updated (if new patterns introduced)
161+
- [ ] Breaking changes documented
162+
- [ ] Features tested within Ralph loop (if applicable)
163+
- [ ] CI/CD pipeline passes
164+
165+
### Rationale
166+
167+
These standards ensure:
168+
- **Quality**: High test coverage and pass rates prevent regressions
169+
- **Traceability**: Git commits and @fix_plan.md provide clear history of changes
170+
- **Maintainability**: Current documentation reduces onboarding time and prevents knowledge loss
171+
- **Collaboration**: Pushed changes enable team visibility and code review
172+
- **Reliability**: Consistent quality gates maintain production stability
173+
- **Automation**: Ralph integration ensures continuous development practices
174+
175+
**Enforcement**: AI agents should automatically apply these standards to all feature development tasks without requiring explicit instruction for each task.

‎@fix_plan.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Ralph Fix Plan
2+
3+
## High Priority
4+
<!-- Add high priority tasks here when working on a specific project -->
5+
6+
## Medium Priority
7+
<!-- Add medium priority tasks here -->
8+
9+
## Low Priority
10+
<!-- Add low priority tasks here -->
11+
12+
## Completed
13+
- [x] Initial Ralph setup
14+
- [x] Add Ralph state files to .gitignore to prevent dirty repo state
15+
16+
## Notes
17+
- This is a template project - update this file with project-specific tasks after cloning
18+
- For template improvements, add tasks here as needed
19+
- Use `pixi run ci` to verify changes pass all checks

0 commit comments

Comments
 (0)