BMAD-METHOD/workspace-utils/docs/windsurf.md

# BMAD Workspace Integration - Windsurf IDE

## Overview
BMAD workspace utilities provide full compatibility with Windsurf IDE, enabling seamless AI-assisted collaborative development with intelligent workspace management.

## Setup

### 1. Initialize Workspace
```bash
npm run workspace-init
```
Windsurf-specific setup includes:
- Session tracking optimized for Windsurf AI agent workflows
- Context sharing compatible with Windsurf's AI conversation memory
- Integration with Windsurf's project understanding capabilities

### 2. Verify Integration
```bash
npm run workspace-status
```
Expected output for Windsurf:
- ✅ Active session detected (windsurf)
- 🤖 AI agent compatibility enabled
- 📁 Workspace structure optimized for AI context

## Windsurf-Specific Features

### 🤖 AI Agent Integration
- **Context Continuity**: Workspace context integrates with Windsurf's AI memory
- **Agent Handoffs**: Seamless transitions between human developers and AI agents
- **Conversation Context**: Workspace state informs AI assistant conversations
- **Multi-Modal Support**: Workspace handles code, documentation, and AI interactions

### 🧠 Intelligent Workspace Features

#### AI-Enhanced Session Management
```bash
npm run workspace-init       # Creates AI-aware session with conversation context
npm run workspace-status     # Shows AI agent activity and human collaboration
npm run workspace-sync       # Synchronizes with Windsurf AI conversation memory
```

#### Smart Agent Handoffs
```bash
# Handoff to AI agent
npm run workspace-handoff create --to ai --work "Implement user authentication"

# Handoff to human developer
npm run workspace-handoff create --to dev --work "Review AI-generated code"

# Handoff to QA with AI context
npm run workspace-handoff create --to qa --work "Test AI-implemented features"
```

## Windsurf Integration Patterns

### 1. AI Conversation Context
The workspace system automatically integrates with Windsurf's AI conversations:

```markdown
# Example: AI Context Integration
## Current Workspace State
- **Session**: windsurf-session-abc123
- **Active Work**: Feature development with AI assistance
- **Context Files**: 12 shared context files
- **Recent Handoffs**: AI → Developer → QA

## AI Conversation Summary
- Discussed authentication implementation approach
- Generated user model and service layer
- Identified testing requirements for AI-generated code
```

### 2. Multi-Agent Workflows
Windsurf supports both AI and human agents in the same workspace:

```bash
# Check active agents (AI + human)
npm run workspace-status

# Create handoff between AI and human agents
npm run workspace-handoff create --from ai --to dev --work "Code review needed"

# Sync context for AI understanding
npm run workspace-sync
```

### 3. Intelligent Context Sharing
The workspace adapts to Windsurf's AI capabilities:

- **Code Understanding**: AI agents can reference workspace context files
- **Conversation Memory**: Workspace state informs ongoing AI conversations
- **Decision Tracking**: AI and human decisions are recorded together
- **Quality Monitoring**: AI-generated code tracked through quality metrics

## Best Practices for Windsurf Users

### 🚀 Starting AI-Assisted Development
1. **Initialize workspace**: `npm run workspace-init`
2. **Verify AI integration**: Check session shows `windsurf` IDE type
3. **Sync with AI context**: `npm run workspace-sync`
4. **Begin AI conversation**: Reference workspace context in Windsurf chat

### 🤖 Working with AI Agents
- **Context Sharing**: Add important context to `.workspace/context/` for AI reference
- **Decision Recording**: Document AI suggestions in `.workspace/decisions/`
- **Quality Tracking**: Monitor AI-generated code through workspace quality reports
- **Handoff Preparation**: Use workspace handoffs when switching between AI and human work

### 🔄 AI-Human Collaboration Patterns

#### Pattern 1: AI-First Development
```bash
# 1. Start with AI agent
npm run workspace-handoff create --to ai --work "Initial implementation"

# 2. AI implements core functionality
# (AI adds context to workspace automatically)

# 3. Handoff to human for review
npm run workspace-handoff create --from ai --to dev --work "Review and refine"

# 4. Human reviews and improves
npm run workspace-sync  # Get latest AI context

# 5. Handoff to QA
npm run workspace-handoff create --to qa --work "Test AI-assisted implementation"
```

#### Pattern 2: Human-AI Pair Programming
```bash
# Continuous sync during pair programming
npm run workspace-sync    # Before AI conversation
# ... work with AI in Windsurf ...
npm run workspace-sync    # After AI generates code
```

### 📊 Quality Monitoring for AI Code
```bash
# Health check includes AI code quality metrics
npm run workspace-health

# Specific checks for AI-generated code:
# - Code consistency with human patterns
# - Integration with existing codebase
# - Test coverage for AI implementations
```

## Windsurf-Specific Configuration

### Environment Variables
```bash
# Set in your environment or .env file
export IDE_TYPE=windsurf
export WINDSURF_AI_INTEGRATION=true
export WORKSPACE_AI_CONTEXT=true
```

### AI Context Files
The workspace creates Windsurf-specific context files:

```
📁 .workspace/
├── 📂 ai-context/        # AI conversation summaries
├── 📂 ai-decisions/      # AI-suggested architectural decisions
├── 📂 ai-handoffs/       # AI ↔ Human work transitions
└── 📂 ai-quality/        # Quality metrics for AI-generated code
```

### Windsurf AI Prompts
Use these patterns in Windsurf AI conversations:

```
"Check the workspace context in .workspace/context/sync-summary.md before implementing"

"Consider the recent handoff details in .workspace/handoffs/ for this feature"

"Review the workspace quality metrics in .workspace/quality/ to ensure consistency"

"Update the workspace context with your implementation approach"
```

## Advanced Windsurf Integration

### 1. Custom AI Workflows
```json
// package.json additions for AI workflows
{
  "scripts": {
    "ai-handoff": "npm run workspace-handoff create --to ai",
    "ai-review": "npm run workspace-sync && echo 'Context ready for AI review'",
    "ai-quality": "npm run workspace-health --ai-focus"
  }
}
```

### 2. AI Context Optimization
```bash
# Optimize workspace for AI understanding
npm run workspace-cleanup --ai-optimize

# Generate AI-friendly summaries
npm run workspace-sync --ai-summary

# Health check with AI code focus
npm run workspace-health --ai-metrics
```

### 3. Multi-Modal Context
Windsurf can handle various content types in workspace:

- **Code Files**: Traditional source code with AI annotations
- **Documentation**: AI-generated and human-written docs
- **Conversations**: AI chat history integrated with workspace
- **Decisions**: Joint AI-human architectural decisions
- **Quality Reports**: AI code quality metrics and human reviews

## Troubleshooting

### AI Integration Issues

**"AI context not loading"**
- Verify `WINDSURF_AI_INTEGRATION=true` environment variable
- Check workspace initialization: `npm run workspace-init`
- Sync context manually: `npm run workspace-sync`

**"Handoff between AI and human not working"**
- Ensure both agent types are recognized: `npm run workspace-handoff agents`
- Check session is properly initialized for Windsurf
- Verify workspace structure: `npm run workspace-health`

**"AI not referencing workspace context"**
- Explicitly reference context files in AI conversations
- Use workspace sync before AI conversations: `npm run workspace-sync`
- Check context file permissions and content

### Windsurf-Specific Issues

**"Windsurf not detecting workspace"**
- Initialize from project root: `npm run workspace-init`
- Check IDE detection: Session should show `windsurf` type
- Restart Windsurf if needed

**"AI conversation memory conflicts with workspace"**
- Workspace context complements AI memory, not replaces it
- Use `npm run workspace-sync` to align contexts
- Clear workspace if needed: `npm run workspace-cleanup --force`

## Performance Optimization

### AI Context Efficiency
- **Selective Context**: Only share relevant context with AI
- **Context Summarization**: Use workspace summaries for large projects
- **Regular Cleanup**: Remove outdated AI context regularly

```bash
# Optimize workspace for AI performance
npm run workspace-cleanup --ai-optimize

# Generate efficient AI summaries
npm run workspace-sync --compress
```

### Memory Management
- **Conversation Limits**: Workspace helps track long AI conversations
- **Context Rotation**: Older context automatically archived
- **Session Cleanup**: Stale AI sessions cleaned up automatically

## Integration Examples

### Example 1: AI Feature Implementation
```bash
# 1. Initialize workspace for AI work
npm run workspace-init

# 2. Create handoff to AI
npm run workspace-handoff create --to ai --work "Implement user dashboard"

# 3. Work with AI in Windsurf
# AI: "I see from the workspace context that we're using React. I'll implement..."

# 4. AI completes work, human reviews
npm run workspace-sync  # Get AI's context updates

# 5. Handoff to QA
npm run workspace-handoff create --from ai --to qa --work "Test dashboard implementation"
```

### Example 2: AI Code Review
```bash
# 1. Human completes feature
npm run workspace-handoff create --to ai --work "Review authentication logic"

# 2. AI reviews with workspace context
# AI: "Based on the workspace quality metrics, I recommend..."

# 3. Apply AI suggestions
npm run workspace-sync  # Update with AI feedback

# 4. Final quality check
npm run workspace-health --ai-review
```

---

*This guide is optimized for Windsurf IDE's AI capabilities. The workspace system enhances AI-human collaboration while maintaining compatibility with traditional development workflows.*