Coverage for session_buddy / session_commands.py: 100.00%
2 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-01-04 00:43 -0800
1#!/usr/bin/env python3
2"""Session command definitions for MCP prompts.
4This module contains the SESSION_COMMANDS dictionary with all command
5descriptions following crackerjack architecture patterns.
6"""
8from __future__ import annotations
10# Session command definitions for MCP prompts
11SESSION_COMMANDS = {
12 "init": """# Session Initialization
14Initialize Claude session with comprehensive setup and intelligent lifecycle management.
16This command will:
17- **Set up Claude directory structure** (~/.claude/ for logs, data, cache)
18- **Initialize ACB storage adapters** (file, S3, Azure, GCS support)
19- **Configure vector database** (DuckDB with FLOAT[384] embeddings)
20- **Set up knowledge graph** (DuckPGQ for entity/relationship queries)
21- **Initialize quality scoring V2** (filesystem-based assessment)
22- **Configure dependency injection** (ACB lifecycle management)
23- **Enable auto-session management** (git repos: automatic init/cleanup)
24- **Set up conversation memory** (local ONNX embeddings, no external APIs)
25- **Configure Crackerjack integration** (quality metrics tracking)
26- **Create slash command shortcuts** (/start, /checkpoint, /end)
28**Key Features:**
29- 🚀 **Automatic for git repos**: Zero manual intervention required
30- 🔒 **Local-first privacy**: All embeddings generated locally via ONNX
31- 📊 **Quality monitoring**: V2 scoring with project health metrics
32- 🧠 **Semantic search**: 384-dimensional vector similarity
33- 🔄 **Auto-cleanup**: Crash-resilient session management
34- 📦 **ACB integration**: Modern async component lifecycle
36**Storage Options** (configurable in settings/session-buddy.yaml):
37- `file` - Local file storage (default)
38- `s3` - AWS S3/MinIO cloud storage
39- `azure` - Azure Blob Storage
40- `gcs` - Google Cloud Storage
42Run this at the start of any coding session for optimal Claude integration.
43""",
44 "checkpoint": """# Session Checkpoint
46Perform mid-session quality checkpoint with workflow analysis and optimization recommendations.
48This command will:
49- **Calculate quality score V2** (filesystem-based assessment, 0-100 scale)
50- **Analyze project health** (maturity, dependencies, documentation coverage)
51- **Review session permissions** (trusted operations for workflow efficiency)
52- **Track Crackerjack metrics** (quality trends, test patterns, error resolutions)
53- **Optimize storage adapters** (ACB-based vector/graph database performance)
54- **Perform strategic cleanup** (when context window is high):
55 • DuckDB VACUUM/ANALYZE for vector database optimization
56 • Knowledge graph cleanup (orphaned entities/relationships)
57 • Session log rotation (retain last 10 files)
58 • Cache cleanup (.DS_Store, .coverage files, __pycache__)
59 • Git repository optimization (gc --auto, prune remote branches)
60 • UV package cache cleanup
61- **Analyze context usage** and recommend `/compact` when beneficial
62- **Create automatic git commit** with checkpoint metadata
63- **Generate workflow recommendations** for productivity improvements
65**Quality Score V2 Factors:**
66- Project maturity (README, docs structure, test coverage)
67- Code quality (Ruff complexity, type hints coverage)
68- Session optimization (permissions, tools integration)
69- Development workflow (git history, commit patterns)
71**RECOMMENDED WORKFLOW:**
721. Run `/session-buddy:checkpoint` for comprehensive analysis
732. Review quality score and workflow recommendations
743. If context compaction is recommended, run: `/compact`
754. Continue with optimized session context
77Use this periodically during long coding sessions to maintain optimal productivity and system performance.
78""",
79 "end": """# Session End
81Complete your Claude Code session with comprehensive cleanup, learning capture, and handoff documentation.
83This command will:
84- **Generate session handoff documentation** with key insights
85- **Perform final quality assessment V2** (filesystem-based scoring)
86- **Store session reflections** in vector database with embeddings
87- **Optimize ACB storage adapters** (compact vector/graph databases)
88- **Clean up temporary files** (cache, .DS_Store, test artifacts)
89- **Capture Crackerjack insights** (quality trends, successful patterns)
90- **Create final commit** with session summary metadata
91- **Provide next session recommendations** based on current state
93**Handoff Documentation Includes:**
94- Quality score V2 with detailed metrics (0-100 scale)
95- Actionable recommendations for next session
96- Key achievements and technical insights
97- Next steps for continuing work
98- Session context and environment information
99- Reflection database statistics (conversations stored)
100- Knowledge graph summary (entities/relationships)
102**Automatic for Git Repos:**
103If you're in a git repository, session end happens automatically on disconnect, quit, or crash. No manual action needed.
105**For Non-Git Projects:**
106Run this command at the end of your session to ensure proper closure and knowledge transfer.
107""",
108 "status": """# Session Status
110Get comprehensive status of your current Claude Code session including project health, storage adapters, permissions, and optimization opportunities.
112This command provides:
113- **Current session state** (active/inactive, duration)
114- **Quality score V2** (0-100 with detailed breakdown)
115- **Project health metrics** (maturity, dependencies, documentation)
116- **Storage adapter status** (ACB backend: file/S3/Azure/GCS)
117- **Database status** (vector database + knowledge graph)
118- **Session permissions** (trusted operations for workflow efficiency)
119- **MCP server integrations** (79+ tools available)
120- **Crackerjack metrics** (recent quality scores, trends)
121- **Memory usage** (context window, optimization suggestions)
122- **Git status** (branch, uncommitted changes, repo health)
123- **Recent activity** (last checkpoint, reflections stored)
125**Storage Adapters (ACB-Based):**
126- Current backend: file, S3, Azure, or GCS
127- Connection status and health check
128- Vector database: DuckDB with FLOAT[384] embeddings
129- Knowledge graph: DuckPGQ entity/relationship queries
131**Quality Metrics:**
132- Project maturity (README, docs, tests)
133- Code quality (complexity, type hints)
134- Session optimization (permissions, shortcuts)
135- Development workflow (git patterns, automation)
137Use this to quickly understand your development environment and identify optimization opportunities.
138""",
139 "permissions": """# Session Permissions Management
141Manage session permissions for trusted operations to avoid repeated prompts during development workflows.
143This command allows you to:
144- View current permissions and trusted operations
145- Trust specific operations (git commits, file operations, etc.)
146- Revoke all permissions and reset to default security
147- Configure permission scopes and time limits
148- Review permission usage history
150**Available Actions:**
151- `status` - Show current permissions and trusted operations
152- `trust <operation>` - Add an operation to trusted list
153- `revoke_all` - Reset all permissions to default
155Use this to streamline repetitive operations while maintaining security control.
156""",
157 "reflect": """# Store Session Reflection
159Store important insights, learnings, or reflections from your current session for future reference and team knowledge sharing.
161This command will:
162- Store your reflection with semantic embedding for search
163- Tag reflections for easy categorization and retrieval
164- Enable cross-project learning and pattern recognition
165- Support team knowledge base building
166- Provide search and retrieval capabilities
168**Usage Examples:**
169- Store technical insights: "This pattern solved our async concurrency issues"
170- Document decisions: "We chose FastAPI over Flask because of async support"
171- Capture learnings: "The key to debugging this was checking the database connection pool"
172- Share solutions: "This regex pattern handles edge cases in user input validation"
174Reflections become searchable across all your projects and sessions.
175""",
176 "quick-search": """# Quick Conversation Search
178Perform a fast search through your conversation history to find relevant past discussions, solutions, and insights.
180This command provides:
181- **Quick Overview**: Returns count and top result only for fast scanning
182- **Semantic Search**: Uses AI embeddings to find conceptually similar content
183- **Cross-Project**: Searches across all your project conversations
184- **Recent Priority**: Prioritizes more recent conversations in results
185- **Fallback**: Uses text search if AI embeddings unavailable
187**Best For:**
188- "Did I solve this before?" quick checks
189- Finding similar error patterns
190- Locating specific technical discussions
191- Quick reference to past decisions
193**Example Queries:**
194- "async database connection issues"
195- "React component optimization patterns"
196- "Docker deployment configurations"
197- "testing strategies for API endpoints"
199For detailed results, use the full search tools after getting the quick overview.
200""",
201 "search-summary": """# Search Summary & Insights
203Get aggregated insights from your conversation history without individual result details - perfect for understanding patterns and themes.
205This command provides:
206- **Pattern Analysis**: Common themes and approaches across conversations
207- **Solution Trends**: Frequently used solutions and their contexts
208- **Knowledge Gaps**: Areas where you've sought help repeatedly
209- **Best Practices**: Patterns that emerged from successful solutions
210- **Technology Evolution**: How your approach to technologies has changed
212**Best For:**
213- Understanding your development patterns
214- Identifying recurring challenges
215- Finding knowledge consolidation opportunities
216- Discovering your most effective approaches
217- Planning learning and documentation priorities
219**Example Queries:**
220- "database performance optimization" → Shows your evolution in DB tuning approaches
221- "React testing strategies" → Reveals your preferred testing patterns
222- "deployment automation" → Highlights your deployment workflow evolution
224Use this for strategic analysis of your development journey and knowledge patterns.
225""",
226 "reflection-stats": """# Reflection Database Statistics
228Get comprehensive statistics about your stored knowledge, conversation history, and learning patterns.
230This command provides:
231- **Database Health**: Connection status, size, and performance metrics
232- **Content Overview**: Total conversations, reflections, and search patterns
233- **Usage Patterns**: Most searched topics and retrieval trends
234- **Growth Metrics**: Knowledge base expansion over time
235- **Search Effectiveness**: Query success rates and pattern analysis
236- **Storage Efficiency**: Database optimization opportunities
238**Includes:**
239- Total stored conversations and reflections
240- Most frequently searched topics
241- Database size and performance metrics
242- Search effectiveness and patterns
243- Recent activity and growth trends
244- Optimization recommendations
246Use this to understand your knowledge base growth and optimize your learning workflow.
247""",
248 "crackerjack-run": """# Enhanced Crackerjack Execution with Memory Integration
250Execute Crackerjack commands with comprehensive analytics, memory integration, and intelligent insights.
252**Enhanced Features:**
253- **Memory Integration**: Results stored and searchable across sessions
254- **Intelligent Insights**: AI analysis of patterns, trends, and recommendations
255- **Quality Tracking**: Historical comparison and regression detection
256- **Context Awareness**: Project-specific recommendations and best practices
257- **Failure Analysis**: Deep dive into error patterns and resolution strategies
259**Available Commands:**
260- `analyze` - Code quality analysis with trend insights
261- `check` - Quick health check with historical comparison
262- `test` - Test execution with pattern analysis
263- `lint` - Linting with rule effectiveness tracking
264- `security` - Security scan with threat trend analysis
265- `complexity` - Complexity analysis with refactoring recommendations
267**Example Usage:**
268- `/session-buddy:crackerjack_run test` - Run tests with intelligent analysis
269- `/session-buddy:crackerjack_run analyze` - Full quality analysis with insights
271Results include execution output, trend analysis, and actionable recommendations based on your project's history.
272""",
273 "crackerjack-history": """# Crackerjack Execution History & Trends
275View comprehensive history of Crackerjack executions with trend analysis and pattern recognition.
277**Features:**
278- **Execution Timeline**: Chronological view of all Crackerjack runs
279- **Quality Trends**: Track code quality metrics over time
280- **Command Patterns**: Most used commands and their success rates
281- **Error Evolution**: How error patterns have changed
282- **Performance Tracking**: Execution time trends and optimization opportunities
283- **Success Metrics**: Pass/fail rates and improvement patterns
285**Filters Available:**
286- Time range (last 7/30/90 days)
287- Command type (test, lint, analyze, etc.)
288- Success/failure status
289- Project scope
291**Insights Provided:**
292- Quality improvement trends
293- Most effective commands for your workflow
294- Recurring issue patterns
295- Optimal execution timing
296- Workflow efficiency recommendations
298Use this to optimize your development workflow and identify quality improvement opportunities.
299""",
300 "crackerjack-metrics": """# Quality Metrics & Trends Analysis
302Get comprehensive quality metrics trends from Crackerjack execution history with actionable insights.
304**Metric Categories:**
305- **Code Quality**: Complexity, maintainability, technical debt trends
306- **Test Coverage**: Coverage percentage evolution and gap analysis
307- **Security Posture**: Vulnerability trends and resolution effectiveness
308- **Performance**: Build times, test execution speed, and optimization opportunities
309- **Compliance**: Code standard adherence and improvement patterns
311**Trend Analysis:**
312- **Improvement Velocity**: Rate of quality enhancement over time
313- **Regression Detection**: Automatic identification of quality drops
314- **Comparative Analysis**: Performance vs. industry/team benchmarks
315- **Seasonal Patterns**: Quality variations and their causes
316- **Predictive Insights**: Projected quality trends and recommendations
318**Visualizations:**
319- Quality score evolution graphs
320- Test coverage heat maps
321- Security vulnerability timelines
322- Performance benchmark comparisons
324**Actionable Recommendations:**
325- Priority areas for improvement
326- Optimal refactoring timing
327- Resource allocation suggestions
328- Risk mitigation strategies
330Use this for strategic development planning and continuous quality improvement.
331""",
332 "crackerjack-patterns": """# Test Failure Pattern Analysis
334Analyze test failure patterns and trends to identify systematic issues and optimization opportunities.
336**Pattern Detection:**
337- **Recurring Failures**: Tests that fail consistently across runs
338- **Flaky Tests**: Intermittent failures and their triggers
339- **Dependency Issues**: Failures caused by external dependencies
340- **Environment Sensitivity**: Platform or configuration-specific failures
341- **Performance Degradation**: Tests failing due to timing or resource constraints
343**Failure Classification:**
344- **Systematic Issues**: Code quality problems requiring refactoring
345- **Infrastructure Problems**: CI/CD, environment, or dependency issues
346- **Test Quality Issues**: Poorly written or maintained tests
347- **Coverage Gaps**: Missing test scenarios revealed by failures
348- **Performance Issues**: Resource or timing-related problems
350**Insights Provided:**
351- Most problematic test suites and their root causes
352- Optimal test execution strategies and timing
353- Resource allocation recommendations for test infrastructure
354- Test maintenance priorities and refactoring opportunities
355- Quality gate optimization suggestions
357**Actionable Recommendations:**
358- Immediate fixes for critical failure patterns
359- Long-term test suite improvement strategies
360- Infrastructure optimization opportunities
361- Test quality improvement priorities
363Use this to transform test failures from obstacles into learning opportunities and systematic improvements.
364""",
365}