24 Windsurf Cascade Agent Prompts (2026)

Goal: [describe the feature or change in one sentence].

Do NOT write any code yet. First produce a step-by-step plan:
1. The exact files you will create or edit, with a one-line reason for each.
2. The order you will make the changes in.
3. Any assumptions you are making and open questions for me.

Stop after the plan and wait for my explicit "approved" before you touch a single file.

@codebase Break this large task into a checklist of small, independently shippable steps: [describe the epic, e.g. "migrate auth from sessions to JWT"].

For each step give: a short title, the files involved, and a done-check I can verify. Keep each step under ~1 hour of work. Number them. Do not start implementing — just return the checklist so we can work through it one item at a time.

Before we change [module or feature], assess the blast radius. Use @codebase to find every file that imports or depends on it. List:
- Which callers would break if I change the [function/signature/schema].
- Which changes are safe vs. which need a migration or a deprecation path.
- A risk rating (low/medium/high) with one line of reasoning.

Return the assessment only. Do not edit anything yet.

[Switch Cascade to Chat/Ask mode first, then send:]

You are read-only for this message. Design an implementation approach for [feature]. Compare 2 possible designs, note the trade-offs, and recommend one with reasoning. Reference the real files in @folder [path/]. When I switch you to Write mode, I want you to follow the recommended design — so make it concrete and file-specific.

Implement [feature] end to end in @folder [path/].

Acceptance criteria:
- [criterion 1]
- [criterion 2]
- [criterion 3]

Write or update tests to cover these criteria, then run [npm test] and read the output. If any test fails, fix the code and re-run. Repeat until the suite is fully green. When done, summarize what you changed and paste the final passing test output.

Here is the ticket:

"""
[paste the full ticket / spec text]
"""

Implement it across whatever files are needed. Use @codebase to locate the right modules. Follow the existing patterns in this repo (routing, error handling, naming). Add tests for the new behavior. After each file, keep going until the ticket's acceptance criteria are all satisfied. List every file you touched at the end.

Get [the app / this package] building and running cleanly.

Run [the build command], read the errors, fix them, and re-run. Then run [the lint command] and [the test command] and do the same. Iterate the run-read-fix loop autonomously — do not stop to ask me between iterations unless you hit a decision that changes behavior. Stop only when build, lint, and tests all pass, then report what was broken and how you fixed it.

Feature: [name]. Build it in @file [path/to/file] and any files it requires.

Definition of done (all must hold):
- Running [command] exits 0.
- [endpoint/behavior] returns [expected result] for input [example].
- No existing test regresses — run the full suite to confirm.

Work autonomously toward this definition of done. If you cannot satisfy a criterion, stop and explain why rather than marking it complete.

Make this change: [describe it].

Hard constraint: you may only edit these files — [path/a.ts], [path/b.ts], and their test files. Do NOT modify, rename, or delete anything else. If completing the task correctly requires a change outside this list, stop and ask me first with the specific file and reason. Confirm you understand the scope before editing.

Refactor the internals of @file [path/to/module] to [goal].

Non-negotiable: the public API stays exactly the same — same exported function names, signatures, and return types. Nothing that imports this module should need to change. After refactoring, use @codebase to confirm no caller was modified, and run the tests to prove behavior is unchanged.

Implement [task]. Prefer the standard library and packages already in [package.json / requirements.txt].

If you believe a NEW dependency is genuinely required, stop and ask me first: name the package, why it is needed, and one lighter alternative you considered. Do not run any install command until I approve it.

Work on [task]. Operating rule for this run: when you are less than ~80% confident about a decision — data shape, a business rule, which of two files owns this logic, or anything that changes behavior — STOP and ask me a specific question instead of guessing. I would rather answer three questions than review a wrong 200-line diff.

@codebase Where is [concept, e.g. "rate limiting" or "the checkout total is calculated"] implemented? Return the specific files and functions, how they connect, and the single place I would change to [desired change]. Do not edit yet — just map it out so I know where to point you next.

Using @file [path/to/reference.ts] as the pattern to follow and everything in @folder [path/feature/] as the context, add [new capability]. Match the style, error handling, and test structure of the reference file exactly. Only work within @folder [path/feature/].

@docs [library name] Implement [task] using [library]. Follow the current, documented API — no deprecated methods and no invented options. If the docs show a recommended pattern for [use case], use it and cite the section. Then write a small test that exercises the integration and run it.

@terminal Take the error I just hit in the terminal, find the root cause, and fix it. Explain in one line what caused it before you edit. After the fix, re-run the same command to confirm it is gone, and make sure no other test breaks.

@git Review only the changes in my current diff. For each changed file, check for bugs, missing edge cases, and anything that breaks an existing test. Fix what you find within the already-changed files, then run the tests. Don't expand the scope beyond files I've already touched.

Create a new rule file at .windsurf/rules/[testing].md. Set the trigger to Glob matching [**/*.test.ts]. In the body, write concise, imperative conventions for how tests in this repo must be written: [e.g. use Vitest, arrange-act-assert, no snapshot tests, mock network with msw].

Keep it short. Show me the full file contents including the trigger frontmatter before saving.

Create a memory: in this project we [state the durable decision, e.g. "always use the Result type for fallible functions instead of throwing" or "API responses are camelCase, DB columns are snake_case"]. Keep it to one or two sentences so it loads cheaply, and apply it automatically from now on without me repeating it.

Create a workflow file at .windsurf/workflows/ship-feature.md that I can invoke with /ship-feature. It should encode these steps in order:
1. Run the full test suite; stop if anything fails.
2. Run the linter and formatter; auto-fix what's safe.
3. Update the changelog with a one-line entry.
4. Create a conventional-commit message from the diff and show it to me before committing.

Write it as a clear Markdown recipe with numbered steps. Show me the file before saving.

/[workflow-name]

[After it runs:] That mostly worked, but step [N] should also [adjustment, e.g. "run the type-checker before the linter" or "skip the changelog when the branch is a hotfix"]. Update .windsurf/workflows/[workflow-name].md to reflect that, and show me the diff of the workflow file.

We are migrating [from X to Y, e.g. "Moment.js to date-fns across the codebase"]. This is large — treat it as a long-running task.

First, use @codebase to build a checklist of every file that needs migrating. Then work through them in batches. After each batch: run the tests, report which items are done vs. remaining as a checklist, and continue to the next batch without waiting for me. Stop only if a batch fails tests you can't fix, and tell me exactly where you stopped.

Continue the [migration/task] from where we left off. Use @git to see what's already changed and @codebase to find what still matches the old pattern [describe it]. Re-derive the remaining checklist, then keep going through it. Confirm the remaining list with me first, then proceed autonomously and run the tests after each batch.

I've connected the [name] MCP server in Windsurf (tools: [list the tools it exposes]). For this task — [describe it, e.g. "pull the open issues labeled 'bug' and scaffold a fix branch for each"] — use the MCP tool to fetch the data, then act on it in code. Show me which tool call you make and its result before you write any code based on it.