@devobsessed/code-captain 0.0.8 → 0.1.0

package/windsurf/workflows/explain-code.md

@@ -1,288 +0,0 @@
----
-description: Provide comprehensive AI-powered explanations of code segments, functions, classes, or files with visual diagrams
----
-
-# Explain Code Workflow
-
-## Overview
-Provides comprehensive, AI-powered explanations of code segments, functions, classes, or entire files. Combines natural language explanations with visual diagrams to help developers understand complex code quickly and thoroughly.
-
-## Command Targets
-
-**Target types:**
-- `[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
-
-**Automatically includes:**
-- Visual diagrams (flowcharts, sequence diagrams, class diagrams)
-- Intermediate complexity level (technical but accessible)
-- Full context (includes dependencies and related components)
-- Saves explanations to `.code-captain/explanations/` for future reference
-
-## Examples
-
-```bash
-# Explain a specific function
-/explain-code calculateUserDiscount
-
-# Explain a class
-/explain-code PaymentProcessor
-
-# Explain entire file
-/explain-code src/auth/AuthService.js
-
-# Explain specific line range
-/explain-code "src/utils/helpers.js:45-78"
-
-# Explain currently selected code
-/explain-code current-selection
-```
-
-## Workflow Process
-
-### Step 1: Target Identification & Location
-
-**Locate the target code:**
-
-- Use `find_by_name` to search for files matching the target
-- Use `view_code_item` to locate specific functions or classes
-- Use `grep_search` to find function/class definitions by name
-- Use `view_file` to read file contents for line ranges or full files
-
-**Target validation:**
-- Confirm target exists and is accessible
-- If ambiguous, present multiple options for user selection
-- If not found, provide suggestions for similar names
-
-### Step 2: Context Gathering & Analysis
-
-**Gather comprehensive context:**
-
-- Use `codebase_search` to understand architectural context
-- Use `view_file` to read related files and dependencies
-- Use `grep_search` to find all usages of the target code
-- Use `view_code_item` to analyze related classes/functions
-
-**Analyze code characteristics:**
-- Parse syntax and identify patterns
-- Measure complexity and performance characteristics
-- Understand dependencies and integration points
-- Identify design patterns and architectural decisions
-
-### Step 3: Explanation Generation
-
-**Create structured explanation:**
-
-**📋 Code Overview**
-- Purpose: What this code does
-- Parameters: Input expectations and validation
-- Return Value: What it outputs and formats
-- Key Logic: Step-by-step breakdown of main functionality
-
-**🔄 Execution Flow**
-- Control flow through the code
-- Decision points and branching logic
-- Error handling paths and edge cases
-- Performance characteristics and bottlenecks
-
-**🏗️ Architecture Context**
-- Where this fits in the overall system
-- Dependencies and related components
-- Design patterns and architectural decisions
-- Integration points with other modules
-
-**⚡ Technical Details**
-- Time and space complexity analysis
-- Memory usage patterns
-- Potential issues and gotchas
-- Optimization opportunities
-
-### Step 4: Visual Diagram Creation
-
-**Generate appropriate diagrams using Mermaid syntax:**
-
-**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
-
-**Example Mermaid flowchart:**
-```mermaid
-graph TD
-    A[Input Validation] --> B{Valid Input?}
-    B -->|Yes| C[Process Data]
-    B -->|No| D[Return Error]
-    C --> E[Apply Business Logic]
-    E --> F[Return Result]
-    D --> G[Log Error]
-```
-
-### Step 5: Documentation & Auto-Save
-
-**Save explanation with date prefix:**
-
-Use `write_to_file` to create explanation file in `.code-captain/explanations/[DATE]-[target-name].md`
-
-**File format:**
-```markdown
-# Code Explanation: [Target Name]
-
-_Generated on [DATE]_
-
-## Overview
-[Natural language summary of purpose and functionality]
-
-## Execution Flow
-```mermaid
-[Generated diagram showing control flow]
-```
-
-## Detailed Breakdown
-[Step-by-step explanation of key logic and decision points]
-
-## Architecture Context
-[How this code fits within the broader system architecture]
-
-## Usage Examples
-[Practical examples of how to use this code]
-
-## Related Components
-[Links to other explanations and dependencies]
-
-## Technical Analysis
-[Performance characteristics, complexity, and optimization notes]
-
----
-_Generated by Code Captain on [timestamp]_
-```
-
-### Step 6: Date Determination
-
-**Primary method - System clock:**
-1. Read the current UTC date from the system clock and format as `YYYY-MM-DD`.
-2. Store it for naming: `.code-captain/explanations/[DATE]-[target-name].md`
-
-**Fallback method - User confirmation:**
-If system clock access isn't available:
-1. Ask user: "What is today's date? (YYYY-MM-DD format)"
-2. Validate format matches `^\d{4}-\d{2}-\d{2}$`
-3. Store date for file naming
-
-### Step 7: Present Results
-
-**Display structured explanation in chat:**
-- Overview with purpose and key functionality
-- Visual diagram showing execution flow
-- Detailed breakdown of logic and decision points
-- Architecture context and system integration
-- Technical analysis with performance notes
-- Usage examples and related components
-
-**Confirm auto-save:**
-- Notify user that explanation saved to `.code-captain/explanations/[DATE]-[target-name].md`
-- Provide file path for future reference
-- Mention integration with other Code Captain commands
-
-## Output Characteristics
-
-**Technical level:** Intermediate complexity balancing accessibility with depth
-**Context:** Always includes related functions, dependencies, and architectural context
-**Visual elements:** Every explanation includes appropriate diagrams
-**Comprehensive:** Shows how code fits in the entire system
-**Saved format:** Markdown with Mermaid diagrams for future reference
-
-## Integration with Code Captain Ecosystem
-
-**Cross-command integration:**
-- Saved explanations accessible by `/research` workflow for context
-- Referenced by `/create-spec` workflow for understanding existing patterns
-- Used by `/execute-task` workflow for implementation guidance
-- Integrated with other workflows for comprehensive codebase understanding
-
-**File 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 named: `[DATE]-[target-name].md` (YYYY-MM-DD format)
-
-## Error Handling
-
-**Common issues and responses:**
-- **Code not found**: "Could not locate [target]. Please check the path/name." Use `find_by_name` to suggest alternatives
-- **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 using `grep_search` results
-- If code is too large, suggest breaking into smaller segments
-
-**Resolution strategies:**
-1. Use `codebase_search` to find alternative approaches
-2. Break complex code into logical segments
-3. Provide partial explanations with clear boundaries
-4. Suggest related files or functions for additional context
-
-## Diagram Types
-
-**Flowcharts:** Control flow, decision trees, error handling paths
-**Sequence diagrams:** Function calls, API interactions, database transactions
-**Class diagrams:** Object relationships, inheritance, dependencies
-**Architecture diagrams:** Component interactions, data flow, service communication
-
-## Management Features
-
-**Explanation discovery:**
-- Use `find_by_name` to list all saved explanations
-- Use `grep_search` to search explanation content
-- Use `view_file` to read previous explanations for context
-
-**Update detection:**
-- Compare file modification times with explanation dates
-- Suggest refreshing explanations for changed code
-- Maintain explanation history and versioning
-
-## Quality Standards
-
-**Clarity:** Explanations understandable to developers at intermediate level
-**Completeness:** Cover purpose, logic, context, and technical details
-**Accuracy:** Reflect actual code behavior and architectural patterns
-**Visual:** Include appropriate diagrams for better understanding
-**Consistency:** Use standard format and terminology across explanations
-
-## Windsurf Tools Used
-
-- `find_by_name`: Locate target files, functions, and classes
-- `view_file`: Read file contents and related code
-- `view_code_item`: Examine specific code elements (classes, functions)
-- `codebase_search`: Understand architectural context and dependencies
-- `grep_search`: Find function definitions, usages, and patterns
-- `write_to_file`: Save explanations to dated files
-- `list_dir`: Explore directory structure for context
-
-## Windsurf Features Used
-
-- **Memories**: After explaining complex architectural patterns, ask Cascade to "create a memory of this architectural pattern and its usage"
-
----
-
-*🧠 Understanding code through comprehensive explanation and visual insight.*

package/windsurf/workflows/initialize.md

@@ -1,298 +0,0 @@
----
-description: Set up technical foundation and development infrastructure for greenfield or brownfield projects
----
-
-# Initialize Workflow
-
-## Overview
-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
-
-**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
-
-**Classify as:**
-- **Greenfield**: Empty directory or minimal files
-- **Brownfield**: Existing codebase with established structure
-
-## Workflow Process
-
-### Step 1: Project Type Detection
-
-**Use Windsurf tools to analyze project state:**
-
-- Use `list_dir` to scan current directory structure
-- Use `find_by_name` to search for common project files (package.json, requirements.txt, etc.)
-- Use `view_file` to check existing configuration files
-- Use `codebase_search` to understand existing code patterns and architecture
-
-**Detection criteria:**
-- **Greenfield indicators**: Empty/minimal directory, no dependency files, no src/ directories
-- **Brownfield indicators**: Existing dependency files, established directory structure, source code present
-
-### Step 2A: Greenfield Workflow (New Projects)
-
-**Phase 1: Technical Foundation Setup**
-
-**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**
-
-**Create project structure:**
-- Use `write_to_file` to create package/dependency files (package.json, requirements.txt, etc.)
-- Use `write_to_file` to create Git configuration (.gitignore, .gitattributes)
-- Use `write_to_file` to create development configuration (prettier, eslint, testing config)
-- Use `write_to_file` to create build and deployment configuration (if applicable)
-
-**Documentation Creation:**
-
-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
-
-**Tech Stack Documentation Template:**
-```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 Documentation Template:**
-```markdown
-# Code Style Guide
-
-## File Organization
-[Directory structure patterns]
-
-## Naming Conventions
-- [Variable naming patterns]
-- [Function naming patterns]
-- [File naming patterns]
-
-## Code Patterns
-[Common patterns for the technology stack]
-
-## Testing Patterns
-[How tests are structured and named]
-
-## Documentation Style
-[Comment and documentation patterns]
-```
-
-### Step 2B: Brownfield Workflow (Existing Projects)
-
-**Phase 1: Codebase Analysis**
-
-**Scan and analyze existing project:**
-- Use `codebase_search` to understand overall architecture and patterns
-- Use `list_dir` to analyze file structure and organization patterns
-- Use `view_file` to examine dependencies and technology stack
-- Use `grep_search` to find code patterns, conventions, and architecture
-- Use `view_file` to review configuration files and build processes
-- Use `find_by_name` to locate testing setup and development tools
-- Use `codebase_search` to identify documentation gaps and technical debt
-
-**Analysis areas:**
-- **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**
-
-**Create comprehensive technical documentation:**
-
-Use `write_to_file` to create:
-
-1. **`.code-captain/docs/tech-stack.md`** - Current technology stack analysis
-2. **`.code-captain/docs/code-style.md`** - Observed code patterns and conventions
-3. **`.code-captain/docs/architecture.md`** - System architecture and technical decisions (if complex)
-
-**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**
-
-### Step 3: Directory Structure Setup
-
-**Ensure Code Captain structure exists:**
-
-Use `list_dir` to check and `write_to_file` to create if missing:
-
-```
-.code-captain/
-├── 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)
-└── research/                 # Research outputs and technical analysis
-```
-
-### Step 4: Final Steps & Guidance
-
-**For Greenfield Projects:**
-```
-🚀 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 Product Strategy (Recommended First):
-/plan-product "your product idea" - Define product vision, strategy, and roadmap
-
-### For Feature Development:
-/create-spec "feature description" - Create detailed feature specifications
-/execute-task - Implement features with TDD workflow
-
-### For Research:
-/research "topic" - Conduct systematic technical research
-/create-adr "decision" - Document architectural decisions
-
-Ready to define your product strategy and start building!
-```
-
-**For Brownfield Projects:**
-```
-🔍 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):
-/plan-product "enhanced product vision" - Define product strategy and roadmap
-
-### For Feature Development:
-/create-spec "feature description" - Create detailed feature specifications
-/execute-task - Implement features following established patterns
-
-### For Technical Improvements:
-/research "technical topic" - Research solutions for identified gaps
-/create-adr "technical decision" - Document architectural improvements
-
-Ready to define your product strategy and enhance your codebase!
-```
-
-## Integration with Code Captain Ecosystem
-
-**Workflow relationship:**
-- **Initialize** handles ONLY technical foundation
-- **/plan-product** handles product strategy and vision  
-- Users need both for complete project setup
-- **/plan-product** should be the next step before feature development
-
-**Cross-workflow integration:**
-- Documentation created here used by `/create-spec` for understanding patterns
-- Tech stack analysis used by `/execute-task` for implementation guidance
-- Architecture documentation used by `/create-adr` for decision context
-- Gap analysis used by `/research` for improvement priorities
-
-## Technical Implementation
-
-**File creation process:**
-1. Use `write_to_file` to create all documentation files
-2. Ensure `.code-captain/docs/` directory exists
-3. Create comprehensive content in each file
-4. Verify file paths match expected locations
-
-**Analysis process:**
-- Use `codebase_search` for semantic understanding of existing code
-- Use `find_by_name` for discovering project files and patterns
-- Use `view_file` for examining specific configuration and code files
-- Use `grep_search` for finding specific patterns and conventions
-
-## Quality Standards
-
-**Documentation completeness:**
-- Tech stack with versions and justifications
-- Code style with observable patterns
-- Architecture decisions and rationale
-- Clear setup and development instructions
-
-**Analysis thoroughness:**
-- Complete technology inventory
-- Consistent pattern identification
-- Gap analysis with actionable recommendations
-- Integration point documentation
-
-## Error Handling
-
-**Common scenarios:**
-- **Empty directory**: Proceed with greenfield workflow
-- **Ambiguous project type**: Ask user for clarification
-- **Missing permissions**: Guide user to resolve access issues
-- **Complex architecture**: Break analysis into smaller components
-
-**Fallback strategies:**
-- If automated detection fails, ask user directly
-- If file creation fails, provide manual instructions
-- If analysis is incomplete, document known limitations
-- If tools fail, provide alternative approaches
-
-## Windsurf Tools Used
-
-- `list_dir`: Explore project directory structure and organization
-- `find_by_name`: Locate project files, configurations, and dependencies
-- `view_file`: Examine existing code, configurations, and documentation
-- `write_to_file`: Create technical documentation and configuration files
-- `codebase_search`: Understand architecture, patterns, and codebase structure
-- `grep_search`: Find specific patterns, conventions, and code structures
-- `run_command`: Execute setup commands and validate configurations
-
-## Windsurf Features Used
-
-- **Memories**: After setup completion, ask Cascade to "create a memory of the technology stack and architectural decisions"
-
----
-
-*🏗️ Building solid technical foundations for sustainable development.*