# Flutter client — working agreement ## Scope and acceptance - Only change files under `app/`. The Go server, `web/`, existing `android/`, installation and deployment are read-only. Never restart shared services or manipulate real operator chats/runs for testing. - Copy current web behavior, request shapes and words, NOT CSS or layout styling. Read `../web/src/` and `../web/PARITY.md` as references. No backend changes; report missing capabilities. - Standard Material and Cupertino controls, including buttons/menus in custom graphs/diffs/chat. System typography, theme colors, light/dark, content-driven layout and text scaling. No fixed row/bubble/button dimensions, bespoke palette or CSS token port. Platform differences are intentional. Centralize necessary layout constraints; do not ban legitimate native default spacing or graph coordinates. - Develop and test ONLY web now. No ADB, emulators, device changes, Android/iOS builds or installs. Keep source portable to all three targets. Explicitly report mobile as unverified. - Small cohesive files (aim below 250 lines; split by responsibility, not arbitrary fragments). Each task owns a directory and its tests. Do not edit another lane or root pubspec/main unless assigned. - Code quality is a delivery requirement. No minified implementations, silent capability fallbacks, fake data masking missing features, or workarounds that bypass the real defect. A pipeline success does not waive missing behavior, native controls, regression coverage or rendered evidence. Label incomplete work honestly and complete it before claiming parity. ## Shared contract - `lib/core/api_gateway.dart`: `JsonMap` alias; `ApiGateway.call(type, [fields])` yields the entire decoded reply envelope; `frames` yields unsolicited server envelopes. Gateway owns request IDs. Do not put domain interpretation in transport. - Feature directories: `lib/features/{pipelines,runs,chat,schedules,search,artifacts,settings,templates}/`. Pure domain logic has no widget imports. Feature screens receive an `ApiGateway`; do not open their own sockets. - `lib/ui/adaptive/` owns platform primitives; `lib/shell/` owns navigation and composition. Manager integrates feature registration. Feature lanes may supply `screen.dart` but do not edit shell/main. - Use existing dependencies. Only the assigned foundation lane or manager edits pubspec/lock. - Tests mirror directories under `test/`; tests use local fixtures/fake gateways, never mutate production. Put item evidence in `notes/.md`, not shared queue. ## Tools and verification Flutter: `/Users/alan/development/flutter/bin/flutter`; Dart beside it. Run pub get per worktree; never upgrade shared SDK. Focused `flutter test test/` while editing, `flutter analyze` and `flutter build web` for integrated acceptance. No Go/legacy client checks needed for app-only changes. Rendered changes require real browser interaction/captures; widget tests alone are not browser evidence. Use isolated loopback servers and OS-assigned ports. Browser automation may use Chrome DevTools, with independent scripts under `app/tool/`; do not modify legacy browser drivers. Never disable authentication on exposed services. Keep commits referenced; do not discard unrelated work or delete branches. No deployment/canonical URL cutover. Land candidates per selected pipeline; manager verifies actual ancestry and serves a separate preview.