@devobsessed/code-captain 0.0.8 → 0.0.9

package/windsurf/workflows/edit-spec.md

@@ -1,273 +0,0 @@
----
-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.*

package/windsurf/workflows/execute-task.md

@@ -1,276 +0,0 @@
----
-description: Execute specific tasks systematically following Test-Driven Development workflow with comprehensive testing
----
-
-# Execute Task Workflow
-
-## Overview
-Execute specific tasks and sub-tasks systematically following a Test-Driven Development (TDD) workflow. Reads task specifications from `.code-captain/specs/` directories and implements features with comprehensive testing, following established code standards and best practices.
-
-## CRITICAL REQUIREMENT: 100% Test Pass Rate
-
-**⚠️ ZERO TOLERANCE FOR FAILING TESTS ⚠️**
-
-This workflow enforces strict test validation:
-- **NO story can be marked "COMPLETED" with ANY failing tests**
-- **100% test pass rate is MANDATORY before completion**
-- **"Edge case" or "minor" test failures are NOT acceptable**
-- **Implementation is considered incomplete until all tests pass**
-
-If tests fail, the story remains "IN PROGRESS" until all failures are resolved.
-
-## Command Process
-
-### Step 1: Task Discovery & Selection
-
-**Scan for available specifications:**
-
-- Use `find_by_name` to search `.code-captain/specs/` for dated specification folders
-- Use `view_file` to load user stories from `user-stories/` folders in each spec
-- Use `view_file` to read `user-stories/README.md` for story overview and progress
-- Use `view_file` to parse individual `story-N-{name}.md` files for available tasks
-- Present available stories and tasks organized by specification
-
-**Story selection 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 create-spec workflow first
-
-**Selection format:**
-```
-Available specifications:
-├── 2024-01-15-user-auth/ (3 stories, 12 total tasks)
-│   ├── Story 1: User Registration (5 tasks) - Not Started
-│   ├── Story 2: User Login (4 tasks) - Not Started
-│   └── Story 3: Password Reset (3 tasks) - Not Started
-└── 2024-01-20-payment-system/ (2 stories, 8 total tasks)
-    ├── Story 1: Payment Processing (5 tasks) - In Progress (2/5)
-    └── Story 2: Refund Management (3 tasks) - Not Started
-```
-
-### Step 2: Context Gathering & Analysis
-
-**Load specification context:**
-
-- Use `view_file` to read primary spec document: `spec.md`
-- Use `view_file` to load user stories overview: `user-stories/README.md`
-- Use `view_file` to read selected story file: `user-stories/story-N-{name}.md`
-- Use `view_file` to review technical specifications: `sub-specs/technical-spec.md`
-- Parse task breakdown from individual story file
-
-**Analyze current codebase:**
-
-Use `codebase_search` to understand:
-- Current architecture and patterns
-- Related existing functionality
-- Integration points for new features
-- Testing frameworks and conventions
-
-**Load project standards:**
-- Code style guide: `.code-captain/docs/code-style.md`
-- Technology stack: `.code-captain/docs/tech-stack.md`
-- Best practices: `.code-captain/docs/best-practices.md`
-
-### Step 3: Story & Task Analysis
-
-**Parse selected story structure:**
-
-- Use `view_file` to load complete story file: `user-stories/story-N-{name}.md`
-- Extract user story, acceptance criteria, and implementation tasks
-- Analyze task dependencies and execution order within the story
-- Understand test requirements (first task typically writes tests)
-- Plan implementation approach based on story's task breakdown
-
-**Validate TDD approach within story:**
-
-- **First task**: Should write tests for the story functionality
-- **Middle tasks**: Implement functionality to pass tests (max 5-7 tasks total)
-- **Final task**: Verify all tests pass and acceptance criteria are met
-- **Integration considerations**: Update adjacent/related tests as needed
-
-**Story structure:** User story → Acceptance criteria → Implementation tasks (max 5-7 tasks, first task writes tests, final task verifies 100% pass rate)
-
-### Step 4: Pre-Implementation Preparation
-
-**Validate testing setup:**
-- Use `codebase_search` to confirm testing framework is configured
-- Use `find_by_name` to verify test directories and naming conventions
-- Use `view_file` to check existing test patterns and utilities
-- Use `run_command` to ensure test runner is functional
-
-### Step 5: Story Task Execution (TDD Workflow)
-
-**Execute story tasks in sequential order:**
-
-#### Task 1: Write Tests (Test-First Approach)
-
-**Actions:**
-- Write comprehensive test cases for the entire feature using `write_to_file`
-- Include unit tests, integration tests, and edge cases
-- Cover happy path, error conditions, and boundary cases
-- Ensure tests fail appropriately (red phase)
-
-**Test categories to include:**
-- **Unit tests**: Individual function/method testing
-- **Integration tests**: Component interaction testing
-- **Edge cases**: Boundary conditions and error scenarios
-- **Acceptance tests**: User story validation
-
-#### Tasks 2-N: Implementation (Green Phase)
-
-**For each implementation task within the story:**
-
-1. **Focus on specific functionality**: Implement only what's needed for current task
-2. **Make tests pass**: Write minimal code to satisfy failing tests using `replace_file_content`
-3. **Update related tests**: Modify adjacent tests if behavior changes
-4. **Maintain compatibility**: Ensure no regressions in existing functionality
-5. **Refactor when green**: Improve code quality while tests remain passing
-
-**Implementation approach:**
-- Start with simplest implementation that passes tests
-- Add complexity incrementally as required by test cases
-- Keep tests passing at each step using `run_command` to verify
-- Refactor for clarity and maintainability
-
-#### Final Task: Test & Acceptance Verification
-
-**CRITICAL: 100% Test Pass Rate Required**
-
-**Mandatory Actions (ALL must succeed before story completion):**
-
-1. **Run complete test suite for this story** using `run_command`
-2. **Achieve 100% pass rate for ALL tests** - NO EXCEPTIONS
-3. **Verify no regressions in existing test suites**
-4. **Validate all acceptance criteria are met for the user story**
-5. **Confirm story delivers the specified user value**
-
-**⚠️ STORY CANNOT BE MARKED COMPLETE WITH ANY FAILING TESTS ⚠️**
-
-If ANY tests fail:
-- **STOP IMMEDIATELY** - Do not mark story as complete
-- Debug and fix each failing test
-- Re-run test suite until 100% pass rate achieved
-- Only then proceed to mark story as complete
-
-### Step 6: Story-Specific Test Validation
-
-**Run targeted test validation:**
-
-Use `run_command` to verify:
-- All tests written in first task are passing
-- New functionality works as specified in user story
-- All acceptance criteria are satisfied
-- No regressions introduced to existing features
-- Performance requirements are met (if specified)
-
-**Test execution strategy:**
-- **First**: Run only tests for current story/feature
-- **Then**: Run related test suites to check for regressions
-- **Finally**: Consider full test suite if significant changes made
-- **Acceptance**: Validate user story acceptance criteria are met
-
-**Failure handling:**
-
-**ZERO TOLERANCE FOR FAILING TESTS:**
-- **If ANY tests fail**: Story CANNOT be marked complete
-- **Required action**: Debug and fix ALL failing tests before proceeding
-- **No exceptions**: "Edge case" or "minor" failing tests are NOT acceptable
-- **If performance issues**: Optimize implementation until all tests pass
-- **If regressions found**: Fix regressions - story completion is blocked until resolved
-
-**Failure Resolution Process:**
-1. Identify root cause of each failing test
-2. Fix implementation to make test pass using `replace_file_content`
-3. Re-run ALL tests using `run_command` to ensure 100% pass rate
-4. Repeat until NO tests fail
-5. Only then mark story as complete
-
-### Step 7: Story Completion & Status Updates
-
-**Update story file status:**
-
-Use `replace_file_content` to mark completed tasks in story file:
-- Change status from "Not Started" to "Completed ✅"
-- Mark all tasks as [x] with ✅
-- Mark all acceptance criteria as [x] with ✅
-- Update Definition of Done with **ALL tests passing (100% pass rate)** ✅ **MANDATORY**
-- Add note: "Story CANNOT be marked complete without 100% test pass rate"
-
-**Update stories overview:**
-
-Use `replace_file_content` to update progress tracking in `user-stories/README.md`:
-
-```markdown
-| Story | Title | Status | Tasks | Progress |
-|-------|-------|--------|-------|----------|
-| 1 | User Authentication | Completed ✅ | 5 | 5/5 ✅ |
-| 2 | Password Reset | Not Started | 4 | 0/4 |
-| 3 | Profile Management | Not Started | 6 | 0/6 |
-
-**Total Progress:** 5/15 tasks (33%)
-```
-
-**Document completion:**
-- Update spec status if all stories in the specification are complete
-- Note any deviations from original plan in story notes
-- Document lessons learned or improvements made
-- Identify any follow-up tasks or technical debt
-
-**Present completion summary:**
-
-**If ALL tests pass (100%):** "Story completed successfully: [Story name] - Tasks: X/X ✅ - Tests: X/X (100%) ✅ - Next stories available"
-
-**If ANY tests fail:** "Story INCOMPLETE - Tests failing: [Story name] - Tests: X/Y (Z%) ❌ COMPLETION BLOCKED - Must fix all failing tests before completion"
-
-### Step 8: Create Memory of Completed Story (Optional)
-After successful story completion, ask Cascade:
-"Please create a memory of this completed story: [story name and key implementation approach, noting 100% test pass achievement]"
-
-## Integration with Code Captain Ecosystem
-
-**Specification dependency:**
-- Requires existing spec created by create-spec workflow
-- 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`
-- Follows technical approach from `sub-specs/technical-spec.md`
-
-**Code style compliance:**
-- Adheres to patterns in `.code-captain/docs/code-style.md`
-- Uses technology stack from `.code-captain/docs/tech-stack.md`
-- Follows best practices from `.code-captain/docs/best-practices.md`
-
-## Quality Standards
-
-**TDD:** Tests before implementation, **100% pass rate MANDATORY**, ZERO TOLERANCE for failures, comprehensive coverage, regression testing, failed tests = incomplete implementation.
-
-**Code quality:** Follow project patterns, maintain compatibility, proper error handling, appropriate logging.
-
-## Error Handling & Best Practices
-
-**Common failures:** No specs (→ create-spec), test framework issues (→ setup guidance), implementation conflicts (→ resolution strategies), performance issues (→ optimization)
-
-**Blocking issues:** Document as `⚠️ Blocking issue: [DESCRIPTION]` in story notes. Try alternatives, research solutions, break down tasks. Max 3 attempts before escalating.
-
-**TDD adherence:** Start with failing tests, minimal code to pass, refactor when green. **MANDATORY: 100% test pass rate before completion. NO EXCEPTIONS.**
-
-**Development:** Sequential tasks, verify each step with `run_command`, test early, validate incrementally, update status immediately, document decisions.
-
-## Windsurf Tools Used
-
-- `find_by_name`: Locate specifications, story files, and test directories
-- `view_file`: Read specification documents, story files, and existing code
-- `write_to_file`: Create test files and new implementation files
-- `replace_file_content`: Update existing code and story status files
-- `codebase_search`: Understand current architecture and patterns
-- `run_command`: Execute tests, verify functionality, and run build processes
-
-## Windsurf Features Used
-
-- **Memories**: After completion, optionally create memory of completed story and implementation approach
-
----
-
-*🧪 Tests first, code second, success always. No compromises on quality.*