@devobsessed/code-captain 0.0.3

package/cursor/commands/explain-code.md

@@ -0,0 +1,289 @@
+# Explain Code Command
+
+## Purpose
+
+The `explain-code` command provides comprehensive, AI-powered explanations of code segments, functions, classes, or entire files. It combines natural language explanations with visual diagrams to help developers understand complex code quickly and thoroughly.
+
+## Command Syntax
+
+```bash
+cc: explain-code [target]
+```
+
+## Parameters
+
+### Target (Required)
+
+- `[function-name]` - Specific function to explain
+- `[class-name]` - Entire class explanation
+- `[file-path]` - Explain entire file
+- `[line-range]` - Explain specific lines (e.g., "125-150")
+- `current-selection` - Explain currently selected code in IDE
+
+The command automatically:
+
+- Includes visual diagrams (flowcharts, sequence diagrams, class diagrams)
+- Uses intermediate complexity level (technical but accessible)
+- Provides full context (includes dependencies and related components)
+- Saves explanations to `.code-captain/explanations/` for future reference
+
+## Examples
+
+```bash
+# Explain a specific function
+cc: explain-code calculateUserDiscount
+
+# Explain a class
+cc: explain-code PaymentProcessor
+
+# Explain entire file
+cc: explain-code src/auth/AuthService.js
+
+# Explain specific line range
+cc: explain-code "src/utils/helpers.js:45-78"
+
+# Explain currently selected code in IDE
+cc: explain-code current-selection
+```
+
+## Output Structure
+
+All explanations are displayed in chat and automatically saved to `.code-captain/explanations/`
+
+### Chat Display
+
+```
+📋 Function Overview
+├── Purpose: What this code does
+├── Parameters: Input expectations
+├── Return Value: What it outputs
+├── Key Logic: Step-by-step breakdown
+└── Usage Examples: How to call it
+
+🔄 Execution Flow
+├── [Flowchart diagram showing decision paths]
+├── Decision points and branches
+├── Error handling paths
+└── Performance characteristics
+
+🏗️ Architecture Context
+├── Where this fits in the system
+├── Dependencies and related components
+├── Design patterns used
+└── Integration points
+
+⚡ Technical Details
+├── Time complexity
+├── Memory usage
+├── Potential issues
+└── Optimization opportunities
+```
+
+### Saved Format
+
+````markdown
+# Code Explanation: [Target Name]
+
+_Generated on [DATE]_
+
+## Overview
+
+[Natural language summary]
+
+## Execution Flow
+
+```mermaid
+[Generated diagram]
+```
+````
+
+## Detailed Breakdown
+
+[Step-by-step explanation]
+
+## Architecture Context
+
+[How it fits in the system]
+
+## Usage Examples
+
+[Code examples]
+
+## Related Components
+
+[Links to other explanations]
+
+---
+
+_Generated by Code Captain on [timestamp]_
+_Last updated: [timestamp]_
+
+```
+
+## File Organization
+
+Saved explanations are stored with date prefixes for chronological organization:
+
+```
+
+.code-captain/
+└── explanations/
+├── 2024-01-15-AuthenticationFlow.md
+├── 2024-01-16-PaymentProcessor.md
+├── 2024-01-16-UserService.md
+└── 2024-01-17-SearchAlgorithm.md
+
+````
+
+Files are named using the format: `[DATE]-[target-name].md` where DATE is YYYY-MM-DD format.
+
+## Auto-Save Behavior
+
+All explanations are automatically saved to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`. The system uses the same date determination process as the research command to ensure consistent timestamps.
+
+## Date Determination Process
+
+### Primary Method: File System Timestamp
+
+1. **CREATE** directory if not exists: `.code-captain/explanations/`
+2. **CREATE** temporary file: `.code-captain/explanations/.date-check`
+3. **READ** file creation timestamp from filesystem
+4. **EXTRACT** date in YYYY-MM-DD format
+5. **DELETE** temporary file
+6. **STORE** date in variable for file naming
+
+### Fallback Method: User Confirmation
+
+If file system method fails:
+
+1. **STATE**: "I need to confirm today's date for the explanation file"
+2. **ASK**: "What is today's date? (YYYY-MM-DD format)"
+3. **WAIT** for user response
+4. **VALIDATE** format matches `^\d{4}-\d{2}-\d{2}$`
+5. **STORE** date for file naming
+
+**Example filename:** `.code-captain/explanations/2024-01-15-AuthenticationFlow.md`
+
+## Integration Points
+
+### With Other Commands
+```bash
+# Saved explanations can be referenced by other commands
+cc: research authentication
+cc: create-spec payment-processing
+cc: execute-task "optimize the user search"
+
+# AI can access saved explanations from .code-captain/explanations/
+# to provide better context for other commands
+```
+
+### With IDE Integration
+
+- Hover over function calls to see saved explanations
+- Right-click context menu: "Explain with Code Captain"
+- Inline explanation widgets for complex code blocks
+
+## Management Commands
+
+```bash
+# List all saved explanations
+cc: list-explanations
+
+# Search explanations
+cc: search-explanations "authentication"
+
+# Show explanation history
+cc: explanation-history calculateDiscount
+
+# Update outdated explanations when code changes
+cc: refresh-explanations --check-code-changes
+```
+
+## Diagram Types Generated
+
+### Flowcharts
+
+- Control flow through functions
+- Decision trees for complex logic
+- Error handling paths
+
+### Sequence Diagrams
+
+- Function call sequences
+- API interaction flows
+- Database transaction flows
+
+### Class Diagrams
+
+- Object relationships
+- Inheritance hierarchies
+- Dependency structures
+
+### Architecture Diagrams
+
+- Component interactions
+- Data flow through system
+- Service communication patterns
+
+## Output Characteristics
+
+All explanations use a consistent intermediate technical level that balances accessibility with depth:
+
+- **Technical but accessible**: Explains how the code works with some optimization details
+- **Full context**: Always includes related functions, dependencies, and architectural context
+- **Visual diagrams**: Every explanation includes appropriate flowcharts, sequence diagrams, or class diagrams
+- **Comprehensive coverage**: Shows how the code fits in the entire system
+
+## AI Processing Workflow
+
+1. **Code Analysis**: Parse syntax, identify patterns, measure complexity
+2. **Context Gathering**: Understand surrounding code and dependencies
+3. **Explanation Generation**: Create intermediate-level natural language description
+4. **Diagram Creation**: Generate appropriate visual representations (flowcharts, sequence, class diagrams)
+5. **Formatting**: Structure output for both chat display and markdown file
+6. **Auto-Save**: Save explanation to `.code-captain/explanations/` with date-prefixed filename `[DATE]-[target-name].md`
+
+## Error Handling
+
+### Common Issues
+
+- **Code not found**: "Could not locate [target]. Please check the path/name."
+- **Too complex**: "This code is very complex. Consider breaking into smaller explanations."
+- **Limited context**: "Some context may be missing. Ensure related files are accessible."
+
+### Fallback Behaviors
+
+- If diagrams fail to generate, provide text-based flow description
+- If target is ambiguous, offer multiple options to choose from
+- If code is too large, suggest breaking into smaller segments
+
+## Success Metrics
+
+Track effectiveness through:
+
+- Explanation clarity ratings from users
+- Frequency of re-explanations for same code
+- Time saved in code reviews and onboarding
+- Reduction in "what does this do?" questions during development
+
+## Future Enhancements
+
+### Planned Features
+
+- Interactive explanations with expandable sections
+- Voice-generated explanations for accessibility
+- Integration with code review tools
+- Automatic explanation updates when code changes
+- Explanation versioning and history tracking
+
+### Advanced Capabilities
+
+- Performance profiling integration
+- Security vulnerability highlighting in explanations
+- Code quality suggestions as part of explanations
+- Integration with documentation generation tools
+
+```
+
+```
+````

package/cursor/commands/initialize.md

@@ -0,0 +1,397 @@
+# Initialize Command Workflow
+
+## Command: `cc: initialize`
+
+### Purpose
+
+Set up technical foundation and development infrastructure by detecting if this is a greenfield (new) or brownfield (existing) project and executing the appropriate technical setup workflow.
+
+### Detection Logic
+
+1. **Scan current directory** for indicators:
+
+   - Presence of package.json, requirements.txt, Cargo.toml, go.mod, etc.
+   - Existing source code directories (src/, lib/, app/, etc.)
+   - Git repository status
+   - Configuration files
+
+2. **Classify as**:
+   - **Greenfield**: Empty directory or minimal files
+   - **Brownfield**: Existing codebase with established structure
+
+---
+
+## Greenfield Workflow
+
+### Phase 1: Technical Foundation Setup
+
+#### Greenfield Todo Checklist
+
+Use `todo_write` to track progress through technical setup:
+
+```json
+{
+  "todos": [
+    {
+      "id": "greenfield-tech-analysis",
+      "content": "Determine technology stack and development requirements",
+      "status": "in_progress"
+    },
+    {
+      "id": "greenfield-tech-stack",
+      "content": "Document technology stack in .code-captain/docs/tech-stack.md",
+      "status": "pending"
+    },
+    {
+      "id": "greenfield-structure",
+      "content": "Create project directory structure and config files",
+      "status": "pending"
+    },
+    {
+      "id": "greenfield-dev-setup",
+      "content": "Set up development configuration and tooling",
+      "status": "pending"
+    },
+    {
+      "id": "greenfield-readme",
+      "content": "Generate technical README.md with setup instructions",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+**Ask focused technical questions**:
+
+1. **Project Type**: "What type of application are you building? (web app, API, mobile app, library, CLI tool, etc.)"
+2. **Technical Constraints**: "Any required technologies, frameworks, or platforms?"
+3. **Development Environment**: "What's your preferred development setup? (local, containerized, cloud-based)"
+4. **Scale Requirements**: "Expected technical scale? (prototype, small team, enterprise)"
+
+### Phase 2: Technology Recommendations
+
+Based on technical requirements, recommend:
+
+- **Tech Stack**: Languages, frameworks, databases suitable for the project type
+- **Architecture Pattern**: Monolith, microservices, serverless based on scale needs
+- **Development Tools**: Testing frameworks, build tools, linting/formatting
+- **Project Structure**: Directory layout, naming conventions, configuration
+
+### Phase 3: Technical Foundation Setup
+
+#### Directory Structure (Pre-existing)
+
+The `.code-captain/` directory structure already exists from installation:
+
+- `.code-captain/docs/` - For technical documentation
+- `.code-captain/research/` - For research outputs
+- `.code-captain/commands/` - Pre-installed command definitions
+
+#### Configuration Files
+
+- **Package/dependency files** (package.json, requirements.txt, etc.)
+- **Git configuration** (.gitignore, .gitattributes)
+- **Development configuration** (prettier, eslint, testing config, etc.)
+- **Build and deployment configuration** (if applicable)
+
+#### Documentation Creation (Exact File Paths)
+
+1. **`.code-captain/docs/tech-stack.md`** - Technology stack decisions and rationale
+2. **`.code-captain/docs/code-style.md`** - Coding standards and development patterns
+3. **`README.md`** - Technical overview and setup instructions
+
+### Phase 4: Next Steps Guidance
+
+After technical foundation is complete, provide clear next steps:
+
+```
+🚀 Technical Foundation Complete!
+
+Your development environment is now set up and documented:
+- Technology stack documented and configured
+- Development tools and standards established  
+- Project structure and configuration ready
+
+## Recommended Next Steps:
+
+### For New Products:
+cc: plan-product "your product idea" - Define product vision, strategy, and roadmap
+
+### For Existing Products:
+cc: create-spec "feature description" - Create detailed feature specifications
+cc: execute-task - Implement features with TDD workflow
+
+### For Research:
+cc: research "topic" - Conduct systematic technical research
+cc: create-adr "decision" - Document architectural decisions
+
+Ready to define your product strategy and start building!
+```
+
+---
+
+## Brownfield Workflow
+
+### Phase 1: Codebase Analysis
+
+#### Brownfield Todo Checklist
+
+Use `todo_write` to track analysis progress:
+
+```json
+{
+  "todos": [
+    {
+      "id": "brownfield-analysis",
+      "content": "Analyze existing codebase structure, dependencies, and patterns",
+      "status": "in_progress"
+    },
+    {
+      "id": "brownfield-tech-stack",
+      "content": "Document current tech stack in .code-captain/docs/tech-stack.md",
+      "status": "pending"
+    },
+    {
+      "id": "brownfield-code-style",
+      "content": "Analyze and document code patterns in .code-captain/docs/code-style.md",
+      "status": "pending"
+    },
+    {
+      "id": "brownfield-architecture",
+      "content": "Document system architecture and technical decisions",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+**Scan and analyze**:
+
+- **File structure** and organization patterns
+- **Dependencies** and technology stack
+- **Code patterns**, conventions, and architecture
+- **Configuration files** and build processes
+- **Testing setup** and development tools
+- **Documentation gaps** and technical debt
+
+### Phase 2: Documentation Generation
+
+#### tech-stack.md
+
+```markdown
+# Technology Stack
+
+## Languages
+
+- [Primary language with version]
+- [Secondary languages if any]
+
+## Frameworks & Libraries
+
+- [Main framework with version and purpose]
+- [Key dependencies with purposes]
+
+## Infrastructure
+
+- [Database technology]
+- [Deployment platform]
+- [CI/CD tools]
+
+## Development Tools
+
+- [Package manager]
+- [Testing framework]
+- [Linting/formatting tools]
+
+## Architecture Pattern
+
+[Monolith/Microservices/Serverless/etc. with reasoning]
+```
+
+#### code-style.md
+
+```markdown
+# Code Style Guide
+
+## File Organization
+
+[Directory structure patterns observed]
+
+## Naming Conventions
+
+- [Variable naming patterns]
+- [Function naming patterns]
+- [File naming patterns]
+
+## Code Patterns
+
+[Common patterns observed in codebase]
+
+## Testing Patterns
+
+[How tests are structured and named]
+
+## Documentation Style
+
+[Comment and documentation patterns]
+```
+
+### Phase 3: Gap Analysis & Recommendations
+
+Identify and document:
+
+- **Missing technical documentation**
+- **Inconsistent code patterns**
+- **Technical debt and improvement opportunities**
+- **Testing coverage gaps**
+- **Development workflow improvements**
+- **Architecture optimization opportunities**
+
+### Phase 4: Next Steps Guidance
+
+After brownfield analysis is complete, provide clear next steps:
+
+```
+🔍 Technical Foundation Analysis Complete!
+
+Your existing project has been analyzed and documented:
+- Current technology stack and architecture documented
+- Code patterns and conventions identified
+- Technical gaps and improvement opportunities noted
+
+## Recommended Next Steps:
+
+### For Product Strategy (Recommended First):
+cc: plan-product "enhanced product vision" - Define product strategy and roadmap
+
+### For Feature Development:
+cc: create-spec "feature description" - Create detailed feature specifications
+cc: execute-task - Implement features following established patterns
+
+### For Technical Improvements:
+cc: research "technical topic" - Research solutions for identified gaps
+cc: create-adr "technical decision" - Document architectural improvements
+
+Ready to define your product strategy and enhance your codebase!
+```
+
+---
+
+---
+
+## CRITICAL: Final Message Requirements
+
+**MANDATORY**: The initialize command MUST end with a message that prominently recommends `plan-product` as the next logical step for both greenfield and brownfield projects. This is required because:
+
+1. Initialize handles ONLY technical foundation
+2. plan-product handles product strategy and vision  
+3. Users need both for complete project setup
+4. plan-product should be the next step before feature development
+
+**Required message format**:
+```
+🚀 Technical Foundation Complete! / 🔍 Technical Foundation Analysis Complete!
+
+## Recommended Next Steps:
+
+### For Product Strategy (Recommended First):
+cc: plan-product "your product idea/vision" - Define product strategy and roadmap
+
+### For Feature Development:
+cc: create-spec "feature description" - Create detailed feature specifications
+cc: execute-task - Implement features
+
+### For Technical Improvements:
+cc: research "topic" - Research solutions for gaps
+cc: create-adr "decision" - Document architectural decisions
+```
+
+---
+
+## Implementation Notes
+
+### Tool Integration
+
+- Use `codebase_search` for semantic understanding
+- Use `file_search` for pattern discovery
+- Use `todo_write` for progress tracking throughout both workflows
+- Use `edit_file` to create documentation files
+
+### Output Locations & File Structure
+
+#### Directory Structure (Created by Install Script)
+
+```
+.code-captain/
+├── commands/                 # CC command definitions (pre-installed)
+└── docs/
+    ├── best-practices.md     # Development best practices (pre-installed)
+    ├── code-style.md         # Code conventions and patterns
+    ├── tech-stack.md         # Technology decisions and rationale
+    └── architecture.md       # System architecture (if complex)
+```
+
+#### Specific File Locations
+
+**Docs Directory** (`.code-captain/docs/`):
+
+- `best-practices.md` - Development best practices (pre-installed)
+- `code-style.md` - Coding standards, naming conventions, patterns
+- `tech-stack.md` - Technology choices with justifications
+- `architecture.md` - System architecture and technical decisions (if complex)
+
+**Research Directory** (`.code-captain/research/`):
+
+- Research outputs, technical analysis, and investigation results
+
+**Commands Directory** (`.code-captain/commands/`):
+
+- Pre-installed CC command definitions (managed by system)
+
+**Root Directory**:
+
+- `README.md` - Project overview and quick start (only for new projects)
+
+### Todo Integration
+
+Each phase should update todos to show progress, enabling Cursor's todo tracking:
+
+#### Example Todo Updates
+
+```javascript
+// Mark analysis complete and start documentation phase
+todo_write({
+  merge: true,
+  todos: [
+    { id: "greenfield-tech-analysis", status: "completed" },
+    { id: "greenfield-tech-stack", status: "in_progress" },
+  ],
+});
+
+// Update when creating documentation files
+todo_write({
+  merge: true,
+  todos: [
+    { id: "greenfield-tech-stack", status: "completed" },
+    { id: "greenfield-dev-setup", status: "completed" },
+    { id: "greenfield-readme", status: "in_progress" },
+  ],
+});
+```
+
+#### Todo Best Practices
+
+- **Always include file paths** in todo content for clarity
+- **Use descriptive IDs** that indicate workflow type (greenfield/brownfield)
+- **Update todos immediately** after completing each task
+- **Mark todos as completed** only after files are actually created
+- **Use `merge: true`** to update existing todos without replacing the entire list
+
+#### File Creation Verification
+
+Before marking documentation todos as complete, ensure:
+
+1. **Directory exists**: `.code-captain/docs/`
+2. **File is created**: Use `write` tool to create the actual file
+3. **Content is complete**: File contains all required sections
+4. **Path is correct**: Double-check exact file path matches todo description