@devobsessed/code-captain 0.0.3

package/windsurf/workflows/execute-task.md

@@ -0,0 +1,276 @@
+---
+description: Execute specific tasks systematically following Test-Driven Development workflow with comprehensive testing
+---
+
+# Execute Task Workflow
+
+## Overview
+Execute specific tasks and sub-tasks systematically following a Test-Driven Development (TDD) workflow. Reads task specifications from `.code-captain/specs/` directories and implements features with comprehensive testing, following established code standards and best practices.
+
+## CRITICAL REQUIREMENT: 100% Test Pass Rate
+
+**⚠️ ZERO TOLERANCE FOR FAILING TESTS ⚠️**
+
+This workflow enforces strict test validation:
+- **NO story can be marked "COMPLETED" with ANY failing tests**
+- **100% test pass rate is MANDATORY before completion**
+- **"Edge case" or "minor" test failures are NOT acceptable**
+- **Implementation is considered incomplete until all tests pass**
+
+If tests fail, the story remains "IN PROGRESS" until all failures are resolved.
+
+## Command Process
+
+### Step 1: Task Discovery & Selection
+
+**Scan for available specifications:**
+
+- Use `find_by_name` to search `.code-captain/specs/` for dated specification folders
+- Use `view_file` to load user stories from `user-stories/` folders in each spec
+- Use `view_file` to read `user-stories/README.md` for story overview and progress
+- Use `view_file` to parse individual `story-N-{name}.md` files for available tasks
+- Present available stories and tasks organized by specification
+
+**Story selection process:**
+
+1. **If multiple specs exist**: Present selection menu with spec dates and story summaries
+2. **If single spec exists**: Show available stories and their tasks within that specification
+3. **If story/task specified**: Validate story exists and select specific task for execution
+4. **If no specs exist**: Guide user to run create-spec workflow first
+
+**Selection format:**
+```
+Available specifications:
+├── 2024-01-15-user-auth/ (3 stories, 12 total tasks)
+│   ├── Story 1: User Registration (5 tasks) - Not Started
+│   ├── Story 2: User Login (4 tasks) - Not Started
+│   └── Story 3: Password Reset (3 tasks) - Not Started
+└── 2024-01-20-payment-system/ (2 stories, 8 total tasks)
+    ├── Story 1: Payment Processing (5 tasks) - In Progress (2/5)
+    └── Story 2: Refund Management (3 tasks) - Not Started
+```
+
+### Step 2: Context Gathering & Analysis
+
+**Load specification context:**
+
+- Use `view_file` to read primary spec document: `spec.md`
+- Use `view_file` to load user stories overview: `user-stories/README.md`
+- Use `view_file` to read selected story file: `user-stories/story-N-{name}.md`
+- Use `view_file` to review technical specifications: `sub-specs/technical-spec.md`
+- Parse task breakdown from individual story file
+
+**Analyze current codebase:**
+
+Use `codebase_search` to understand:
+- Current architecture and patterns
+- Related existing functionality
+- Integration points for new features
+- Testing frameworks and conventions
+
+**Load project standards:**
+- Code style guide: `.code-captain/docs/code-style.md`
+- Technology stack: `.code-captain/docs/tech-stack.md`
+- Best practices: `.code-captain/docs/best-practices.md`
+
+### Step 3: Story & Task Analysis
+
+**Parse selected story structure:**
+
+- Use `view_file` to load complete story file: `user-stories/story-N-{name}.md`
+- Extract user story, acceptance criteria, and implementation tasks
+- Analyze task dependencies and execution order within the story
+- Understand test requirements (first task typically writes tests)
+- Plan implementation approach based on story's task breakdown
+
+**Validate TDD approach within story:**
+
+- **First task**: Should write tests for the story functionality
+- **Middle tasks**: Implement functionality to pass tests (max 5-7 tasks total)
+- **Final task**: Verify all tests pass and acceptance criteria are met
+- **Integration considerations**: Update adjacent/related tests as needed
+
+**Story structure:** User story → Acceptance criteria → Implementation tasks (max 5-7 tasks, first task writes tests, final task verifies 100% pass rate)
+
+### Step 4: Pre-Implementation Preparation
+
+**Validate testing setup:**
+- Use `codebase_search` to confirm testing framework is configured
+- Use `find_by_name` to verify test directories and naming conventions
+- Use `view_file` to check existing test patterns and utilities
+- Use `run_command` to ensure test runner is functional
+
+### Step 5: Story Task Execution (TDD Workflow)
+
+**Execute story tasks in sequential order:**
+
+#### Task 1: Write Tests (Test-First Approach)
+
+**Actions:**
+- Write comprehensive test cases for the entire feature using `write_to_file`
+- Include unit tests, integration tests, and edge cases
+- Cover happy path, error conditions, and boundary cases
+- Ensure tests fail appropriately (red phase)
+
+**Test categories to include:**
+- **Unit tests**: Individual function/method testing
+- **Integration tests**: Component interaction testing
+- **Edge cases**: Boundary conditions and error scenarios
+- **Acceptance tests**: User story validation
+
+#### Tasks 2-N: Implementation (Green Phase)
+
+**For each implementation task within the story:**
+
+1. **Focus on specific functionality**: Implement only what's needed for current task
+2. **Make tests pass**: Write minimal code to satisfy failing tests using `replace_file_content`
+3. **Update related tests**: Modify adjacent tests if behavior changes
+4. **Maintain compatibility**: Ensure no regressions in existing functionality
+5. **Refactor when green**: Improve code quality while tests remain passing
+
+**Implementation approach:**
+- Start with simplest implementation that passes tests
+- Add complexity incrementally as required by test cases
+- Keep tests passing at each step using `run_command` to verify
+- Refactor for clarity and maintainability
+
+#### Final Task: Test & Acceptance Verification
+
+**CRITICAL: 100% Test Pass Rate Required**
+
+**Mandatory Actions (ALL must succeed before story completion):**
+
+1. **Run complete test suite for this story** using `run_command`
+2. **Achieve 100% pass rate for ALL tests** - NO EXCEPTIONS
+3. **Verify no regressions in existing test suites**
+4. **Validate all acceptance criteria are met for the user story**
+5. **Confirm story delivers the specified user value**
+
+**⚠️ STORY CANNOT BE MARKED COMPLETE WITH ANY FAILING TESTS ⚠️**
+
+If ANY tests fail:
+- **STOP IMMEDIATELY** - Do not mark story as complete
+- Debug and fix each failing test
+- Re-run test suite until 100% pass rate achieved
+- Only then proceed to mark story as complete
+
+### Step 6: Story-Specific Test Validation
+
+**Run targeted test validation:**
+
+Use `run_command` to verify:
+- All tests written in first task are passing
+- New functionality works as specified in user story
+- All acceptance criteria are satisfied
+- No regressions introduced to existing features
+- Performance requirements are met (if specified)
+
+**Test execution strategy:**
+- **First**: Run only tests for current story/feature
+- **Then**: Run related test suites to check for regressions
+- **Finally**: Consider full test suite if significant changes made
+- **Acceptance**: Validate user story acceptance criteria are met
+
+**Failure handling:**
+
+**ZERO TOLERANCE FOR FAILING TESTS:**
+- **If ANY tests fail**: Story CANNOT be marked complete
+- **Required action**: Debug and fix ALL failing tests before proceeding
+- **No exceptions**: "Edge case" or "minor" failing tests are NOT acceptable
+- **If performance issues**: Optimize implementation until all tests pass
+- **If regressions found**: Fix regressions - story completion is blocked until resolved
+
+**Failure Resolution Process:**
+1. Identify root cause of each failing test
+2. Fix implementation to make test pass using `replace_file_content`
+3. Re-run ALL tests using `run_command` to ensure 100% pass rate
+4. Repeat until NO tests fail
+5. Only then mark story as complete
+
+### Step 7: Story Completion & Status Updates
+
+**Update story file status:**
+
+Use `replace_file_content` to mark completed tasks in story file:
+- Change status from "Not Started" to "Completed ✅"
+- Mark all tasks as [x] with ✅
+- Mark all acceptance criteria as [x] with ✅
+- Update Definition of Done with **ALL tests passing (100% pass rate)** ✅ **MANDATORY**
+- Add note: "Story CANNOT be marked complete without 100% test pass rate"
+
+**Update stories overview:**
+
+Use `replace_file_content` to update progress tracking in `user-stories/README.md`:
+
+```markdown
+| Story | Title | Status | Tasks | Progress |
+|-------|-------|--------|-------|----------|
+| 1 | User Authentication | Completed ✅ | 5 | 5/5 ✅ |
+| 2 | Password Reset | Not Started | 4 | 0/4 |
+| 3 | Profile Management | Not Started | 6 | 0/6 |
+
+**Total Progress:** 5/15 tasks (33%)
+```
+
+**Document completion:**
+- Update spec status if all stories in the specification are complete
+- Note any deviations from original plan in story notes
+- Document lessons learned or improvements made
+- Identify any follow-up tasks or technical debt
+
+**Present completion summary:**
+
+**If ALL tests pass (100%):** "Story completed successfully: [Story name] - Tasks: X/X ✅ - Tests: X/X (100%) ✅ - Next stories available"
+
+**If ANY tests fail:** "Story INCOMPLETE - Tests failing: [Story name] - Tests: X/Y (Z%) ❌ COMPLETION BLOCKED - Must fix all failing tests before completion"
+
+### Step 8: Create Memory of Completed Story (Optional)
+After successful story completion, ask Cascade:
+"Please create a memory of this completed story: [story name and key implementation approach, noting 100% test pass achievement]"
+
+## Integration with Code Captain Ecosystem
+
+**Specification dependency:**
+- Requires existing spec created by create-spec workflow
+- Uses story breakdown from `user-stories/` folder in spec directories
+- Loads individual story files: `user-stories/story-N-{name}.md`
+- Tracks progress in `user-stories/README.md`
+- Follows technical approach from `sub-specs/technical-spec.md`
+
+**Code style compliance:**
+- Adheres to patterns in `.code-captain/docs/code-style.md`
+- Uses technology stack from `.code-captain/docs/tech-stack.md`
+- Follows best practices from `.code-captain/docs/best-practices.md`
+
+## Quality Standards
+
+**TDD:** Tests before implementation, **100% pass rate MANDATORY**, ZERO TOLERANCE for failures, comprehensive coverage, regression testing, failed tests = incomplete implementation.
+
+**Code quality:** Follow project patterns, maintain compatibility, proper error handling, appropriate logging.
+
+## Error Handling & Best Practices
+
+**Common failures:** No specs (→ create-spec), test framework issues (→ setup guidance), implementation conflicts (→ resolution strategies), performance issues (→ optimization)
+
+**Blocking issues:** Document as `⚠️ Blocking issue: [DESCRIPTION]` in story notes. Try alternatives, research solutions, break down tasks. Max 3 attempts before escalating.
+
+**TDD adherence:** Start with failing tests, minimal code to pass, refactor when green. **MANDATORY: 100% test pass rate before completion. NO EXCEPTIONS.**
+
+**Development:** Sequential tasks, verify each step with `run_command`, test early, validate incrementally, update status immediately, document decisions.
+
+## Windsurf Tools Used
+
+- `find_by_name`: Locate specifications, story files, and test directories
+- `view_file`: Read specification documents, story files, and existing code
+- `write_to_file`: Create test files and new implementation files
+- `replace_file_content`: Update existing code and story status files
+- `codebase_search`: Understand current architecture and patterns
+- `run_command`: Execute tests, verify functionality, and run build processes
+
+## Windsurf Features Used
+
+- **Memories**: After completion, optionally create memory of completed story and implementation approach
+
+---
+
+*🧪 Tests first, code second, success always. No compromises on quality.*

package/windsurf/workflows/explain-code.md

@@ -0,0 +1,292 @@
+---
+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 - 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 for file naming
+
+**Fallback method - User confirmation:**
+If file system method fails:
+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.*