@devobsessed/code-captain 0.0.3

package/copilot/prompts/explain-code.prompt.md

@@ -0,0 +1,292 @@
+---
+mode: agent
+---
+
+# Explain Code Command
+
+## Overview
+
+Provide comprehensive, AI-powered explanations of code segments, functions, classes, or entire files. This command combines natural language explanations with visual diagrams to help developers understand complex code quickly and thoroughly.
+
+## 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
+
+```
+# 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 in IDE
+/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
+```
+# Saved explanations can be referenced by other commands
+/research authentication
+/create-spec payment-processing
+/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
+
+```
+# List all saved explanations
+/list-explanations
+
+# Search explanations
+/search-explanations "authentication"
+
+# Show explanation history
+/explanation-history calculateDiscount
+
+# Update outdated explanations when code changes
+/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`
+
+## Tool Integration
+
+**Primary tools:**
+- `codebase` - Analyzing code structure and dependencies
+- `search` - Finding related components and existing explanations
+- `editFiles` - Creating explanation documents
+- `runCommands` - Date determination and directory creation
+- `usages` - Understanding how code is used throughout the system
+
+**Documentation organization:**
+- Explanations stored in `.code-captain/explanations/`
+- Date-prefixed filenames for chronological organization
+- Cross-references to related explanations and components
+
+## 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/copilot/prompts/initialize.prompt.md

@@ -0,0 +1,65 @@
+---
+mode: agent
+---
+
+# Initialize Command
+
+## Overview
+
+Analyze and set up technical foundation for either greenfield (new) or brownfield (existing) projects. This command intelligently detects project type, scans the codebase, and generates foundational documentation including technology stack analysis, code style guide, and architectural overview.
+
+## Command Process
+
+### Step 1: Project Type Detection
+
+**Scan for existing code:**
+- Check for common files indicating existing project (package.json, pom.xml, etc.)
+- Detect programming languages and frameworks
+- Identify project structure patterns
+- Determine if greenfield (new) or brownfield (existing) project
+
+### Step 2: Project Analysis
+
+**For Brownfield Projects:**
+- Scan codebase for technology stack inventory
+- Analyze code patterns and conventions
+- Infer project purpose and goals
+- Generate comprehensive documentation
+
+**For Greenfield Projects:**
+- Guide through strategic project setup questions
+- Recommend technology stack based on requirements
+- Create project foundation structure
+
+### Step 3: Documentation Generation
+
+Generate foundational documents in `.code-captain/docs/`:
+
+**tech-stack.md** - Complete technology inventory and analysis
+**code-style.md** - Observed patterns and coding conventions  
+**objective.md** - Inferred or defined project purpose and goals
+**architecture.md** - System architecture overview and decisions
+
+### Step 4: Next Steps Recommendation
+
+Provide clear guidance on next steps, typically:
+1. **`/plan-product`** - For product strategy and vision planning
+2. **`/create-spec`** - For specific feature development
+3. **`/research`** - For technology investigation needs
+
+## Tool Integration
+
+**Primary tools:**
+- `codebase` - Analyzing codebase patterns and structure
+- `search` - Finding specific patterns and technologies
+- `editFiles` - Creating foundational documentation
+- `runCommands` - Detecting build tools and dependencies
+- `githubRepo` - Understanding repository context and history
+- `findTestFiles` - Locating test files and patterns
+- `problems` - Identifying code issues
+
+**Documentation organization:**
+- Progress documented in `.code-captain/initialization-progress.md`
+- Results organized in `.code-captain/docs/` folder
+
+This command provides comprehensive project analysis and setup using GitHub Copilot's native capabilities.

package/copilot/prompts/new-command.prompt.md

@@ -0,0 +1,310 @@
+---
+mode: agent
+---
+
+# New Command Creator
+
+## Overview
+
+A meta command that creates new Code Captain commands following established patterns and conventions. This command generates properly structured command files, updates documentation, and ensures consistency across the Code Captain ecosystem.
+
+## Examples
+
+```
+# Create optimization command
+/new-command "optimize" "Performance optimization for slow code sections"
+
+# Create deployment command  
+/new-command "deploy" "Deploy applications to various cloud platforms"
+
+# Create test generation command
+/new-command "test-gen" "Generate comprehensive test suites from existing code"
+```
+
+## Command Process
+
+### Step 1: Command Specification Gathering
+
+**Initial Input Processing:**
+- Parse command name (validate format: lowercase, hyphens allowed)
+- Extract brief description from user input
+- Validate command name doesn't conflict with existing commands
+
+**Interactive Specification Building:**
+Ask clarifying questions to build complete command specification:
+
+1. **Command Category**: "Is this a [Setup/Analysis/Implementation/Integration] command?"
+2. **Execution Style**: "Should this use contract style (extensive clarification rounds like create-spec) or direct execution (immediate action like swab)?"
+3. **Usage Pattern**: "Does it take arguments, flags, or is it standalone?"
+4. **AI Coordination**: "Does it need AI prompts for complex decision-making?"
+5. **Output Location**: "Where should outputs be stored? (.code-captain/[folder])"
+6. **Tool Integration**: "Which GitHub Copilot tools will it use? (codebase, search, etc.)"
+7. **Workflow Steps**: "What are the main phases/steps the command follows?"
+
+### Step 2: Command Structure Generation
+
+**Generate Standard Prompt File Structure:**
+
+```markdown
+---
+mode: agent
+---
+
+# [Command Name] Command
+
+## Overview
+[Generated from description and clarifying questions]
+
+## Command Process
+
+### Step 1: [Phase Name]
+[Generated workflow steps]
+
+### Step 2: [Phase Name]
+[Generated workflow steps]
+
+## Tool Integration
+[Generated based on command type]
+
+## AI Implementation Prompt
+[Generated if AI coordination needed]
+
+## Integration Notes
+[Generated integration details]
+```
+
+**Template Sections Based on Command Type and Execution Style:**
+
+**Contract Style Commands** (like `/create-spec`, `/create-adr`):
+- Phase 1: Contract Establishment (No File Creation)
+- Interactive clarification rounds with structured questions
+- Critical analysis and assumption challenging
+- Echo check/contract proposal phase
+- Explicit user agreement before proceeding
+
+**Direct Execution Commands** (like `/swab`, `/execute-task`):
+- Immediate action workflows
+- Minimal clarification if needed
+- Clear step-by-step execution
+- Progress feedback and completion confirmation
+
+**Setup/Analysis Commands:**
+- Context scanning steps
+- File generation workflows
+- Progress tracking workflows
+
+**Implementation Commands:**
+- TDD workflows if applicable
+- Code modification steps
+- Verification procedures
+
+**Integration Commands:**
+- Platform-specific API interactions
+- Sync and conflict resolution
+- Error handling patterns
+
+### Step 3: Documentation Integration
+
+**Provide guidance for documentation updates:**
+
+1. **Command Documentation:**
+   - Generate complete prompt file structure
+   - Include usage examples and integration notes
+   - Provide clear implementation guidelines
+
+2. **Integration Recommendations:**
+   - Suggest where command fits in existing workflow
+   - Identify related commands and dependencies
+   - Recommend documentation updates if needed
+
+### Step 4: Validation and Integration
+
+**Verify Command Integration:**
+- Check command file syntax and structure
+- Validate documentation updates
+- Ensure no conflicts with existing commands
+- Run basic structure validation
+
+**Present Summary:**
+```
+✅ New command prompt created successfully!
+
+📁 Generated Content:
+  - .github/prompts/[command-name].prompt.md
+  - Complete prompt file structure with frontmatter
+  - Usage examples and documentation
+  - Integration guidelines and recommendations
+
+🚀 Command Ready:
+  Usage: /[command-name] [args]
+  Implementation: Follow generated prompt structure
+```
+
+## Core Rules
+
+1. **Consistent Structure** - All generated commands follow established patterns
+2. **Clear Documentation** - Each section has purpose and implementation details
+3. **Integration Guidance** - Provides recommendations for documentation and workflow integration
+4. **Validation Required** - Check for conflicts and proper structure
+5. **Template Flexibility** - Adapt template based on command type and requirements
+6. **Language & Shell Agnostic** - Commands should work across different programming languages and shell environments, using Code Captain's existing tools rather than making assumptions about tech stack
+
+## AI Implementation Prompt
+
+```
+You are creating a new Code Captain command following established patterns.
+
+MISSION: Generate a complete, well-structured command file and update documentation.
+
+COMMAND SPECIFICATION:
+- Name: {command_name}
+- Description: {description}
+- Category: {category}
+- Execution Style: {contract_style_or_direct_execution}
+- Usage Pattern: {usage_pattern}
+- AI Coordination: {needs_ai_prompts}
+- Output Location: {output_location}
+- Tool Integration: {copilot_tools}
+- Workflow Steps: {workflow_phases}
+
+TEMPLATE STRUCTURE:
+1. Frontmatter: mode: agent
+2. Title: # [Command Name] Command
+3. Overview: Purpose and capabilities
+4. Command Process: Detailed step-by-step workflow
+5. Tool Integration: GitHub Copilot tool coordination
+6. AI Implementation Prompt: (if AI coordination needed)
+7. Integration Notes: Platform coordination
+
+TEMPLATE ADAPTATION RULES:
+- Contract Style commands: Include clarification phases, contract establishment, critical analysis, user agreement checkpoints
+- Direct Execution commands: Include immediate action workflows, minimal interaction, clear progress feedback
+- Setup/Analysis commands: Include context scanning, file generation, progress tracking
+- Implementation commands: Include TDD workflows, code modification, verification
+- Integration commands: Include API interactions, sync, error handling
+- All commands: Include clear examples, tool coordination, progress tracking
+- CRITICAL: Be language and shell agnostic - use codebase, search instead of language-specific commands or hardcoded file extensions
+
+DOCUMENTATION GUIDANCE:
+Provide recommendations for integrating the new command:
+- Suggest workflow placement and related commands
+- Include usage examples and best practices
+- Recommend documentation structure and content
+
+OUTPUT REQUIREMENTS:
+1. Generate complete .prompt.md file with frontmatter following the template
+2. Provide integration recommendations and workflow guidance
+3. Include clear usage examples and implementation notes
+4. Ensure consistency with existing command patterns
+5. Validate no conflicts with existing commands
+
+QUALITY CHECKS:
+- Command name follows naming conventions (lowercase, hyphens)
+- Usage examples are clear and practical
+- Workflow steps are actionable and specific
+- Integration points are clearly documented
+- All sections serve a clear purpose
+- No hardcoded language assumptions or shell-specific commands
+- Uses Code Captain's existing tools (codebase, search) rather than system-specific commands
+```
+
+## Implementation Details
+
+### Command Name Validation
+
+**Validation Rules:**
+- Lowercase letters, numbers, hyphens only
+- No spaces or special characters
+- Maximum 20 characters
+- Cannot start with number or hyphen
+- Must not conflict with existing commands
+
+**Validation Process:**
+```bash
+# Check format
+echo "command-name" | grep -E '^[a-z][a-z0-9-]*[a-z0-9]$'
+
+# Check conflicts
+ls .github/prompts/ | grep "^command-name.prompt.md$"
+```
+
+### Template Selection Logic
+
+**Command Categories and Templates:**
+
+1. **Setup/Analysis** (`initialize`, `research`, `explain-code`)
+   - Context scanning workflows
+   - Documentation generation
+   - Progress tracking emphasis
+
+2. **Planning/Specification** (`create-spec`, `create-adr`, `plan-product`)
+   - Interactive clarification phases
+   - Structured output formats
+   - Contract-based workflows
+
+3. **Implementation** (`execute-task`, `swab`)
+   - Code modification workflows
+   - TDD patterns
+   - Verification steps
+
+4. **Integration** (`sync`, `create-github-issues`)
+   - Platform API interactions
+   - Sync and conflict handling
+   - Status reporting
+
+
+
+### Error Handling
+
+**Common Issues:**
+- **Duplicate command name**: Check existing prompts, suggest alternatives
+- **Invalid command name format**: Provide format guidance and examples
+- **Documentation integration conflicts**: Use safe merge strategies, manual review if needed
+- **Template generation errors**: Validate inputs, provide clear error messages
+
+**Error Messages:**
+```
+❌ Command creation failed: [specific reason]
+
+Suggestions:
+- Check command name format (lowercase, hyphens only)
+- Ensure name doesn't conflict with existing commands
+- Verify all required inputs are provided
+
+Try: /new-command "valid-name" "clear description"
+```
+
+## Tool Integration
+
+**Primary tools:**
+- `codebase` - Analyzing existing prompt patterns and structure
+- `search` - Finding existing prompts to check for conflicts
+- `editFiles` - Creating new prompt files and updating documentation
+- `runCommands` - Command name validation and directory operations
+
+**Documentation organization:**
+- Prompt files stored in `.github/prompts/`
+- Integration guidance for documentation updates
+- Validation and conflict checking before creation
+
+## Integration Notes
+
+This command integrates with Code Captain by:
+
+1. **Following Established Patterns** - Uses same structure as existing prompts
+2. **Maintaining Consistency** - Ensures all new prompts match style and format
+3. **Documentation Guidance** - Provides clear recommendations for integration and usage
+4. **Extensibility** - Makes it easy to add new capabilities to Code Captain
+5. **Quality Assurance** - Validates structure and prevents conflicts
+
+## Future Enhancements
+
+Potential improvements (not in initial version):
+
+- **Template Library**: Multiple prompt templates for different use cases
+- **Interactive Wizard**: Step-by-step prompt creation with guidance
+- **Integration Testing**: Automated testing of generated prompts
+- **Version Control**: Track prompt changes and updates
+- **Command Dependencies**: Handle prompts that depend on other prompts
+
+But for now: Focus on core functionality - create well-structured prompts that integrate seamlessly with the existing Code Captain ecosystem.