@devobsessed/code-captain 0.0.5 → 0.0.8

package/windsurf/workflows/swab.md

@@ -0,0 +1,212 @@
+---
+description: "A deck-cleaning workflow that makes one small, focused improvement to the codebase following the Boy Scout Rule"
+---
+
+# Swab Workflow
+
+## Overview
+
+A deck-cleaning workflow that makes one small, focused improvement to the codebase, following the "Boy Scout Rule" - leave the code cleaner than you found it. Identifies the single best small cleanup opportunity and applies it with your approval.
+
+## Usage
+
+```bash
+/swab
+```
+
+**Note:** No options, no flags, no complexity. Just simple deck cleaning.
+
+## Process
+
+### Step 1: Codebase Scanning
+
+**Scan for improvement opportunities:**
+
+- Search project files for common code smells
+- Analyze file patterns and naming conventions  
+- Identify low-risk, high-impact improvements
+- Focus on clarity and maintainability wins
+
+**Target Areas:**
+- Unclear variable names (`d`, `temp`, `data`, single letters)
+- Magic numbers that should be constants
+- Missing error handling on JSON.parse, API calls
+- Commented-out code blocks
+- Inconsistent formatting patterns
+- Overly abbreviated names
+- Unused imports or variables
+
+### Step 2: Opportunity Prioritization
+
+**Selection Criteria:**
+1. **Clarity Impact** - How much clearer will the code be?
+2. **Risk Level** - How certain are we this won't break anything?
+3. **Scope** - Prefer 1-10 line changes maximum
+4. **Confidence** - Only suggest changes we're 100% certain about
+
+**Priority Order:**
+1. Variable/function name improvements
+2. Magic number extraction to constants
+3. Adding missing error handling
+4. Removing dead code
+5. Formatting consistency fixes
+
+### Step 3: Present Single Best Option
+
+**Display Format:**
+```
+🧽 Swabbing the deck... found some mess in {filename}
+
+=== SUGGESTED CLEANUP ===
+
+- {before_code}
++ {after_code}
+
+Reason: {clear_explanation}
+Risk: {Low|Medium}
+
+Clean this up? [y/N]
+```
+
+### Step 4: Apply Change
+
+**If approved:**
+- Make the exact replacement using search/replace
+- Verify the change was applied correctly
+- Show success message: "✅ Deck swabbed! One less mess aboard."
+
+**If declined:**
+- Exit gracefully with: "🧽 Deck inspection complete. No changes made."
+
+## Core Rules
+
+1. **One change only** - Never fix multiple things at once
+2. **Small changes** - Maximum 10 lines modified
+3. **Safe changes** - If uncertain, do nothing
+4. **Your approval required** - Always ask before applying
+5. **Exact replacements** - Surgical precision, no formatting noise
+6. **Conservative approach** - Better to find nothing than break something
+
+## Implementation with Windsurf Tools
+
+### Codebase Scanning Strategy
+
+**File Discovery:**
+- Use `codebase_search` to find code patterns and smells across source files
+- Use `find_by_name` to locate relevant files and directories
+- Use `view_file` to inspect file contents when needed
+- Focus on recently modified files first (higher likelihood of improvement opportunities)
+
+**Content Analysis:**
+- Use `view_file` for reading file contents for analysis
+- Use `codebase_search` for pattern detection
+- Focus on files under 500 lines for simplicity
+- Prioritize recently modified files
+
+### Change Application
+
+**File Modification:**
+```bash
+# Use replace_file_content for exact string replacement
+replace_file_content(
+  file_path=target_file,
+  old_content=exact_match_text,
+  new_content=improved_text
+)
+```
+
+**Verification:**
+- Re-read file with `view_file` to confirm change applied correctly
+- Run basic syntax validation if available
+- Ensure no unintended modifications occurred
+
+### Error Handling
+
+**No opportunities found:**
+```
+🧽 Deck inspection complete. 
+
+No obvious cleanup opportunities found in the scanned files.
+Your codebase looks pretty tidy already! ✨
+
+Run again later as the code evolves, or try focusing on a specific directory.
+```
+
+**Multiple opportunities found:**
+- Always pick the highest-impact, lowest-risk option
+- Never present multiple options (causes decision paralysis)
+- Save other opportunities for future runs
+
+**Change application failure:**
+```
+❌ Swab attempt failed. 
+
+The suggested change couldn't be applied safely.
+This might happen if the file was modified since scanning.
+Try running the workflow again.
+```
+
+## Analysis Prompt for AI
+
+```
+You are a code reviewer cleaning up small messes.
+
+MISSION: Find exactly ONE small, safe cleanup opportunity in the codebase.
+
+RULES:
+- Find ONE small cleanup only (1-10 lines max changed)
+- Prioritize clarity and safety over cleverness
+- Preserve all existing functionality exactly
+- Be extremely conservative - if ANY uncertainty, do nothing
+- Provide exact search/replace strings
+- Focus on high-impact, zero-risk improvements
+
+SCAN PRIORITIES:
+1. Unclear variable names (single letters, abbreviations)
+2. Magic numbers that should be named constants
+3. Missing error handling (JSON.parse, fetch, etc.)
+4. Dead/commented code removal
+5. Minor formatting consistency
+
+RESPONSE FORMAT:
+If you find a good cleanup opportunity:
+{
+  "cleanup": "Brief description of the improvement",
+  "filename": "path/to/file.js",
+  "searchText": "exact text to find (with proper whitespace)",
+  "replaceText": "exact replacement text (with proper whitespace)",
+  "reasoning": "Why this specific change helps readability/maintainability",
+  "riskLevel": "Low|Medium",
+  "linesChanged": number_of_lines_modified
+}
+
+If no clear, safe cleanup exists:
+{
+  "cleanup": null,
+  "message": "No obvious cleanup opportunities found. Codebase looks tidy!"
+}
+
+CRITICAL: Only suggest changes you are 100% confident about. When in doubt, suggest nothing.
+```
+
+## Integration Notes
+
+This workflow integrates with the existing Code Captain ecosystem by:
+
+1. **Following established patterns** - Uses same markdown structure as other workflows
+2. **Leveraging Windsurf tools** - Uses `codebase_search`, `view_file`, `replace_file_content`
+3. **Maintaining simplicity** - No complex configuration or state management
+4. **Respecting user control** - Always asks permission before making changes
+5. **Quality foundation** - Complements specification and implementation commands by maintaining code quality, supporting the overall project foundation alongside `.code-captain` documentation
+
+## Future Enhancements
+
+Potential future improvements (not in initial version):
+
+- **Directory targeting**: `/swab src/components/`
+- **File type filtering**: `/swab --js-only`
+- **Batch mode**: `/swab --batch` (apply multiple small changes)
+- **Learning**: Remember which types of cleanups user prefers
+- **Metrics**: Track improvements made over time
+
+But for now: Keep it simple. One workflow, one small improvement, user approval required. 

package/cursor/integrations/azure-devops/create-azure-work-items.md

@@ -1,403 +0,0 @@
-# Create Azure DevOps Work Items Command (cc: create-azure-work-items)
-
-## Overview
-
-Automatically create Azure DevOps work items from existing user stories and tasks, establishing parent-child relationships through hierarchical work item types and updating source documents with work item IDs for traceability.
-
-## Usage
-
-```bash
-cc: create-azure-work-items [spec-folder-path]
-```
-
-**Examples:**
-
-```bash
-cc: create-azure-work-items .code-captain/specs/2024-12-28-user-profile-dashboard/
-cc: create-azure-work-items  # Auto-detect latest spec folder
-```
-
-## Command Process
-
-### Step 1: Context Discovery & Validation
-
-**Auto-detect spec folder (if no path provided):**
-
-- Search `.code-captain/specs/` for most recent dated folder
-- Validate folder contains required files: `user-stories.md` and `tasks.md`
-- Confirm Azure DevOps project context is available
-
-**Validate required files exist:**
-
-- `user-stories.md` - Source for User Story work items
-- `tasks.md` - Source for Task and Sub-task work items
-- Optional: `spec.md` for additional context
-
-**Azure DevOps project detection:**
-
-- Check if current directory is a git repository with Azure DevOps remote
-- Extract organization and project from remote origin
-- Validate Azure DevOps access permissions and PAT configuration
-
-### Step 2: Create Todo Tracking
-
-**Use `todo_write` to track the work item creation process:**
-
-```json
-{
-  "todos": [
-    {
-      "id": "azure-workitems-parse",
-      "content": "Parse user stories and tasks from spec documents",
-      "status": "in_progress"
-    },
-    {
-      "id": "azure-workitems-create-stories",
-      "content": "Create User Story work items from user stories",
-      "status": "pending"
-    },
-    {
-      "id": "azure-workitems-create-tasks",
-      "content": "Create Task work items linked to User Stories",
-      "status": "pending"
-    },
-    {
-      "id": "azure-workitems-update-docs",
-      "content": "Update user-stories.md and tasks.md with work item IDs",
-      "status": "pending"
-    },
-    {
-      "id": "azure-workitems-verify",
-      "content": "Verify all work items created and documents updated",
-      "status": "pending"
-    }
-  ]
-}
-```
-
-### Step 3: Parse Spec Documents
-
-**Read and parse user-stories.md:**
-
-- Extract each user story with its structure:
-  - Title
-  - "As a/I want to/So that" format
-  - Acceptance criteria list
-  - Definition of done checklist
-
-**Read and parse tasks.md:**
-
-- Extract main tasks and their subtasks
-- Identify task hierarchy (1.0, 1.1, 1.2, etc.)
-- Preserve task descriptions and checkboxes
-
-**Create mapping structure:**
-
-```javascript
-{
-  userStories: [
-    {
-      title: "Story Title",
-      description: "As a user...",
-      acceptanceCriteria: ["Given...", "When...", "Then..."],
-      definitionOfDone: ["Testable requirement 1", "..."],
-      originalLineRange: [25, 45]
-    }
-  ],
-  tasks: [
-    {
-      title: "Main Task Title",
-      subtasks: [
-        { title: "Subtask 1", description: "...", originalLineRange: [10, 12] },
-        { title: "Subtask 2", description: "...", originalLineRange: [13, 15] }
-      ],
-      originalLineRange: [8, 20]
-    }
-  ]
-}
-```
-
-### Step 4: Create User Story Work Items
-
-**For each user story:**
-
-**Work item title format:**
-
-```
-{Story Title}
-```
-
-**Work item fields:**
-
-- **Work Item Type:** User Story
-- **Title:** Story title
-- **Description:** Full user story with acceptance criteria
-- **State:** New
-- **Area Path:** Current project area
-- **Iteration Path:** Current iteration
-- **Tags:** user-story, code-captain
-
-**Description template:**
-
-```markdown
-## User Story
-
-{User Story Description - "As a ... I want to ... So that ..."}
-
-## Acceptance Criteria
-
-{Acceptance Criteria formatted as checklist}
-
-- [ ] Given [context], when [action], then [outcome]
-- [ ] Given [context], when [action], then [outcome]
-
-## Definition of Done
-
-{Definition of Done formatted as checklist}
-
-- [ ] [Testable requirement]
-- [ ] [Testable requirement]
-
----
-
-_Generated from spec: {spec-folder-name}_
-_Source: user-stories.md_
-```
-
-**Create work items using Azure DevOps REST API:**
-
-- Use Azure DevOps REST API to create User Story work items
-- Store returned work item IDs with user story mapping
-
-### Step 5: Create Task Work Items
-
-**For each main task:**
-
-**Main task work item:**
-
-- **Work Item Type:** Task
-- **Title:** Main task title
-- **Parent Link:** Link to related User Story (if applicable)
-- **Description:** Task overview with subtask list
-- **State:** New
-- **Tags:** task, code-captain
-
-**For each subtask:**
-
-**Subtask work item:**
-
-- **Work Item Type:** Task
-- **Title:** Subtask title
-- **Parent Link:** Link to main task
-- **Description:** Subtask details
-- **State:** New
-- **Tags:** subtask, code-captain
-
-**Description template for main tasks:**
-
-```markdown
-## Task Overview
-
-{Main Task Description}
-
-## Sub-Tasks
-
-This task includes the following sub-tasks:
-
-{List of subtask work items with links - populated after creation}
-
----
-
-_Generated from spec: {spec-folder-name}_
-_Source: tasks.md_
-```
-
-**Description template for subtasks:**
-
-```markdown
-## Subtask Details
-
-{Subtask Description}
-
-## Parent Task
-
-This subtask belongs to: {parent-task-work-item-link}
-
----
-
-_Generated from spec: {spec-folder-name}_
-_Source: tasks.md_
-```
-
-### Step 6: Update Source Documents with Work Item IDs
-
-**Update user-stories.md:**
-
-For each user story, add work item ID reference:
-
-```markdown
-## Story 1: User Profile Creation [#123]
-
-**As a** new user
-**I want to** create a profile with basic information
-**So that** I can personalize my experience
-
-### Work Item: [123](https://dev.azure.com/org/project/_workitems/edit/123)
-
-### Acceptance Criteria
-
-...
-```
-
-**Update tasks.md:**
-
-For each task and subtask, add work item ID references:
-
-```markdown
-## Tasks
-
-- [ ] 1. User Authentication System [#124]
-
-  - [ ] 1.1 Write tests for authentication middleware [#125]
-  - [ ] 1.2 Implement JWT token generation [#126]
-  - [ ] 1.3 Create password hashing utilities [#127]
-
-### Task Work Items:
-
-- Main Task: [124](https://dev.azure.com/org/project/_workitems/edit/124)
-- Subtasks: [125](https://dev.azure.com/org/project/_workitems/edit/125), [126](https://dev.azure.com/org/project/_workitems/edit/126), [127](https://dev.azure.com/org/project/_workitems/edit/127)
-```
-
-### Step 7: Create Work Item Relationship Mapping
-
-**Generate mapping document:**
-
-Create `.code-captain/specs/{spec-folder}/azure-workitems-mapping.md`:
-
-```markdown
-# Azure DevOps Work Items Mapping
-
-> Generated: {current-date}
-> Spec: {spec-folder-name}
-> Organization: {org-name}
-> Project: {project-name}
-
-## User Story Work Items
-
-| Story Title   | Work Item # | Azure DevOps Link                                             |
-| ------------- | ----------- | ------------------------------------------------------------- |
-| Story 1 Title | 123         | [Link](https://dev.azure.com/org/project/_workitems/edit/123) |
-| Story 2 Title | 124         | [Link](https://dev.azure.com/org/project/_workitems/edit/124) |
-
-## Task Work Items
-
-| Task Title   | Main Work Item | Sub Work Items           |
-| ------------ | -------------- | ------------------------ |
-| Task 1 Title | [125](link)    | [126](link), [127](link) |
-| Task 2 Title | [128](link)    | [129](link), [130](link) |
-
-## Summary
-
-- **Total Work Items Created:** {count}
-- **User Stories:** {count}
-- **Main Tasks:** {count}
-- **Subtasks:** {count}
-
-## Source Files Updated
-
-- ✅ user-stories.md - Added work item references
-- ✅ tasks.md - Added work item references and links
-- ✅ azure-workitems-mapping.md - Created mapping document
-```
-
-### Step 8: Verification & Summary
-
-**Verify all work items created:**
-
-- Check each returned work item ID is valid
-- Verify Azure DevOps links are accessible
-- Confirm parent-child relationships established
-
-**Present completion summary:**
-
-```
-✅ Azure DevOps Work Items Creation Complete
-
-📊 Summary:
-- User Stories: {count} work items created
-- Main Tasks: {count} work items created
-- Subtasks: {count} work items created
-- Total: {total-count} work items
-
-📁 Updated Files:
-- user-stories.md - Added work item references
-- tasks.md - Added work item references and task links
-- azure-workitems-mapping.md - Created mapping document
-
-🔗 Organization: {org-name}
-📋 Project: {project-name}
-📋 All work items available at: https://dev.azure.com/{org}/{project}/_workitems
-```
-
-## Configuration Requirements
-
-**Azure DevOps Access:**
-
-- Personal Access Token (PAT) with Work Items (read, write) permissions
-- Organization and project access
-- Environment variable: `AZURE_DEVOPS_PAT`
-
-**Project Configuration:**
-
-- Extract organization and project from git remote URL
-- Support both SSH and HTTPS Azure DevOps remotes
-- Validate access to target project
-
-## Error Handling & Edge Cases
-
-**Missing configuration:**
-
-- If PAT not configured: Provide setup instructions
-- If not an Azure DevOps repository: Error with guidance
-- If project access denied: Clear permission error message
-
-**API limitations:**
-
-- Handle rate limiting with appropriate delays
-- Retry failed work item creation attempts
-- Validate work item field requirements
-
-**Document parsing errors:**
-
-- Handle malformed user story structures gracefully
-- Skip invalid task hierarchies with warnings
-- Continue processing valid entries when possible
-
-## Integration with Existing Commands
-
-**Works with create-spec:**
-
-- Automatically detects create-spec output format
-- Reads user-stories.md and tasks.md generated by create-spec
-- Maintains consistency with spec folder structure
-
-**Azure DevOps specific features:**
-
-- Utilizes Azure DevOps work item hierarchy (User Story > Task)
-- Creates proper parent-child relationships
-- Applies Azure DevOps specific tags and fields
-- Integrates with Azure DevOps iterations and areas
-
-## Usage Notes
-
-**Prerequisites:**
-
-- Existing spec folder with user-stories.md and tasks.md
-- Azure DevOps project with appropriate permissions
-- Azure DevOps PAT configured in environment
-
-**Best practices:**
-
-- Run after completing spec creation and review
-- Ensure spec documents are finalized before creating work items
-- Use consistent area and iteration paths for better organization