9.6 KiB

Raw Blame History

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

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

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

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

# 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:

# 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:

# 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

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

Initialize workspace: npm run workspace-init
Verify AI integration: Check session shows windsurf IDE type
Sync with AI context: npm run workspace-sync
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

# 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

# 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

# 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

# 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

// 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

# 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

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

# 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

# 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

# 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.

9.6 KiB Raw Blame History