Skip to content
vibespell

.windsurf/rules/project.md

Windsurf rules for Flutter

Windsurf rules tell the Cascade agent how this repo is built and tested. The current location is `.windsurf/rules`. Older setups still read a root `.windsurfrules` file. This copy is written for a Flutter project. This repository is a Flutter app. Widgets stay small, state management matches the package the repo already uses, and `flutter analyze` stays clean.

The example uses a balanced, readable style, pragmatic tests, and comments only where the intent is not obvious. Open the generator to make the agent stricter, switch to test-first, quiet the comments, or pick a different file.

The example assumes Flutter with Dart. It does not assume Riverpod, Bloc, or a particular router. Use the state library already in pubspec.yaml.

Customize in the generatorBrowse the library

Example file

Balanced strictness, readable style, pragmatic tests. Download name: project.md. Legacy path: .windsurfrules

# Windsurf rules

Rules for Windsurf Cascade in this Flutter repository.
If the project still uses a root `.windsurfrules` file, keep the same rules there.

## Stack

This repository is a Flutter app. Widgets stay small, state management matches the package the repo already uses, and `flutter analyze` stays clean.

## Layout

- Screens live with the feature. Reusable widgets live in a shared widgets folder the repo already has.
- Side effects stay out of `build`. `build` returns a widget tree.
- Platform channels stay isolated. Do not sprinkle method channels through UI files.

## Commands

- Analyze: `flutter analyze`
- Tests: `flutter test`
- Run: `flutter run`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Prefer `const` constructors when the widget's inputs are constant.
- Do not call `setState` after the widget is disposed.
- Keys are stable when a list can reorder.
- Add a state-management package only if pubspec already depends on it.
- Handle loading and error in the UI the screen already uses.
- Run the formatter the repo uses (`dart format`).

## Testing

Add or update tests when behavior changes.

Add a widget or unit test with `flutter_test`. Assert on text and finders, not on private fields.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Surface a recoverable error in the widget. Do not swallow a failed future.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not do network or disk work directly inside `build`.
- Do not ignore `BuildContext` across an async gap.
- Do not use `print` for errors the user can hit. Use the project's logger.
- Do not fork a widget into a platform file unless the behavior actually differs.

## Done when

- The requested behavior works.
- `flutter analyze` is clean and `flutter test` passes for the widget you touched.
- The diff stays inside the task.
- You list anything you could not run.

Add it to the project

  1. 01

    Copy a starting file

    Copy the example Windsurf rules on this page, or open the generator if you want different testing, strictness, or comment rules.

  2. 02

    Save it at .windsurf/rules/project.md

    Save it at `.windsurf/rules/project.md` in the Flutter repo. If the project still uses a single root file, save the same body as `.windsurfrules`.

  3. 03

    Start a fresh agent session

    Rules files are read when a session starts. A chat that is already open may still be using the old instructions.

  4. 04

    Give it one small task

    Ask for one change a Flutter agent often gets wrong, such as a widget test that finds a labeled control and taps it. If it ignores the file, confirm the path and start a new session.

Questions about this file

Where do I put Windsurf rules in a Flutter repo?

Save it at `.windsurf/rules/project.md` in the Flutter repo. If the project still uses a single root file, save the same body as `.windsurfrules`.

Which tools read this Windsurf rules?

Windsurf reads `.windsurf/rules/*.md` and, on older projects, `.windsurfrules`. Cursor and Claude Code do not load this path.

What does the Flutter example assume?

The example assumes Flutter with Dart. It does not assume Riverpod, Bloc, or a particular router. Use the state library already in pubspec.yaml.

Does VibeSpell upload my repository?

No. Recipe pages are static, and the generator builds the file in your browser from the options you pick. Your source code never leaves the machine.

Other files for Flutter

Windsurf rules for other stacks