@devobsessed/code-captain 0.0.3

package/windsurf/workflows/create-spec.md

@@ -0,0 +1,280 @@
+---
+description: Generate comprehensive feature specifications using contract-first approach with complete alignment before file creation
+---
+
+# Create Spec Workflow
+
+## Overview
+Generate comprehensive feature specifications using a contract-first approach that ensures complete alignment between developer and AI before creating any supporting files. This eliminates presumptuous file creation by establishing a clear "contract" through structured clarification rounds.
+
+## Command Process
+
+### Phase 1: Contract Establishment (No File Creation)
+
+**Mission Statement:**
+> Turn rough feature ideas into clear work specifications. Deliver the complete spec package only after both parties agree on the requirements contract. **Challenge ideas that don't make technical or business sense - better to surface concerns early than build the wrong thing.**
+
+#### Step 1.1: Initial Context Scan
+- Use `find_by_name` to scan existing `.code-captain/specs/` for related specifications
+- Use `codebase_search` to analyze current architecture and patterns
+- Use `view_file` to 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 domains:
+  - Purpose & business value
+  - Target audience & user personas
+  - Technical constraints & requirements
+  - Success criteria & acceptance tests
+  - Scope boundaries (in/out of scope)
+  - UI/UX requirements & design constraints
+  - Performance & scalability needs
+  - Security & compliance requirements
+  - Integration points with existing systems
+  - Risk tolerance & implementation approach
+
+#### Step 1.3: Structured Clarification Loop
+**Rules:**
+- Ask ONE focused question at a time
+- After each answer, re-scan codebase with `codebase_search` for new 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
+- Let the user signal when they're ready to lock the contract
+- **Challenge ideas that don't make technical or business sense**
+
+**Critical Analysis Responsibility:**
+- Challenge technically infeasible requirements; suggest alternatives
+- Break down overly large scope into focused features
+- Point out conflicts with existing codebase patterns
+- Surface performance/security/scalability concerns proactively
+
+**Question Categories:**
+- "What specific user problem does this solve, and who experiences it?"
+- "Should this integrate with [existing system], 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?"
+- "What's your risk tolerance - stable/proven vs cutting-edge solutions?"
+
+#### Step 1.4: Echo Check (Contract Proposal)
+When confident, present a contract proposal with any concerns surfaced:
+
+```
+## Specification Contract
+
+**Deliverable:** [One clear sentence describing what will be built]
+
+**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]
+
+**⚠️ Technical Concerns (if any):**
+- [Specific concern about feasibility, performance, or architecture]
+- [Suggested alternative or mitigation approach]
+
+**💡 Recommendations:**
+- [Suggestions for improving the approach based on codebase analysis]
+- [Ways to reduce risk or complexity]
+
+---
+Options:
+- Type 'yes' to lock this contract and create the spec package
+- 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
+```
+
+### Phase 2: Spec Package Creation (Post-Agreement Only)
+
+**Triggered only after user confirms contract with 'yes'**
+
+#### Step 2.1: Determine Current Date
+Use `run_command` to get current date:
+```bash
+date +%Y-%m-%d
+```
+
+#### Step 2.2: Create Directory Structure
+Use `write_to_file` to create organized folder structure:
+```
+.code-captain/specs/[DATE]-{feature-name}/
+├── spec.md                    # Main specification (from contract)
+├── 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
+│   ├── story-2-{name}.md     # Each story kept small and manageable
+│   └── story-N-{name}.md     # Max 5-7 implementation tasks per story
+└── sub-specs/                # Technical deep-dives
+    ├── 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)
+```
+
+#### Step 2.3: Generate Core Documents
+
+**spec.md** - Built directly from the locked contract:
+```markdown
+# [Feature Name] Specification
+
+> Created: [DATE]
+> Status: Planning
+> Contract Locked: ✅
+
+## Contract Summary
+[Echo check content verbatim]
+
+## Detailed Requirements
+[Expanded from clarification responses]
+
+## Implementation Approach
+[Technical strategy based on codebase analysis]
+```
+
+**user-stories/README.md** - Overview and progress tracking:
+```markdown
+# User Stories Overview
+
+> **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 |
+
+**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: Feature Name](./story-1-feature-name.md)
+- [Story 2: Feature Name](./story-2-feature-name.md)
+- [Story 3: Feature Name](./story-3-feature-name.md)
+```
+
+**user-stories/story-1-{name}.md** - Individual story files:
+```markdown
+# Story 1: [Title]
+
+> **Status:** Not Started | **Priority:** High | **Dependencies:** None
+
+## User Story
+**As a** [user type] **I want to** [action] **So that** [value]
+
+## Acceptance Criteria
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+
+## Implementation Tasks
+- [ ] 1.1 Write tests for [component]
+- [ ] 1.2 [Technical step]
+- [ ] 1.3 [Technical step]
+- [ ] 1.4 Verify acceptance criteria
+- [ ] 1.5 Verify all tests pass
+
+## Definition of Done
+- [ ] All tasks completed | [ ] Tests passing | [ ] Code reviewed
+```
+
+#### Step 2.4: Generate Technical Sub-Specs
+
+**Only create relevant sub-specs based on contract requirements:**
+
+- **technical-spec.md**: Always created - architecture, patterns, dependencies
+- **database-schema.md**: Only if database changes needed
+- **api-spec.md**: Only if new API endpoints required
+- **ui-wireframes.md**: Only if UI/UX requirements were discussed
+
+#### Step 2.5: Final Package Review & User Validation
+
+Present complete package:
+```
+✅ Specification package created successfully!
+
+📁 .code-captain/specs/[DATE]-feature-name/
+├── 📋 spec.md - Main specification
+├── 📝 spec-lite.md - AI context summary
+├── 👥 user-stories/ - Individual story files
+│   ├── 📊 README.md - Overview and progress tracking
+│   └── 📝 story-N-{name}.md - Focused stories (5-7 tasks each)
+└── 📂 sub-specs/ - Technical specifications
+
+**Stories Created:** [N] user stories | **Total Tasks:** [X] implementation tasks
+
+Please review the specification documents and let me know:
+- Does this accurately capture your vision?
+- Are there any missing requirements or incorrect assumptions?
+- Should any stories be split further or combined?
+
+Once satisfied, I can help start implementation or make adjustments.
+```
+
+#### Step 2.6: Create Memory of Specification (Optional)
+After successful spec creation, ask Cascade:
+"Please create a memory of this feature specification: [brief summary of deliverable and key technical approach]"
+
+## Key Improvements
+
+### 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
+- **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
+- **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
+
+## User Stories Folder Structure
+
+**Philosophy:** Each story gets its own file (max 5-7 tasks), README.md provides overview and progress tracking, follows TDD approach.
+
+**Benefits:** Manageable files, easy navigation, parallel work, clear progress tracking, every task traces to user value.
+
+## Windsurf Tools Used
+
+- `find_by_name`: Locate existing specifications and project files
+- `view_file`: Read existing documentation and context files
+- `codebase_search`: Analyze current architecture and patterns
+- `write_to_file`: Create specification documents and folder structure
+- `run_command`: Get current date for folder naming
+- `search_web`: Research best practices and technical approaches (if needed)
+
+## Windsurf Features Used
+
+- **Memories**: After completion, optionally create memory of specification decision and approach
+
+---
+
+*📋 Great specifications lead to great implementations. Invest in clarity upfront.*

package/windsurf/workflows/edit-spec.md

@@ -0,0 +1,273 @@
+---
+description: Modify existing feature specifications using contract-first approach with safe change management
+---
+
+# Edit Spec Workflow
+
+## Overview
+Modify existing feature specifications using a contract-first approach that ensures complete alignment between developer and AI before updating any supporting files. Prevents assumptions by establishing a clear "modification contract" through structured clarification rounds.
+
+## Usage Examples
+- "user-authentication" "add social login options"
+- "2024-01-15-payment-gateway" "change from Stripe to PayPal"  
+- "latest" "remove the mobile app requirement"
+
+## Command Process
+
+### Phase 1: Specification Loading & Change Contract (No File Modifications)
+
+**Mission Statement:**
+> Help modify existing specifications safely and precisely. Deliver updated spec package only after both parties agree on the modification contract. **Challenge changes that could break existing functionality or create technical debt - better to surface concerns early than implement problematic modifications.**
+
+#### Step 1.1: Specification Discovery & Loading
+
+**Locate Target Specification:**
+1. Use `find_by_name` to scan `.code-captain/specs/` directory for all existing specifications
+2. If spec-identifier provided:
+   - Search for exact folder name match: `[DATE]-{spec-identifier}`
+   - Search for partial name match in folder names
+   - Search for identifier in spec.md titles/content using `view_file`
+3. If spec-identifier is "latest":
+   - Find most recent folder by date prefix using `list_dir`
+4. If no spec-identifier provided:
+   - List all available specifications for user selection
+5. If multiple matches found:
+   - Present options for user disambiguation
+
+**Load Current State:**
+1. Use `view_file` to read primary specification file (`spec.md`)
+2. Use `view_file` to read user stories overview (`user-stories/README.md`)
+3. Use `view_file` to read all individual story files in `user-stories/` directory
+4. Use `view_file` to read all sub-specifications in `sub-specs/` directory
+5. Use `codebase_search` to scan for any implementation progress related to this spec
+6. **Output:** Current specification summary with story status (no modifications yet)
+
+#### Step 1.2: Impact Analysis & Change Assessment
+
+**Internal Process (not shown to user):**
+- Analyze proposed changes against current specification
+- Identify affected individual story files and task groups
+- Note potential ripple effects on:
+  - Existing implementation (if any)
+  - Specific user story files in user-stories/ folder
+  - Story dependencies and sequencing
+  - Technical architecture
+  - Acceptance criteria within affected stories
+  - Project timelines and story priorities
+- Catalog modification domains:
+  - Scope changes (adding/removing/splitting stories)
+  - Technical approach modifications
+  - Individual story adjustments or combinations
+  - Task group reorganization (keeping 5-7 tasks max)
+  - Performance/security requirement changes
+  - Integration point modifications
+  - Success criteria updates within stories
+
+#### Step 1.3: Change Clarification Loop
+
+**Rules:**
+- Ask ONE focused question at a time about the proposed changes
+- After each answer, re-analyze the existing spec and codebase using `codebase_search`
+- Continue until reaching 95% confidence on modification impact
+- Each question should target the highest-impact unknown or risk
+- **Never declare "final question"** - let the conversation flow naturally
+- **Challenge changes that could break existing functionality or create technical debt**
+
+**Critical Analysis Responsibility:**
+- If proposed changes conflict with existing implementation, explain impact and suggest migration strategies
+- If scope changes affect other dependent specifications, identify and discuss dependencies
+- If modifications introduce technical complexity, assess if benefits justify the cost
+- If changes affect user stories that may already be in progress, surface timeline implications
+- If proposed changes contradict original business value, question the modification rationale
+
+**Risk Assessment Categories:**
+- **Breaking Changes**: Will this break existing functionality?
+- **Implementation Impact**: How much existing work needs to be modified/discarded?
+- **Architecture Consistency**: Do changes align with existing patterns?
+- **Scope Creep**: Are we expanding beyond the original contract boundaries?
+- **Business Value**: Do changes improve or compromise original user value?
+
+**Question Categories:**
+- "This change would affect [existing user story]. Should we modify that story or create a new one?"
+- "I see this conflicts with [existing implementation]. Should we plan a migration strategy?"
+- "This modification increases complexity in [area]. Is the added value worth the technical cost?"
+- "The original spec was focused on [goal]. How does this change serve that same goal?"
+- "This would require changes to [dependent system]. Have you considered the downstream impact?"
+
+#### Step 1.4: Modification Contract Proposal
+
+When confident about changes, present a modification contract:
+
+```
+## Modification Contract
+
+**Target Specification:** [Specification name and date]
+
+**Proposed Changes:** [Clear description of what will be modified]
+
+**Change Type:** [Addition/Removal/Modification/Refactor]
+
+**Impact Assessment:**
+- **Story Files Affected:** [Specific story-N-{name}.md files needing changes]
+- **New Stories Required:** [Additional story files to create]
+- **Stories to Remove/Combine:** [Story files becoming obsolete]
+- **Technical Components Affected:** [Code/architecture areas needing updates]
+- **Implementation Status:** [Existing work affected across stories]
+
+**Migration Strategy:** [Handle existing implementation, preserve work, rollback plan]
+
+**Updated Success Criteria:** [How success metrics change]
+
+**Revised Scope:** Still/Now/Removed/Out of scope [summarized changes]
+
+**⚠️ Risks & Concerns:**
+- [Specific technical or business risks from the changes]
+- [Potential complications or dependencies]
+
+**💡 Recommendations:**
+- [Suggestions for safer implementation approaches]
+- [Ways to minimize disruption to existing work]
+
+**Effort Estimate:** [How much additional/changed work is involved]
+
+---
+Options:
+- Type 'yes' to lock this modification contract and update the specification
+- Type 'edit: [your changes]' to modify the contract
+- Type 'compare' to see a detailed before/after comparison
+- Type 'risks' to explore implementation risks in detail
+- Type 'rollback' to understand how to undo these changes later
+- Ask more questions if anything needs clarification
+```
+
+### Phase 2: Specification Update (Post-Agreement Only)
+
+**Triggered only after user confirms modification contract with 'yes'**
+
+#### Step 2.1: Create Backup & Change Documentation
+
+**Backup Process:**
+1. Use `run_command` to get current timestamp:
+   ```bash
+   date +%Y%m%d-%H%M%S
+   ```
+2. Use `write_to_file` to create backup folder structure
+3. Use `view_file` to read all current files and copy to backup location
+4. Use `write_to_file` to create change log entry in `CHANGELOG.md`
+
+**Change Log Format:**
+```markdown
+# Specification Change Log
+
+## [Date] - [Change Type]
+**Modified by:** [User] | **Contract:** [Brief summary]
+
+### Changes: [List changes] | ### Files: [List files] | ### Backup: `backups/[timestamp]/`
+```
+
+#### Step 2.2: Update Core Specification Files
+
+**spec.md Updates:**
+- Use `view_file` to read current content
+- Use `write_to_file` to update with:
+  - Modified contract summary to reflect new agreement
+  - Updated detailed requirements based on clarification
+  - Revised implementation approach if changed
+  - Change log reference
+  - Updated status if appropriate
+
+**user-stories/ folder Updates:**
+- **README.md**: Update progress tracking table and story dependencies
+- **Individual story files**: Modify affected story-N-{name}.md files
+- **Story additions**: Create new story files with focused task groups (5-7 tasks max)
+- **Story combinations**: Merge related stories if they become too granular
+- **Story removals**: Archive or delete story files no longer needed
+- **Task reorganization**: Ensure task groups within stories remain manageable
+- **Status updates**: Mark completed tasks that might need rework across all stories
+
+#### Step 2.3: Update Technical Sub-Specifications
+
+**Selective Updates:**
+- Only update sub-specs affected by the changes using `view_file` and `write_to_file`
+- Create new sub-specs if new technical areas introduced
+- Archive sub-specs no longer relevant
+- Update cross-references between documents
+
+#### Step 2.4: Story-Based Task Reconciliation
+
+**Task Status Assessment Across Stories:**
+- Review each story file for task status and relevance
+- Identify completed tasks within stories that remain valid
+- Flag tasks requiring rework due to changes
+- Add new tasks while maintaining 5-7 task limit per story
+- Split stories if task count would exceed 7 tasks
+- Combine stories if task counts become too small
+- Reorder stories if dependencies changed
+
+**Story-Level Task Annotations:**
+```markdown
+# In story-1-user-auth.md:
+- [x] 1.1 Write tests for user authentication ✅ (Still valid)
+- [ ] 1.2 Implement OAuth provider ⚠️ (Needs modification)
+- [ ] 1.3 Create social login UI 🆕 (New task from scope change)
+- [~~] 1.4 Implement mobile-specific auth ❌ (Moved to new story-4-mobile-auth.md)
+```
+
+**Story Management:**
+- **Split large stories**: If modifications would create >7 tasks, create additional story files
+- **Archive obsolete stories**: Move removed stories to archived/ subfolder with timestamp
+- **Update story dependencies**: Modify README.md to reflect new story relationships
+- **Maintain story cohesion**: Ensure each story delivers standalone user value
+
+#### Step 2.5: Final Update Review & Validation
+
+Present updated package:
+```
+✅ Specification successfully updated!
+
+📁 .code-captain/specs/[DATE]-feature-name/
+├── 📋 spec.md - ⭐ Updated specification
+├── 👥 user-stories/ - ⭐ Updated story organization  
+│   ├── 📊 README.md - ⭐ Updated progress tracking
+│   └── 📝 story-N-{name}.md - ⭐ Modified stories (5-7 tasks each)
+├── 📂 sub-specs/ - ⭐ Updated technical specifications
+├── 💾 backups/[timestamp]/ - Original files preserved
+└── 📝 CHANGELOG.md - ⭐ Change documentation
+
+**Changes:** [X] stories modified, [Y] added, [Z] archived | **Tasks:** [N] total (max 5-7 per story)
+
+Please review: Does this accurately reflect the agreed modifications? Should any stories be split/combined?
+
+Original version backed up. Can help with rollback if needed.
+```
+
+#### Step 2.6: Create Memory of Specification Changes (Optional)
+After successful spec update, ask Cascade:
+"Please create a memory of these specification changes: [brief summary of modifications and their impact on the feature]"
+
+## Key Features
+
+**Safe Modification:** Backup creation, change tracking, rollback capability, impact assessment
+
+**Precise Control:** Focused clarification, risk assessment, migration strategy, selective updates
+
+**Implementation Continuity:** Task status preservation, clear rework annotation, timeline impact analysis
+
+**Change Documentation:** Detailed logs, comparison capability, rationale capture, rollback instructions
+
+## Windsurf Tools Used
+
+- `find_by_name`: Locate existing specifications and story files
+- `list_dir`: Explore specification directories and folder structures
+- `view_file`: Read current specification content and story files
+- `write_to_file`: Update specification documents and create backups
+- `codebase_search`: Analyze implementation progress and conflicts
+- `run_command`: Get timestamps for backup folder naming
+
+## Windsurf Features Used
+
+- **Memories**: After completion, optionally create memory of specification changes and their rationale
+
+---
+
+*📝 Safe evolution keeps specifications valuable. Change with intention, preserve with care.*