Windsurf Integration: Run Your Validated Playbook in Cascade

What Windsurf does

Windsurf is Codeium’s agentic IDE: a VS Code fork built around a chat agent called Cascade. Cascade can read multiple files, write multi-file diffs, run tests, and commit. Compared to Cursor, the contrast is Cascade’s appetite for large refactors in one pass; compared to Claude Code, the contrast is that Windsurf is GUI-first while Claude Code is terminal-first.

Windsurf reads project-level configuration on session start and uses it as context for every Cascade conversation. ShipFit’s stage-9 export uses that mechanism to keep your validated decisions in front of the agent for the life of the project.

What ShipFit ships to Windsurf

When you reach stage 9 (What to Export?) and pick Windsurf, the export takes the validated playbook produced by the previous 8 stages and lands it in your repo as Windsurf configuration. Cascade then works from your validated decisions, not generic defaults.

What carries over from the playbook into the export:

1. Buyer persona from stage 2 (Who Pays?), with verbatim quotes from your interviews.
2. Above-the-line pains from stage 3 (What Hurts?), with frequency × intensity scores.
3. Winning angle from stage 4 (How to Win?), tied to which of the 7 Powers the business will have at maturity.
4. V1 scope from stage 5 (What’s V1?). Differentiator + Operational features; Delights held back for V2.
5. Pricing model from stage 6 (How to Charge?). Tier structure, entry price, the Pricing Position verdict.
6. Launch plan from stage 8 (How to Launch?). Primary channels and message.

ShipFit also installs project-level shortcuts that re-apply the framework gates during development, so Cascade’s appetite for big diffs stays bounded by the validated V1 scope.

Set it up, step by step

Before you start

You need a finished playbook. Run the full 9-decision flow first (a Quick Take takes about 2 minutes, the full playbook 15 to 20 minutes). The export only works once the prior 8 decisions are locked, because that is what fills the rules with real content: your buyer, your above-the-line pains, your V1 cut, and your pricing model.

You also need Windsurf installed and a project folder to work in.

Step by step

1. Finish the playbook and reach the export step. The export is the last of the 9 decisions. Pick Windsurf as a target (you can select multiple tools at once). ShipFit packages your validated decisions into Windsurf’s rules format, i.e. a .windsurfrules file that Cascade reads as standing context.

2. Place the file in the repo root. Unzip the export at the top level of the project and commit. Windsurf reads project rules on session start, so the root is where Cascade looks. A rules file buried in a subfolder will not load.

3. Reopen the project in Windsurf. Project rules load on session start, so reopening the folder guarantees the new context is active. Open the rules file and read it once. You should see your buyer persona, your V1 feature cut, and your pricing model in plain language.

4. Smoke-test Cascade. In a new Cascade conversation, ask: “Who is this for and what is in V1?” If Cascade answers with your validated buyer and V1 scope, the rules are loading. A generic answer means the file is misplaced or the project was not reopened.

5. Keep validation and engineering rules apart. Put validated decisions (buyer, scope, pricing) in one section and engineering conventions (test framework, file layout, linting) in another. Re-exporting after a pivot refreshes the validation section and leaves your engineering section in place.

6. Build against the scope. Cascade is aggressive about large, multi-file changes, which is exactly when scope discipline matters most. With the V1 scope in its rules, Cascade builds the validated cut first and should flag when a request belongs in V2. Ask it to “rebuild the whole onboarding flow,” and a well-scoped project keeps that rebuild inside the V1 boundary instead of quietly shipping features you parked.

Keeping it in sync

Re-run the export after any meaningful pivot, e.g. a new buyer segment or a new pricing model. The repo’s .windsurfrules should always match your current validated state. Because Cascade ships big diffs fast, a stale rules file does real damage quickly: it can rebuild large surfaces against decisions you have already dropped.

Why bother

Cascade is built to ship big diffs. That’s its strength when you’re doing a known refactor with clear scope, and its weakness when the scope hasn’t been defined. Without project-level context, asking Cascade to “build the user dashboard” produces a 12-file shipset that includes admin features, settings panels, and notification preferences, none of which were in your validated V1.

Loading the validated playbook into Windsurf prevents that. The big-diff capability stays useful; the diffs are now constrained to the validated scope.

Common mistakes

1. Treating the export as a one-time setup. Re-export after any meaningful pivot.

2. Letting the framework gates collect dust. The first time the gate flags scope creep, the temptation is to dismiss it. The flag means it caught real drift. Investigate.

3. Mixing engineering conventions with validation context in the wrong place. Re-exporting refreshes the validation context; your engineering conventions stay where you put them.

4. Wrong file location. Rules outside the root that Windsurf does not scan never load. Root, reopen, then smoke-test.

5. Expecting Windsurf to validate the idea. Cascade builds; it does not test demand. Validation happens upstream in the playbook. If you have not run one, see pricing (free tier includes 3 credits a month, paid playbooks from $5).

Further reading

• Windsurf documentation, the official Codeium spec.
• Cursor integration, same playbook, IDE-native alternative.
• Claude Code integration, terminal-native version of the same export.
• Validating a business idea with AI, the workflow this export plugs into.