@devobsessed/code-captain 0.0.6 → 0.0.9

package/cursor/commands/initialize.md

@@ -1,6 +1,6 @@
 # Initialize Command Workflow
 
-## Command: `cc: initialize`
+## Overview
 
 ### Purpose
 
@@ -109,21 +109,21 @@ After technical foundation is complete, provide clear next steps:
 
 Your development environment is now set up and documented:
 - Technology stack documented and configured
-- Development tools and standards established  
+- Development tools and standards established
 - Project structure and configuration ready
 
 ## Recommended Next Steps:
 
 ### For New Products:
-cc: plan-product "your product idea" - Define product vision, strategy, and roadmap
+/plan-product "your product idea" - Define product vision, strategy, and roadmap
 
 ### For Existing Products:
-cc: create-spec "feature description" - Create detailed feature specifications
-cc: execute-task - Implement features with TDD workflow
+/create-spec "feature description" - Create detailed feature specifications
+/execute-task - Implement features with TDD workflow
 
 ### For Research:
-cc: research "topic" - Conduct systematic technical research
-cc: create-adr "decision" - Document architectural decisions
+/research "topic" - Conduct systematic technical research
+/create-adr "decision" - Document architectural decisions
 
 Ready to define your product strategy and start building!
 ```
@@ -262,15 +262,15 @@ Your existing project has been analyzed and documented:
 ## Recommended Next Steps:
 
 ### For Product Strategy (Recommended First):
-cc: plan-product "enhanced product vision" - Define product strategy and roadmap
+/plan-product "enhanced product vision" - Define product strategy and roadmap
 
 ### For Feature Development:
-cc: create-spec "feature description" - Create detailed feature specifications
-cc: execute-task - Implement features following established patterns
+/create-spec "feature description" - Create detailed feature specifications
+/execute-task - Implement features following established patterns
 
 ### For Technical Improvements:
-cc: research "technical topic" - Research solutions for identified gaps
-cc: create-adr "technical decision" - Document architectural improvements
+/research "technical topic" - Research solutions for identified gaps
+/create-adr "technical decision" - Document architectural improvements
 
 Ready to define your product strategy and enhance your codebase!
 ```
@@ -284,26 +284,27 @@ Ready to define your product strategy and enhance your codebase!
 **MANDATORY**: The initialize command MUST end with a message that prominently recommends `plan-product` as the next logical step for both greenfield and brownfield projects. This is required because:
 
 1. Initialize handles ONLY technical foundation
-2. plan-product handles product strategy and vision  
+2. plan-product handles product strategy and vision
 3. Users need both for complete project setup
 4. plan-product should be the next step before feature development
 
 **Required message format**:
+
 ```
 🚀 Technical Foundation Complete! / 🔍 Technical Foundation Analysis Complete!
 
 ## Recommended Next Steps:
 
 ### For Product Strategy (Recommended First):
-cc: plan-product "your product idea/vision" - Define product strategy and roadmap
+/plan-product "your product idea/vision" - Define product strategy and roadmap
 
 ### For Feature Development:
-cc: create-spec "feature description" - Create detailed feature specifications
-cc: execute-task - Implement features
+/create-spec "feature description" - Create detailed feature specifications
+/execute-task - Implement features
 
 ### For Technical Improvements:
-cc: research "topic" - Research solutions for gaps
-cc: create-adr "decision" - Document architectural decisions
+/research "topic" - Research solutions for gaps
+/create-adr "decision" - Document architectural decisions
 ```
 
 ---

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,37 +317,44 @@ 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
 
-4. **Integration** (`sync`, `create-github-issues`)
-   - Platform API interactions
-   - Sync and conflict handling
-   - Status reporting
+4. **Quality** (`status`, `swab`)
+5. **Meta** (`new-command`, `explain-code`)
+   - Command scaffolding and template generation
+   - Documentation updates across the ecosystem
+   - Validation and consistency checks
 
 ### 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
@@ -272,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]
 
@@ -286,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
@@ -309,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

@@ -1,6 +1,6 @@
 # Research Command
 
-## Purpose
+## Overview
 
 Conduct systematic research on a topic using structured phases that build upon each other, creating actionable todos and leveraging web search capabilities.
 
@@ -120,34 +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: File System Timestamp
+Get current date by running: `npx @devobsessed/code-captain date`
 
-1. **CREATE** directory if not exists: `.code-captain/research/`
-2. **CREATE** temporary file: `.code-captain/research/.date-check`
-3. **READ** file creation timestamp from filesystem
-4. **EXTRACT** date in YYYY-MM-DD format
-5. **DELETE** temporary file
-6. **STORE** date in variable for folder naming
-
-### Fallback Method: User Confirmation
-
-If file system method fails:
-
-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