@devobsessed/code-captain 0.0.3

package/windsurf/workflows/initialize.md

@@ -0,0 +1,298 @@
+---
+description: Set up technical foundation and development infrastructure for greenfield or brownfield projects
+---
+
+# Initialize Workflow
+
+## Overview
+Set up technical foundation and development infrastructure by detecting if this is a greenfield (new) or brownfield (existing) project and executing the appropriate technical setup workflow.
+
+## Detection Logic
+
+**Scan current directory for indicators:**
+- Presence of package.json, requirements.txt, Cargo.toml, go.mod, etc.
+- Existing source code directories (src/, lib/, app/, etc.)
+- Git repository status
+- Configuration files
+
+**Classify as:**
+- **Greenfield**: Empty directory or minimal files
+- **Brownfield**: Existing codebase with established structure
+
+## Workflow Process
+
+### Step 1: Project Type Detection
+
+**Use Windsurf tools to analyze project state:**
+
+- Use `list_dir` to scan current directory structure
+- Use `find_by_name` to search for common project files (package.json, requirements.txt, etc.)
+- Use `view_file` to check existing configuration files
+- Use `codebase_search` to understand existing code patterns and architecture
+
+**Detection criteria:**
+- **Greenfield indicators**: Empty/minimal directory, no dependency files, no src/ directories
+- **Brownfield indicators**: Existing dependency files, established directory structure, source code present
+
+### Step 2A: Greenfield Workflow (New Projects)
+
+**Phase 1: Technical Foundation Setup**
+
+**Ask focused technical questions:**
+1. **Project Type**: "What type of application are you building? (web app, API, mobile app, library, CLI tool, etc.)"
+2. **Technical Constraints**: "Any required technologies, frameworks, or platforms?"
+3. **Development Environment**: "What's your preferred development setup? (local, containerized, cloud-based)"
+4. **Scale Requirements**: "Expected technical scale? (prototype, small team, enterprise)"
+
+**Phase 2: Technology Recommendations**
+
+Based on technical requirements, recommend:
+- **Tech Stack**: Languages, frameworks, databases suitable for the project type
+- **Architecture Pattern**: Monolith, microservices, serverless based on scale needs
+- **Development Tools**: Testing frameworks, build tools, linting/formatting
+- **Project Structure**: Directory layout, naming conventions, configuration
+
+**Phase 3: Technical Foundation Setup**
+
+**Create project structure:**
+- Use `write_to_file` to create package/dependency files (package.json, requirements.txt, etc.)
+- Use `write_to_file` to create Git configuration (.gitignore, .gitattributes)
+- Use `write_to_file` to create development configuration (prettier, eslint, testing config)
+- Use `write_to_file` to create build and deployment configuration (if applicable)
+
+**Documentation Creation:**
+
+1. **`.code-captain/docs/tech-stack.md`** - Technology stack decisions and rationale
+2. **`.code-captain/docs/code-style.md`** - Coding standards and development patterns
+3. **`README.md`** - Technical overview and setup instructions
+
+**Tech Stack Documentation Template:**
+```markdown
+# Technology Stack
+
+## Languages
+- [Primary language with version]
+- [Secondary languages if any]
+
+## Frameworks & Libraries
+- [Main framework with version and purpose]
+- [Key dependencies with purposes]
+
+## Infrastructure
+- [Database technology]
+- [Deployment platform]
+- [CI/CD tools]
+
+## Development Tools
+- [Package manager]
+- [Testing framework]
+- [Linting/formatting tools]
+
+## Architecture Pattern
+[Monolith/Microservices/Serverless/etc. with reasoning]
+```
+
+**Code Style Documentation Template:**
+```markdown
+# Code Style Guide
+
+## File Organization
+[Directory structure patterns]
+
+## Naming Conventions
+- [Variable naming patterns]
+- [Function naming patterns]
+- [File naming patterns]
+
+## Code Patterns
+[Common patterns for the technology stack]
+
+## Testing Patterns
+[How tests are structured and named]
+
+## Documentation Style
+[Comment and documentation patterns]
+```
+
+### Step 2B: Brownfield Workflow (Existing Projects)
+
+**Phase 1: Codebase Analysis**
+
+**Scan and analyze existing project:**
+- Use `codebase_search` to understand overall architecture and patterns
+- Use `list_dir` to analyze file structure and organization patterns
+- Use `view_file` to examine dependencies and technology stack
+- Use `grep_search` to find code patterns, conventions, and architecture
+- Use `view_file` to review configuration files and build processes
+- Use `find_by_name` to locate testing setup and development tools
+- Use `codebase_search` to identify documentation gaps and technical debt
+
+**Analysis areas:**
+- **File structure** and organization patterns
+- **Dependencies** and technology stack
+- **Code patterns**, conventions, and architecture
+- **Configuration files** and build processes
+- **Testing setup** and development tools
+- **Documentation gaps** and technical debt
+
+**Phase 2: Documentation Generation**
+
+**Create comprehensive technical documentation:**
+
+Use `write_to_file` to create:
+
+1. **`.code-captain/docs/tech-stack.md`** - Current technology stack analysis
+2. **`.code-captain/docs/code-style.md`** - Observed code patterns and conventions
+3. **`.code-captain/docs/architecture.md`** - System architecture and technical decisions (if complex)
+
+**Phase 3: Gap Analysis & Recommendations**
+
+Identify and document:
+- **Missing technical documentation**
+- **Inconsistent code patterns**
+- **Technical debt and improvement opportunities**
+- **Testing coverage gaps**
+- **Development workflow improvements**
+- **Architecture optimization opportunities**
+
+### Step 3: Directory Structure Setup
+
+**Ensure Code Captain structure exists:**
+
+Use `list_dir` to check and `write_to_file` to create if missing:
+
+```
+.code-captain/
+├── docs/
+│   ├── best-practices.md     # Development best practices (pre-installed)
+│   ├── code-style.md         # Code conventions and patterns
+│   ├── tech-stack.md         # Technology decisions and rationale
+│   └── architecture.md       # System architecture (if complex)
+└── research/                 # Research outputs and technical analysis
+```
+
+### Step 4: Final Steps & Guidance
+
+**For Greenfield Projects:**
+```
+🚀 Technical Foundation Complete!
+
+Your development environment is now set up and documented:
+- Technology stack documented and configured
+- Development tools and standards established  
+- Project structure and configuration ready
+
+## Recommended Next Steps:
+
+### For Product Strategy (Recommended First):
+/plan-product "your product idea" - Define product vision, strategy, and roadmap
+
+### For Feature Development:
+/create-spec "feature description" - Create detailed feature specifications
+/execute-task - Implement features with TDD workflow
+
+### For Research:
+/research "topic" - Conduct systematic technical research
+/create-adr "decision" - Document architectural decisions
+
+Ready to define your product strategy and start building!
+```
+
+**For Brownfield Projects:**
+```
+🔍 Technical Foundation Analysis Complete!
+
+Your existing project has been analyzed and documented:
+- Current technology stack and architecture documented
+- Code patterns and conventions identified
+- Technical gaps and improvement opportunities noted
+
+## Recommended Next Steps:
+
+### For Product Strategy (Recommended First):
+/plan-product "enhanced product vision" - Define product strategy and roadmap
+
+### For Feature Development:
+/create-spec "feature description" - Create detailed feature specifications
+/execute-task - Implement features following established patterns
+
+### For Technical 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!
+```
+
+## Integration with Code Captain Ecosystem
+
+**Workflow relationship:**
+- **Initialize** handles ONLY technical foundation
+- **/plan-product** handles product strategy and vision  
+- Users need both for complete project setup
+- **/plan-product** should be the next step before feature development
+
+**Cross-workflow integration:**
+- Documentation created here used by `/create-spec` for understanding patterns
+- Tech stack analysis used by `/execute-task` for implementation guidance
+- Architecture documentation used by `/create-adr` for decision context
+- Gap analysis used by `/research` for improvement priorities
+
+## Technical Implementation
+
+**File creation process:**
+1. Use `write_to_file` to create all documentation files
+2. Ensure `.code-captain/docs/` directory exists
+3. Create comprehensive content in each file
+4. Verify file paths match expected locations
+
+**Analysis process:**
+- Use `codebase_search` for semantic understanding of existing code
+- Use `find_by_name` for discovering project files and patterns
+- Use `view_file` for examining specific configuration and code files
+- Use `grep_search` for finding specific patterns and conventions
+
+## Quality Standards
+
+**Documentation completeness:**
+- Tech stack with versions and justifications
+- Code style with observable patterns
+- Architecture decisions and rationale
+- Clear setup and development instructions
+
+**Analysis thoroughness:**
+- Complete technology inventory
+- Consistent pattern identification
+- Gap analysis with actionable recommendations
+- Integration point documentation
+
+## Error Handling
+
+**Common scenarios:**
+- **Empty directory**: Proceed with greenfield workflow
+- **Ambiguous project type**: Ask user for clarification
+- **Missing permissions**: Guide user to resolve access issues
+- **Complex architecture**: Break analysis into smaller components
+
+**Fallback strategies:**
+- If automated detection fails, ask user directly
+- If file creation fails, provide manual instructions
+- If analysis is incomplete, document known limitations
+- If tools fail, provide alternative approaches
+
+## Windsurf Tools Used
+
+- `list_dir`: Explore project directory structure and organization
+- `find_by_name`: Locate project files, configurations, and dependencies
+- `view_file`: Examine existing code, configurations, and documentation
+- `write_to_file`: Create technical documentation and configuration files
+- `codebase_search`: Understand architecture, patterns, and codebase structure
+- `grep_search`: Find specific patterns, conventions, and code structures
+- `run_command`: Execute setup commands and validate configurations
+
+## Windsurf Features Used
+
+- **Memories**: After setup completion, ask Cascade to "create a memory of the technology stack and architectural decisions"
+
+---
+
+*🏗️ Building solid technical foundations for sustainable development.*

package/windsurf/workflows/new-command.md

@@ -0,0 +1,321 @@
+---
+description: Create new Code Captain workflows following established patterns and conventions for Windsurf
+---
+
+# New Command Workflow
+
+## Overview
+A meta workflow that creates new Code Captain workflows following established patterns and conventions. This workflow generates properly structured workflow files, updates documentation, and ensures consistency across the Code Captain ecosystem for Windsurf environments.
+
+## Usage Examples
+
+```bash
+# Create a new workflow
+/new-command "optimize" "Performance optimization for slow code sections"
+
+# Create deployment workflow
+/new-command "deploy" "Deploy applications to various cloud platforms"
+
+# Create test generation workflow
+/new-command "test-gen" "Generate comprehensive test suites from existing code"
+```
+
+## Workflow Process
+
+### Step 1: Command Specification Gathering
+
+**Initial Input Processing:**
+- Parse workflow name (validate format: lowercase, hyphens allowed)
+- Extract brief description from user input
+- Use `find_by_name` to validate workflow name doesn't conflict with existing workflows
+
+**Interactive Specification Building:**
+
+Ask clarifying questions to build complete workflow specification:
+
+1. **Workflow Category**: "Is this a [Setup/Analysis/Implementation/Integration] workflow?"
+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 Windsurf tools will it use? (codebase_search, view_file, etc.)"
+7. **Workflow Steps**: "What are the main phases/steps the workflow follows?"
+
+### Step 2: Workflow Structure Generation
+
+**Generate Standard Workflow File Structure:**
+
+Use `write_to_file` to create workflow in `.windsurf/workflows/[command-name].md`:
+
+```markdown
+---
+description: [Generated from description and clarifying questions]
+---
+
+# [Command Name] Workflow
+
+## Overview
+[Generated from description and clarifying questions]
+
+## Usage Examples
+
+```bash
+# Primary usage
+/[command-name] [arguments]
+
+# Example scenarios
+/[command-name] [example-args]
+```
+
+## Workflow Process
+
+### Step 1: [Phase Name]
+[Generated workflow steps]
+
+### Step 2: [Phase Name]
+[Generated workflow steps]
+
+## Core Rules
+[Generated based on workflow type]
+
+## Integration with Code Captain Ecosystem
+[Generated integration details]
+
+## Windsurf Tools Used
+[Generated tool list]
+
+## Windsurf Features Used
+[Generated features list]
+
+---
+*[Generated tagline]*
+```
+
+**Template Sections Based on Workflow Type and Execution Style:**
+
+**Contract Style Workflows** (like `create-spec`, `create-adr`):
+- Phase 1: Contract Establishment (No File Creation)
+- Interactive clarification rounds with structured questions
+- Critical analysis and assumption challenging
+- Contract proposal phase
+- Explicit user agreement before proceeding
+
+**Direct Execution Workflows** (like `swab`, `execute-task`):
+- Immediate action workflows
+- Minimal clarification if needed
+- Clear step-by-step execution
+- Progress feedback and completion confirmation
+
+**Setup/Analysis Workflows:**
+- Context scanning steps
+- File generation workflows
+- Documentation creation
+
+**Implementation Workflows:**
+- TDD workflows if applicable
+- Code modification steps
+- Verification procedures
+
+**Integration Workflows:**
+- Platform-specific API interactions
+- Sync and conflict resolution
+- Error handling patterns
+
+### Step 3: Tool Integration Mapping
+
+**Map appropriate Windsurf tools based on workflow type:**
+
+**File Operations:**
+- `view_file`, `write_to_file`, `replace_file_content`, `find_by_name`, `list_dir`, `grep_search`
+
+**Code Analysis:**
+- `codebase_search`, `view_code_item`, `trajectory_search`
+
+**Web & Browser:**
+- `browser_preview`, `open_browser_url`, `search_web`, `read_url_content`
+
+**System & Deployment:**
+- `run_command`, `command_status`, `deploy_web_app`
+
+**Memory & Context:**
+- `view_content_chunk`, Memories feature for important decisions
+
+### Step 4: Validation and Character Limit Check
+
+**Verify Workflow Integration:**
+- Use `view_file` to check workflow file syntax and structure
+- Use `run_command` with `wc -c` to validate under 12k character limit
+- Use `find_by_name` to ensure no conflicts with existing workflows
+- Run basic structure validation
+
+**Character Limit Enforcement:**
+```bash
+# Check if workflow is under 12k limit
+wc -c .windsurf/workflows/[command-name].md
+
+# Validate limit
+[ $(wc -c < .windsurf/workflows/[command-name].md) -lt 12000 ] && echo "✅ Under 12k" || echo "⚠️ Over 12k"
+```
+
+**Present Summary:**
+```
+✅ New workflow created successfully!
+
+📁 Files Created:
+  - .windsurf/workflows/[command-name].md
+
+🚀 Workflow Ready:
+  Usage: /[command-name] [args]
+  Documentation: .windsurf/workflows/[command-name].md
+  Character count: [X]/12000 characters
+
+📏 Character Limit: ✅ Under 12k limit
+```
+
+## Core Rules
+
+1. **Consistent Structure** - All generated workflows follow established Windsurf patterns
+2. **Clear Documentation** - Each section has purpose and implementation details
+3. **Character Limit Compliance** - All workflows must be under 12k characters
+4. **Slash Command Syntax** - Use /command-name format for all examples
+5. **Windsurf Tool Integration** - Use appropriate Windsurf tools for functionality
+6. **Template Flexibility** - Adapt template based on workflow type and requirements
+7. **Language & Shell Agnostic** - Workflows work across different programming languages using Windsurf's tools
+
+## Workflow Generation Templates
+
+### Contract Style Template Structure
+```markdown
+## Workflow Process
+
+### Step 1: Requirement Clarification
+**Gather detailed requirements through structured questions**
+- [Specific clarification questions]
+- [Assumption challenging]
+- [Context gathering]
+
+### Step 2: Contract Proposal
+**Present structured contract for user agreement**
+- [Contract format specific to workflow type]
+- [Success criteria definition]
+- [Scope boundaries]
+
+### Step 3: User Agreement
+**Explicit confirmation before proceeding**
+- [Agreement validation]
+- [Scope confirmation]
+
+### Step 4: Implementation
+**Execute workflow based on agreed contract**
+- [Implementation steps]
+- [Progress tracking]
+- [Validation procedures]
+```
+
+### Direct Execution Template Structure
+```markdown
+## Workflow Process
+
+### Step 1: Context Analysis
+**Analyze current state and requirements**
+- [Context gathering steps]
+- [Requirement analysis]
+
+### Step 2: Action Execution
+**Perform workflow actions directly**
+- [Action steps]
+- [Tool usage]
+- [Progress feedback]
+
+### Step 3: Verification
+**Validate results and completion**
+- [Verification steps]
+- [Quality checks]
+- [Completion confirmation]
+```
+
+## Command Name Validation
+
+**Validation Rules:**
+- Lowercase letters, numbers, hyphens only
+- No spaces or special characters
+- Maximum 20 characters
+- Cannot start with number or hyphen
+- Must not conflict with existing workflows
+
+**Validation Process:**
+Use `grep_search` and `find_by_name` to check for conflicts:
+```bash
+# Check existing workflows
+find_by_name "[command-name].md" in .windsurf/workflows/
+
+# Validate format using pattern matching
+```
+
+## Error Handling
+
+**Common Issues:**
+- **Duplicate workflow name**: Check existing workflows, suggest alternatives
+- **Invalid workflow name format**: Provide format guidance and examples
+- **Character limit exceeded**: Provide optimization suggestions
+- **Template generation errors**: Validate inputs, provide clear error messages
+
+**Error Messages:**
+```
+❌ Workflow creation failed: [specific reason]
+
+Suggestions:
+- Check workflow name format (lowercase, hyphens only)
+- Ensure name doesn't conflict with existing workflows
+- Verify all required inputs are provided
+- Ensure generated content is under 12k characters
+
+Try: /new-command "valid-name" "clear description"
+```
+
+## Integration with Code Captain Ecosystem
+
+**Workflow relationship:**
+- Generates workflows compatible with other Code Captain workflows
+- Follows established patterns from existing workflows
+- Maintains consistency in structure and tool usage
+- Ensures proper slash command syntax throughout
+
+**Cross-workflow integration:**
+- New workflows can reference existing workflows with proper `/workflow-name` syntax
+- Generated workflows include appropriate tool mappings
+- Documentation follows established Windsurf patterns
+- Character limit compliance ensures deployability
+
+## Quality Standards
+
+**Structure requirements:**
+- Proper frontmatter with description
+- Clear overview and usage examples
+- Detailed workflow process with numbered steps
+- Appropriate tool integration
+- Proper slash command syntax
+
+**Content quality:**
+- Clear, actionable workflow steps
+- Appropriate tool usage for each step
+- Proper error handling guidance
+- Integration notes with other workflows
+- Character count optimization
+
+## Windsurf Tools Used
+
+- `find_by_name`: Locate existing workflows and check for conflicts
+- `view_file`: Examine existing workflow patterns for consistency
+- `write_to_file`: Create new workflow files
+- `run_command`: Validate character limits and file structure
+- `codebase_search`: Understand existing workflow patterns
+- `grep_search`: Search for workflow naming conflicts and patterns
+
+## Windsurf Features Used
+
+- **Memories**: After creating complex workflows, ask Cascade to "create a memory of this workflow pattern and its structure"
+
+---
+
+*🔧 Building workflows that build workflows - meta automation at its finest.*