Files
pipelines/app/AGENTS.md
T
alan e0e8ca68f3 Make the app Material-only in the rules
The app builds one Material UI for every platform. Cupertino code, tests and
captures are being removed, so the agreement, the capture recipe and the
floating-windows plan no longer ask for them.
2026-11-10 20:10:02 +00:00

8.1 KiB

Flutter client — working agreement

Scope and acceptance

  • Only change source files under app/. The Go server, web proxy (web/) and installation scripts are read-only. User-requested web/server deployment and APK publication are allowed through the installer after checking quiescence and preserving a rollback. Never restart shared services merely for client tests or manipulate real operator chats/runs for testing.
  • This Flutter app is the only client: it replaced the former JavaScript web client and the Kotlin Android app.
  • No backend changes; report missing capabilities.
  • One Material UI on every platform: standard Material controls, including buttons/menus in custom graphs/diffs/chat. No Cupertino widgets, cupertino flags, Cupertino tests or Cupertino captures; remove Cupertino branches you touch rather than extend them. System typography, theme colors, light/dark, content-driven layout and text scaling. No fixed row/bubble/button dimensions, bespoke palette or CSS token port. Centralize necessary layout constraints; do not ban legitimate native default spacing or graph coordinates.
  • Develop and test on web by default; user-requested Android release APK builds and publication are allowed. When the user authorizes device installation or testing, perform it directly on the named device; no pipeline stage or resource lease is required. Keep source portable to all three targets. Distinguish APK build/publication from on-device verification; report mobile behavior as unverified when no device test ran.
  • 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.
  • The manager drives authorized routine integration and recovery without repeatedly stopping for permission. Feature implementation stays in pipelines where appropriate; infrastructure blockers can be resolved directly within the user's authorized scope. Verify quiescence, preserve data and rollback, act, and report actual results. Ask only for genuinely new scope or unresolved destructive choices.

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/<item>.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. Run tests only through the memory watchdog, from app/: tool/memwatch/full.sh test (or a focused tool/memwatch/full.sh test/<area> while editing). Never run a bare flutter test, because a runaway test has crashed the Mac. Off a terminal it is quiet: one verdict line (counts, peak MB, duration, exit), only failing tests with bounded errors, and the full log path; read that log with grep or a line range rather than whole, or set MEMWATCH_OUTPUT=full. tool/memwatch/quiet_test.sh checks this output. tool/memwatch/install.sh restores the legacy /tmp/memwatch shims. Use tool/analyze.sh (bounded 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. UI capture and review: use tool/capture/ (see its README). It is one generic Chrome DevTools kit over the full-app fixture tool/search_selection_probe_entry.dart. It opens any route at a given size, platform and theme, clicks by semantics label, identifier or point, types text, takes screenshots and films transitions. If a feature's legacy tool/*_probe.mjs driver is stale (missing labels, outdated status text), capture with this kit; a stale driver is not a reason to report blocked. Inspect every PNG you cite. Keep commits referenced; do not discard unrelated work or delete branches. Deploy only when requested by the user; preserve existing public URLs unless a cutover is part of that request. Land candidates per selected pipeline; manager verifies actual ancestry and records source, checks, landing and deployment separately.

Device testing

The ADB executable is /Users/alan/Library/Android/sdk/platform-tools/adb. Use that absolute path (or explicitly add its directory to PATH); adb: command not found alone is not evidence that the leased device is disconnected.

For populated attention review, TestExportReadyAttentionReviewFixture exports a create-only scratch database when PIPELINES_ATTENTION_REVIEW_DIR names a new directory. Its fixture.json identifies one failed, one finished and one waiting run and the workspace. Build a scratch server, read back those states, and keep the owned server alive through all UI interactions. The export itself does not leave a server running or configure a device. Never use a dead scratch endpoint.

The manager may install, interact, capture and profile directly when authorized by the user. Check for active shared work first, use an explicit adb -s serial, preserve app data, and record and restore any device settings changed for testing. Do not require a runner lease or a particular pipeline role.

Known test devices are:

  • phone-47241FDAS00DLK — the operator's Pixel 9 Pro XL, adb serial 47241FDAS00DLK (metadata kind=phone).
  • emulator-Pipelines_Fold_A — one managed foldable emulator, adb serial emulator-5554 (metadata kind=emulator, avd=Pipelines_Fold_A). Its unfolded built-in display is 2076x2152; its cover display is 1080x2424.

The operator's Pixel 10 Pro Fold (58281FDCG000JF) is delivery-only: never a test target. Do not start an ad-hoc emulator — the one managed foldable AVD above is the only emulator in scope.

The UI reviewer records original app connection/workspace, display size and power/settings before changing them. Before any capture: svc power stayon usb, settings put global stay_on_while_plugged_in 7, input keyevent KEYCODE_WAKEUP, wm dismiss-keyguard. Capture with adb -s <serial> shell screencap -p /sdcard/shot.png then adb pull — never exec-out > file. Wide layout: wm size 2000x2244; the fold's unfolded shape is wm size 2076x2152; wm size reset afterwards either way.

Create controlled fixtures for changed screens/states (including human-decision sheets) on a scratch server/database and throwaway session; never depend on incidental production state, change a real operator session, or restart a deployed service. Use the configured authoritative endpoint, never a scratch URL as a project default. Keep all shell/ADB work foreground and awaited: do not leave test processes running after testing. Restore the captured original settings after testing. Leave the user-requested build installed unless they request otherwise. Confirm every test tool has exited. If capture, restoration or cleanup fails, report the failure explicitly; do not claim verification or readiness.