dart-edit-protocol

Files (1)

• SKILL.md

SKILL.md (first lines)

## Dart edit protocol

Nothing is "done" until the loop below completes clean — analyzer silent, tests green — or you have explicitly given up and surfaced why (e.g. a failure you cannot attribute to your own change).

### Tool preference: the Dart SDK MCP server first

**When the Dart SDK MCP server (`dart mcp-server`, exposed as the `dart` MCP server) is available in your session, use its tools for every step of the loop instead of the equivalent shell commands.** Check for it before your first Dart command; do not default to Bash out of habit.

| Step | Dart MCP tool | CLI fallback |
|---|---|---|
| fix | `analyze_files` with `applyFixes: true` | `dart fix --apply` (`puro dart fix --apply`) |
| format | none | `dart format <files>` |
| analyze | `analyze_files` | `dart analyze` |
| tests | none | `dart test -r failures-only` (`flutter test`) |
| dependencies | `pub` | `dart pub` / `flutter pub` |

Format and tests have no MCP tool, so the CLI is expected for those two steps. Fall back to the CLI for any step when the server is not connected in this session or its tool fails. In that case say so in your report ("Dart MCP unavailable, used CLI") so the reader knows which tooling produced the result. The full tool list and how to use each is in `skills/dart-mcp/SKILL.md`.

### Setup (once per session, before the first Dart MCP call)

The Dart MCP server's analysis and pub tools act on registered roots; with none registered they have nothing to work on. Register the workspace root first with the `roots` tool (`command: "add"`, `uris: ["file:///..."]`).

### The loop

```
1. dart fix --apply                (MCP: dart_fix)
2. dart format <files you edited>  (MCP: dart_format — edited files only, never the whole tree)
3. dart analyze                    (MCP: analyze_files)
   → new diagnostics appeared?     go back to step 1
4. diagnostics remain that
   `dart fix` can't resolve?       fix them manually, then go back to step 1
5. run the test suite
   → a failure requires an edit?   make the edit, then restart from step 1
```

- Read **every** diagnostic, including warnings and infos. "No errors" is not the bar; resolve the underlying issue unless the user has opted out of that lint. Do not silence with `// ignore:` to get to green unless the ignore is genuinely correct and you say why.
- **Async rule, checked by hand when no lint covers it:** functions returning a `Future` are `async` and their futures are `await`ed (including `return await foo();`, for a complete error stack and so errors reach an enclosing `try`/`catch`; also `=> await foo()` in `async` arrow bodies, which `async_return_with_no_await` doesn't cover), unless explicitly `unawaited(...)` or carrying an `// ignore:` for the specific diagnostic (`unawaited_futures`, `discarded_futures`). The narrow exception is returning a `Future.value(...)` / `Future.syncValue(...)` call directly (not `Future.sync`). Never remove a `return await` just to satisfy the deprecated `unnecessary_await_in_return`; flag the conflict instead. If the project doesn't enable those lints, scan your own edits for violations before step 3. Details in `review-flutter-async-and-disposal` (section A).
- Step 5 runs the full suite, not just your file. Prefer failures-only output (`dart test -r failures-only`) to keep it readable and you should mostly not need tail.
- Restart the loop from step 1 after *any* edit made to resolve a diagnostic or a failure; each edit can create new ones.

### Adding dependencies

When several packages are needed, add them in **one** `pub add` call (mix runtime and dev with the `dev:` prefix, e.g. `dart pub add dio dev:build_runner`), so pub solves them together. Never one call per package.

### Role-specific expectations

- **`tester`**: production code does not exist yet, so this step's new tests are *expected* to fail at step 5. Loop only for tooling problems in the test file (format, analyzer diagnostics), and confirm the failure is the expected `UnimplementedError`/missing-symbol one.
- **`api doc writer`**: you only touch doc comments and stubs, so it is a fast pass — still not optional.
- **`implementer` / `scope arbiter` handoffs**: report "tests pass" only after the loop finished clean; otherwise report the exact remaining diagnostic or failure.

### Visual changes: check the live app yourself

Whenever you need to know whether a UI change looks right or whether something else changed visually, do not ask the user to check it. Connect to a running app and check it yourself:

1. Get a DTD URI and connect the Dart SDK MCP server to the running app (see `find-dtd-uri`; ask the user only if no DTD is available).
2. Use `widget_inspector` to find the widget, then `flutter_driver_command` with `command: "screenshot"` to capture it. Use `get_diagnostics_tree` or `get_text` when the screenshot alone is not enough.
3. Compare the screenshot with what the request asked for and report what you saw, with the screenshot.

For a full before/after comparison (baseline via stash, regression and visual-bug checklist), follow `review-flutter-visual-changes` or hand it to `flutter visual reviewer`.

If the change must not alter the UI, also add or keep a golden test (see `write-flutter-ui-tests`) so the next change that does alter it fails loudly.

### The epistemic rule (binds every reviewing agent, not just editors)

**Never assert code is incorrect unless `dart analyze` agrees.** You may flag style, smells, missed simplifications, weak tests and scope concerns on your own judgment — that is your job. But you may not claim something is *wrong* (a bug, invalid, broken) on your own authority when the analyzer, which actually has that authority, is silent or has not been run against the claim. If you believe something is genuinely incorrect and the analyzer does not catch it, say so as a **hypothesis to verify**, not a finding, and state why the analyzer would not catch it (a runtime-only issue, a logic error outside its diagnostic scope) instead of overriding it by assertion.

From FMorschel/agents, MIT.

More from FMorschel/agents