Windsurf Advanced Troubleshooting

Overview

Deep debugging techniques for Windsurf issues that resist standard troubleshooting. Covers Cascade context corruption, indexing engine problems, extension conflicts, MCP failures, and workspace configuration debugging.

Prerequisites

• Standard troubleshooting attempted (see windsurf-common-errors)
• Terminal access
• Understanding of Devin Desktop's editor, Cascade, indexing, extension, and MCP layers

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Isolate Windsurf Layer vs VS Code Layer

Devin Desktop = editor shell + Cascade + indexing/context + extension/MCP layers

If the issue is:
- Editor crashes, rendering, file system → VS Code layer
- AI suggestions wrong, Cascade fails, indexing stuck → Cascade or context/indexing layer
- Extension not working → Extension compatibility layer

Test VS Code layer:
  windsurf --disable-extensions  # Run without extensions
  # If issue persists → VS Code layer problem

Test AI and extension layers:
  # Start with extensions disabled using the documented troubleshooting flow.
  # If the issue resolves, re-enable extensions incrementally to isolate the conflict.

Step 2: Debug Cascade Context Issues

When Cascade consistently gives wrong or irrelevant suggestions:

set -euo pipefail
echo "=== Cascade Context Debug ==="
readonly WORKSPACE_RULE_LIMIT=12000 # Current documented maximum for one workspace rule.
readonly GLOBAL_RULE_LIMIT=6000 # Current documented maximum for the global rule.

# 1. Check rules file
echo "--- .devin/rules/project.md ---"
if [ -f .devin/rules/project.md ]; then
  CHARS=$(wc -c < .devin/rules/project.md)
  echo "Size: $CHARS chars (workspace rule limit: $WORKSPACE_RULE_LIMIT)"
  [ "$CHARS" -gt "$WORKSPACE_RULE_LIMIT" ] && echo "WARNING: Workspace rule exceeds its limit"
else
  echo "MISSING — Cascade has no project context"
fi

# 2. Check workspace rules
echo "--- Workspace Rules ---"
TOTAL_RULE_CHARS=0
if [ -d .devin/rules ]; then
  for rule in .devin/rules/*.md; do
    [ -f "$rule" ] || continue
    CHARS=$(wc -c < "$rule")
    TOTAL_RULE_CHARS=$((TOTAL_RULE_CHARS + CHARS))
    HAS_TRIGGER=$(grep -c "^trigger:" "$rule" || true)
    echo "  $(basename "$rule"): $CHARS chars, trigger: $([[ $HAS_TRIGGER -gt 0 ]] && echo 'YES' || echo 'MISSING')…

Windsurf Architecture Variants

Overview

Workspace structure directly affects Cascade context and indexing behavior. Select and verify an architecture for single projects, monorepos, multi-service systems, polyglot codebases, or large organizations.

Prerequisites

• Windsurf installed
• Understanding of Cascade's workspace indexing model
• Git workflow established

Confirm the target repository size, ownership boundaries, and developer workflow before selecting a workspace layout.

Authentication

Public documentation checks require no authentication. Any editor, organization, remote-indexing, or MCP operation uses the operator's existing Devin Desktop session and the target provider's approved credentials; never copy those credentials into repository files.

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Select the Single-Project Variant (Solo / Small Team)

Best for: 1-3 developers, single service, <10K files.

my-project/
├── .devin/rules/project.md          # Full project context
├── .codeiumignore          # Exclude build artifacts
├── src/
├── tests/
├── package.json
└── README.md

Configuration:

• Open entire project as workspace
• Cascade indexes everything — no partitioning needed
• .devin/rules/project.md contains complete stack and architecture details

Step 2: Select Focused Monorepo Windows (Medium Team)

Best for: 3-15 developers, monorepo with 2-10 packages.

monorepo/
├── .devin/rules/project.md          # Brief shared conventions
├── .codeiumignore          # Aggressive exclusions at root
├── packages/
│   ├── api/
│   │   ├── .devin/rules/project.md  # API-specific rules
│   │   └── .codeiumignore
│   ├── web/
│   │   ├── .devin/rules/project.md  # Frontend-specific rules
│   │   └── .codeiumignore
│   └── shared/
│       ├── .devin/rules/project.md  # Library conventions
│       └── .codeiumignore
└── .windsurf/
    └── workflows/          # Shared workflows

Strategy:

# Each developer opens their package directory:
windsurf packages/api/        # Backend dev
windsurf packages/web/        # Frontend dev
windsurf packages/shared/     # Library maintainer

# NOT: windsurf monorepo/     # Too broad!

Step 3: Select a Multi-Window Team Workflow (Large Team)

Best for: 15+ developers, microservices, 50K+ total files.

Developer A: Windsurf → services/auth/        (auth service)
Developer B: Windsurf → services/paym…

Windsurf CI Integration

Overview

Integrate Windsurf configuration validation and AI code quality gates into CI/CD pipelines. Covers validating .devin/rules/project.md, enforcing team policies for AI-generated code, and automating Windsurf config distribution.

Prerequisites

• GitHub repository with Actions enabled
• Windsurf configuration files in repository
• Team agreement on AI code review policy

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Validate Windsurf Config in CI

# .github/workflows/windsurf-config.yml
name: Windsurf Config Validation

on:
  pull_request:
    paths:
      - '.devin/rules/project.md'
      - '.codeiumignore'
      - '.windsurf/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check .devin/rules/project.md exists and is valid
        run: |
          if [ ! -f .devin/rules/project.md ]; then
            echo "::error::.devin/rules/project.md is missing"
            exit 1
          fi
          CHARS=$(wc -c < .devin/rules/project.md)
          if [ "$CHARS" -gt 12000 ]; then
            echo "::error::.devin/rules/project.md exceeds 12000 char limit ($CHARS chars)"
            exit 1
          fi
          echo ".devin/rules/project.md: $CHARS chars (limit: 12000)"

      - name: Check .codeiumignore covers secrets
        run: |
          REQUIRED_PATTERNS=(".env" "*.pem" "*.key" "credentials")
          MISSING=()
          for pattern in "${REQUIRED_PATTERNS[@]}"; do
            if ! grep -q "$pattern" .codeiumignore 2>/dev/null; then
              MISSING+=("$pattern")
            fi
          done
          if [ ${#MISSING[@]} -gt 0 ]; then
            echo "::warning::.codeiumignore missing patterns: ${MISSING[*]}"
          fi

      - name: Validate workspace rules frontmatter
        run: |
          for rule in .devin/rules/*.md; do
            [ -f "$rule" ] || continue
            if ! head -1 "$rule" | grep -q "^---"; then
              echo "::error::$rule missing YAML frontmatter"
              exit 1
            fi
            # Check for required trigger field
            if ! grep -q "^trigger:" "$rule"; then
              e…

Windsurf Common Errors

Overview

Quick reference for the most common Windsurf IDE errors and their solutions. Covers Cascade failures, Supercomplete issues, indexing problems, and extension conflicts.

Prerequisites

• Windsurf installed and previously working
• Access to Windsurf settings and logs

Reproduce the issue with a harmless workspace before changing shared configuration or collecting diagnostic data.

Authentication

The public status page requires no authentication. Account, organization, and MCP diagnostics use the operator's existing Devin Desktop session plus provider-specific OAuth or environment-backed credentials; redact all values from logs and support bundles.

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Error 1: Cascade Not Responding

Symptoms: Cascade panel shows spinner indefinitely, no response to prompts.

Solutions:

1. Check internet connection -- Cascade requires cloud access
2. Check Windsurf status: https://status.windsurf.com
3. Check the usage meter and account state in Devin Desktop
4. Restart Cascade: Command Palette > "Cascade: Restart"
5. Restart Windsurf: Cmd/Ctrl+Shift+P > "Reload Window"

Error 2: Supercomplete Not Showing Suggestions

Symptoms: No ghost text appears while typing.

Solutions:

1. Check if disabled: Click Windsurf widget (status bar) > verify autocomplete is ON
2. Check file type: Supercomplete may be disabled for certain languages
3. Check .codeiumignore: Current file might be excluded from indexing
4. Ensure not conflicting: Disable GitHub Copilot or TabNine if installed

// Verify in settings.json
{
  "editor.inlineSuggest.enabled": true,
  "codeium.autocomplete.enable": true
}

Error 3: Indexing Stuck or Slow

Symptoms: Status bar shows "Indexing..." for extended periods, Cascade lacks context.

Solutions:

1. Compare workspace file count and available memory with the current indexing guidance
2. Create or update .codeiumignore:

node_modules/
.git/
dist/
build/
.next/
coverage/
vendor/
__pycache__/
*.min.js
*.bundle.js
*.map

1. Open a subdirectory instead of monorepo root
2. Use the current indexing controls in…

Windsurf Core Workflow A — Cascade Code Mode

Overview

Devin Desktop is the current name for Windsurf. Cascade Code mode is its agentic editing workflow: it can create and modify files, call tools, run approved terminal commands, inspect diagnostics, and iterate on failures.

Prerequisites

• Devin Desktop with Cascade enabled
• .devin/rules/project.md configured (see windsurf-sdk-patterns)
• Git initialized with clean working tree

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Create a Git Checkpoint

Always commit or stash before a Cascade session. Cascade writes directly to your files.

git add -A && git commit -m "checkpoint: before cascade session"
# Or for uncommitted work:
git stash push -m "pre-cascade stash"

Step 2: Open Cascade in Code Mode

Open the Cascade panel and select Code rather than Chat. Keyboard shortcuts can vary by imported profile, so use the visible command or confirm the current binding before documenting it.

• Create and modify files
• Run terminal commands (with Turbo or per-command approval)
• Install dependencies
• Read terminal output for debugging
• Open browser previews

Step 3: Write an Effective Prompt

Structure your prompt with scope, specifics, and constraints:

"In src/services/, create a NotificationService that:
1. Sends email via Resend API (already in package.json)
2. Sends Slack messages via webhook URL from env
3. Uses the Result<T,E> pattern from src/types/result.ts
4. Includes retry logic with exponential backoff (max 3 retries)
5. Add unit tests in tests/services/notification.test.ts
Don't modify any existing files except to add exports."

Step 4: Review Cascade's Plan and Execution

Cascade shows its reasoning and plan before executing:

Cascade output flow:
1. "I'll create the notification service with email and Slack support..."
2. Creates src/services/notification.ts (shows diff)
3. Creates tests/services/notification.test.ts (shows diff)
4. Runs: npm install resend (if needed)
5. Runs: npx vitest run tests/services/notification.…

Devin Desktop Customizations

Overview

Devin Desktop is the current name for Windsurf. Select the smallest customization that matches the task instead of treating Workflows and Memories as interchangeable automation.

Prerequisites

• Devin Desktop with Cascade enabled
• A version-controlled workspace for shared customizations
• A concrete behavior or procedure to encode

Authentication

Rules, AGENTS.md, Workflows, and Skills require no separate authentication. MCP-backed steps use provider OAuth or environment-backed secrets; never embed tokens in customization files.

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Choose the mechanism

Prefer .devin/rules/*.md for Rules. Legacy .windsurf/rules/ remains a fallback. Keep durable team knowledge in version control rather than relying on local auto-generated Memories.

Step 2: Create a Rule or AGENTS.md

Use a Rule for controlled activation:

---
trigger: glob
globs: "src/api/**/*.ts"
---

# API constraints
- Validate external input at the route boundary.
- Return the repository's standard error envelope.

Use a root or directory-level AGENTS.md when location alone should determine scope.

Step 3: Create a Workflow

Save manual procedures under .windsurf/workflows/<name>.md, within the documented 12,000-character limit:

…

Devin Desktop Cost Tuning

Overview

Devin Desktop is the current name for Windsurf. Optimize the combined Devin subscription using current plan terms, full and flex seats, included daily or weekly quota, and approved on-demand or extra usage.

Prerequisites

• Current plan and invoice period
• Member roster with full or flex seat assignment
• Usage observations for a representative four-week period
• Billing-owner approval for any plan, seat, or spending-limit change

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Establish current terms

Open the current plan page and record the observation date. Do not copy a static price table into durable policy; grandfathered and enterprise contracts can differ from public self-serve plans.

Step 2: Classify members

For each member, capture role, eligible surfaces, active days, included-quota use, on-demand use, and business-critical workflows. Avoid judging value from prompt volume alone.

Step 3: Model seat allocation

• Use a full seat for regular users who need Devin Desktop and included quota.
• Use a flex seat only where current plan terms support the required surfaces and occasional usage.
• Remove or reassign seats for departed or persistently inactive members through the documented admin workflow.
• Preserve minimum commitments and contract constraints in the calculation.

Step 4: Control variable usage

1. Set approved on-demand or extra-usage limits.
2. Use lower-cost SWE-family models for routine work.
3. Start focused sessions instead of carrying irrelevant context.
4. Reserve frontier and fast variants for work whose value justifies their cost.
5. Review exceptions with the billing owner rather than silently disabling productive users.

Step 5: Calculate scenarios

Compare the status quo with at least two alternatives. For each scenario include recurring seats, plan minimums, expected variable usage, migration cost, productivity risk, and confidence level.

Step 6: Pilot and verify

Apply changes to a small cohort for one billing cycle. Compare delivery, incident, and satisfaction signals alongside usage; roll back allocations that create operational harm.

Output

Deliver a dated cost-and-usage brief with current plan assumptions, full and flex seat allocation, included quota utilization, on-demand or extra-usage exposure, scenario totals, confidence, and prioritized actions. Link current pricing instead of freezing mutable amounts.

Error Handling

Devin Desktop Data Handling

Overview

Build an evidence-backed data map for Devin Desktop. Do not infer retention, residency, training use, certification coverage, or zero-data-retention from plan names; verify mutable vendor claims against the current contract and security documentation.

Prerequisites

• Data-classification policy and approved repository inventory
• Contract, DPA, or security evidence available to the authorized reviewer
• Named security, privacy, and legal decision owners

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Inventory data flows

For Cascade, autocomplete, indexing, remote indexing, MCP, Hooks, diagnostics, and App Deploys, record inputs, destination, purpose, identity, retention evidence, administrator, and applicable policy. Include metadata and logs, not only source files.

Step 2: Minimize local context

Use .gitignore and repository .codeiumignore to exclude secrets, generated output, customer datasets, private keys, production exports, and irrelevant large files. Enterprise administrators may apply a global .codeiumignore under ~/.codeium/.

Ignored paths are context controls. They do not revoke filesystem access, rotate secrets, satisfy least privilege, or prove a regulatory requirement.

Step 3: Choose durable instructions

Put shared data-handling requirements in AGENTS.md or .devin/rules/*.md, for example:

# Regulated data boundary
- Never paste customer records, access tokens, or production exports into prompts.
- Use synthetic fixtures in tests and examples.
- Require security review for changes under `src/payments/`.
- Stop and escalate if a requested artifact contains regulated data.

Step 4: Review integrations

For every MCP server, Hook, deployment target, and analytics export, confirm an owner, authentication method, approved scopes, destination, log policy, revocation path, and incident contact. Disable integrations that lack an accountable owner.

Step 5: Reconcile vendor evidence

Capture the URL or contract section, observation date, product/plan scope, and reviewer for each claim. Where public documentation and negotiated terms differ, label the applicable authority rather than blending them.

Step 6: Test and approve

Use synthetic canaries to verify exclusions and policy behavior. Obtain the required security/privacy/legal approval before enabling regulated workload…

Windsurf Debug Bundle

Current State

Collect editor, runtime, and operating-system versions only after the user requests a diagnostic bundle; do not execute shell substitutions while loading this skill.

Overview

Collect a minimal, redacted diagnostic package for troubleshooting Devin Desktop issues or preparing an effective support request without sweeping unrelated user data.

Prerequisites

• Windsurf installed (even if malfunctioning)
• Terminal access
• Permission to read Windsurf config directories

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Collect Windsurf Configuration State

#!/bin/bash
set -euo pipefail

BUNDLE="windsurf-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"/{config,logs,workspace}

echo "=== Windsurf Debug Bundle ===" > "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"

# 1. Windsurf version and environment
echo "--- Environment ---" >> "$BUNDLE/summary.txt"
windsurf --version >> "$BUNDLE/summary.txt" 2>&1 || echo "windsurf CLI not found" >> "$BUNDLE/summary.txt"
node --version >> "$BUNDLE/summary.txt" 2>&1
echo "OS: $(uname -srm)" >> "$BUNDLE/summary.txt"

# 2. Codeium config (redacted)
echo "--- Codeium Config ---" >> "$BUNDLE/summary.txt"
ls -la ~/.codeium/ >> "$BUNDLE/config/codeium-dir.txt" 2>&1 || echo "No ~/.codeium/" >> "$BUNDLE/config/codeium-dir.txt"

# 3. MCP server config (redacted)
if [ -f ~/.codeium/windsurf/mcp_config.json ]; then
  sed 's/"[A-Za-z0-9_-]\{20,\}"/"***REDACTED***"/g' ~/.codeium/windsurf/mcp_config.json > "$BUNDLE/config/mcp-config-redacted.json"
fi

# 4. Workspace config
cp .devin/rules/project.md "$BUNDLE/workspace/" 2>/dev/null || true
cp .codeiumignore "$BUNDLE/workspace/" 2>/dev/null || true
ls -la .windsurf/ >> "$BUNDLE/workspace/windsurf-dir.txt" 2>/dev/null || true
ls -la .devin/rules/ >> "$BUNDLE/workspace/rules-dir.txt" 2>/dev/null || true

# 5. Extension list
windsurf --list-extensions > "$BUNDLE/config/extensions.txt" 2>/dev/null || echo "Cannot list extensions" > "$BUNDLE/config/extensions.txt"

Step 2: Collect Logs

Windsurf Deploy Integration

Overview

Devin Desktop documents native App Deploys for Netlify. Use Cascade with reviewed provider CLIs or CI workflows for other targets, keeping build, approval, health-check, and rollback evidence explicit.

Prerequisites

• Windsurf Pro plan or higher
• Deployment platform account (Netlify, Vercel, or cloud provider)
• Application ready to deploy
• Git repository configured

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Use Windsurf's Native Deploy (Netlify)

Windsurf has a first-party Netlify integration:

1. Open Cascade (Cmd/Ctrl+L)
2. Prompt: "Deploy this project to Netlify"
3. Cascade runs the build, connects to Netlify, and deploys
4. Preview URL appears in Cascade output
5. Click to verify in browser or use in-IDE Preview

For first-time setup:

Cascade prompt: "Set up Netlify deployment for this Next.js project.
Configure build command, output directory, and environment variables."

Step 2: Create a Deployment Workflow

<!-- .windsurf/workflows/deploy-staging.md -->
---
name: deploy-staging
description: Build, test, and deploy to staging
---

## Pre-Deploy Checks
// turbo-all
1. Run `git status` — abort if uncommitted changes
2. Run `npm run typecheck` — abort if type errors
3. Run `npm test` — abort if test failures
4. Run `npm run lint` — abort if lint errors

## Build and Deploy
5. Run `npm run build`
6. Run `npx netlify deploy --dir=dist --site=$NETLIFY_SITE_ID`
   Or: `npx vercel --yes`

## Post-Deploy Verification
7. Run `curl -sf $DEPLOY_URL/health | jq .`
8. Report: deploy URL, build time, health check result

Step 3: Vercel Deployment via Cascade

Cascade prompt: "Prepare a Vercel preview deployment for this project.
- Run the repository build and tests first
- Do not deploy to production
- Do not read or print secret values
- Return the preview URL and rollback instructions"

Cascade will run:

set -euo pipefail
npm ci
npm test
npm run build

# Create a preview only; review provider output before any production promotion.
command -v vercel >/dev/null || { echo "Vercel CLI is not installed" >&2; exit 1; }
vercel --yes

Configure environment variables through the provider's…

Devin Desktop Enterprise Access Control

Overview

Build an evidence-backed enterprise access model for Devin Desktop, the current name for Windsurf. RBAC is an Enterprise feature; verify plan eligibility and current control labels in the admin console before promising a capability.

Prerequisites

• An Enterprise organization and an authenticated administrator
• Named identity, security, billing, and developer-experience owners
• The organization's identity lifecycle, least-privilege, and break-glass requirements
• Current first-party documentation and contract terms for any mutable product claim

Authentication

Perform administrative changes only from a protected enterprise-admin session. Treat SAML metadata, SCIM tokens, service keys, recovery codes, cookies, and exported member data as secrets; keep values in approved identity or secret systems and place only redacted references in deliverables.

Tool Use

• Use Read to inspect only the repository policy and configuration files needed for the access design.
• Use Write only for a new access matrix or rollout artifact explicitly requested by the user.
• Use Edit for bounded changes to existing policy documents, preserving unrelated work and all credential boundaries.

Instructions

Step 1: Establish the administrative boundary

Record the organization, administrator group, identity provider, affected teams, repositories, and environments. Use the Devin Desktop admin console under the team settings surface; do not invent SAML endpoints or API scopes from examples.

Step 2: Design roles from documented permissions

Devin Desktop provides default Admin and User roles and supports custom Enterprise roles. Start the User role with no administrative permissions, then grant only the documented actions required for the job.

Map needs against the current permission families:

• Attribution and analytics read access
• Team read, update, delete, and invite actions
• Index read, create, update, delete, and management actions
• SSO read and write actions
• Service-key read, create, update, and delete actions
• Billing read and write actions
• Role read, create, update, and delete actions

Never copy a role name from this skill without checking the live permissions list. The product can add, rename, or split permissions.

Step 3: Connect SSO and SCIM lifecycle

Use SSO for authentication and SCIM for automated provisioning, deprovisioning, and group-to-team mapping where supported. Define:

1. The IdP group that grants base access.
2. The IdP groups that map to Devin Desktop teams.
3. The role each team receives.
4. The offboarding event and maximum revocation time.
5. A tested break-g…

Devin Desktop Hello World

Overview

Devin Desktop is the current name for Windsurf. This walkthrough exercises Cascade Code and Chat modes, Supercomplete, and inline Command editing with a disposable example.

Prerequisites

• Completed windsurf-install-auth setup
• Devin Desktop open with a disposable or version-controlled project folder

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Experience Supercomplete (Tab Completions)

Open any code file and start typing. Supercomplete predicts your intent based on recent edits, cursor movement, and surrounding context.

// Type this in a new file: hello.ts
// After typing "function greet", Supercomplete suggests the rest

function greet(name: string): string {
  // Just type "return" and press Tab -- Supercomplete fills the template literal
  return `Hello, ${name}! Welcome to Windsurf.`;
}

// Start typing "const users" -- Supercomplete predicts array based on greet() context
const users = ["Alice", "Bob", "Charlie"];
users.forEach(user => console.log(greet(user)));

Key Supercomplete behaviors:

• Press Tab to accept a suggestion
• Press Esc to dismiss
• Suggestions appear as gray ghost text
• Uses recent editor activity and surrounding context for intent prediction

Step 2: Use Cascade Code Mode

Open Cascade and select Code mode. Use the visible command or current keybinding because imported editor profiles can change shortcuts.

Prompt to try:
"Create a REST API endpoint in src/api.ts using Express that serves
the greet function. Include error handling for missing name parameter."

Cascade will:

1. Create src/api.ts with Express setup
2. Import the greet function
3. Add error handling
4. Show diffs for your review

Review and accept/reject each file change before Cascade proceeds.

Step 3: Use Cascade Chat Mode

Switch to Chat mode (toggle in Cascade panel) for questions that don't need file edits:

Prompt: "Explain the difference between Code and Chat mode in Cascade"

Expected response: Code mode can create/modify files and run terminal commands.
Chat mode answers questions without touching your codebase.

Step 4: Try Inline Command (Cmd/Ctrl+I)

Highlight a block of code in the editor …

Windsurf Incident Runbook

Overview

Incident response procedures for Windsurf-related issues: Cascade service outages, AI-generated code causing bugs, and team workflow disruptions.

Prerequisites

• Access to Windsurf dashboard and status page
• Git access to affected repositories
• Team communication channel (Slack, Teams)

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

1. Classify severity and assign an incident commander.
2. Preserve evidence, stop unsafe automation, and check the official service status.
3. Use the matching playbook below; prefer a reviewed revert through the protected delivery path.
4. Validate recovery with production health signals and record follow-up owners.

Severity Levels

Quick Triage Decision Tree

Is Windsurf service itself down?
├─ YES: Check https://status.windsurf.com
│   ├─ Status page shows incident → WAIT for Windsurf to resolve
│   │   Action: Switch to manual coding, notify team
│   └─ Status page green → Local issue
│       Action: Restart Windsurf, check internet, re-authenticate
│
└─ NO: Did AI-generated code cause a production issue?
    ├─ YES → P1 INCIDENT
    │   1. Revert the deployment immediately
    │   2. Identify the Cascade-generated commit(s)
    │   3. Fix manually or with targeted Cascade prompt
    │   4. Post-incident: update review policy
    │
    └─ NO: Is Cascade giving bad suggestions?
        ├─ YES → Check .devin/rules/project.md, start fresh Cascade session
        └─ NO → See windsurf-common-errors

P1 Playbook: AI Code Caused Production Bug

Step 1: Immediate Mitigation

set -euo pipefail
# Revert the deployment
git log --oneline -10  # Find the bad commit(s)

# On a dedicated incident branch created through the normal repository process:
git revert HEAD --no-edit  # Revert the confirmed ba…

Install and Authenticate Devin Desktop

Overview

Devin Desktop is the new name for Windsurf. Existing Windsurf installations receive it as a standard over-the-air update, with plans, settings, extensions, workflows, and in-progress work carried forward.

Prerequisites

• A supported desktop operating system shown on the current download page
• A Devin/Windsurf account or organization invitation
• Browser access for the interactive sign-in flow
• Organization approval before installing on a managed device

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.

Instructions

Step 1: Choose update or fresh install

If Windsurf is already installed, use its normal update flow and preserve the existing profile. For a fresh install, download the signed installer from the official product page; do not use an unverified curl-to-shell command or third-party package.

Step 2: Preserve the current profile

Before a major update, record the editor version and export any profile the product exposes. Commit repository Rules, AGENTS.md, Workflows, and Skills separately so team customizations do not depend on one workstation.

Step 3: Sign in interactively

1. Launch Devin Desktop.
2. Select the visible sign-in option.
3. Complete the browser-based account or enterprise identity-provider flow.
4. Return to the editor and select the intended organization.
5. Confirm that the account identity and plan shown in the product are expected.

Do not ask users to paste session tokens, cookies, SAML assertions, recovery codes, or API keys into chat or repository files.

Step 4: Apply enterprise controls

For managed organizations, verify repository access, identity-provider policy, seat assignment, MCP policy, system Rules, network allowlists, and data controls through the current admin documentation. Do not invent private server URLs or undocumented settings keys.

Step 5: Verify non-destructively

Open a disposable or clean version-controlled project. Confirm:

• Cascade opens and identifies Code and Chat modes;
• a read-only codebase question returns relevant context;
• Supercomplete is available where the plan and policy permit it;
• no unexpected organization or repository is connected.

Output

Report the installed Devin Desktop version, operating system, update or fresh-install path, sign-in method, selected organization, profile migration result, and successful non-destructive Cascade check. Redact all account identifiers not needed for verification.

Error Handling

Windsurf Known Pitfalls

Overview

Avoid common failure modes involving Cascade, Supercomplete, workspace indexing, Rules, review, checkpoints, secrets, and terminal auto-execution. Verify mutable limits and labels against current first-party documentation.

Prerequisites

• Windsurf installed and configured
• Understanding of Cascade vs Supercomplete
• Awareness of workspace indexing behavior

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Avoid Using Cascade for Simple Tasks

The mistake: Opening Cascade (Cmd+L) to complete a single line of code.

BAD: Opening Cascade to write "add a console.log"
→ Cascade spins up full agent context, reads multiple files = slow and expensive

GOOD: Use Supercomplete (Tab) for inline completions
→ Instant; verify the current model's usage label before assuming no quota charge

RULE OF THUMB:
- Single line / simple completion → Tab (Supercomplete)
- Inline edit of selection → Cmd+I (Command)
- Multi-file task / complex reasoning → Cmd+L (Cascade)

Step 2: Avoid Opening a Monorepo Root

The mistake: Opening a 100K+ file monorepo as a single workspace.

BAD:  windsurf ~/company-monorepo/
→ Cascade indexes everything, slow context, vague suggestions

GOOD: windsurf ~/company-monorepo/services/payments/
→ Focused context, fast indexing, precise suggestions

WHY: Cascade's context window is limited. More files = more noise.
A focused workspace with 5K files gives better suggestions than
a bloated workspace with 100K files.

Step 3: Replace Vague Cascade Prompts

The mistake: Giving Cascade broad, unscoped instructions.

BAD: "Refactor the codebase to use TypeScript"
→ Cascade may try to convert EVERY file at once, breaking everything

BAD: "Add validation to the API"
→ Which API? Which endpoints? What validation rules?

GOOD: "Convert src/utils/api.js to TypeScript. Add proper types for
all function parameters and return values. Don't change other files."

GOOD: "In src/routes/users.ts, add zod validation for the POST /users
endpoint. Validate email format, name length (2-50 chars), and role
must be 'admin' or 'user'. Return 400 with field-level errors."

Step 4: Review Every Proposed Change

The mistake: Accepting all Cascade changes without reading the diffs.

BAD: Cascade modifies 12 files → "Accept All" → broken tests
→ Cascade may have changed shared utilities, removed error handling,
  or introduced dependencies on APIs…

Windsurf Load & Scale

Overview

Strategies for deploying Devin Desktop (formerly Windsurf) across large organizations. Covers workspace partitioning, policy distribution, quota governance, and performance at scale.

Prerequisites

• Windsurf Teams or Enterprise plan
• Admin dashboard access
• Understanding of team structure and repository layout
• Network/IT involvement for enterprise features

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Workspace Strategy for Large Codebases

# Windsurf performance degrades with workspace size
# Cascade context quality inversely correlates with file count

workspace_sizing:
  optimal: "<5,000 files — fast indexing, precise Cascade context"
  acceptable: "Measure against available RAM and current indexing guidance"
  problematic: "20,000+ files — must partition into sub-workspaces"
  unworkable: "100,000+ files at root — Cascade context diluted, indexing very slow"

# Strategy: one Windsurf window per service/package
# Each developer opens their assigned service directory

Step 2: Monorepo Partitioning

# Large monorepo (100K+ files)
company-monorepo/
├── .devin/rules/project.md              # Brief shared conventions only
├── .codeiumignore              # Aggressive: exclude EVERYTHING except src
├── apps/
│   ├── web-app/                # Developer A opens this window
│   │   ├── .devin/rules/project.md      # Next.js-specific AI context
│   │   └── .codeiumignore      # Local exclusions
│   ├── mobile-app/             # Developer B opens this window
│   │   ├── .devin/rules/project.md      # React Native context
│   │   └── .codeiumignore
│   └── admin-portal/           # Developer C opens this window
│       ├── .devin/rules/project.md
│       └── .codeiumignore
├── services/
│   ├── api-gateway/            # Backend team opens individual services
│   ├── auth-service/
│   ├── payment-service/
│   └── notification-service/
├── packages/
│   └── shared-types/           # Library maintainer opens this
└── infrastructure/
    └── terraform/              # DevOps opens this

Rule: Never open the monorepo root in Windsurf. Each developer opens their service directory.

Step 3: Configuration Distribution at Scale

# Central config repo for team-wide standards
windsurf-config/
├── templates/
│   ├── windsurfrules/
│   │   ├── nextjs.md           # Template for Next.js projects
│   │   ├── fast…

Windsurf Local Dev Loop

Overview

Set up a fast, AI-augmented local development workflow using Windsurf's Cascade, Turbo mode, Previews, and terminal integration. The goal is a tight loop: edit with Cascade, preview in-IDE, iterate, test, commit.

Prerequisites

• Windsurf authenticated and project open
• Node.js 18+ or Python 3.10+
• Git initialized in project

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Create .devin/rules/project.md for Project Context

<!-- .devin/rules/project.md - placed at project root, committed to git -->

# Project: my-app

## Stack
- Language: TypeScript (strict mode)
- Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS v3
- Testing: Vitest + Testing Library
- Package manager: pnpm

## Architecture
- Server Components by default
- Client Components only when state/interactivity needed
- API routes in app/api/
- Business logic in lib/services/
- Types in lib/types/

## Conventions
- Named exports, never default
- async/await, never raw .then()
- zod for all runtime validation
- Error handling: Result pattern in services

Step 2: Configure .codeiumignore

# .codeiumignore - exclude from AI indexing (same syntax as .gitignore)
node_modules/
.next/
dist/
build/
coverage/
*.min.js
*.map
.env
.env.*

Step 3: Set Up Turbo Mode for Fast Terminal Execution

Turbo mode lets Cascade auto-execute terminal commands without asking permission for each one.

Enable: Windsurf Settings > Cascade > Terminal Execution Level > Turbo

Configure safety lists:

// Settings (JSON) — search "cascadeCommands"
{
  "windsurf.cascadeCommandsAllowList": [
    "npm", "pnpm", "npx", "node", "tsc",
    "vitest", "jest", "eslint", "prettier",
    "git status", "git diff", "git log", "git add"
  ],
  "windsurf.cascadeCommandsDenyList": [
    "rm -rf", "sudo", "git push --force",
    "git reset --hard", "DROP TABLE", "shutdown"
  ]
}

Step 4: U…

Windsurf Migration Deep Dive

Current State

Collect source and target editor versions during the inventory step; do not execute shell substitutions while loading this skill.

Overview

Comprehensive guide for migrating teams to Windsurf from VS Code + Copilot, Cursor, or other AI editors. Covers settings transfer, concept mapping, team rollout planning, and rollback strategy.

Prerequisites

• Current editor still installed (for config export)
• Target repositories identified
• Team buy-in for evaluation period

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

Instructions

Step 1: Feature Comparison Matrix

Step 2: Migrate from Cursor

#!/bin/bash
set -euo pipefail
echo "=== Migrating Cursor → Windsurf ==="

# 1. Convert rules files
if [ -f .cursorrules ]; then
  mkdir -p .devin/rules
  cp .cursorrules .devin/rules/project.md
  echo "Converted .cursorrules → .devin/rules/project.md"
fi

# 2. Convert ignore…

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

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Per-Project Cascade Rules

<!-- .devin/rules/project.md - 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/
      .devin/rules/project.md        # Auth context: JWT, OAuth, session management
      .codeiumignore         # Exclude auth secrets directory
    payments/
      .devin/rules/project.md        # Payments context: Stripe, PCI compliance
      .codeiumignore         # Exclude PCI data directories
    notifications/
      .devin/rules/project.md        # Notifications: queues, email templates
      .codeiumignore
  .windsurf/
    settings.json            # Shared IDE settings
    rules/
      shared-patterns.md     # trigger: always_on
    workflows/
      deploy-service.md      # /deploy-s…

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

Authentication

Use an authenticated organization-admin session for dashboards. If analytics API access is enabled, use the organization-issued credential from an approved secret store, request read-only scope where available, and never include the credential or raw member data in reports.

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

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 set by the organization)"
    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:
    quota_utilization: "Daily and weekly included usage, when exposed"
    on_demand_usage: "Approved variable usage beyond included quota"

  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 .devin/rules/project.md — 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"

  variable_usage_risk:
    condition: "on-demand usage approaches the approved spending limit"
    action: "Notify the billing owner and review model/context choice…

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

Capture a repeatable latency or indexing symptom before changing exclusions, extensions, workspace scope, or editor settings.

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

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
  …

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

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

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/

<!-- .devin/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 schem…

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

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Complete Pre-Deployment Configuration

Workspace Config (per repository):

• [ ] .devin/rules/project.md created with project stack, patterns, and constraints
• [ ] .codeiumignore excludes secrets, build artifacts, and large binaries
• [ ] .devin/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 retention and training-use terms verified against the current contract

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)

Step 2: Complete 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 .devin/rules/project.md ] || echo "WARNING: .devin/rules/project.md 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…

Devin Desktop Quota and Usage

Overview

Devin Desktop is the current name for Windsurf. Its current usage system uses daily and weekly quota; optional extra usage can continue work after included quota is exhausted.

Prerequisites

• The user's current plan and reset time from the in-product usage meter
• Permission to view billing only when account-level diagnosis is requested
• A task or session sample representative of the reported consumption

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Identify the applicable plan

Read the plan page instead of assuming a legacy tier or price. Record whether the account is Free, Pro, Max, Teams, Enterprise, or a grandfathered plan.

Step 2: Read the usage meter

Capture without credentials:

• remaining daily quota and reset time, when present;
• remaining weekly quota and reset time;
• whether extra usage is enabled and its configured limit;
• the model and speed option used when the issue occurred.

Paid plans and full seats can have included allowances. Free accounts wait for reset; eligible paid accounts can use configured extra usage after quota.

Step 3: Explain what consumes quota

Usage is token-based and varies by model. Long shared timelines, large context, tool calls, output, and fast or priority variants can increase consumption. Free models do not count against quota. Do not publish a fixed per-prompt conversion table.

Step 4: Choose the least-cost correction

1. Start a focused conversation when old context is no longer needed.
2. Scope repository context and attachments to the task.
3. Use a lower-cost SWE-family model, such as a currently available SWE model, for routine work.
4. Keep frontier or fast variants for tasks that justify their higher consumption.
5. Configure extra-usage limits only with the billing owner's approval.

Step 5: Handle legacy credit language

Treat "prompt credits" as the retired built-in system. Historical add-on credits were converted to extra-usage balance under the migration rules. Current self-serve Devin billing also uses on-demand credits outside included quota; do not confuse those billing credits with the retired per-prompt Windsurf allocation.

Step 6: Verify

Run one representative, non-destructive request and confirm the meter behaves as expected. If usage remains unavailable, preserve the displayed error and reset time and route it to account support.

Output

Provide a current usage diagnosis naming the plan, daily or weekly quota state, extra-usage or on-demand balance s…

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                       │
│  ┌───────────────┐  ┌────────────────────────────┐    │
│  │ .devin/rules/project.md│  │ .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   │
└──────────────────────────────────────────────────────┘

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.

Instructions

Step 1: Project File Structure

my-project/
├── .devin/rules/project.md              # 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/        …

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 Code mode

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

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 sui…

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 Code and Chat modes
• Project with established coding conventions

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Root-Level .devin/rules/project.md (Permanent Context)

The .devin/rules/project.md file is the single highest-impact configuration for Cascade output quality. It provides persistent context every session.

<!-- .devin/rules/project.md -->

# 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 .devin/rules/ with YAML frontmatter:

<!-- .devin/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

<!-- .devin/rules/api-routes.md -->
---
trigger: glob
globs: src/routes/**/*.ts
---
API route handlers must:
- Validate input with zod sch…

Devin Desktop Security Basics

Overview

Devin Desktop is the current name for Windsurf. Secure it with layered controls: repository permissions and secret management are authoritative; .codeiumignore, Rules, and prompts reduce context exposure but do not replace access control.

Prerequisites

• A version-controlled workspace and clean working tree
• The organization's data-classification and secret-handling policy
• Authorization to inspect configuration without collecting secret values

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.

Instructions

Step 1: Map trust boundaries

Record repository sensitivity, connected organizations, enabled models, MCP servers, Hooks, terminal permissions, remote indexing, and deployment integrations. Identify which controls are local, repository-owned, or centrally administered.

Step 2: Configure context exclusions

Create .codeiumignore at the repository root using gitignore syntax. Include only project-relevant patterns, for example:

.env
.env.*
*.pem
*.key
credentials/
secrets/
customer-data/
dist/
node_modules/

Windsurf also honors .gitignore, and Enterprise administrators can add a global .codeiumignore under ~/.codeium/. Verify behavior with a harmless canary filename; do not place a real secret in the test.

Step 3: Enforce durable behavior

Use repository AGENTS.md or .devin/rules/*.md to require secure coding, validation, least privilege, and explicit approval for risky operations. Keep each workspace Rule within the documented 12,000-character limit and use the correct trigger: mode.

Step 4: Review tools and automation

1. Disable unused MCP servers and tools.
2. Prefer provider OAuth or environment-backed secrets over literal values in mcp_config.json.
3. Review Hooks as executable policy code and fail closed where required.
4. Keep protected branches, code owners, CI, and deployment approvals outside the model's discretion.
5. Require human approval for production, destructive, identity, and billing mutations.

Step 5: Respond to exposure

If a secret appears in a prompt, output, log, diff, or diagnostic bundle, treat it as exposed: stop sharing, revoke or rotate it through the provider, remove it from history where authorized, and document the incident. Adding an ignore rule alone is not remediation.

Step 6…

Windsurf Upgrade & Migration

Current State

Collect the installed editor versions during Step 1; do not execute shell substitutions while loading this skill.

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

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

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:

set -euo pipefail
# 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:       .devin/rules/project.md     # AI context rules
  .cursorignore:      .codeiumignore     # AI indexing exclusions
  .cursor/rules/:     .devin/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 -eu…

Windsurf Extension Development & Events

Overview

Build compatible extensions on Devin Desktop's VS Code foundation to observe workspace events and integrate external tools. Keep telemetry, credential, network, and user-consent boundaries explicit instead of assuming every VS Code behavior is product-guaranteed.

Prerequisites

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

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.
• Use only the command-scoped Bash entries declared in frontmatter, with non-destructive checks before mutations.

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 f…