@devobsessed/code-captain 0.0.3

package/cursor/commands/status.md

@@ -0,0 +1,413 @@
+# Code Captain Status Command (cc: status)
+
+## Overview
+A command that provides developers with a comprehensive status report when starting work or switching context. Analyzes current git state, active work, and project health to orient developers and suggest next actions.
+
+## Command Structure
+
+```bash
+cc: status
+```
+
+Simple, no parameters needed. Works in any git repository with optional Code Captain project structure.
+
+## Core Functionality
+
+### 1. Git Status & Context Analysis
+**Current Position:**
+- Branch name and relationship to main/origin
+- Commits ahead/behind main branch
+- Last commit message and timestamp
+- Uncommitted changes summary (files modified, added, deleted)
+- Stash status if any
+
+**Recent Activity:**
+- Last 3-5 commits on current branch
+- Recent activity on main branch that might affect current work
+- Branch age and creation context
+
+### 2. Active Work Detection
+**Code Captain Integration:**
+- Scan `.code-captain/specs/` for active specifications
+- Parse current task progress from most recent spec's tasks.md
+- Identify completed vs pending tasks
+- Determine current user story context
+
+**Project Context:**
+- Detect if work appears to be mid-feature vs starting fresh
+- Identify obvious next steps based on file changes
+- Check for TODO comments in recently modified files
+
+### 3. Project Health Check
+**Basic Viability:**
+- Can the project build/compile? (language-specific checks)
+- Are core services startable?
+- Any obvious configuration issues?
+- Dependencies status (package.json, requirements.txt, etc.)
+
+**Immediate Blockers:**
+- Merge conflicts that need resolution
+- Missing environment variables or config files
+- Failed builds or critical errors
+
+### 4. Contextual Command Suggestions
+**Based on Current State:**
+- If mid-task: Suggest `cc: execute-task`
+- If no active work: Suggest `cc: create-spec`
+- If specifications exist: Suggest `cc: create-github-issues`
+- Always suggest `cc: swab` for code cleanup
+
+## Output Format
+
+**Important**: The status report should be output as **clean, formatted text** (not wrapped in code blocks) for optimal readability in the chat interface.
+
+### Standard Status Report
+
+⚓ 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%)
+   Last completed: 2.3 Create notification display component ✅
+   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 (3 new commits)
+
+⚡ QUICK COMMANDS
+   cc: execute-task     # Continue current task
+   cc: commit-wip       # Commit work in progress  
+   cc: sync-main        # Pull latest from main
+   cc: swab             # Quick code cleanup
+
+### Clean State Example
+
+⚓ Code Captain Status Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📍 CURRENT POSITION
+   Branch: main (up to date)
+   Last commit: "Fix user authentication bug" (1 day ago)
+   Working directory: Clean ✅
+
+📋 ACTIVE WORK
+   No active specifications found
+   Ready to start new work
+
+🎯 SUGGESTED ACTIONS
+   • Start new feature development
+   • Review pending issues or backlog
+   • Perform maintenance tasks
+
+⚡ QUICK COMMANDS
+   cc: create-spec      # Plan new feature
+   cc: swab             # Clean up existing code
+   cc: review-specs     # Check previous specifications
+
+### Problem State Example
+
+⚓ Code Captain Status Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📍 CURRENT POSITION
+   Branch: feature/payment-flow (5 commits ahead, 2 behind main)
+   Last commit: "WIP: payment validation" (3 days ago)
+   Uncommitted: 7 modified files, 2 conflicts
+
+⚠️  IMMEDIATE ATTENTION
+   • Merge conflicts in src/api/payments.js, package.json
+   • Branch is 2 commits behind main (potential conflicts)
+   • Stashed changes from 2 days ago
+
+📋 ACTIVE WORK
+   Spec: Payment Processing Integration
+   Progress: Story 1 (User completes payment flow) - In Progress
+   Tasks completed: 3/5 tasks (60%)
+   Status: Task 1.4 appears incomplete
+   Next task: 1.4 Validate payment with external API
+
+🎯 SUGGESTED ACTIONS
+   • Resolve merge conflicts first
+   • Sync with main branch changes
+   • Review stashed changes for relevance
+   • Continue or restart task 1.4
+
+⚡ QUICK COMMANDS
+  cc: execute-task     # Continue current task
+  cc: swab            # Code cleanup
+
+## Implementation Details
+
+### Output Presentation
+
+**Critical**: When Code Captain executes the status command, the report should be presented as **clean, formatted text** directly in the chat response, NOT wrapped in code blocks or markdown formatting. This ensures maximum readability and a professional presentation.
+
+The status report uses Unicode characters (⚓, 📍, 📋, 🎯, ⚡, ⚠️) and box-drawing characters (━) for visual appeal. These should be output exactly as shown in the examples above.
+
+### Git Analysis
+**Commands to Run:**
+```bash
+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
+```
+
+**Parsing Logic:**
+- Extract meaningful context from commit messages
+- Detect work patterns (feature vs bug fix vs refactor)
+- Identify if work appears complete or in-progress
+- Calculate time since last activity
+
+### Code Captain Integration
+
+**Spec Detection:**
+```bash
+# Find most recent spec directory
+LATEST_SPEC=$(ls -t .code-captain/specs/*/spec.md | head -1 | xargs dirname)
+
+# Read overall progress from user stories overview
+cat "$LATEST_SPEC/user-stories/README.md"
+
+# Find all individual story files
+ls "$LATEST_SPEC/user-stories/story-"*.md
+```
+
+**Task Progress Analysis:**
+
+For each individual story file (`user-stories/story-N-{name}.md`), parse the Implementation Tasks section:
+
+```bash
+# Count completed tasks (marked with [x])
+grep -c "^\- \[x\].*✅" story-file.md
+
+# Count total tasks (any checkbox)
+grep -c "^\- \[[x ]\]" story-file.md
+
+# Find next incomplete task
+grep -n "^\- \[ \]" story-file.md | head -1
+```
+
+**Story Status Detection:**
+
+Parse the story status from the header:
+```bash
+# Extract status from story file header
+grep "^> \*\*Status:\*\*" story-file.md
+```
+
+Possible statuses:
+- `Not Started` - No tasks completed
+- `In Progress` - Some tasks completed, some remaining  
+- `Completed ✅` - All tasks and acceptance criteria completed
+
+**Progress Analysis:**
+- Count completed vs total tasks across all stories
+- Identify current active story (has In Progress status)
+- Extract next logical task from current story
+- Detect if entire spec work is complete
+- Parse progress summary from `user-stories/README.md` table
+
+**Active Work Prioritization:**
+
+1. **Multiple specs exist**: Show the most recently modified spec (based on file timestamps)
+2. **Single spec, multiple stories**: Show the story with "In Progress" status, or first "Not Started" story if none in progress
+3. **All stories complete**: Show overall completion status and suggest next actions
+4. **No specs found**: Indicate no Code Captain specifications exist
+
+**Task Parsing Edge Cases:**
+
+Handle various task formats that may exist in story files:
+```bash
+# Standard format with checkmark
+- [x] 1.1 Implement authentication ✅
+
+# Format without checkmark emoji
+- [x] 1.1 Implement authentication
+
+# Incomplete task
+- [ ] 1.2 Add validation logic
+
+# Tasks with sub-items (count as single task)
+- [x] 1.3 Database setup
+  - Created user table
+  - Added indexes
+```
+
+**Validation:**
+- Only count top-level task items (lines starting with `- [`)
+- Ignore indented sub-items
+- Handle both `[x]` and `[X]` as completed
+- Treat any other character in brackets as incomplete
+
+### Project Health Checks
+**Language-Specific:**
+```bash
+# Node.js
+npm run build --if-present
+node -c package.json
+
+# Python  
+python -m py_compile main.py
+pip check
+
+# General
+# Check for .env.example vs .env
+# Verify critical config files exist
+```
+
+### Command Suggestion Logic
+**Decision Tree:**
+1. **Is there a merge conflict?** → Suggest conflict resolution
+2. **Is working directory dirty?** → Suggest commit or stash
+3. **Is branch behind main?** → Suggest sync
+4. **Is there an active task?** → Suggest continue task
+5. **Is current task complete?** → Suggest next task
+6. **No active work?** → Suggest create spec
+7. **Always:** → Suggest swab for cleanup
+
+## Usage Patterns
+
+### Morning Routine
+```bash
+# Developer starts their day
+$ cc: status
+
+# Gets oriented on yesterday's work
+# Sees exactly what to do next
+# Jumps into flow state quickly
+```
+
+### Context Switching
+```bash
+# After meetings, interruptions, or breaks
+$ cc: status
+
+# Quick reminder of current state
+# Understand what changed while away
+# Resume work efficiently
+```
+
+### Project Handoff
+```bash
+# When picking up someone else's work
+$ cc: status
+
+# Understand current project state
+# See what was being worked on
+# Get oriented without diving into code
+```
+
+## Error Handling
+
+### Not a Git Repository
+```bash
+❌ Not in a git repository
+   Initialize git first: git init
+```
+
+### No Code Captain Structure
+```bash
+⚓ Code Captain Status Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📍 CURRENT POSITION
+   Branch: main (up to date)
+   Last commit: "Initial commit" (1 hour ago)
+   Working directory: Clean ✅
+
+📋 ACTIVE WORK
+   No Code Captain specifications found
+   Project structure: Standard git repository
+
+🎯 SUGGESTED ACTIONS
+   • Set up Code Captain workflow
+   • Create first feature specification
+
+⚡ QUICK COMMANDS
+   cc: init             # Initialize Code Captain
+   cc: create-spec      # Create first specification
+```
+
+### Corrupted Project State
+```bash
+⚠️  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
+
+⚡ RECOVERY COMMANDS
+   cc: doctor           # Diagnose and fix common issues
+   cc: reset-deps       # Reinstall dependencies
+```
+
+## Security & Privacy
+
+### Local-Only Analysis
+- All analysis happens locally
+- No external API calls or data transmission
+- Git history and file contents remain private
+
+### Sensitive Information
+- Avoid displaying sensitive data in commit messages
+- Mask environment variables or config values
+- Sanitize file paths that might contain personal info
+
+## Performance Considerations
+
+### Fast Execution
+- Target <2 second execution time
+- Cache expensive operations when possible
+- Limit git log queries to reasonable ranges
+
+### Incremental Analysis
+- Store last analysis timestamp
+- Only re-analyze changed files/commits
+- Use git's efficient diffing for change detection
+
+## Integration Points
+
+### Existing Code Captain Commands
+- Status should inform other commands about current state
+- Share analysis results to avoid duplicate work
+- Coordinate with task execution and spec management
+
+### Future Enhancements
+- Integration with GitHub/GitLab for PR status
+- Team activity awareness (without external dependencies)
+- Customizable status report sections
+- Export status for external tools or dashboards
+
+## Success Metrics
+
+### Developer Experience
+- Time to context restoration after interruptions
+- Frequency of "what was I working on?" moments
+- Accuracy of suggested next actions
+- Adoption rate and daily usage patterns
+
+### Project Health
+- Early detection of project issues
+- Improved workflow consistency
+- Better task completion rates
+- Reduced context switching overhead
+
+---
+
+*⚓ Keep your bearings, maintain your heading, and always know where you stand in the code.*

package/cursor/commands/swab.md

@@ -0,0 +1,209 @@
+# Code Captain Swab Command (cc: swab)
+
+## Overview
+
+A deck-cleaning agent that makes one small, focused improvement to the codebase, following the "Boy Scout Rule" - leave the code cleaner than you found it. This command identifies the single best small cleanup opportunity and applies it with your approval.
+
+## Usage
+
+```bash
+cc: swab
+```
+
+**Note:** No options, no flags, no complexity. Just simple deck cleaning.
+
+## Command 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
+
+## AI Implementation Prompt
+
+```
+You are a code reviewer cleaning up small messes on the ship.
+
+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
+
+CODEBASE CONTEXT: {scanned_files_content}
+
+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.
+```
+
+## Implementation Details
+
+### Codebase Scanning Strategy
+
+**File Discovery:**
+- Use `codebase_search` to find code patterns and smells across all source files
+- Use `list_dir` to explore project structure and identify main source directories
+- Use `file_search` to locate specific file types if needed
+- Focus on recently modified files first (higher likelihood of improvement opportunities)
+
+**Content Analysis:**
+- Read 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 search_replace tool for exact string replacement
+search_replace(
+  file_path=target_file,
+  old_string=exact_match_text,
+  new_string=improved_text
+)
+```
+
+**Verification:**
+- Re-read 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 command again.
+```
+
+## Integration Notes
+
+This command integrates with the existing Code Captain ecosystem by:
+
+1. **Following established patterns** - Uses same markdown structure as other commands
+2. **Leveraging existing tools** - Uses `codebase_search`, `read_file`, `search_replace`
+3. **Maintaining simplicity** - No complex configuration or state management
+4. **Respecting user control** - Always asks permission before making changes
+
+## Future Enhancements
+
+Potential future improvements (not in initial version):
+
+- **Directory targeting**: `cc: swab src/components/`
+- **File type filtering**: `cc: swab --js-only`
+- **Batch mode**: `cc: 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 command, one small improvement, user approval required.

package/cursor/docs/best-practices.md

@@ -0,0 +1,74 @@
+# Development Best Practices
+
+## Context
+
+Global development guidelines for Agent OS projects.
+
+## Core Principles
+
+### Keep It Simple
+
+- Implement code in the fewest lines possible
+- Avoid over-engineering solutions
+- Choose straightforward approaches over clever ones
+
+### Optimize for Readability
+
+- Prioritize code clarity over micro-optimizations
+- Write self-documenting code with clear variable names
+- Add comments for "why" not "what"
+
+### DRY (Don't Repeat Yourself)
+
+- Extract repeated business logic to private methods
+- Extract repeated UI markup to reusable components
+- Create utility functions for common operations
+
+### File Structure
+
+- Keep files focused on a single responsibility
+- Group related functionality together
+- Use consistent naming conventions
+
+## Critical Thinking and Decision Making
+
+### Challenge Ideas and Assumptions
+
+- Question the "why" behind every technical decision
+- Identify unstated assumptions in requirements and designs
+- Ask "What could go wrong?" for proposed solutions
+- Consider edge cases and failure scenarios
+
+### Provide Constructive Pushback
+
+- Disagree when you have evidence-based concerns
+- Offer alternative approaches with clear reasoning
+- Challenge overly complex solutions in favor of simpler ones
+- Point out potential security, performance, or maintainability issues
+
+### Focus on Evidence Over Agreement
+
+- Base decisions on data, benchmarks, and measurable outcomes
+- Cite specific examples when discussing trade-offs
+- Reference industry standards and established patterns
+- Avoid "yes, and..." responses when "no, because..." is more appropriate
+
+### Question Popular Choices
+
+- Don't assume popularity equals correctness
+- Evaluate if trendy technologies actually solve the problem
+- Consider long-term maintenance costs of new frameworks
+- Assess if existing solutions already meet the need
+
+## Dependencies
+
+### Choose Libraries Wisely
+
+When adding third-party dependencies:
+
+- Select the most popular and actively maintained option
+- Check the library's GitHub repository for:
+  - Recent commits (within last 6 months)
+  - Active issue resolution
+  - Number of stars/downloads
+  - Clear documentation