Windsurf

Integration Architecture

Windsurf uses a combination of .windsurfrules (global rules) and.windsurf/workflows/ (individual command files). Fulcrum maps to both:

┌─────────────────────────────────────────────────┐
│              fulcrum/                           │
│  ├── agents/        → .windsurfrules           │
│  ├── commands/      → .windsurf/workflows/     │
│  └── skills/        → .windsurfrules           │
└─────────────────────────────────────────────────┘

Generated Structure

Running fulcrum sync --vendor windsurf generates:

project-root/
├── .windsurfrules              # Agents + skills definitions
├── .windsurfrules.local        # Your additions (gitignored)
└── .windsurf/
    └── workflows/
        ├── start.md            # Start workflow command
        ├── execute-work.md     # Execute work command
        ├── status.md           # Status check command
        ├── review.md           # Code review command
        └── pr.md               # PR creation command

.windsurfrules Contents

# Fulcrum Configuration for Windsurf

## Project Context
This project uses Fulcrum for AI-assisted development.

---

## Agents

### Tech Lead (@tech-lead)
**Role:** Technical leadership and architectural decisions

**Expertise:**
- System design and architecture
- Code review and quality standards  
- Cross-team coordination

**When to invoke:** 
- Architectural decisions
- Design reviews
- Complex trade-offs

**Decision framework:**
1. Evaluate against project principles
2. Consider maintainability and scale
3. Document rationale for decisions

---

### Backend Engineer (@backend-engineer)
**Role:** Server-side implementation specialist

**Expertise:**
- API design and implementation
- Database optimization
- Performance tuning

---

## Skills

### Brainstorming
**Trigger:** Requirements exploration, design decisions
**Process:**
1. Clarify the problem space
2. Generate multiple approaches
3. Evaluate trade-offs
4. Recommend with rationale

### Code Reviewer
**Trigger:** Code review requests
**Checklist:**
- Security vulnerabilities
- Performance implications
- Code style and conventions
- Test coverage

---

Using Agents

Reference agents in your Cascade prompts by role or @ mention style:

# Role-based invocation
"As tech lead, review this architecture"

# @ style reference (parsed from rules)
"Get @tech-lead perspective on this design"

# Multiple agents
"Need input from @backend-engineer and @devops-engineer"

Agent Sections in Rules

Using Commands

Each command is a separate workflow file in .windsurf/workflows/:

# .windsurf/workflows/start.md

# Start Workflow

## Purpose
Initialize a new work session with proper context and tracking.

## Trigger
Use when beginning a new task or feature.

## Steps

1. **Analyze Request**
   - Parse the task description
   - Identify scope and requirements
   - Check for dependencies

2. **Create Work Item**
   - Generate a bead ID (BEAD-XXX)
   - Set initial status to "planned"
   - Link to relevant context

3. **Load Context**
   - Find related files
   - Check recent changes
   - Load team conventions

4. **Present Plan**
   - Outline approach
   - Estimate complexity
   - Identify risks

## Output
Work item created with clear plan and next steps.

Invoking Workflows

# Natural language triggers
"Start a new task for implementing OAuth"

# Direct workflow reference
"Run the start workflow for: add user authentication"

# Windsurf command palette
Cmd/Ctrl + Shift + P → "Run Workflow" → select "start"

Available Workflows

Using Skills

Skills are documented in .windsurfrules and activate based on context:

# Skill section from .windsurfrules

## Skills

### Brainstorming
**Trigger:** Requirements exploration, design decisions
**Process:**
1. Clarify the problem space
2. Generate multiple approaches  
3. Evaluate trade-offs
4. Recommend with rationale

### Code Reviewer  
**Trigger:** Code review requests, "review this"
**Checklist:**
- [ ] Security vulnerabilities
- [ ] Performance implications
- [ ] Code style conventions
- [ ] Test coverage

### Test Engineer
**Trigger:** "write tests", "test coverage"
**Process:**
1. Analyze code under test
2. Identify test cases
3. Generate test code
4. Verify coverage

Triggering Skills

# Natural triggers (parsed from skill definitions)
"Let's brainstorm API design options"

# Explicit skill invocation  
"Use the code-reviewer skill on my changes"

# Cascade auto-detection
# Windsurf recognizes skill patterns from .windsurfrules

Customization

Extend with .windsurfrules.local for team-specific rules:

# .windsurfrules.local (gitignored)

## Team Conventions

### Branch Naming
- feature/JIRA-123-description
- bugfix/JIRA-456-description
- hotfix/JIRA-789-description

### Commit Style
type(scope): subject

Types: feat, fix, docs, style, refactor, test, chore

### Code Review Requirements
- Minimum 2 approvals
- Security review for auth changes
- Performance review for DB changes

---

## Custom Workflows

### Deploy Preview
When asked to deploy preview:
1. Push to preview branch
2. Wait for CI to pass
3. Share preview URL

Customization Workflow

# 1. Sync base configuration
fulcrum sync --vendor windsurf

# 2. Create local additions
cat > .windsurfrules.local << 'EOF'
## Team Conventions
...
EOF

# 3. Add custom workflows
cat > .windsurf/workflows/deploy-preview.md << 'EOF'
# Deploy Preview Workflow
...
EOF

# 4. Re-sync (preserves local files)
fulcrum sync --vendor windsurf

Vendor Comparison

Troubleshooting

Rules not loading

# Verify file locations
ls -la .windsurfrules
ls -la .windsurf/workflows/

# Check for syntax errors (markdown lint)
npx markdownlint .windsurfrules

# Reload Windsurf
Cmd/Ctrl + Shift + P → "Reload Window"

Workflows not appearing

# Ensure .windsurf directory exists
mkdir -p .windsurf/workflows

# Check workflow file format
head -5 .windsurf/workflows/start.md  # Should start with "# Title"

# Re-sync
fulcrum sync --vendor windsurf --force