@devobsessed/code-captain 0.0.8 → 0.1.0

package/windsurf/workflows/research.md

@@ -1,240 +0,0 @@
----
-description: "Conduct systematic research using structured phases with web search capabilities and actionable todos"
----
-
-# Research Workflow
-
-## Overview
-
-Conduct systematic research using structured phases with web search capabilities and actionable todos.
-
-## Usage
-
-```bash
-/research "topic description"
-```
-
-## Process
-
-### Phase 1: Define Research Scope
-
-**Create research todos:**
-
-Use memory feature to track progress:
-```
-- Phase 1: Define scope and questions [in_progress]
-- Phase 2: Initial discovery [pending]  
-- Phase 3: Deep dive analysis [pending]
-- Phase 4: Synthesis and recommendations [pending]
-```
-
-**Actions:**
-1. Define primary research question(s)
-2. Identify key stakeholders and information needs
-3. Set success criteria for research
-
-### Phase 2: Initial Discovery
-
-**Objective:** Gather broad understanding of topic landscape
-
-**Actions:**
-1. Use `search_web` with broad search terms
-2. Search for:
-   - Overview articles and introductory content
-   - Current trends and recent developments
-   - Key players and thought leaders
-   - Common terminology and concepts
-3. Document initial findings and themes
-4. Identify knowledge gaps for deeper investigation
-
-**Search Strategy:**
-- Start with general terms: "[topic] overview", "[topic] 2024", "[topic] trends"
-- Look for authoritative sources: documentation, whitepapers, industry reports
-- Note recurring themes for Phase 3
-
-### Phase 3: Deep Dive Analysis
-
-**Objective:** Investigate specific aspects identified in Phase 2
-
-**Actions:**
-1. Use `search_web` with targeted queries from Phase 2 findings
-2. Research specific sub-topics:
-   - Technical implementation details
-   - Pros and cons of different approaches
-   - Real-world case studies and examples
-   - Performance metrics and benchmarks
-3. Compare alternatives and trade-offs
-4. Validate claims from multiple sources
-
-**Search Strategy:**
-- Use specific terminology from Phase 2
-- Search for: "[approach] vs [alternative]", "[topic] case study", "[topic] performance"
-- Look for criticism and limitations, not just benefits
-
-### Phase 4: Synthesis and Recommendations
-
-**Objective:** Transform research into actionable insights
-
-**Actions:**
-1. Synthesize findings into key insights
-2. Create recommendations based on research
-3. Identify next steps or further investigation needs
-4. Document sources and evidence
-5. Create research document in `.code-captain/research/` folder
-
-**Deliverables:**
-- Executive summary of key findings
-- Pros/cons analysis of options
-- Specific recommendations with rationale
-- Risk assessment and mitigation strategies
-- Research document: `.code-captain/research/[DATE]-[topic-name]-research.md`
-
-## 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/research/[DATE]-[topic-name]-research.md`
-
-### Fallback Method
-
-If system clock access isn't available:
-1. Prompt: "What is today's date? (YYYY-MM-DD)"
-2. Validate against `^\d{4}-\d{2}-\d{2}$`
-3. Store the date for naming
-
-## Research Document Template
-
-Create: `.code-captain/research/[DATE]-[topic-name]-research.md`
-
-```markdown
-# [Topic Name] Research
-
-**Date:** [Current date]
-**Researcher:** [Name]
-**Status:** [In Progress/Complete]
-
-## Research Question(s)
-
-[Primary questions this research aimed to answer]
-
-## Executive Summary
-
-[2-3 paragraph overview of key findings and recommendations]
-
-## Background & Context
-
-[Why research was needed, current situation, stakeholders]
-
-## Methodology
-
-[How research was conducted, sources used, timeframe]
-
-## Key Findings
-
-### Finding 1: [Title]
-
-- **Evidence:** [Supporting data/sources]
-- **Implications:** [What this means for project/decision]
-
-### Finding 2: [Title]
-
-- **Evidence:** [Supporting data/sources]
-- **Implications:** [What this means for project/decision]
-
-## Options Analysis
-
-### Option 1: [Name]
-
-- **Pros:** [Benefits and advantages]
-- **Cons:** [Drawbacks and limitations]
-- **Cost/Effort:** [Implementation requirements]
-- **Risk Level:** [High/Medium/Low with explanation]
-
-### Option 2: [Name]
-
-- **Pros:** [Benefits and advantages]
-- **Cons:** [Drawbacks and limitations]
-- **Cost/Effort:** [Implementation requirements]
-- **Risk Level:** [High/Medium/Low with explanation]
-
-## Recommendations
-
-### Primary Recommendation
-
-[Specific recommended course of action with rationale]
-
-### Alternative Approaches
-
-[Secondary options if primary isn't feasible]
-
-### Implementation Considerations
-
-[Key factors to consider when moving forward]
-
-## Risks & Mitigation
-
-- **Risk 1:** [Description] → **Mitigation:** [How to address]
-- **Risk 2:** [Description] → **Mitigation:** [How to address]
-
-## Further Research Needed
-
-- [Questions/areas needing additional investigation]
-
-## Sources
-
-- [Source 1 with URL and access date]
-- [Source 2 with URL and access date]
-
-## Appendix
-
-[Additional detailed information, raw data, extended quotes]
-```
-
-## Best Practices
-
-### Search Strategy
-- Start broad, then narrow down
-- Use multiple search terms and phrasings
-- Look for recent content (last 1-2 years) for evolving topics
-- Cross-reference information from multiple sources
-- Search for both benefits AND criticisms
-
-### Critical Thinking
-- Question assumptions and biases in sources
-- Look for evidence, not just opinions
-- Consider source credibility and potential conflicts
-- Distinguish between correlation and causation
-- Identify missing information
-
-### Documentation
-- Keep track of sources for all claims
-- Note information dates (especially for fast-moving topics)
-- Document search process for reproducibility
-- Save important quotes with proper attribution
-
-## Common Pitfalls to Avoid
-
-- Confirmation bias (only seeking supporting information)
-- Stopping research too early when findings seem obvious
-- Not considering implementation challenges
-- Ignoring edge cases or limitations
-- Failing to consider stakeholder perspectives beyond your own
-
-## Implementation with Windsurf Tools
-
-**File Operations:**
-- Use `write_to_file` to create research documents
-- Use `view_file` to review existing research
-- Use `find_by_name` to locate related files
-
-**Research Tools:**
-- Use `search_web` for all web research phases
-- Use `codebase_search` for understanding current implementation
-- Use memory feature to track research progress and key findings
-
-**Integration:**
-- Works with existing `.code-captain/research/` directory structure
-- Feeds into Architecture Decision Records (ADRs)
-- Supports product planning and feature specification workflows 

package/windsurf/workflows/status.md

@@ -1,213 +0,0 @@
----
-description: Code Captain status report for project orientation and next actions
----
-
-# Code Captain Status Workflow
-
-## Overview
-Provides comprehensive status report when starting work or switching context. Analyzes git state, active work, and project health to orient developers and suggest next actions.
-
-## Core Functionality
-
-### 1. Git Status & Context Analysis
-Use `run_command` to gather git information:
-- Current branch and relationship to main/origin
-- Commits ahead/behind main branch  
-- Last commit message and timestamp
-- Uncommitted changes summary
-- Stash status
-
-### 2. Active Work Detection
-Use `codebase_search` and `view_file` to find:
-- Code Captain specs in `.code-captain/specs/`
-- Current task progress from most recent spec
-- Completed vs pending tasks
-- Current user story context
-
-### 3. Project Health Check
-Use `run_command` for language-specific checks:
-- Can the project build/compile?
-- Dependencies status (package.json, requirements.txt, etc.)
-- Configuration issues
-- Missing environment variables
-
-### 4. Contextual Suggestions
-Based on current state, suggest appropriate next commands.
-
-## Implementation Steps
-
-### Step 1: Git Analysis
-```bash
-# Use run_command for these git operations:
-git status --porcelain              # File changes
-git log --oneline -5                # Recent commits  
-git log main..HEAD --oneline        # Commits ahead
-git log HEAD..main --oneline        # Commits behind
-git stash list                      # Stashed changes
-git branch -v                       # Branch info
-```
-
-### Step 2: Code Captain Integration
-Use `find_by_name` to locate specs:
-```bash
-# Find most recent spec directory
-find .code-captain/specs -name "spec.md" -type f
-```
-
-Use `view_file` to read spec content and task progress:
-- Read overall progress from user stories overview
-- Parse individual story files for task completion
-- Count completed tasks (marked with [x])
-- Find next incomplete task
-
-### Step 3: Project Health
-Use `run_command` for health checks:
-```bash
-# Node.js
-npm run build --if-present
-node -c package.json
-
-# Python
-python -m py_compile main.py
-pip check
-```
-
-### Step 4: Generate Status Report
-
-**Output Format** (clean formatted text, not code blocks):
-
-```
-⚓ Code Captain Status Report
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📍 CURRENT POSITION
-   Branch: feature/dashboard-websockets (2 commits ahead of main)
-   Last commit: "Add WebSocket connection hook" (2 hours ago)
-   Uncommitted: 3 modified files in src/components/
-
-📋 ACTIVE WORK
-   Spec: Real-time Dashboard with WebSocket Integration 
-   Progress: Story 2 (User receives real-time notifications) - In Progress
-   Tasks completed: 3/6 tasks (50%)
-   Next task: 2.4 Implement client-side WebSocket connection
-
-🎯 SUGGESTED ACTIONS
-   • Continue with task 2.4 (WebSocket connection management)
-   • Commit current changes before switching tasks
-   • Review recent main branch changes
-
-⚡ QUICK COMMANDS
-   Execute task workflow    # Continue current task
-   Code cleanup workflow    # Quick code improvements
-   Sync main workflow       # Pull latest from main
-```
-
-## Task Progress Analysis
-
-### Parsing Logic
-For each story file in `user-stories/story-N-{name}.md`:
-
-1. **Count completed tasks**:
-   ```bash
-   grep -c "^\- \[x\].*✅" story-file.md
-   ```
-
-2. **Count total tasks**:
-   ```bash
-   grep -c "^\- \[[x ]\]" story-file.md
-   ```
-
-3. **Find next incomplete task**:
-   ```bash
-   grep -n "^\- \[ \]" story-file.md | head -1
-   ```
-
-4. **Extract status from story header**:
-   ```bash
-   grep "^> \*\*Status:\*\*" story-file.md
-   ```
-
-### Status Detection
-- `Not Started` - No tasks completed
-- `In Progress` - Some tasks completed, some remaining
-- `Completed ✅` - All tasks and acceptance criteria completed
-
-## Error Handling
-
-### Not a Git Repository
-```
-❌ Not in a git repository
-   Initialize git first: git init
-```
-
-### No Code Captain Structure
-```
-📋 ACTIVE WORK
-   No Code Captain specifications found
-   Project structure: Standard git repository
-
-🎯 SUGGESTED ACTIONS
-   • Set up Code Captain workflow
-   • Create first feature specification
-```
-
-### Project Issues
-```
-⚠️  PROJECT ISSUES DETECTED
-   • package.json syntax error
-   • Missing critical dependencies
-   • Build process failing
-
-🔧 SUGGESTED FIXES
-   • Fix package.json syntax
-   • Run npm install or equivalent
-   • Check build configuration
-```
-
-## Decision Tree for Suggestions
-
-1. **Merge conflict?** → Suggest conflict resolution
-2. **Working directory dirty?** → Suggest commit or stash
-3. **Branch behind main?** → Suggest sync
-4. **Active task?** → Suggest continue task
-5. **Current task complete?** → Suggest next task
-6. **No active work?** → Suggest create spec
-7. **Always** → Suggest code cleanup
-
-## Usage Patterns
-
-### Morning Routine
-Developer starts day, gets oriented on yesterday's work, sees exactly what to do next.
-
-### Context Switching  
-After meetings or interruptions, quick reminder of current state, resume work efficiently.
-
-### Project Handoff
-When picking up someone else's work, understand current project state without diving into code.
-
-## Performance Considerations
-
-- Target <2 second execution time
-- Limit git log queries to reasonable ranges
-- Cache expensive operations when possible
-- Use efficient file scanning with `find_by_name`
-
-## Windsurf Tools Used
-
-- `run_command`: Git operations, build checks
-- `codebase_search`: Find specs and project structure
-- `view_file`: Read spec content and progress
-- `find_by_name`: Locate Code Captain files
-- `grep_search`: Parse task completion status
-- `list_dir`: Directory structure analysis
-
-## Security & Privacy
-
-- All analysis happens locally
-- No external API calls or data transmission
-- Git history and file contents remain private
-- Sanitize sensitive information in output
-
----
-
-*⚓ Keep your bearings, maintain your heading, and always know where you stand in the code.*

package/windsurf/workflows/swab.md

@@ -1,212 +0,0 @@
----
-description: "A deck-cleaning workflow that makes one small, focused improvement to the codebase following the Boy Scout Rule"
----
-
-# Swab Workflow
-
-## Overview
-
-A deck-cleaning workflow that makes one small, focused improvement to the codebase, following the "Boy Scout Rule" - leave the code cleaner than you found it. Identifies the single best small cleanup opportunity and applies it with your approval.
-
-## Usage
-
-```bash
-/swab
-```
-
-**Note:** No options, no flags, no complexity. Just simple deck cleaning.
-
-## Process
-
-### Step 1: Codebase Scanning
-
-**Scan for improvement opportunities:**
-
-- Search project files for common code smells
-- Analyze file patterns and naming conventions  
-- Identify low-risk, high-impact improvements
-- Focus on clarity and maintainability wins
-
-**Target Areas:**
-- Unclear variable names (`d`, `temp`, `data`, single letters)
-- Magic numbers that should be constants
-- Missing error handling on JSON.parse, API calls
-- Commented-out code blocks
-- Inconsistent formatting patterns
-- Overly abbreviated names
-- Unused imports or variables
-
-### Step 2: Opportunity Prioritization
-
-**Selection Criteria:**
-1. **Clarity Impact** - How much clearer will the code be?
-2. **Risk Level** - How certain are we this won't break anything?
-3. **Scope** - Prefer 1-10 line changes maximum
-4. **Confidence** - Only suggest changes we're 100% certain about
-
-**Priority Order:**
-1. Variable/function name improvements
-2. Magic number extraction to constants
-3. Adding missing error handling
-4. Removing dead code
-5. Formatting consistency fixes
-
-### Step 3: Present Single Best Option
-
-**Display Format:**
-```
-🧽 Swabbing the deck... found some mess in {filename}
-
-=== SUGGESTED CLEANUP ===
-
-- {before_code}
-+ {after_code}
-
-Reason: {clear_explanation}
-Risk: {Low|Medium}
-
-Clean this up? [y/N]
-```
-
-### Step 4: Apply Change
-
-**If approved:**
-- Make the exact replacement using search/replace
-- Verify the change was applied correctly
-- Show success message: "✅ Deck swabbed! One less mess aboard."
-
-**If declined:**
-- Exit gracefully with: "🧽 Deck inspection complete. No changes made."
-
-## Core Rules
-
-1. **One change only** - Never fix multiple things at once
-2. **Small changes** - Maximum 10 lines modified
-3. **Safe changes** - If uncertain, do nothing
-4. **Your approval required** - Always ask before applying
-5. **Exact replacements** - Surgical precision, no formatting noise
-6. **Conservative approach** - Better to find nothing than break something
-
-## Implementation with Windsurf Tools
-
-### Codebase Scanning Strategy
-
-**File Discovery:**
-- Use `codebase_search` to find code patterns and smells across source files
-- Use `find_by_name` to locate relevant files and directories
-- Use `view_file` to inspect file contents when needed
-- Focus on recently modified files first (higher likelihood of improvement opportunities)
-
-**Content Analysis:**
-- Use `view_file` for reading file contents for analysis
-- Use `codebase_search` for pattern detection
-- Focus on files under 500 lines for simplicity
-- Prioritize recently modified files
-
-### Change Application
-
-**File Modification:**
-```bash
-# Use replace_file_content for exact string replacement
-replace_file_content(
-  file_path=target_file,
-  old_content=exact_match_text,
-  new_content=improved_text
-)
-```
-
-**Verification:**
-- Re-read file with `view_file` to confirm change applied correctly
-- Run basic syntax validation if available
-- Ensure no unintended modifications occurred
-
-### Error Handling
-
-**No opportunities found:**
-```
-🧽 Deck inspection complete. 
-
-No obvious cleanup opportunities found in the scanned files.
-Your codebase looks pretty tidy already! ✨
-
-Run again later as the code evolves, or try focusing on a specific directory.
-```
-
-**Multiple opportunities found:**
-- Always pick the highest-impact, lowest-risk option
-- Never present multiple options (causes decision paralysis)
-- Save other opportunities for future runs
-
-**Change application failure:**
-```
-❌ Swab attempt failed. 
-
-The suggested change couldn't be applied safely.
-This might happen if the file was modified since scanning.
-Try running the workflow again.
-```
-
-## Analysis Prompt for AI
-
-```
-You are a code reviewer cleaning up small messes.
-
-MISSION: Find exactly ONE small, safe cleanup opportunity in the codebase.
-
-RULES:
-- Find ONE small cleanup only (1-10 lines max changed)
-- Prioritize clarity and safety over cleverness
-- Preserve all existing functionality exactly
-- Be extremely conservative - if ANY uncertainty, do nothing
-- Provide exact search/replace strings
-- Focus on high-impact, zero-risk improvements
-
-SCAN PRIORITIES:
-1. Unclear variable names (single letters, abbreviations)
-2. Magic numbers that should be named constants
-3. Missing error handling (JSON.parse, fetch, etc.)
-4. Dead/commented code removal
-5. Minor formatting consistency
-
-RESPONSE FORMAT:
-If you find a good cleanup opportunity:
-{
-  "cleanup": "Brief description of the improvement",
-  "filename": "path/to/file.js",
-  "searchText": "exact text to find (with proper whitespace)",
-  "replaceText": "exact replacement text (with proper whitespace)",
-  "reasoning": "Why this specific change helps readability/maintainability",
-  "riskLevel": "Low|Medium",
-  "linesChanged": number_of_lines_modified
-}
-
-If no clear, safe cleanup exists:
-{
-  "cleanup": null,
-  "message": "No obvious cleanup opportunities found. Codebase looks tidy!"
-}
-
-CRITICAL: Only suggest changes you are 100% confident about. When in doubt, suggest nothing.
-```
-
-## Integration Notes
-
-This workflow integrates with the existing Code Captain ecosystem by:
-
-1. **Following established patterns** - Uses same markdown structure as other workflows
-2. **Leveraging Windsurf tools** - Uses `codebase_search`, `view_file`, `replace_file_content`
-3. **Maintaining simplicity** - No complex configuration or state management
-4. **Respecting user control** - Always asks permission before making changes
-5. **Quality foundation** - Complements specification and implementation commands by maintaining code quality, supporting the overall project foundation alongside `.code-captain` documentation
-
-## Future Enhancements
-
-Potential future improvements (not in initial version):
-
-- **Directory targeting**: `/swab src/components/`
-- **File type filtering**: `/swab --js-only`
-- **Batch mode**: `/swab --batch` (apply multiple small changes)
-- **Learning**: Remember which types of cleanups user prefers
-- **Metrics**: Track improvements made over time
-
-But for now: Keep it simple. One workflow, one small improvement, user approval required.