@devobsessed/code-captain 0.0.8 → 0.0.9

package/cursor/commands/new-command.md

@@ -1,78 +1,178 @@
-# New Command Creator (cc: new-command)
+# New Command Creator (/new-command)
 
 ## 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.
 
-## Usage
+## Command Process
 
-```bash
-cc: new-command "command-name" "brief description"
-```
+### Phase 1: Command Contract Establishment (No File Creation)
+
+**Mission Statement:**
+
+> Your goal is to turn my rough command idea into a comprehensive command specification. You will deliver the complete command package only after we both agree on the command contract. **Important: Challenge command ideas that don't fit the Code Captain ecosystem or would create maintenance burden - it's better to surface concerns early than build the wrong command.**
+
+#### Step 1.1: Initial Context Scan
+
+- Scan existing commands in `.cursor/commands/` to understand patterns
+- Analyze existing Code Captain ecosystem using `codebase_search`
+- Load command patterns from successful commands (`create-spec`, `execute-task`, etc.)
+- **Output:** Context summary (no files created yet)
+
+#### Step 1.2: Gap Analysis & Silent Enumeration
+
+**Internal Process (not shown to user):**
+
+- Silently list every missing detail about the command's purpose and implementation
+- Identify ambiguities in the initial command description
+- Note potential conflicts with existing commands
+- Catalog unknowns across these domains:
+  - Command purpose & unique value proposition
+  - Target workflow & user scenarios
+  - Execution complexity & style requirements
+  - Input/output specifications
+  - Tool integration requirements
+  - File organization & output locations
+  - Error handling & edge cases
+  - Integration with existing commands
+  - Documentation & help text needs
+
+#### Step 1.3: Structured Clarification Loop
+
+**Rules:**
+
+- Ask ONE focused question at a time
+- After each answer, re-scan existing commands for additional context if relevant
+- Continue until reaching 95% confidence on command specification
+- Each question should target the highest-impact unknown
+- **Never declare "final question"** - let the conversation flow naturally
+- Let the user signal when they're ready to lock the contract
+- **Challenge command ideas that create complexity or don't fit** - better to surface concerns early than build problematic commands
+
+**Critical Analysis Responsibility:**
+
+- If command seems to duplicate existing functionality, explain the overlap and suggest alternatives
+- If complexity seems too high for the proposed value, recommend simplification
+- If the command doesn't fit Code Captain patterns, point out the inconsistency
+- If implementation would create maintenance burden, suggest alternative approaches
+- If command scope is unclear or too broad, ask for focus and boundaries
+
+**Pushback Phrasing Examples:**
+
+- "I see potential overlap with [existing command]. How would [your command] be different from [existing]?"
+- "The complexity you're describing sounds like it might need 3-4 separate commands. Should we focus on [core piece] first?"
+- "I'm concerned that [proposed approach] would break Code Captain's [established pattern]. Have you considered [alternative]?"
+- "This command would need significant ongoing maintenance. Could we achieve the same goal with [simpler approach]?"
+
+**Question Categories (examples):**
+
+- "What specific developer workflow does this solve that existing commands don't cover?"
+- "Should this integrate with [existing command found in scan], or remain separate?"
+- "What does 'success' look like - how will developers know the command worked correctly?"
+- "Should this be a contract-style command (extensive clarification like create-spec) or direct execution (immediate action like swab)?"
+- "Where should outputs be stored - new folder or existing (.code-captain/[folder])?"
+- "What Cursor tools will it need - codebase_search, file_search, edit_file, web_search?"
+
+**Transition to Contract:**
+
+- When confidence is high, present contract without declaring it "final"
+- Use phrases like "I think I understand the command you need" or "Based on our discussion, here's the command specification"
+- Always leave room for more questions if needed
+
+#### Step 1.4: Echo Check (Command Contract Proposal)
+
+When confident, present a command contract proposal with any concerns surfaced:
+
+**Format:**
 
-**Examples:**
-```bash
-cc: new-command "optimize" "Performance optimization for slow code sections"
-cc: new-command "deploy" "Deploy applications to various cloud platforms"
-cc: new-command "test-gen" "Generate comprehensive test suites from existing code"
 ```
+## Command Contract
 
-## Command Process
+**Command Name:** [validated-command-name]
+
+**Purpose:** [One clear sentence describing what this command does]
 
-### Step 1: Command Specification Gathering
+**Unique Value:** [How this differs from existing commands and why it's needed]
 
-**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
+**Execution Style:** [Contract-style with clarification OR Direct execution]
 
-**Interactive Specification Building:**
-Ask clarifying questions to build complete command specification:
+**Workflow Pattern:** [Step-by-step process the command follows]
 
-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 Cursor tools will it use? (codebase_search, read_file, etc.)"
-7. **Workflow Steps**: "What are the main phases/steps the command follows?"
+**Inputs Required:** [Arguments, flags, or interactive inputs needed]
 
-### Step 2: Command Structure Generation
+**Outputs Created:** [Files, directories, or modifications made]
+
+**Tool Integration:** [Cursor tools required: codebase_search, file_search, etc.]
+
+**⚠️ Implementation Concerns (if any):**
+- [Specific concern about complexity, maintenance, or ecosystem fit]
+- [Suggested alternative or mitigation approach]
+
+**💡 Recommendations:**
+- [Suggestions for improving the command based on ecosystem analysis]
+- [Ways to reduce complexity or improve consistency]
+
+---
+Options:
+- Type 'yes' to lock this contract and create the command
+- Type 'edit: [your changes]' to modify the contract
+- Type 'examples' to see similar commands for reference
+- Type 'blueprint' to see the planned file structure and documentation
+- Ask more questions if anything needs clarification
+```
+
+### Phase 2: Command Package Creation (Post-Agreement Only)
+
+**Triggered only after user confirms contract with 'yes'**
+
+#### Step 2.1: Initialize Tracking
+
+```bash
+# Use todo_write to track creation process
+1. Generate command documentation with proper structure
+2. Update ecosystem documentation and references
+3. Validate command integration and consistency
+4. Present completed command for user review
+```
+
+#### Step 2.2: Generate Command File Structure
 
 **Generate Standard Command File Structure:**
 
 ```markdown
-# [Command Name] Command (cc: [command-name])
+# [Command Name] Command ([command-name])
 
 ## Overview
-[Generated from description and clarifying questions]
 
-## Usage
-```bash
-cc: [command-name] [arguments]
-```
+[Generated from description and clarifying questions]
 
 ## Command Process
 
 ### Step 1: [Phase Name]
-[Generated workflow steps]
+
+[Generated workflow steps based on contract]
 
 ### Step 2: [Phase Name]
-[Generated workflow steps]
+
+[Generated workflow steps based on contract]
 
 ## Core Rules
-[Generated based on command type]
 
-## AI Implementation Prompt
-[Generated if AI coordination needed]
+[Generated based on command type and execution style from contract]
+
+## Tool Integration
+
+[Generated tool usage based on contract requirements]
 
 ## Integration Notes
-[Generated integration details]
+
+[Generated integration details with existing commands]
 ```
 
 **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
@@ -80,65 +180,50 @@ cc: [command-name] [arguments]
 - 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 with `todo_write`
 
 **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 Updates
-
-**Automatically update main documentation files:**
-
-1. **cc.md Updates:**
-   - Add to appropriate category section
-   - Add to command documentation reading list
-   - Add to usage examples
-
-2. **cc.mdc Updates:**
-   - Add to Core Commands or Platform Integration section
-   - Include brief description
-
-3. **README.md Updates:**
-   - Add to appropriate feature section
-   - Add to command reference table
-   - Include in workflow examples if relevant
-
-### Step 4: Validation and Integration
+### Step 3: 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
+- Validate command follows established patterns
+- Test command can be discovered by Cursor
 
 **Present Summary:**
+
 ```
 ✅ New command created successfully!
 
-📁 Files Created/Updated:
-  - .code-captain/commands/[command-name].md
-  - cc.md (updated)
-  - cc.mdc (updated) 
-  - README.md (updated)
+📁 Files Created:
+  - .cursor/commands/[command-name].md
 
 🚀 Command Ready:
-  Usage: cc: [command-name] [args]
-  Documentation: .code-captain/commands/[command-name].md
+  Usage: /[command-name] [args]
+  Documentation: .cursor/commands/[command-name].md
 ```
 
 ## Core Rules
@@ -169,7 +254,7 @@ COMMAND SPECIFICATION:
 - Workflow Steps: {workflow_phases}
 
 TEMPLATE STRUCTURE:
-1. Title: # [Command Name] Command (cc: [command-name])
+1. Title: # [Command Name] Command ([command-name])
 2. Overview: Purpose and capabilities
 3. Usage: Command syntax with examples
 4. Command Process: Detailed step-by-step workflow
@@ -187,17 +272,13 @@ TEMPLATE ADAPTATION RULES:
 - CRITICAL: Be language and shell agnostic - use codebase_search, list_dir, file_search instead of language-specific find commands or hardcoded file extensions
 
 DOCUMENTATION UPDATES:
-Update these files with the new command:
-- cc.md: Add to appropriate category, command list, examples
-- cc.mdc: Add to Core Commands with brief description  
-- README.md: Add to features, command table, workflow examples
+Commands are automatically discovered by Cursor from `.cursor/commands/` - no manual documentation updates needed.
 
 OUTPUT REQUIREMENTS:
 1. Generate complete command file following the template
-2. Identify exact locations in documentation files to update
-3. Provide specific text additions for each documentation file
-4. Ensure consistency with existing command patterns
-5. Validate no conflicts with existing commands
+2. Ensure consistency with existing command patterns
+3. Validate no conflicts with existing commands
+4. Create command in `.cursor/commands/[command-name].md`
 
 QUALITY CHECKS:
 - Command name follows naming conventions (lowercase, hyphens)
@@ -214,6 +295,7 @@ QUALITY CHECKS:
 ### Command Name Validation
 
 **Validation Rules:**
+
 - Lowercase letters, numbers, hyphens only
 - No spaces or special characters
 - Maximum 20 characters
@@ -221,6 +303,7 @@ QUALITY CHECKS:
 - Must not conflict with existing commands
 
 **Validation Process:**
+
 ```bash
 # Check format
 echo "command-name" | grep -E '^[a-z][a-z0-9-]*[a-z0-9]$'
@@ -234,16 +317,19 @@ ls .code-captain/commands/ | grep "^command-name.md$"
 **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
@@ -257,15 +343,18 @@ ls .code-captain/commands/ | grep "^command-name.md$"
 ### Documentation Update Locations
 
 **cc.md Update Points:**
+
 - Line ~15-50: Available Commands sections
 - Line ~95-110: Command documentation list
 - Line ~150-190: Usage examples
 
 **cc.mdc Update Points:**
+
 - Line ~25-35: Core Commands list
 - Line ~35-45: Enhanced workflows (if integration)
 
 **README.md Update Points:**
+
 - Line ~120-140: Feature sections
 - Line ~400-415: Command reference table
 - Line ~250-270: Source structure
@@ -273,12 +362,14 @@ ls .code-captain/commands/ | grep "^command-name.md$"
 ### Error Handling
 
 **Common Issues:**
+
 - **Duplicate command name**: Check existing commands, suggest alternatives
 - **Invalid command name format**: Provide format guidance and examples
 - **Documentation update 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]
 
@@ -287,7 +378,7 @@ Suggestions:
 - Ensure name doesn't conflict with existing commands
 - Verify all required inputs are provided
 
-Try: cc: new-command "valid-name" "clear description"
+Try: /new-command "valid-name" "clear description"
 ```
 
 ## Integration Notes
@@ -310,4 +401,4 @@ Potential improvements (not in initial version):
 - **Version Control**: Track command changes and updates
 - **Command Dependencies**: Handle commands that depend on other commands
 
-But for now: Focus on core functionality - create well-structured commands that integrate seamlessly with the existing Code Captain ecosystem.
+But for now: Focus on core functionality - create well-structured commands that integrate seamlessly with the existing Code Captain ecosystem.

package/cursor/commands/plan-product.md

@@ -1,15 +1,9 @@
-# Plan Product Command (cc: plan-product)
+# Plan Product Command (plan-product)
 
 ## Overview
 
 Generate comprehensive product planning documentation using a contract-first approach that establishes clear product vision, mission, and roadmap before creating any supporting files. This command eliminates assumptions by gathering complete product context through structured discovery, then creates a complete product planning package for AI-assisted development.
 
-## Usage
-
-```bash
-cc: plan-product "product idea description"
-```
-
 ## Command Process
 
 ### Phase 1: Product Discovery & Contract Establishment (No File Creation)
@@ -386,9 +380,9 @@ Please review the planning documents and let me know:
 - Does the roadmap timeline align with your expectations?
 
 Once you're satisfied with the product plan, you can use:
-- `cc: create-spec` to detail specific features from the roadmap
-- `cc: execute-task` to begin implementing planned features
-- `cc: research` to investigate any market or product unknowns
+- `/create-spec` to detail specific features from the roadmap
+- `/execute-task` to begin implementing planned features
+- `/research` to investigate any market or product unknowns
 ```
 
 ## Key Improvements Over Basic Product Planning
@@ -436,9 +430,9 @@ Once you're satisfied with the product plan, you can use:
 - Integrates with established project patterns if present
 
 **Cross-command integration:**
-- Feeds into `cc: create-spec` for detailed feature planning
-- Supports `cc: execute-task` with clear product context
-- Can trigger `cc: research` for market or technical investigation
+- Feeds into `/create-spec` for detailed feature planning
+- Supports `/execute-task` with clear product context
+- Can trigger `/research` for market or technical investigation
 
 **Output integration:**
 - Product documents provide context for all future development

package/cursor/commands/research.md

@@ -120,31 +120,12 @@ Conduct systematic research on a topic using structured phases that build upon e
 - **Further Research:** [What questions remain]
 - **Decision Points:** [Key choices that need to be made]
 
-## Date Determination Process
+## Date Determination
 
-### Primary Method: System Clock
+Get current date by running: `npx @devobsessed/code-captain date`
 
-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: User Confirmation
-
-If system clock access isn't available:
-
-1. **STATE**: "I need to confirm today's date for the research folder"
-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}$`
-   - year: 2024-2030
-   - month: 01-12
-   - day: 01-31
-5. **STORE** date for folder naming
-
-### Error Handling
-
-- **IF** date_invalid: USE fallback_method
-- **IF** both_methods_fail: ERROR "Unable to determine current date"
+This returns the current date in `YYYY-MM-DD` format for folder naming:
+`.code-captain/research/[DATE]-[topic-name]-research.md`
 
 ## Research Document Template
 

package/cursor/commands/status.md

@@ -1,4 +1,4 @@
-# Code Captain Status Command (cc: status)
+# Code Captain Status Command (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.
@@ -6,7 +6,7 @@ A command that provides developers with a comprehensive status report when start
 ## Command Structure
 
 ```bash
-cc: status
+/status
 ```
 
 Simple, no parameters needed. Works in any git repository with optional Code Captain project structure.
@@ -52,10 +52,10 @@ Simple, no parameters needed. Works in any git repository with optional Code Cap
 
 ### 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 implementation with `cc: execute-task`
-- Always suggest `cc: swab` for code cleanup
+- If mid-task: Suggest `/execute-task`
+- If no active work: Suggest `/create-spec`
+- If specifications exist: Suggest implementation with `/execute-task`
+- Always suggest `/swab` for code cleanup
 
 ## Output Format
 
@@ -84,10 +84,10 @@ Simple, no parameters needed. Works in any git repository with optional Code Cap
    • 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
+   /execute-task     # Continue current task
+   /commit-wip       # Commit work in progress  
+   /sync-main        # Pull latest from main
+   /swab             # Quick code cleanup
 
 ### Clean State Example
 
@@ -109,9 +109,9 @@ Simple, no parameters needed. Works in any git repository with optional Code Cap
    • Perform maintenance tasks
 
 ⚡ QUICK COMMANDS
-   cc: create-spec      # Plan new feature
-   cc: swab             # Clean up existing code
-   cc: review-specs     # Check previous specifications
+   /create-spec      # Plan new feature
+   /swab             # Clean up existing code
+   /review-specs     # Check previous specifications
 
 ### Problem State Example
 
@@ -142,8 +142,8 @@ Simple, no parameters needed. Works in any git repository with optional Code Cap
    • Continue or restart task 1.4
 
 ⚡ QUICK COMMANDS
-  cc: execute-task     # Continue current task
-  cc: swab            # Code cleanup
+  /execute-task     # Continue current task
+  /swab            # Code cleanup
 
 ## Implementation Details
 
@@ -282,7 +282,7 @@ pip check
 ### Morning Routine
 ```bash
 # Developer starts their day
-$ cc: status
+$ /status
 
 # Gets oriented on yesterday's work
 # Sees exactly what to do next
@@ -292,7 +292,7 @@ $ cc: status
 ### Context Switching
 ```bash
 # After meetings, interruptions, or breaks
-$ cc: status
+$ /status
 
 # Quick reminder of current state
 # Understand what changed while away
@@ -302,7 +302,7 @@ $ cc: status
 ### Project Handoff
 ```bash
 # When picking up someone else's work
-$ cc: status
+$ /status
 
 # Understand current project state
 # See what was being worked on
@@ -336,8 +336,8 @@ $ cc: status
    • Create first feature specification
 
 ⚡ QUICK COMMANDS
-   cc: init             # Initialize Code Captain
-   cc: create-spec      # Create first specification
+   /init             # Initialize Code Captain
+   /create-spec      # Create first specification
 ```
 
 ### Corrupted Project State
@@ -353,8 +353,8 @@ $ cc: status
    • Check build configuration
 
 ⚡ RECOVERY COMMANDS
-   cc: doctor           # Diagnose and fix common issues
-   cc: reset-deps       # Reinstall dependencies
+   /doctor           # Diagnose and fix common issues
+   /reset-deps       # Reinstall dependencies
 ```
 
 ## Security & Privacy
@@ -416,9 +416,9 @@ $ cc: status
 
 Based on project state analysis, suggest relevant next steps:
 
-- **No specs**: Suggest `cc: create-spec` or `cc: plan-product`
-- **Specs ready for implementation**: Suggest `cc: execute-task`
-- **Tasks ready**: Suggest `cc: execute-task`
-- **Code quality issues**: Suggest `cc: swab`
-- **Missing architecture**: Suggest `cc: create-adr`
-- **Research needed**: Suggest `cc: research`
+- **No specs**: Suggest `/create-spec` or `/plan-product`
+- **Specs ready for implementation**: Suggest `/execute-task`
+- **Tasks ready**: Suggest `/execute-task`
+- **Code quality issues**: Suggest `/swab`
+- **Missing architecture**: Suggest `/create-adr`
+- **Research needed**: Suggest `/research`

package/cursor/commands/swab.md

@@ -1,17 +1,9 @@
-# Code Captain Swab Command (cc: swab)
+# Code Captain Swab Command (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 0: Initialize Progress Tracking
@@ -259,9 +251,9 @@ This command integrates with the existing Code Captain ecosystem by:
 
 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)
+- **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