1#!/usr/bin/env python3

2"""Session command definitions for MCP prompts.

3

4 This module contains the SESSION_COMMANDS dictionary with all command

5 descriptions following crackerjack architecture patterns.

6"""

7

8 from __future__ import annotations

9

10# Session command definitions for MCP prompts

11 SESSION_COMMANDS = {

12 "init": """# Session Initialization

13

14 Initialize Claude session with comprehensive setup and intelligent lifecycle management.

15

16 This 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)

27

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

35

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

41

42 Run this at the start of any coding session for optimal Claude integration.

43""",

44 "checkpoint": """# Session Checkpoint

45

46 Perform mid-session quality checkpoint with workflow analysis and optimization recommendations.

47

48 This 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

64

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)

70

71**RECOMMENDED WORKFLOW:**

72 1. Run `/session-buddy:checkpoint` for comprehensive analysis

73 2. Review quality score and workflow recommendations

74 3. If context compaction is recommended, run: `/compact`

75 4. Continue with optimized session context

76

77 Use this periodically during long coding sessions to maintain optimal productivity and system performance.

78""",

79 "end": """# Session End

80

81 Complete your Claude Code session with comprehensive cleanup, learning capture, and handoff documentation.

82

83 This 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

92

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)

101

102**Automatic for Git Repos:**

103 If you're in a git repository, session end happens automatically on disconnect, quit, or crash. No manual action needed.

104

105**For Non-Git Projects:**

106 Run this command at the end of your session to ensure proper closure and knowledge transfer.

107""",

108 "status": """# Session Status

109

110 Get comprehensive status of your current Claude Code session including project health, storage adapters, permissions, and optimization opportunities.

111

112 This 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)

124

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

130

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)

136

137 Use this to quickly understand your development environment and identify optimization opportunities.

138""",

139 "permissions": """# Session Permissions Management

140

141 Manage session permissions for trusted operations to avoid repeated prompts during development workflows.

142

143 This 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

149

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

154

155 Use this to streamline repetitive operations while maintaining security control.

156""",

157 "reflect": """# Store Session Reflection

158

159 Store important insights, learnings, or reflections from your current session for future reference and team knowledge sharing.

160

161 This 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

167

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"

173

174 Reflections become searchable across all your projects and sessions.

175""",

176 "quick-search": """# Quick Conversation Search

177

178 Perform a fast search through your conversation history to find relevant past discussions, solutions, and insights.

179

180 This 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

186

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

192

193**Example Queries:**

194- "async database connection issues"

195- "React component optimization patterns"

196- "Docker deployment configurations"

197- "testing strategies for API endpoints"

198

199 For detailed results, use the full search tools after getting the quick overview.

200""",

201 "search-summary": """# Search Summary & Insights

202

203 Get aggregated insights from your conversation history without individual result details - perfect for understanding patterns and themes.

204

205 This 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

211

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

218

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

223

224 Use this for strategic analysis of your development journey and knowledge patterns.

225""",

226 "reflection-stats": """# Reflection Database Statistics

227

228 Get comprehensive statistics about your stored knowledge, conversation history, and learning patterns.

229

230 This 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

237

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

245

246 Use this to understand your knowledge base growth and optimize your learning workflow.

247""",

248 "crackerjack-run": """# Enhanced Crackerjack Execution with Memory Integration

249

250 Execute Crackerjack commands with comprehensive analytics, memory integration, and intelligent insights.

251

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

258

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

266

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

270

271 Results include execution output, trend analysis, and actionable recommendations based on your project's history.

272""",

273 "crackerjack-history": """# Crackerjack Execution History & Trends

274

275 View comprehensive history of Crackerjack executions with trend analysis and pattern recognition.

276

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

284

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

290

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

297

298 Use this to optimize your development workflow and identify quality improvement opportunities.

299""",

300 "crackerjack-metrics": """# Quality Metrics & Trends Analysis

301

302 Get comprehensive quality metrics trends from Crackerjack execution history with actionable insights.

303

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

310

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

317

318**Visualizations:**

319- Quality score evolution graphs

320- Test coverage heat maps

321- Security vulnerability timelines

322- Performance benchmark comparisons

323

324**Actionable Recommendations:**

325- Priority areas for improvement

326- Optimal refactoring timing

327- Resource allocation suggestions

328- Risk mitigation strategies

329

330 Use this for strategic development planning and continuous quality improvement.

331""",

332 "crackerjack-patterns": """# Test Failure Pattern Analysis

333

334 Analyze test failure patterns and trends to identify systematic issues and optimization opportunities.

335

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

342

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

349

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

356

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

362

363 Use this to transform test failures from obstacles into learning opportunities and systematic improvements.

364""",

365}