Skip to content

Commit 569a3de

Browse files
phernandezclaude
phernandez
and
claude
committed
feat: add comprehensive custom Claude Code slash commands
Adds custom slash commands for streamlined development workflow: Release Management (/project:release:*): - beta - Create beta releases with automated quality checks - release - Create stable releases with comprehensive validation - release-check - Pre-flight validation without making changes - changelog - Generate changelog entries from commits Development (/project:*): - test-coverage - Run tests with detailed coverage analysis - lint-fix - Comprehensive code quality fixes with auto-repair - check-health - Project health assessment and metrics Commands are organized in .claude/commands/ directory following Claude Code conventions and provide structured automation for common development tasks. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent ac08a8d commit 569a3de

File tree

8 files changed

+963
-0
lines changed

8 files changed

+963
-0
lines changed

‎.claude/commands/check-health.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# /project:check-health - Project Health Assessment
2+
3+
Comprehensive health check of the Basic Memory project including code quality, test coverage, dependencies, and documentation.
4+
5+
## Usage
6+
```
7+
/project:check-health
8+
```
9+
10+
## Implementation
11+
12+
You are an expert DevOps engineer for the Basic Memory project. When the user runs `/project:check-health`, execute the following comprehensive assessment:
13+
14+
### Step 1: Git Repository Health
15+
1. **Repository Status**
16+
```bash
17+
git status
18+
git log --oneline -5
19+
git branch -vv
20+
```
21+
- Check working directory status
22+
- Verify branch alignment with remote
23+
- Check recent commit activity
24+
25+
2. **Branch Analysis**
26+
- Verify on main branch
27+
- Check if ahead/behind remote
28+
- Identify any untracked files
29+
30+
### Step 2: Code Quality Assessment
31+
1. **Linting and Formatting**
32+
```bash
33+
uv run ruff check .
34+
uv run pyright
35+
```
36+
- Count linting issues by severity
37+
- Check type annotation coverage
38+
- Verify code formatting compliance
39+
40+
2. **Test Suite Health**
41+
```bash
42+
uv run pytest --collect-only -q
43+
uv run pytest --co -q | wc -l
44+
```
45+
- Count total tests
46+
- Check for test discovery issues
47+
- Verify test structure integrity
48+
49+
### Step 3: Dependency Analysis
50+
1. **Dependency Health**
51+
```bash
52+
uv tree
53+
uv lock --dry-run
54+
```
55+
- Check for dependency conflicts
56+
- Identify outdated dependencies
57+
- Verify lock file consistency
58+
59+
2. **Security Scan**
60+
```bash
61+
uv run pip-audit --desc
62+
```
63+
- Scan for known vulnerabilities
64+
- Check dependency licenses
65+
- Identify security advisories
66+
67+
### Step 4: Performance Metrics
68+
1. **Test Performance**
69+
```bash
70+
uv run pytest --durations=10
71+
```
72+
- Identify slowest tests
73+
- Check overall test execution time
74+
- Monitor test suite growth
75+
76+
2. **Build Performance**
77+
```bash
78+
time uv run python -c "import basic_memory"
79+
```
80+
- Check import time
81+
- Validate package installation
82+
- Monitor startup performance
83+
84+
### Step 5: Documentation Health
85+
1. **Documentation Coverage**
86+
- Check README.md currency
87+
- Verify CLI documentation
88+
- Validate MCP tool documentation
89+
- Check changelog completeness
90+
91+
2. **API Documentation**
92+
- Verify docstring coverage
93+
- Check type annotation completeness
94+
- Validate example code
95+
96+
### Step 6: Project Metrics
97+
1. **Code Statistics**
98+
```bash
99+
find src -name "*.py" | xargs wc -l
100+
find tests -name "*.py" | xargs wc -l
101+
```
102+
- Lines of code trends
103+
- Test-to-code ratio
104+
- File organization metrics
105+
106+
## Health Report Format
107+
108+
Generate comprehensive health dashboard:
109+
110+
```
111+
🏥 Basic Memory Project Health Report
112+
113+
📊 OVERALL HEALTH: 🟢 EXCELLENT (92/100)
114+
115+
🗂️ GIT REPOSITORY
116+
✅ Clean working directory
117+
✅ Up to date with origin/main
118+
✅ Recent commit activity (5 commits this week)
119+
120+
🔍 CODE QUALITY
121+
✅ Linting: 0 errors, 2 warnings
122+
✅ Type checking: 100% coverage
123+
✅ Formatting: Compliant
124+
⚠️ Complex functions: 3 need refactoring
125+
126+
🧪 TEST SUITE
127+
✅ Total tests: 744
128+
✅ Test discovery: All tests found
129+
✅ Coverage: 98.2%
130+
⚡ Performance: 45.2s (good)
131+
132+
📦 DEPENDENCIES
133+
✅ Dependencies: Up to date
134+
✅ Security: No vulnerabilities
135+
✅ Conflicts: None detected
136+
⚠️ Outdated: 2 minor updates available
137+
138+
📖 DOCUMENTATION
139+
✅ README: Current
140+
✅ API docs: 95% coverage
141+
⚠️ CLI reference: Needs update
142+
✅ Changelog: Complete
143+
144+
📈 METRICS
145+
├── Source code: 15,432 lines
146+
├── Test code: 8,967 lines
147+
├── Test ratio: 58% (excellent)
148+
└── Complexity: Low (maintainable)
149+
150+
🎯 RECOMMENDATIONS:
151+
1. Update CLI documentation
152+
2. Refactor 3 complex functions
153+
3. Update minor dependencies
154+
4. Consider splitting large test files
155+
156+
🏆 PROJECT STATUS: Ready for v0.13.0 release!
157+
```
158+
159+
## Health Scoring
160+
161+
### Excellent (90-100)
162+
- All quality gates pass
163+
- High test coverage (>95%)
164+
- No security issues
165+
- Documentation current
166+
167+
### Good (75-89)
168+
- Minor issues present
169+
- Good test coverage (>90%)
170+
- No critical security issues
171+
- Most documentation current
172+
173+
### Needs Attention (60-74)
174+
- Several quality issues
175+
- Adequate test coverage (>80%)
176+
- Minor security concerns
177+
- Documentation gaps
178+
179+
### Critical (<60)
180+
- Major quality problems
181+
- Low test coverage (<80%)
182+
- Security vulnerabilities
183+
- Significant documentation issues
184+
185+
## Context
186+
- Provides comprehensive project overview
187+
- Identifies potential issues before they become problems
188+
- Tracks project health trends over time
189+
- Helps prioritize maintenance tasks
190+
- Supports release readiness decisions

‎.claude/commands/commands.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Basic Memory Custom Commands
2+
3+
This directory contains custom Claude Code slash commands for the Basic Memory project.
4+
5+
## Available Commands
6+
7+
### Release Management (`/project:release:*`)
8+
- `/project:release:beta` - Create beta releases with automated quality checks
9+
- `/project:release:release` - Create stable releases with comprehensive validation
10+
- `/project:release:release-check` - Pre-flight validation without making changes
11+
- `/project:release:changelog` - Generate changelog entries from commits
12+
13+
### Development (`/project:*`)
14+
- `/project:test-coverage` - Run tests with detailed coverage analysis
15+
- `/project:fix-imports` - Clean up and organize imports
16+
- `/project:lint-fix` - Run comprehensive linting with auto-fix
17+
18+
## Command Structure
19+
20+
Commands are organized by functionality:
21+
```
22+
.claude/commands/
23+
├── release/ # Release management commands
24+
│ ├── beta.md # /project:release:beta
25+
│ ├── release.md # /project:release:release
26+
│ ├── release-check.md # /project:release:release-check
27+
│ └── changelog.md # /project:release:changelog
28+
├── test-coverage.md # /project:test-coverage
29+
└── commands.md # This overview file
30+
```
31+
32+
## Usage
33+
34+
Commands are invoked using the `/project:` prefix:
35+
- `/project:release:beta v0.13.0b4`
36+
- `/project:test-coverage mcp`
37+
- `/project:release:release-check`
38+
39+
## Implementation
40+
41+
Each command is implemented as a Markdown file containing structured prompts that:
42+
1. Validate preconditions
43+
2. Execute steps in the correct order
44+
3. Handle errors gracefully
45+
4. Provide clear status updates
46+
5. Return actionable results
47+
48+
## Tooling Integration
49+
50+
Commands leverage existing project tooling:
51+
- `make check` - Quality checks
52+
- `make test` - Test suite
53+
- `make update-deps` - Dependency updates
54+
- `uv` - Package management
55+
- `git` - Version control
56+
- GitHub Actions - CI/CD pipeline

‎.claude/commands/lint-fix.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# /project:lint-fix - Comprehensive Code Quality Fix
2+
3+
Run comprehensive linting and auto-fix code quality issues across the codebase.
4+
5+
## Usage
6+
```
7+
/project:lint-fix
8+
```
9+
10+
## Implementation
11+
12+
You are an expert code quality engineer for the Basic Memory project. When the user runs `/project:lint-fix`, execute the following steps:
13+
14+
### Step 1: Pre-flight Check
15+
1. **Verify Clean Working Directory**
16+
```bash
17+
git status --porcelain
18+
```
19+
- Check for uncommitted changes
20+
- Warn if working directory is not clean
21+
- Suggest stashing changes if needed
22+
23+
### Step 2: Import Organization
24+
1. **Fix Import Order and Cleanup**
25+
```bash
26+
uv run ruff check --select I --fix .
27+
```
28+
- Sort imports by category (standard, third-party, local)
29+
- Remove unused imports
30+
- Fix import spacing and organization
31+
32+
### Step 3: Code Formatting
33+
1. **Apply Consistent Formatting**
34+
```bash
35+
uv run ruff format .
36+
```
37+
- Format code according to project style
38+
- Fix line length issues (100 chars max)
39+
- Standardize quotes and spacing
40+
41+
### Step 4: Linting with Auto-fix
42+
1. **Fix Linting Issues**
43+
```bash
44+
uv run ruff check --fix .
45+
```
46+
- Auto-fix safe linting issues
47+
- Report any remaining manual fixes needed
48+
- Focus on code quality and best practices
49+
50+
### Step 5: Type Checking
51+
1. **Validate Type Annotations**
52+
```bash
53+
uv run pyright
54+
```
55+
- Check for type errors
56+
- Report any missing type annotations
57+
- Validate type compatibility
58+
59+
### Step 6: Report Generation
60+
Generate comprehensive quality report:
61+
62+
```
63+
🔧 Code Quality Fix Report
64+
65+
✅ FIXES APPLIED:
66+
├── Import organization: 12 files updated
67+
├── Code formatting: 8 files reformatted
68+
├── Auto-fixable lint issues: 23 issues resolved
69+
└── Total files processed: 156
70+
71+
⚠️ MANUAL ATTENTION NEEDED:
72+
├── Type annotations missing in entity_service.py:45
73+
├── Complex function needs refactoring in sync_service.py:123
74+
└── Unused variable in test_utils.py:67
75+
76+
🎯 QUALITY SCORE: 96.2% (excellent)
77+
78+
📁 Run `git diff` to review all changes
79+
```
80+
81+
## Error Handling
82+
83+
### Common Issues
84+
- **Merge Conflicts**: Provide resolution guidance
85+
- **Syntax Errors**: Point to specific files and lines
86+
- **Type Errors**: Suggest specific fixes
87+
- **Import Errors**: Check for missing dependencies
88+
89+
### Recovery Steps
90+
- If auto-fixes introduce issues, provide rollback instructions
91+
- If type checking fails, suggest incremental fixes
92+
- If tests break, provide debugging guidance
93+
94+
## Quality Gates
95+
96+
### Must Pass
97+
- [ ] All auto-fixable lint issues resolved
98+
- [ ] Code formatting consistent
99+
- [ ] No syntax errors
100+
- [ ] Import organization clean
101+
102+
### Should Pass (Warnings)
103+
- [ ] No type checking errors
104+
- [ ] No complex function warnings
105+
- [ ] No unused variables/imports
106+
- [ ] Consistent naming conventions
107+
108+
## Output Examples
109+
110+
### Successful Fix
111+
```
112+
🎉 CODE QUALITY IMPROVED!
113+
114+
✅ All auto-fixes applied successfully
115+
📏 Code formatting: 100% compliant
116+
🔍 Linting: No issues found
117+
🏷️ Type checking: All passed
118+
119+
Ready for commit! Use:
120+
git add -A && git commit -m "style: fix code quality issues"
121+
```
122+
123+
### Issues Requiring Attention
124+
```
125+
⚠️ PARTIAL SUCCESS - MANUAL FIXES NEEDED
126+
127+
✅ Auto-fixes applied: 45 issues
128+
❌ Manual fixes needed: 3 issues
129+
130+
Priority fixes:
131+
1. Fix type annotation in services/entity_service.py:142
132+
2. Simplify complex function in sync/sync_service.py:67
133+
3. Remove unused import in tests/conftest.py:12
134+
135+
Run these commands:
136+
# Fix specific file
137+
uv run pyright src/basic_memory/services/entity_service.py
138+
```
139+
140+
## Context
141+
- Uses ruff for fast Python linting and formatting
142+
- Uses pyright for type checking
143+
- Follows project code style guidelines (100 char line length)
144+
- Maintains backward compatibility
145+
- Integrates with existing pre-commit hooks

0 commit comments

Comments
 (0)