Windsurf Cascade: Advanced Agentic Workflows

What makes Cascade different

Most AI coding assistants respond to individual prompts. You ask a question, you get an answer. You request a change, you get a diff. Each interaction is a standalone transaction.

Windsurf's Cascade is built on a different idea. Instead of answering questions, Cascade executes workflows. You describe an outcome -- "add a user settings page with email preferences and notification toggles" -- and Cascade plans the work, creates files, writes code, runs terminal commands, and validates the result. It operates as an autonomous agent inside your editor.

This is what developers mean by "agentic workflows." The AI doesn't just suggest. It acts. And that shift changes how you work with it.

If you're coming from Cursor or Claude Code, the comparison guide breaks down the fundamental differences between the three tools. This guide focuses specifically on getting the most out of Cascade's agentic capabilities.

Code vs Chat: two modes, different purposes

Cascade gives you two primary interaction modes:

Chat mode works like a traditional AI assistant. Ask a question, get an answer. Use it for explanations, code review, quick lookups, and brainstorming. Chat can propose code snippets you can accept and insert, but it won't directly modify your files or run commands.

Code mode is the agentic engine. It reads your codebase, creates and edits files, runs terminal commands, installs packages, and orchestrates multi-step changes across your project. Code mode is the reason most developers choose Windsurf.

There's also Plan mode, activated by typing /plan in the Cascade input. A specialized planning agent creates a detailed implementation plan before any code is written, which helps Cascade stay on track during longer tasks.

When to use which:

The key insight: start in Chat to understand, switch to Code to act. Developers who try to do everything in Code mode waste tokens on explanations. Developers who stay in Chat miss the tool's strongest capability.

Multi-step task execution

Cascade's real power shows up when a task requires more than one step. Here's what happens when you ask Cascade to add a feature:

1. Planning -- Cascade reads your project structure, understands existing patterns, and creates a plan. You see this plan before execution starts.
2. File operations -- It creates new files, modifies existing ones, and manages imports across the project.
3. Terminal commands -- It runs build tools, package managers, linters, and test suites directly in the integrated terminal.
4. Validation -- After making changes, Cascade checks that the build passes and tests succeed.
5. Iteration -- If something fails (a type error, a test assertion), Cascade reads the error and fixes it autonomously.

This loop is what separates Cascade from a chat-based assistant. When Cursor or a standard copilot generates code with a type error, you fix it manually. When Cascade generates code with a type error, it reads the compiler output and fixes it in the next step.

Practical example: adding a settings page

Here's what a real Cascade session looks like for a non-trivial task:

Prompt: "Add a user settings page at /settings. Include sections for
profile info (name, email), notification preferences (email notifications
toggle, marketing emails toggle), and a danger zone (delete account button).
Use our existing component patterns and Tailwind classes."

Cascade will typically:

1. Read your existing pages to understand routing patterns and layout structure
2. Read your component library to match the existing UI style
3. Create src/app/settings/page.tsx with the correct layout wrapper
4. Create sub-components for each section (profile form, notification toggles, danger zone)
5. Wire up form state and API calls matching your existing patterns
6. Run pnpm type-check to verify there are no type errors
7. Run pnpm dev or the build command to validate

The entire workflow runs in one Cascade session. You review the plan, approve it, and watch it execute. If something breaks at step 6, Cascade reads the error and patches the code before moving to step 7.

File context and codebase awareness

Cascade doesn't work in a vacuum. It indexes your project and understands file relationships, import graphs, and naming patterns. This context is what allows it to generate code that actually fits your codebase rather than producing generic boilerplate.

How Cascade uses context

Automatic file discovery -- When you describe a task, Cascade identifies which files are relevant. Ask it to "add a new API route for user preferences" and it will read your existing API routes, your database schema, your auth middleware, and your type definitions before writing a single line.

Import resolution -- Cascade traces imports to understand your module structure. If your components import from @/lib/utils, Cascade will use the same path aliases. If you have a custom cn() utility for Tailwind class merging, it will use that instead of raw classnames calls.

Pattern matching -- This is Cascade's strongest contextual behavior. It doesn't just read your code -- it extracts patterns from it. If all your API routes use NextResponse.json() with a consistent { data, error } shape, new routes will follow the same pattern without you specifying it.

Improving context quality

You can improve Cascade's context awareness by:

• Keeping consistent patterns -- The more consistent your codebase, the better Cascade's output. If half your components use default exports and half use named exports, Cascade has to guess.
• Using descriptive file names -- user-settings-form.tsx gives Cascade more signal than form.tsx.
• Organizing by feature -- Colocating related files (component, test, types) helps Cascade find everything it needs for a change.

Terminal integration

Cascade's terminal access is what makes it a true agent rather than a code generator. It runs commands in Windsurf's integrated terminal, reads the output, and reacts to it.

Common terminal operations Cascade handles:

• Package installation -- npm install, pnpm add, yarn add -- Cascade installs dependencies it needs for the code it's writing
• Build validation -- Running pnpm build or tsc --noEmit after changes to catch compile errors
• Test execution -- Running test suites and reading failures to fix assertions
• Code generation -- Running tools like pnpm db:generate for database migrations or openapi-generator for API types
• Linting -- Running eslint or prettier and fixing reported issues

Controlling terminal behavior

By default, Cascade asks for confirmation before running commands. This is the right default -- you don't want an AI agent running rm -rf without your approval. But you can tune this behavior:

• Allow list -- Configure cascadeCommandsAllowList in Windsurf settings to specify commands that always auto-execute (e.g., git, ls, pnpm test)
• Deny list -- Configure cascadeCommandsDenyList to specify commands that always require manual approval (e.g., rm, drop)
• Turbo mode -- Enables automatic execution of all terminal commands that aren't on the deny list, letting Cascade move through workflows without pausing for approval at each step

This is where Windsurf rules become critical. Explicit command policies in your rules prevent Cascade from doing things you don't want:

## Terminal policies

- Always use pnpm, never npm or yarn
- Never run database migrations automatically -- generate the migration file and stop
- Always run type-check after making TypeScript changes
- Never delete files without explicit confirmation

Writing rules that work with Cascade

Cascade reads your Windsurf rules at the start of every session and uses them throughout execution. But writing rules for an agentic workflow is different from writing rules for a chat assistant.

Rules for the planning phase

Cascade plans before it acts. High-level architectural rules shape these plans:

# Architecture rules

## Project structure
- Pages go in src/app/ (Next.js App Router)
- Shared components in src/components/
- Server-only utilities in src/lib/server/
- Client utilities in src/lib/client/
- Database schema in src/db/schema.ts

## Dependencies
- Do NOT add new npm packages without asking first
- Prefer built-in Node.js APIs over third-party libraries
- If a package is needed, check if a similar one already exists in package.json

These rules prevent Cascade from making architectural decisions you'll have to undo. Without the "do not add packages" rule, Cascade will install a library for every minor convenience.

Rules for the execution phase

During execution, Cascade needs specific patterns to follow:

# Code patterns

## API routes
- Use NextResponse.json() for all responses
- Wrap handler body in try/catch
- Return { data: result } on success
- Return { error: string } with appropriate HTTP status on failure
- Always validate request body with zod before processing

## Components
- Named exports only (no default exports)
- Props interface defined above component
- "use client" directive only when the component uses hooks or event handlers

Execution rules should include concrete examples. Cascade is better at matching patterns than interpreting abstract descriptions.

Rules for the validation phase

Tell Cascade what "done" looks like:

# Validation

After any code changes, run these checks in order:
1. pnpm type-check -- must pass with zero errors
2. pnpm test -- all tests must pass
3. pnpm lint -- fix any warnings before finishing

A task is not complete until all three checks pass.
If a check fails, fix the issue and re-run all checks.

Without validation rules, Cascade may consider a task complete after writing code -- even if that code has type errors or breaks existing tests.

SWE models and model selection

Windsurf offers its own SWE (Software Engineering) model family alongside 80+ models from Anthropic, OpenAI, Google, and others. Understanding when to use which makes a real difference.

SWE-1.5 (recommended) -- Windsurf's latest and best agentic coding model. Trained end-to-end with reinforcement learning on real task environments, it delivers near-frontier-level performance at up to 950 tokens per second -- 13x faster than Claude Sonnet 4.5. SWE-1.5 is the recommended model for Cascade workflows.

SWE-1 -- The original agentic model. Still available but largely superseded by SWE-1.5.

Claude Sonnet / Opus -- Strong at reasoning through complex logic, understanding nuanced requirements, and producing high-quality code. Good for tasks that require deep understanding of business logic or subtle architectural decisions.

GPT models -- OpenAI's latest models including GPT-5.3-Codex variants offer solid coding capabilities. Useful if you have existing OpenAI workflows or prefer their output style.

Gemini -- Google's models offer fast response times and strong performance on standard coding tasks.

Windsurf also uses specialized models behind the scenes: SWE-1-mini powers passive code suggestions in the editor tab, and SWE-grep handles fast context retrieval across your codebase.

For most Cascade workflows, SWE-1.5 is the right default. It's optimized for the exact operations Cascade performs -- reading files, planning changes, writing code, running commands, and iterating on errors. Switch to a frontier model like Claude Opus when the task requires deeper reasoning or when you're working through a complex design problem in Chat mode.

Advanced Cascade patterns

Once you're comfortable with basic Cascade usage, these patterns help you get more out of it:

Checkpoint before big changes

Before asking Cascade to refactor a module or make sweeping changes, commit your current state:

First, run "git add -A && git commit -m 'checkpoint before refactor'"
Then refactor the auth module to use the new session API.

This gives you a clean rollback point. Cascade respects git and will run the commit before starting the refactor.

Chain tasks with context

Cascade retains context within a session. Use this for multi-phase work:

Phase 1: Create the database schema for user preferences
(Cascade creates schema, generates migration)

Phase 2: Now build the API routes for CRUD operations on user preferences
(Cascade reads the schema it just created and builds matching routes)

Phase 3: Add the settings UI that calls these API routes
(Cascade reads the routes it just built and creates matching frontend code)

Each phase builds on the previous one. Cascade uses the files it created in earlier phases as context for later ones.

Use Cascade for test-driven development

Cascade is particularly effective for TDD workflows:

1. Write failing tests for a calculateDiscount function that handles
   percentage discounts, flat discounts, and stacked coupons.
2. Run the tests to confirm they fail.
3. Implement the function to make all tests pass.
4. Run the tests again to confirm they pass.

Because Cascade can run tests and read output, the red-green-refactor cycle happens in one continuous session.

Making Cascade work across your team

Individual Cascade mastery is valuable, but the real payoff comes when your whole team operates with shared conventions. If one developer's Cascade rules produce API routes with { data, error } shapes and another's produce { result, message }, you end up with an inconsistent codebase -- and the AI assistance that caused it.

The fix is shared rules. Commit your .windsurf/rules/ folder to git so every developer on the team gets the same Cascade behavior.

For teams that use multiple AI tools -- which is increasingly common in 2026 -- maintaining separate rules for Windsurf, Cursor, and Claude Code becomes a real burden. This is the problem localskills.sh solves. Publish your rules once and install them into every tool:

# Publish your Windsurf rules to the registry
localskills publish

# Your teammates install with one command
localskills install your-team/api-conventions --target windsurf cursor claude

Skills are versioned, so you can update conventions and roll them out incrementally. The CLI handles format translation between Windsurf's markdown rules, Cursor's .mdc format, and Claude Code's CLAUDE.md structure.

For the full guide on configuring Windsurf rules, see the Windsurf rules guide. For broader strategies on AI-assisted coding, the AI pair programming guide covers workflow patterns that apply across all tools.

---

Get consistent Cascade behavior across your team. Sign up for localskills.sh and share your Windsurf rules in minutes.

npm install -g @localskills/cli
localskills login
localskills publish