@devobsessed/code-captain 0.0.6 → 0.0.9

package/cursor/commands/create-spec.md

@@ -1,36 +1,34 @@
-# Enhanced Create Spec Command (cc: create-spec)
+# Enhanced Create Spec Command (create-spec)
 
 ## Overview
 
 Generate comprehensive feature specifications using a contract-first approach that ensures complete alignment between developer and AI before creating any supporting files. This command eliminates presumptuous file creation by establishing a clear "contract" through structured clarification rounds.
 
-## Usage
-
-```bash
-cc: create-spec "rough feature description"
-```
-
 ## Command Process
 
 ### Phase 1: Contract Establishment (No File Creation)
 
 **Mission Statement:**
+
 > Your goal is to turn my rough feature idea into a very clear work specification. You will deliver the complete spec package only after we both agree on the requirements contract. **Important: Challenge ideas that don't make technical or business sense - it's better to surface concerns early than build the wrong thing.**
 
 #### Step 1.1: Initial Context Scan
+
 - Scan existing `.code-captain/specs/` for related specifications
 - Analyze current codebase architecture and patterns using `codebase_search`
 - Load project context files (`tech-stack.md`, `code-style.md`, `objective.md`)
 - **Output:** Context summary (no files created yet)
 
 #### Step 1.2: Gap Analysis & Silent Enumeration
+
 **Internal Process (not shown to user):**
+
 - Silently list every missing fact, constraint, or requirement
 - Identify ambiguities in the initial description
 - Note potential integration points and dependencies
 - Catalog unknowns across these domains:
   - Purpose & business value
-  - Target audience & user personas  
+  - Target audience & user personas
   - Technical constraints & requirements
   - Success criteria & acceptance tests
   - Scope boundaries (in/out of scope)
@@ -41,9 +39,11 @@ cc: create-spec "rough feature description"
   - Risk tolerance & implementation approach
 
 #### Step 1.3: Structured Clarification Loop
+
 **Rules:**
+
 - Ask ONE focused question at a time
-- After each answer, re-scan codebase for new context if relevant
+- After each answer, re-scan codebase for additional context if relevant
 - Continue until reaching 95% confidence on deliverable
 - Each question should target the highest-impact unknown
 - **Never declare "final question"** - let the conversation flow naturally
@@ -51,6 +51,7 @@ cc: create-spec "rough feature description"
 - **Challenge ideas that don't make technical or business sense** - better to surface concerns early than build the wrong thing
 
 **Critical Analysis Responsibility:**
+
 - If requirements seem technically infeasible with current architecture, explain why and suggest alternatives
 - If scope seems too large for a single feature, recommend breaking it down
 - If user requests conflict with existing patterns found in codebase, point out the inconsistency
@@ -58,42 +59,47 @@ cc: create-spec "rough feature description"
 - If performance/security/scalability concerns arise, surface them proactively
 
 **Pushback Phrasing Examples:**
+
 - "I see a potential issue with [requirement] because [technical reason]. Would [alternative approach] work better?"
 - "Based on your existing codebase, [proposed approach] might conflict with [existing pattern]. How should we handle this?"
 - "The scope you're describing sounds like it might be 3-4 separate features. Should we focus on [core piece] first?"
 - "I'm concerned that [requirement] could create [specific problem]. Have you considered [alternative]?"
 
 **Question Categories (examples):**
+
 - "What specific user problem does this solve, and who experiences it?"
-- "Should this integrate with [existing system found in codebase], or remain separate?"  
+- "Should this integrate with [existing system found in codebase], or remain separate?"
 - "What does 'success' look like - how will we measure if this works?"
 - "Are there performance requirements (response time, throughput, scale)?"
 - "What UI/UX constraints exist - web only, mobile responsive, accessibility needs?"
 - "What's your risk tolerance - prefer stable/proven approaches or cutting-edge solutions?"
 
 **Transition to Contract:**
+
 - When confidence is high, present contract without declaring it "final"
 - Use phrases like "I think I have enough to create a solid contract" or "Based on our discussion, here's what I understand"
 - Always leave room for more questions if needed
 
 #### Step 1.4: Echo Check (Contract Proposal)
+
 When confident, present a contract proposal with any concerns surfaced:
 
 **Format:**
+
 ```
 ## Specification Contract
 
 **Deliverable:** [One clear sentence describing what will be built]
 
-**Must Include:** [Critical requirement that makes this valuable]  
+**Must Include:** [Critical requirement that makes this valuable]
 
 **Hardest Constraint:** [Biggest technical/business limitation to navigate]
 
 **Success Criteria:** [How we'll know it's working correctly]
 
-**Scope Boundaries:** 
-- In Scope: [2-3 key features]
-- Out of Scope: [2-3 things we won't build]
+**Scope Boundaries:**
+- Included: [2-3 key features]
+- Excluded: [2-3 things we won't build]
 
 **⚠️ Technical Concerns (if any):**
 - [Specific concern about feasibility, performance, or architecture]
@@ -106,7 +112,7 @@ When confident, present a contract proposal with any concerns surfaced:
 ---
 Options:
 - Type 'yes' to lock this contract and create the spec package
-- Type 'edit: [your changes]' to modify the contract  
+- Type 'edit: [your changes]' to modify the contract
 - Type 'risks' to explore potential implementation risks in detail
 - Type 'blueprint' to see the planned folder structure and documents
 - Ask more questions if anything needs clarification
@@ -117,49 +123,32 @@ Options:
 **Triggered only after user confirms contract with 'yes'**
 
 #### Step 2.1: Initialize Tracking
+
 ```bash
 # Use todo_write to track creation process
-1. Determine current date for folder naming
-2. Create spec folder structure
-3. Generate core specification document  
-4. Create user stories with acceptance criteria
-5. Generate technical sub-specifications
-6. Create implementation task breakdown
-7. Present package for user review and validation
+1. Get current date and create spec folder structure
+2. Generate core specification document
+3. Create user stories with acceptance criteria
+4. Generate technical sub-specifications
+5. Create implementation task breakdown
+6. Present package for user review and validation
 ```
 
 #### Step 2.2: Determine Current Date
-**Objective:** Get current date for folder naming and document timestamps
-
-**Date Determination Process:**
-
-1. **CREATE** directory if not exists: `.code-captain/specs/`
-2. **CREATE** temporary file: `.code-captain/specs/.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:** If file system method fails:
-1. **STATE**: "I need to confirm today's date for the specification 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"
+
+Get current date by running: `npx @devobsessed/code-captain date`
+
+This returns the current date in `YYYY-MM-DD` format for folder naming:
+`.code-captain/specs/[DATE]-[feature-name]/`
 
 #### Step 2.3: Create Directory Structure
+
 **Generated folder (using determined date):**
+
 ```
 .code-captain/specs/[DATE]-{feature-name}/
 ├── spec.md                    # Main specification (from contract)
-├── spec-lite.md              # Condensed version for AI context  
+├── spec-lite.md              # Condensed version for AI context
 ├── user-stories/             # Individual user story files
 │   ├── README.md             # Overview and progress tracking
 │   ├── story-1-{name}.md     # Individual user story with focused tasks
@@ -169,12 +158,13 @@ Options:
     ├── technical-spec.md     # Architecture & implementation details
     ├── database-schema.md    # Database changes (if needed)
     ├── api-spec.md          # API documentation (if needed)
-    └── ui-wireframes.md     # UI/UX specifications (if needed)  
+    └── ui-wireframes.md     # UI/UX specifications (if needed)
 ```
 
 #### Step 2.4: Generate Core Documents
 
 **spec.md** - Built directly from the locked contract:
+
 ```markdown
 # [Feature Name] Specification
 
@@ -183,46 +173,51 @@ Options:
 > Contract Locked: ✅
 
 ## Contract Summary
+
 [Echo check content verbatim]
 
 ## Detailed Requirements
+
 [Expanded from clarification responses]
 
 ## Implementation Approach
+
 [Technical strategy based on codebase analysis]
 ```
 
 **user-stories/ folder structure** - Individual user story files for better organization:
 
 **user-stories/README.md** - Overview and progress tracking:
+
 ```markdown
 # User Stories Overview
 
-> **Specification:** [Feature Name]
-> **Created:** [DATE]
-> **Status:** Planning
+> **Specification:** [Feature Name] > **Created:** [DATE] > **Status:** Planning
 
 ## Stories Summary
 
-| Story | Title | Status | Tasks | Progress |
-|-------|-------|--------|-------|----------|
-| 1 | [Story title] | Not Started | 5 | 0/5 |
-| 2 | [Story title] | Not Started | 4 | 0/4 |
-| 3 | [Story title] | Not Started | 6 | 0/6 |
+| Story | Title         | Status      | Tasks | Progress |
+| ----- | ------------- | ----------- | ----- | -------- |
+| 1     | [Story title] | Not Started | 5     | 0/5      |
+| 2     | [Story title] | Not Started | 4     | 0/4      |
+| 3     | [Story title] | Not Started | 6     | 0/6      |
 
 **Total Progress:** 0/15 tasks (0%)
 
 ## Story Dependencies
+
 - Story 2 depends on Story 1 completion
 - Story 3 can run parallel to Story 2
 
 ## Quick Links
+
 - [Story 1: User Login](./story-1-user-login.md)
 - [Story 2: Password Reset](./story-2-password-reset.md)
 - [Story 3: Profile Management](./story-3-profile-management.md)
 ```
 
 **user-stories/story-1-{name}.md** - Individual story files (max 5-7 tasks each):
+
 ```markdown
 # Story 1: [Title from contract deliverable]
 
@@ -231,27 +226,32 @@ Options:
 > **Dependencies:** None
 
 ## User Story
+
 **As a** [user type from clarification]
 **I want to** [action from contract]  
 **So that** [value from contract must-include]
 
 ## Acceptance Criteria
+
 - [ ] Given [context], when [action], then [outcome]
 - [ ] Given [context], when [action], then [outcome]
 - [ ] Given [context], when [action], then [outcome]
 
 ## Implementation Tasks
+
 - [ ] 1.1 Write tests for [specific component]
 - [ ] 1.2 [Focused technical step]
-- [ ] 1.3 [Focused technical step] 
+- [ ] 1.3 [Focused technical step]
 - [ ] 1.4 [Focused technical step]
 - [ ] 1.5 Verify acceptance criteria are met
 - [ ] 1.6 Verify all tests pass
 
 ## Notes
+
 [Any specific technical considerations, risks, or dependencies for this story]
 
 ## Definition of Done
+
 - [ ] All tasks completed
 - [ ] All acceptance criteria met
 - [ ] Tests passing
@@ -275,6 +275,7 @@ Options:
 **user-stories/ folder** - Organized individual story files with focused task groups:
 
 **Structure Philosophy:**
+
 - Each user story gets its own file for better organization
 - Implementation tasks are kept small and focused (max 5-7 per story)
 - Complex stories are broken into multiple smaller stories
@@ -283,6 +284,7 @@ Options:
 - Each story follows TDD: test → implement → verify acceptance criteria
 
 **Benefits of Folder Structure:**
+
 - **Manageability**: Each file stays focused and readable
 - **Navigation**: Easy to find and work on specific stories
 - **Parallel Work**: Multiple developers can work on different stories
@@ -291,12 +293,14 @@ Options:
 - **Traceability**: Every technical task traces to user value
 
 **File Organization:**
+
 - **README.md**: Overview, progress summary, dependencies
 - **story-N-{name}.md**: Individual stories with focused tasks (5-7 tasks max)
 - **Story Naming**: Clear, descriptive names for easy identification
 - **Task Numbering**: N.1, N.2, N.3... within each story file
 
 **Task Breakdown Strategy:**
+
 - If a story would have >7 tasks, split into multiple stories
 - Each story should deliver standalone user value
 - Tasks within a story should be cohesive and related
@@ -306,12 +310,13 @@ Options:
 #### Step 2.7: Final Package Review & User Validation
 
 Present complete package with file references:
+
 ```
 ✅ Specification package created successfully!
 
 📁 .code-captain/specs/[DATE]-feature-name/
 ├── 📋 spec.md - Main specification document
-├── 📝 spec-lite.md - AI context summary  
+├── 📝 spec-lite.md - AI context summary
 ├── 👥 user-stories/ - Individual user story files
 │   ├── 📊 README.md - Overview and progress tracking
 │   ├── 📝 story-1-{name}.md - Focused story with 5-7 tasks
@@ -348,22 +353,26 @@ Once you're satisfied with the specification, I can help you start implementatio
 ## Key Improvements Over Original
 
 ### 1. Contract-First Approach
+
 - **No presumptuous file creation** - Nothing gets built until contract is locked
 - **Structured clarification** - One question at a time, building understanding
 - **Echo check validation** - Clear contract summary before proceeding
 
-### 2. Codebase-Aware Questioning  
+### 2. Codebase-Aware Questioning
+
 - **Context scanning between questions** - Each answer triggers fresh codebase analysis
 - **Integration-focused queries** - Questions shaped by what exists in the codebase
 - **Architecture consistency** - Recommendations align with existing patterns
 
 ### 3. User Control & Transparency
+
 - **Clear decision points** - User explicitly approves before file creation
-- **Risk assessment option** - Can explore implementation risks before committing  
+- **Risk assessment option** - Can explore implementation risks before committing
 - **Blueprint preview** - Can see planned structure before creation
 - **Edit capability** - Can modify contract before locking
 
 ### 4. Efficient Clarification Process
+
 - **Gap enumeration** - Systematically identifies all unknowns
 - **95% confidence threshold** - Stops asking when ready to deliver
 - **Token efficiency** - Focused questions, no verbose explanations during clarification
@@ -371,7 +380,7 @@ Once you're satisfied with the specification, I can help you start implementatio
 ## Example Usage Flow
 
 ```
-Developer: cc: create-spec "real-time multiplayer chat with blockchain integration"
+Developer: /create-spec "real-time multiplayer chat with blockchain integration"
 
 Agent: I'm ready to help you create a comprehensive specification.
 
@@ -385,7 +394,7 @@ First question: You mentioned "real-time multiplayer chat with blockchain integr
 
 Developer: I want messages to be permanently stored and verifiable, plus users should pay crypto to send messages to prevent spam
 
-Agent: I understand the anti-spam goal, but I'm concerned about the user experience. If users have to wait 30+ seconds for transaction confirmation before each message appears, that breaks the "real-time" chat experience. 
+Agent: I understand the anti-spam goal, but I'm concerned about the user experience. If users have to wait 30+ seconds for transaction confirmation before each message appears, that breaks the "real-time" chat experience.
 
 Would a hybrid approach work better - immediate message delivery with blockchain settlement in the background? Or are you thinking of a different model where users pre-purchase message credits?
 
@@ -414,8 +423,8 @@ Agent: [Continues with more informed questions about the hybrid architecture...]
 **Success Criteria:** Messages appear instantly, spam is prevented via crypto payments, blockchain verification happens within 5 minutes
 
 **Scope Boundaries:**
-- In Scope: Real-time chat, wallet integration, background blockchain settlement
-- Out of Scope: Advanced chat features (file sharing, voice), custom token creation
+- Included: Real-time chat, wallet integration, background blockchain settlement
+- Excluded: Advanced chat features (file sharing, voice), custom token creation
 
 ---
 Options: [yes/edit/risks/blueprint]

package/cursor/commands/edit-spec.md

@@ -1,22 +1,9 @@
-# Enhanced Edit Spec Command (cc: edit-spec)
+# Enhanced Edit Spec Command (edit-spec)
 
 ## Overview
 
 Modify existing feature specifications using a contract-first approach that ensures complete alignment between developer and AI before updating any supporting files. This command prevents assumptions by establishing a clear "modification contract" through structured clarification rounds.
 
-## Usage
-
-```bash
-cc: edit-spec [spec-identifier] "proposed changes description"
-```
-
-**Examples:**
-```bash
-cc: edit-spec "user-authentication" "add social login options"
-cc: edit-spec "2024-01-15-payment-gateway" "change from Stripe to PayPal"
-cc: edit-spec "latest" "remove the mobile app requirement"
-```
-
 ## Command Process
 
 ### Phase 1: Specification Loading & Change Contract (No File Modifications)
@@ -338,7 +325,7 @@ The original version is safely backed up in the backups folder. If you need to r
 ## Example Usage Flow
 
 ```
-Developer: cc: edit-spec "user-auth" "add biometric authentication"
+Developer: /edit-spec "user-auth" "add biometric authentication"
 
 Agent: I found your user authentication specification from 2024-01-15. Let me load the current state...
 

package/cursor/commands/execute-task.md

@@ -1,17 +1,9 @@
-# Execute Task Command (cc: execute-task)
+# Execute Task Command (execute-task)
 
 ## Overview
 
 Execute a specific task and its sub-tasks systematically following a Test-Driven Development (TDD) workflow. This command reads task specifications from `.code-captain/specs/` directories and implements features with comprehensive testing, following established code standards and best practices.
 
-## Usage
-
-```bash
-cc: execute-task
-```
-
-**Note:** This command automatically detects and lists available task specifications for selection, or executes a specific task if context is clear.
-
 ## CRITICAL REQUIREMENT: 100% Test Pass Rate
 
 **⚠️ ZERO TOLERANCE FOR FAILING TESTS ⚠️**
@@ -77,7 +69,7 @@ Use `todo_write` to track the execution 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 `cc: create-spec` first
+4. **If no specs exist**: Guide user to run `/create-spec` first
 
 **Selection format:**
 ```
@@ -417,7 +409,7 @@ REQUIRED ACTIONS:
 
 **Specification dependency:**
 
-- Requires existing spec created by `cc: create-spec`
+- Requires existing spec created by `/create-spec`
 - 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`
@@ -431,8 +423,8 @@ REQUIRED ACTIONS:
 
 **Cross-command integration:**
 
-- Complements `cc: create-spec` for complete development workflow
-- Can trigger `cc: research` if unknown technologies encountered
+- Complements `/create-spec` for complete development workflow
+- Can trigger `/research` if unknown technologies encountered
 - Integrates with testing and validation workflows
 
 ## Quality Standards
@@ -464,7 +456,7 @@ REQUIRED ACTIONS:
 
 **Common failure scenarios:**
 
-- **No specifications found**: Guide to `cc: create-spec`
+- **No specifications found**: Guide to `/create-spec`
 - **Test framework issues**: Provide setup guidance
 - **Implementation conflicts**: Suggest conflict resolution
 - **Performance issues**: Recommend optimization approaches
@@ -482,7 +474,7 @@ Update story status and notes section to document the blocking issue.
 **Resolution strategies:**
 
 1. Try alternative implementation approach
-2. Research solution using `cc: research`
+2. Research solution using `/research`
 3. Break down task into smaller components
 4. Maximum 3 attempts before escalating or documenting as blocked
 

package/cursor/commands/explain-code.md

@@ -7,7 +7,7 @@ The `explain-code` command provides comprehensive, AI-powered explanations of co
 ## Command Syntax
 
 ```bash
-cc: explain-code [target]
+/explain-code [target]
 ```
 
 ## Parameters
@@ -31,19 +31,19 @@ The command automatically:
 
 ```bash
 # Explain a specific function
-cc: explain-code calculateUserDiscount
+/explain-code calculateUserDiscount
 
 # Explain a class
-cc: explain-code PaymentProcessor
+/explain-code PaymentProcessor
 
 # Explain entire file
-cc: explain-code src/auth/AuthService.js
+/explain-code src/auth/AuthService.js
 
 # Explain specific line range
-cc: explain-code "src/utils/helpers.js:45-78"
+/explain-code "src/utils/helpers.js:45-78"
 
 # Explain currently selected code in IDE
-cc: explain-code current-selection
+/explain-code current-selection
 ```
 
 ## Output Structure
@@ -139,39 +139,20 @@ Files are named using the format: `[DATE]-[target-name].md` where DATE is YYYY-M
 
 ## Auto-Save Behavior
 
-All explanations are automatically saved to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`. The system uses the same date determination process as the research command to ensure consistent timestamps.
+All explanations are automatically saved to `.code-captain/explanations/` using the format `[DATE]-[target-name].md`.
 
-## Date Determination Process
+Get current date by running: `npx @devobsessed/code-captain date`
 
-### 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 in variable for file naming
-
-### Fallback Method: User Confirmation
-
-If file system method fails:
-
-1. **STATE**: "I need to confirm today's date for the explanation file"
-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}$`
-5. **STORE** date for file naming
-
-**Example filename:** `.code-captain/explanations/2024-01-15-AuthenticationFlow.md`
+**Example filename:** `.code-captain/explanations/2025-09-27-AuthenticationFlow.md`
 
 ## Integration Points
 
 ### With Other Commands
 ```bash
 # Saved explanations can be referenced by other commands
-cc: research authentication
-cc: create-spec payment-processing
-cc: execute-task "optimize the user search"
+/research authentication
+/create-spec payment-processing
+/execute-task "optimize the user search"
 
 # AI can access saved explanations from .code-captain/explanations/
 # to provide better context for other commands
@@ -187,16 +168,16 @@ cc: execute-task "optimize the user search"
 
 ```bash
 # List all saved explanations
-cc: list-explanations
+/list-explanations
 
 # Search explanations
-cc: search-explanations "authentication"
+/search-explanations "authentication"
 
 # Show explanation history
-cc: explanation-history calculateDiscount
+/explanation-history calculateDiscount
 
 # Update outdated explanations when code changes
-cc: refresh-explanations --check-code-changes
+/refresh-explanations --check-code-changes
 ```
 
 ## Diagram Types Generated