@devobsessed/code-captain 0.1.0 → 0.2.1

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

@@ -1,12 +1,13 @@
 ---
-mode: agent
+agent: agent
+description: "Generate comprehensive code explanations with diagrams"
 ---
 
-# Explain Code Command
+# You are executing the Explain Code command.
 
-## Overview
+You MUST follow these instructions exactly. Do NOT describe this process — execute it.
 
-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.
+Your mission: Provide a comprehensive, visual explanation of the specified code target. Combine natural language explanations with Mermaid diagrams to help the developer understand the code quickly and thoroughly.
 
 ## Parameters
 
@@ -46,31 +47,31 @@ The command automatically:
 
 ## Output Structure
 
-All explanations are displayed in chat and automatically saved to `.code-captain/explanations/`
+Display in chat and automatically save to `.code-captain/explanations/`.
 
 ### Chat Display
 
 ```
-📋 Function Overview
+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
+Execution Flow
 ├── [Flowchart diagram showing decision paths]
 ├── Decision points and branches
 ├── Error handling paths
 └── Performance characteristics
 
-🏗️ Architecture Context
+Architecture Context
 ├── Where this fits in the system
 ├── Dependencies and related components
 ├── Design patterns used
 └── Integration points
 
-⚡ Technical Details
+Technical Details
 ├── Time complexity
 ├── Memory usage
 ├── Potential issues
@@ -79,6 +80,8 @@ All explanations are displayed in chat and automatically saved to `.code-captain
 
 ### Saved Format
 
+Save as `.code-captain/explanations/[DATE]-[target-name].md`:
+
 ````markdown
 # Code Explanation: [Target Name]
 
@@ -116,99 +119,11 @@ _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`.
-
 Get current date by running: `npx @devobsessed/code-captain date`
 
-**Example filename:** `.code-captain/explanations/2025-09-27-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
+Save all explanations automatically to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`.
 
 ## AI Processing Workflow
 
@@ -217,7 +132,7 @@ All explanations use a consistent intermediate technical level that balances acc
 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`
+6. **Auto-Save**: Save explanation to `.code-captain/explanations/` with date-prefixed filename
 
 ## Tool Integration
 
@@ -234,43 +149,3 @@ All explanations use a consistent intermediate technical level that balances acc
 - 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

@@ -1,14 +1,13 @@
 ---
-mode: agent
+agent: agent
+description: "Analyze and set up project foundation with documentation"
 ---
 
-# Initialize Command
+# You are executing the Initialize command.
 
-## Overview
+You MUST follow these instructions exactly. Do NOT describe this process — execute it.
 
-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
+Your mission: Analyze the current project and set up the technical foundation. Detect whether this is a greenfield (new) or brownfield (existing) project, scan the codebase, and generate foundational documentation.
 
 ### Step 1: Project Type Detection
 
@@ -35,10 +34,10 @@ Analyze and set up technical foundation for either greenfield (new) or brownfiel
 
 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
+- **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
 
@@ -61,5 +60,3 @@ Provide clear guidance on next steps, typically:
 **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

@@ -1,12 +1,13 @@
 ---
-mode: agent
+agent: agent
+description: "Create new Code Captain commands following established patterns"
 ---
 
-# New Command Creator
+# You are executing the New Command command.
 
-## Overview
+You MUST follow these instructions exactly. Do NOT describe this process — execute it.
 
-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.
+Your mission: Create a new Code Captain command file following established patterns and conventions. Generate a properly structured prompt file and provide integration guidance.
 
 ## Examples
 
@@ -14,15 +15,13 @@ A meta command that creates new Code Captain commands following established patt
 # Create optimization command
 /new-command "optimize" "Performance optimization for slow code sections"
 
-# Create deployment command  
+# 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:**
@@ -47,15 +46,15 @@ Ask clarifying questions to build complete command specification:
 
 ```markdown
 ---
-mode: agent
+agent: agent
+description: "[Short description]"
 ---
 
-# [Command Name] Command
+# You are executing the [Command Name] command.
 
-## Overview
-[Generated from description and clarifying questions]
+You MUST follow these instructions exactly. Do NOT describe this process — execute it.
 
-## Command Process
+Your mission: [Generated from description and clarifying questions]
 
 ### Step 1: [Phase Name]
 [Generated workflow steps]
@@ -65,15 +64,9 @@ mode: agent
 
 ## 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:**
+**Template Adaptation Based on Execution Style:**
 
 **Contract Style Commands** (like `/create-spec`, `/create-adr`):
 - Phase 1: Contract Establishment (No File Creation)
@@ -88,36 +81,6 @@ mode: agent
 - Clear step-by-step execution
 - Progress feedback and completion confirmation
 
-**Foundation Commands:**
-- Project initialization steps
-- Planning and product setup workflows
-- Configuration and environment setup
-
-**Analysis Commands:**
-- Context scanning steps
-- Research and analysis workflows
-- Documentation review and assessment
-
-**Specification Commands:**
-- Specification creation and editing
-- Structured documentation workflows
-- Contract-based clarification processes
-
-**Implementation Commands:**
-- TDD workflows if applicable
-- Code modification steps
-- Task execution procedures
-
-**Quality Commands:**
-- Health and status reporting
-- QA-oriented checks and validations
-- Lightweight remediation workflows
-
-**Meta Commands:**
-- Command scaffolding and documentation updates
-- Code understanding and explanation
-- Process and tooling refinements
-
 ### Step 3: Documentation Integration
 
 **Provide guidance for documentation updates:**
@@ -142,15 +105,15 @@ mode: agent
 
 **Present Summary:**
 ```
-✅ New command prompt created successfully!
+New command prompt created successfully!
 
-📁 Generated Content:
+Generated Content:
   - .github/prompts/[command-name].prompt.md
   - Complete prompt file structure with frontmatter
   - Usage examples and documentation
   - Integration guidelines and recommendations
 
-🚀 Command Ready:
+Command Ready:
   Usage: /[command-name] [args]
   Implementation: Follow generated prompt structure
 ```
@@ -159,159 +122,30 @@ mode: agent
 
 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
+3. **Integration Guidance** - Provide 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
+6. **Language & Shell Agnostic** - Commands should work across different programming languages and shell environments
 
-```
-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
-- Foundation commands: Include project initialization, planning workflows, configuration setup
-- Analysis commands: Include context scanning, research workflows, documentation assessment
-- Specification commands: Include specification creation, structured documentation, contract-based processes
-- Implementation commands: Include TDD workflows, code modification, task execution
-- Quality commands: Include health and status reporting, QA-oriented checks and validations, lightweight remediation workflows
-- Meta commands: Include command scaffolding and documentation updates, code understanding and explanation, process and tooling refinements
-- 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$"
-```
-
-### Command Categories
+## Command Categories
 
 Commands are organized into logical categories:
 
 1. **Foundation** (`initialize`, `plan-product`)
-2. **Analysis** (`research`, `create-adr`)  
-3. **Specification** (`create-spec`, `edit-spec`)
-4. **Implementation** (`execute-task`)
-5. **Quality** (`status`, `swab`)
-6. **Meta** (`new-command`, `explain-code`)
-
-### Template Selection Logic
-
-**Command Categories and Templates:**
-
-1. **Foundation** (`initialize`, `plan-product`)
-   - Project initialization workflows
-   - Planning and setup processes
-   - Configuration and environment preparation
-
 2. **Analysis** (`research`, `create-adr`)
-   - Context scanning workflows
-   - Documentation generation
-   - Research and assessment emphasis
-
 3. **Specification** (`create-spec`, `edit-spec`)
-   - Interactive clarification phases
-   - Structured output formats
-   - Contract-based workflows
-
 4. **Implementation** (`execute-task`)
-   - Code modification workflows
-   - TDD patterns
-   - Task execution steps
-
 5. **Quality** (`status`, `swab`)
-   - Health and status reporting
-   - QA-oriented checks and validations
-   - Lightweight remediation workflows
-
 6. **Meta** (`new-command`, `explain-code`)
-   - Command scaffolding and documentation updates
-   - Code understanding and explanation
-   - Process and tooling refinements
-
-
-
-### 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
+## Command Name Validation
 
-Try: /new-command "valid-name" "clear description"
-```
+**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
 
 ## Tool Integration
 
@@ -325,25 +159,3 @@ Try: /new-command "valid-name" "clear description"
 - 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.