Windsurf Multi-Environment Setup

Overview

Configure Windsurf consistently across team members, projects, and deployment contexts. Windsurf is an IDE, not a cloud API -- "multi-environment setup" means standardizing AI behavior, workspace configuration, and Cascade context across your team.

Prerequisites

• Windsurf IDE installed on developer machines
• Shared git repository
• Team agreement on coding standards per service

Instructions

Step 1: Per-Project Cascade Rules

<!-- .windsurfrules - committed to each service repo -->

# Project: PaymentService

## Stack
- Language: TypeScript (strict)
- Framework: Fastify v4
- Database: PostgreSQL with Drizzle
- Testing: Vitest
- Queue: BullMQ for async jobs

## Architecture Rules
- All handlers in src/routes/ — never business logic
- Business logic in src/services/ only
- Database queries in src/repositories/ only
- Use Result<T, E> pattern for errors, never throw in services
- PCI-sensitive data only in src/pci/ (encrypted at rest)

## Naming Conventions
- Route handlers: GET/POST/PUT/DELETE prefix
- Service methods: verb + noun (createPayment, findOrder)
- Repository methods: DB operations (findById, upsert)

Step 2: Team IDE Settings Template

// .windsurf/settings.json - committed to repo
{
  "codeium.indexing.excludePatterns": [
    "node_modules/**", "dist/**", ".next/**",
    "coverage/**", "*.min.js", "**/*.map", "**/*.lock"
  ],
  "codeium.autocomplete.enable": true,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.tsdk": "node_modules/typescript/lib"
}

Step 3: Monorepo Multi-Service Setup

monorepo/
  services/
    auth/
      .windsurfrules        # Auth context: JWT, OAuth, session management
      .codeiumignore         # Exclude auth secrets directory
    payments/
      .windsurfrules        # Payments context: Stripe, PCI compliance
      .codeiumignore         # Exclude PCI data directories
    notifications/
      .windsurfrules        # Notifications: queues, email templates
      .codeiumignore
  .windsurf/
    settings.json            # Shared IDE settings
    rules/
      shared-patterns.md     # trigger: always_on
    workflows/
      deploy-service.md      # /deploy-service workflow

Key practice: Each developer opens their service directory as the workspace, NOT the monorepo root. This gives Cascade focused context and fast indexing.

Step 4: Environment-Specific Workflow Rules

<!-- .windsurf/rules/deployment-context.md -->
---
trigger: glob
globs: deploy/**, scripts/deploy-*, .github/workflows/deploy-

Windsurf Observability

Overview

Monitor Windsurf AI IDE adoption, feature usage, and productivity impact across your team. Covers Admin Dashboard analytics, custom tracking via extensions, and ROI measurement.

Prerequisites

• Windsurf Teams or Enterprise plan
• Admin dashboard access at windsurf.com/dashboard
• Team members actively using Windsurf

Instructions

Step 1: Access Admin Dashboard Analytics

Navigate to Admin Dashboard > Analytics for team-wide metrics:

# Key metrics available in Windsurf Admin Dashboard
core_metrics:
  adoption:
    active_users_daily: "Unique developers using Windsurf per day"
    seat_utilization: "Active users / total seats (target: >80%)"
    feature_adoption: "Which AI features each user uses"

  quality:
    completion_acceptance_rate: "Supercomplete suggestions accepted vs shown"
    cascade_flow_success_rate: "Cascade tasks completed vs failed"

  consumption:
    credits_consumed_per_user: "Monthly credit usage per team member"
    credits_by_model: "Which AI models consume the most credits"

  efficiency:
    tasks_per_session: "Average Cascade interactions per session"
    time_saved_estimate: "Based on task complexity and completion speed"

Step 2: Set Up Usage Alerts

Monitor for underutilization and overuse:

# Alert thresholds for team management
alerts:
  low_adoption:
    condition: "seat_utilization < 50% for 7 days"
    action: "Schedule team training session"

  low_acceptance_rate:
    condition: "completion_acceptance_rate < 20% for 7 days"
    action: "Review .windsurfrules — AI suggestions not matching project patterns"

  high_cascade_failures:
    condition: "cascade_success_rate < 50% for 3 days"
    action: "Check workspace config — .codeiumignore may be too aggressive"

  credit_overspend:
    condition: "team_credits > 80% consumed before month half"
    action: "Review per-user usage, coach on credit conservation"

  inactive_seats:
    condition: "user has <10 interactions in 30 days"
    action: "Offer training or downgrade to Free tier"

Step 3: Build Custom Extension for Detailed Tracking

// windsurf-analytics-extension/src/extension.ts
import * as vscode from "vscode";

interface UsageEvent {
  event: string;
  timestamp: string;
  userId: string;
  file?: string;
  metadata?: Record<string, unknown>;
}

const events: UsageEvent[] = [];

export function activate(context: vscode.ExtensionContext) {
  // Track Cascade usage patterns
  const cascadeListener = vscode.workspace.onDidSaveTextDocument((doc) => {
    events.push({
      e

Windsurf Performance Tuning

Overview

Optimize Windsurf's indexing engine, Cascade context building, Supercomplete latency, and overall IDE responsiveness. Most performance issues stem from indexing too many files or missing exclusion patterns.

Prerequisites

• Windsurf IDE installed
• Understanding of workspace indexing
• Access to Windsurf settings

Instructions

Step 1: Optimize Workspace Indexing

The indexing engine is the #1 performance factor. Exclude everything that isn't source code:

# .codeiumignore — aggressive exclusion for large codebases
# Build artifacts
node_modules/
dist/
build/
.next/
.nuxt/
.output/
.svelte-kit/
coverage/
.cache/

# Package manager
pnpm-lock.yaml
package-lock.json
yarn.lock

# Generated code
*.min.js
*.min.css
*.bundle.js
*.chunk.js
**/*.map
generated/
__generated__/

# Binary and media files
*.png
*.jpg
*.gif
*.svg
*.ico
*.mp4
*.woff
*.woff2
*.ttf
*.eot

# Data files
*.sqlite
*.db
*.sql.gz
*.csv

# Python
__pycache__/
*.pyc
.venv/
venv/
.tox/
*.egg-info/

# Go
vendor/

# Rust
target/

Step 2: Open Focused Workspaces

# DON'T: Open entire monorepo root
windsurf ~/monorepo/          # Indexes ALL packages = slow

# DO: Open specific service directories
windsurf ~/monorepo/apps/web/        # Only indexes web app
windsurf ~/monorepo/packages/api/    # Only indexes API

# Each Windsurf window gets its own focused AI context
# Cascade performs better with fewer, relevant files

Step 3: Tune IDE Settings

// settings.json — performance-focused configuration
{
  // Indexing limits
  "codeium.indexing.maxFileSize": 524288,

  // Reduce extension overhead
  "extensions.autoUpdate": false,
  "extensions.autoCheckUpdates": false,

  // Editor performance
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "none",
  "editor.bracketPairColorization.enabled": false,

  // File watcher optimization
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/.git/objects/**": true,
    "**/build/**": true
  },

  // Search exclusions
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/*.min.js": true
  }
}

Step 4: Optimize Cascade Usage

## Cascade Performance Tips

1. Start fresh sessions for new tasks
   - Long conversations accumulate context, slowing responses
   - Click + in Cascade panel to start new conversation

2. Use @ mentions instead of describing files
   - BAD: "Look at the auth service file"
   - GOOD: "@src/services/auth.ts fix the token refresh logic"

3. Scope pr

Windsurf Policy Guardrails

Overview

Policy guardrails for team Windsurf usage: controlling what Cascade can do, enforcing code review for AI output, configuring terminal safety controls, and preventing common AI coding mistakes.

Prerequisites

• Windsurf configured for team use
• Git workflow established
• CI/CD pipeline in place
• Team agreement on AI usage standards

Instructions

Step 1: Terminal Command Safety (Turbo Mode Controls)

Configure what Cascade can and cannot auto-execute:

// settings.json — Team-wide terminal safety
{
  "windsurf.cascadeCommandsAllowList": [
    "npm test", "npm run", "npx vitest", "npx tsc",
    "git status", "git diff", "git log", "git add",
    "eslint", "prettier", "biome",
    "ls", "cat", "head", "tail", "wc", "grep"
  ],
  "windsurf.cascadeCommandsDenyList": [
    "rm -rf", "rm -r /",
    "sudo",
    "git push --force", "git reset --hard",
    "DROP TABLE", "DELETE FROM", "TRUNCATE",
    "curl | bash", "wget | sh",
    "chmod 777",
    "kill -9",
    "shutdown", "reboot", "halt",
    "mkfs", "dd if=",
    "npm publish", "npx publish"
  ]
}

Step 2: Workspace Isolation Rules

Prevent Cascade from accessing sensitive directories:

# .codeiumignore — security boundary
# AI cannot see or modify files matching these patterns

# Credentials
.env
.env.*
credentials/
secrets/
*.pem
*.key

# Infrastructure
terraform.tfstate*
*.tfvars
ansible/vault*

# Customer data
data/production/
exports/

<!-- .windsurf/rules/protected-files.md -->
---
trigger: always_on
---
## Protected Files Policy
- NEVER modify files in migrations/ without explicit request
- NEVER modify Dockerfile or docker-compose.yml without explicit request
- NEVER modify CI/CD workflows (.github/workflows/) without explicit request
- NEVER modify package.json dependencies without explicit request
- ALWAYS ask before changing database schema files

Step 3: AI Code Review Policy

# .github/workflows/ai-code-gate.yml
name: AI Code Quality Gate
on: pull_request

jobs:
  ai-review-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - name: Check cascade commit policy
        run: |
          # Count files changed
          FILES=$(git diff --name-only origin/main..HEAD | wc -l)

          # Large changesets need explicit review
          if 

Windsurf Production Checklist

Overview

Complete checklist for rolling out Windsurf to production teams. Covers workspace configuration, security hardening, team onboarding, and monitoring.

Prerequisites

• Windsurf plan selected (Pro, Teams, or Enterprise)
• Admin access to Windsurf dashboard
• Git repositories identified for rollout
• Team agreement on AI usage policy

Instructions

Phase 1: Pre-Deployment Configuration

Workspace Config (per repository):

• [ ] .windsurfrules created with project stack, patterns, and constraints
• [ ] .codeiumignore excludes secrets, build artifacts, and large binaries
• [ ] .windsurf/rules/ contains glob-triggered rules for file-type-specific patterns
• [ ] Workspace settings committed to .windsurf/settings.json

Security:

• [ ] Telemetry configured per company policy
• [ ] .codeiumignore covers all secret file patterns
• [ ] Autocomplete disabled for secret-containing file types (.env, .key)
• [ ] Enterprise: SSO/SAML configured and enforced
• [ ] Enterprise: zero-data-retention verified with Codeium

Team Policy:

• [ ] AI usage policy document created and shared
• [ ] Commit convention for AI-generated code established (e.g., [cascade] prefix)
• [ ] Code review requirements for AI-generated changes defined
• [ ] Competing AI extensions disabled (Copilot, TabNine)

Phase 2: Team Onboarding

Per-Developer Setup:

#!/bin/bash
# scripts/setup-windsurf.sh — run on each developer machine

echo "Setting up Windsurf for this project..."

# Verify Windsurf is installed
windsurf --version || { echo "Install Windsurf first: https://windsurf.com/download"; exit 1; }

# Verify config files exist
[ -f .windsurfrules ] || echo "WARNING: .windsurfrules missing"
[ -f .codeiumignore ] || echo "WARNING: .codeiumignore missing"

# Install recommended extensions
windsurf --install-extension esbenp.prettier-vscode
windsurf --install-extension dbaeumer.vscode-eslint

# Disable conflicting extensions
windsurf --disable-extension github.copilot 2>/dev/null || true

echo "Setup complete. Open project folder (not monorepo root) for best AI context."

Training Checklist:

• [ ] Demo: Supercomplete (Tab) vs Cascade (Cmd+L) vs Command (Cmd+I)
• [ ] Demo: Write mode vs Chat mode
• [ ] Demo: @ mentions for file context
• [ ] Demo: Turbo mode with allow/deny lists
• [ ] Demo: Previews for UI development
• [ ] Demo: Git checkpoint before Cascade workflow
• [ ] Share: .windsurfrules ex

Windsurf Reference Architecture

Overview

Complete project architecture optimized for Windsurf AI. Covers workspace configuration, rules hierarchy, workflow organization, and team standardization patterns that maximize Cascade's effectiveness.

Prerequisites

• Windsurf IDE installed
• Team agreement on coding standards
• Repository with consistent project structure

Architecture Diagram

┌──────────────────────────────────────────────────────┐
│              Windsurf Workspace                       │
│  ┌───────────────┐  ┌────────────────────────────┐    │
│  │ .windsurfrules│  │ .windsurf/                 │    │
│  │ (AI context)  │  │  ├── rules/ (trigger rules)│    │
│  │               │  │  ├── workflows/ (automation)│    │
│  │               │  │  └── settings.json         │    │
│  └───────────────┘  └────────────────────────────┘    │
│  ┌───────────────┐  ┌────────────────────────────┐    │
│  │ .codeiumignore│  │ ~/.codeium/                │    │
│  │ (index rules) │  │  ├── global_rules.md       │    │
│  │               │  │  ├── windsurf/memories/    │    │
│  │               │  │  └── windsurf/mcp_config   │    │
│  └───────────────┘  └────────────────────────────┘    │
├──────────────────────────────────────────────────────┤
│              Cascade AI Engine                        │
│  ┌───────────┐  ┌───────────┐  ┌─────────────────┐   │
│  │ Super-    │  │ Cascade   │  │ Command         │   │
│  │ complete  │  │ Write/Chat│  │ (Inline Edit)   │   │
│  │ (Tab)     │  │ (Cmd+L)  │  │ (Cmd+I)         │   │
│  └───────────┘  └───────────┘  └─────────────────┘   │
├──────────────────────────────────────────────────────┤
│              Context Layers                           │
│  Rules > Memories > @Mentions > Open Files > Index   │
└──────────────────────────────────────────────────────┘

Instructions

Step 1: Project File Structure

my-project/
├── .windsurfrules              # AI context (stack, patterns, constraints)
├── .codeiumignore              # Indexing exclusions
├── .windsurf/
│   ├── settings.json           # IDE settings (committed)
│   ├── rules/
│   │   ├── testing.md          # trigger: glob **/*.test.ts
│   │   ├── api-routes.md       # trigger: glob src/routes/**
│   │   ├── security.md         # trigger: model_decision
│   │   └── migrations.md       # trigger: manual
│   └── workflows/
│       ├── new-feature.md      # /new-feature
│       ├── deploy-staging.md   # /deploy-staging
│       ├── review-pr.md        # /review-pr
│       └── quality-check.md    # /quality-check
├── src/
│   ├── routes/                 # API route handlers
│   ├── services/               # Business logic
│   ├── repositories/           # Data access
│   └── types/                  # Shared types
├── tests/
│   ├── fixtures/               # Test data factories
│   └── services/               # Service

Windsurf Reliability Patterns

Overview

Reliability patterns for safe Cascade usage: Git checkpointing, incremental task scoping, validation gates, and rollback strategies. Cascade's multi-file editing is powerful but requires discipline to avoid breaking your codebase.

Prerequisites

• Windsurf with Cascade enabled
• Git repository initialized
• Test suite available
• Understanding of Cascade Write mode

Instructions

Step 1: Always Commit Before Cascade

The most important reliability pattern: create a clean Git checkpoint before every Cascade session.

# Before starting a Cascade task
git add -A && git commit -m "checkpoint: before cascade session"

# After Cascade completes:
git diff                                    # Review all changes
npm test && npm run typecheck               # Validate

# If good:
git add -A && git commit -m "[cascade] add notification service"

# If bad:
git checkout -- .                           # Revert everything
# Or selectively:
git checkout -- src/problem-file.ts         # Revert one file

Step 2: Use Feature Branches for Cascade Work

# Create dedicated branch for each Cascade task
git checkout -b cascade/add-notification-service

# Do Cascade work on this branch
# ...

# If results are good:
git checkout main && git merge cascade/add-notification-service

# If results are bad:
git checkout main && git branch -D cascade/add-notification-service
# Clean slate, main branch untouched

Step 3: Scope Tasks Incrementally

Large tasks cause Cascade to make sweeping changes that are hard to review. Break into steps.

BAD (too broad):
"Refactor the authentication system to use JWT instead of sessions"
→ Cascade may modify 30+ files, hard to review, likely has bugs

GOOD (incremental):
Step 1: "Create src/services/jwt.ts with functions: generateToken,
         validateToken, refreshToken. Use the jose library."
Step 2: "Create tests/services/jwt.test.ts with tests for all three functions"
Step 3: "Run the tests and fix any failures"
Step 4: "Update src/middleware/auth.ts to use jwt.ts instead of
         express-session. Keep the old code commented out."
Step 5: "Run the full test suite and fix any failures"
Step 6: "Remove commented-out session code from auth.ts"

Each step: review diff → test → commit → next step

Step 4: Validate After Every Cascade Edit

#!/bin/bash
# scripts/cascade-validate.sh — run after every Cascade edit
set -euo pipefail

echo "=== Post-Cascade Validation ==="

# Type check
echo "1/4 TypeScript..."
npm run typecheck || { echo "FAIL: Type errors. Ask Cascade to fix."; exit 1; }

Windsurf Configuration Patterns

Overview

Production-ready configuration patterns for Windsurf IDE: rules files, workspace rules with trigger modes, MCP server integration, and Cascade prompt engineering.

Prerequisites

• Windsurf authenticated and operational
• Understanding of Cascade Write vs Chat modes
• Project with established coding conventions

Instructions

Step 1: Root-Level .windsurfrules (Permanent Context)

The .windsurfrules file is the single highest-impact configuration for Cascade output quality. It provides persistent context every session.

<!-- .windsurfrules -->

# Project: payments-api

## Stack
- Runtime: Node.js 20 LTS
- Language: TypeScript 5.x (strict, noUncheckedIndexedAccess)
- Framework: Fastify v4
- ORM: Drizzle (PostgreSQL)
- Validation: zod
- Testing: Vitest
- Linting: Biome

## Architecture Rules
- Route handlers in src/routes/ — no business logic
- Business logic in src/services/ — never throw, use Result<T,E>
- Database queries in src/repositories/ — Drizzle only
- Shared types in src/types/ — all exported with JSDoc

## Don't
- Don't use `any` type
- Don't use default exports
- Don't use class-based patterns (use functions + closures)
- Don't modify files in migrations/ without explicit request
- Don't use deprecated APIs: my_old_helper, legacyAuth

## Testing
- Unit tests for every service method
- Integration tests for every route handler
- No mocking repositories in integration tests
- Use test fixtures from tests/fixtures/

Limits: 6,000 characters per rules file. 12,000 total (global + workspace combined).

Step 2: Workspace Rules with Trigger Modes

Create granular rules in .windsurf/rules/ with YAML frontmatter:

<!-- .windsurf/rules/testing.md -->
---
trigger: glob
globs: **/*.test.ts, **/*.spec.ts
---
All test files must:
- Use describe/it blocks (not test())
- Mock external API calls with msw
- Assert both success and error paths
- Include at least one snapshot test for UI components
- Use factory functions from tests/fixtures/ for test data

<!-- .windsurf/rules/api-routes.md -->
---
trigger: glob
globs: src/routes/**/*.ts
---
API route handlers must:
- Validate input with zod schema before processing
- Return consistent error format: { error: string, code: string, statusCode: number }
- Include request ID in all log lines
- Never call database directly — use repository layer

<!-- .windsurf/rules/security.md -->
---
trigger: model_decision
description: Apply when code touches authentication, authorization, or secrets
---
Security requirements:
- Never log secrets, tokens, or PII
- Use parameterized queries (never string interpolation

Windsurf Security Basics

Overview

Security best practices for Windsurf AI IDE: controlling what code Cascade can see, preventing secrets from leaking into AI context, managing telemetry, and configuring workspace isolation for regulated environments.

Prerequisites

• Windsurf installed
• Understanding of Codeium's data processing model
• Repository with identified sensitive files

Instructions

Step 1: Exclude Secrets from AI Indexing

Create .codeiumignore at project root (gitignore syntax):

# .codeiumignore — files Codeium/Windsurf will NEVER index or read

# Secrets and credentials
.env
.env.*
.env.local
credentials.json
serviceAccountKey.json
*.pem
*.key
*.p12
*.pfx

# Cloud provider configs
.aws/
.gcloud/
.azure/

# Infrastructure secrets
terraform.tfstate
terraform.tfstate.backup
*.tfvars
vault-config.*

# Customer data
data/customers/
exports/
backups/
*.sql.gz

Default exclusions (automatic): Files in .gitignore, node_modules/, hidden directories (. prefix).

Enterprise: Place a global .codeiumignore at ~/.codeium/ for org-wide exclusions.

Step 2: Disable Telemetry (If Required)

// Windsurf Settings (settings.json)
{
  "codeium.enableTelemetry": false,
  "codeium.enableSnippetTelemetry": false,
  "telemetry.telemetryLevel": "off"
}

Step 3: Configure AI Autocomplete Exclusions

Disable Supercomplete for file types that commonly contain secrets:

{
  "codeium.autocomplete.languages": {
    "plaintext": false,
    "env": false,
    "dotenv": false,
    "properties": false,
    "ini": false
  }
}

Step 4: Create Security-Focused .windsurfrules

<!-- .windsurfrules - security section -->

## Security Requirements
- Never suggest hardcoded secrets, API keys, or passwords in code
- Always use environment variables via process.env for secrets
- Never log PII (email, phone, SSN, credit card numbers)
- Use parameterized queries for all database operations
- Never suggest wildcard CORS origins in production code
- All user input must be validated before processing
- Use constant-time comparison for secret/token validation

Step 5: Audit AI Workspace Access

#!/bin/bash
set -euo pipefail
echo "=== Windsurf Security Audit ==="

# Check if .codeiumignore exists
if [ ! -f .codeiumignore ]; then
  echo "WARNING: No .codeiumignore — AI can index all non-gitignored files"
fi

# Check for secrets that AI could index
echo "--- Potentially exposed secret files ---"
find . 

Windsurf Upgrade & Migration

Current State

!windsurf --version 2>/dev/null || echo 'Not installed' !code --version 2>/dev/null | head -1 || echo 'VS Code not installed'

Overview

Guide for upgrading Windsurf to new versions and migrating from VS Code or Cursor. Covers settings transfer, extension compatibility, and Windsurf-specific configuration that doesn't exist in other editors.

Prerequisites

• Current editor installation accessible
• Git for version controlling config files
• Backup of existing settings

Instructions

Step 1: Check Current Windsurf Version

# Current version
windsurf --version

# Check for updates
# Windsurf auto-updates by default
# Manual: Help > Check for Updates (or download from windsurf.com)

Step 2: Migrate from VS Code

Windsurf is VS Code-based and supports most VS Code settings and extensions:

# Windsurf imports VS Code settings on first launch
# For manual migration:

# 1. Export VS Code extensions list
code --list-extensions > vscode-extensions.txt

# 2. Install in Windsurf
cat vscode-extensions.txt | xargs -L1 windsurf --install-extension

# 3. Copy settings
# macOS:
cp ~/Library/Application\ Support/Code/User/settings.json \
   ~/Library/Application\ Support/Windsurf/User/settings.json

# Linux:
cp ~/.config/Code/User/settings.json \
   ~/.config/Windsurf/User/settings.json

Key difference: Remove or disable GitHub Copilot -- it conflicts with Windsurf's Supercomplete.

Step 3: Migrate from Cursor

Cursor and Windsurf both extend VS Code but have different AI config files:

# Mapping Cursor concepts to Windsurf:
cursor_to_windsurf:
  .cursorrules:       .windsurfrules     # AI context rules
  .cursorignore:      .codeiumignore     # AI indexing exclusions
  .cursor/rules/:     .windsurf/rules/   # Workspace rules
  cursor_settings:    windsurf_settings  # IDE preferences
  Composer:           Cascade            # Agentic AI assistant
  Tab:                Supercomplete      # Inline completions
  Cmd+K:              Cmd+I              # Inline editing
  Cmd+L:              Cmd+L              # AI chat (same!)

Migration script:

#!/bin/bash
set -euo pipefail
echo "Migrating Cursor config to Windsurf..."

# Convert .cursorrules to .windsurfrules
[ -f .cursorrules ] && cp .cursorrules .windsurfrules && echo "Copied .cursorrules → .windsurfrules"

# Convert .cursorignore to .codeiumignore
[ -f .cursorignore ] && cp .cursorignore .codeiumignore && echo "Copied .cursorignore → .codeiumignore"

# Migrate workspace rules
if [ -d .cursor/rules ]; then
  mkdir -p .windsurf/r

Windsurf Extension Development & Events

Overview

Windsurf is built on VS Code and supports the full VS Code Extension API. Build custom extensions to track workspace events, integrate with external tools, and extend Cascade's capabilities. This skill covers extension development specific to the Windsurf environment.

Prerequisites

• Node.js 18+ and npm
• VS Code Extension API familiarity
• yo and generator-code for scaffolding
• Windsurf IDE for testing

Instructions

Step 1: Scaffold Extension

# Install scaffolding tools
npm install -g yo generator-code

# Generate extension
yo code
# Select: New Extension (TypeScript)
# Name: my-windsurf-extension

Step 2: Track Workspace Events

// src/extension.ts
import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  console.log("Extension active in Windsurf");

  // Track file saves
  const saveListener = vscode.workspace.onDidSaveTextDocument(
    async (document) => {
      const diagnostics = vscode.languages.getDiagnostics(document.uri);
      const errors = diagnostics.filter(
        (d) => d.severity === vscode.DiagnosticSeverity.Error
      );
      if (errors.length > 0) {
        vscode.window.showWarningMessage(
          `${document.fileName}: ${errors.length} error(s) after save`
        );
      }
    }
  );

  // Track active editor changes
  const editorListener = vscode.window.onDidChangeActiveTextEditor(
    (editor) => {
      if (editor) {
        const lang = editor.document.languageId;
        const lines = editor.document.lineCount;
        console.log(`Opened: ${editor.document.fileName} (${lang}, ${lines} lines)`);
      }
    }
  );

  // Track terminal output
  const terminalListener = vscode.window.onDidWriteTerminalData((event) => {
    // Can monitor for specific patterns (errors, warnings)
    if (event.data.includes("ERROR") || event.data.includes("FAIL")) {
      vscode.window.showWarningMessage("Error detected in terminal output");
    }
  });

  context.subscriptions.push(saveListener, editorListener, terminalListener);
}

Step 3: Send Events to External System

// src/webhook.ts
import * as vscode from "vscode";

interface WorkspaceEvent {
  event: string;
  file?: string;
  language?: string;
  timestamp: string;
  metadata?: Record<string, unknown>;
}

async function sendEvent(event: WorkspaceEvent): Promise<void> {
  const webhookUrl = vscode.workspace
    .getConfiguration("windsurf-events")
    .get<string>("webhookUrl");

  if (!webhookUrl) return;

  try {
    await fetch(webhookUrl, {
      method: "POST",
      headers: { "Content-Type&q