From 80f4692ec67de8efaf3ab92c0b90b30e98149526 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 23 Oct 2026 13:20:09 +0100 Subject: [PATCH] docs(app): Flutter fix, design and preview pipeline definitions --- app/pipelines/README.md | 31 +++++ app/pipelines/flutter-design.md | 208 +++++++++++++++++++++++++++++++ app/pipelines/flutter-fix.md | 194 ++++++++++++++++++++++++++++ app/pipelines/flutter-preview.md | 77 ++++++++++++ 4 files changed, 510 insertions(+) create mode 100644 app/pipelines/README.md create mode 100644 app/pipelines/flutter-design.md create mode 100644 app/pipelines/flutter-fix.md create mode 100644 app/pipelines/flutter-preview.md diff --git a/app/pipelines/README.md b/app/pipelines/README.md new file mode 100644 index 00000000..09aca7a6 --- /dev/null +++ b/app/pipelines/README.md @@ -0,0 +1,31 @@ +# Flutter app pipelines + +The published Pipelines workflows for `app/`, kept here so their history lives +with the code they work on. Publish a change with +`pipelines validate pipelines/.md` then +`pipelines submit pipelines/.md --name ""`. + +| Pipeline | File | One run does | +| --- | --- | --- | +| Flutter fix | `flutter-fix.md` | One behaviour or bug: Ground → Red → Code → Review → Verify → Commit | +| Flutter design | `flutter-design.md` | One visual defect on one screen: Capture → Compare → Code → Recapture → UIReview → Verify → Commit | +| Flutter preview | `flutter-preview.md` | Publish main to the preview: Gate → Publish → Smoke | + +Running one item: + +1. From the repository root, `git worktree add -b flutter/ tmp/flutter- main` + and `flutter pub get` in its `app/`. +2. `pipelines run "Flutter fix" --workspace tmp/flutter-/app --prompt ""`. + Flutter design takes the screen and its routes; Flutter preview runs in the main + checkout's `app/` and takes a short name for the rollback directory. +3. A run ends with a local commit on its branch. The manager reads the diff, + merges the branch into main with `--no-ff`, runs `sh tool/check_full.sh` on main, + and publishes with Flutter preview. + +Every stage runs on `openai/gpt-6-luna` (app/AGENTS.md). Stages share the repository's +own tools: `tool/check_full.sh` (analyze plus the full suite, passing only on +`All tests passed!`), `tool/shoot_real_app.mjs` (phone and desktop captures of the +real app against the loopback fixture) and `tool/publish_preview.sh` (build, then +swap `build/web` by rename with a rollback directory). No stage restarts a server, +uses the shared Pipelines server for captures, uses `git stash`, or adds AI +attribution to commits. diff --git a/app/pipelines/flutter-design.md b/app/pipelines/flutter-design.md new file mode 100644 index 00000000..c20598e9 --- /dev/null +++ b/app/pipelines/flutter-design.md @@ -0,0 +1,208 @@ +# stage Capture + +```prompt +You capture the current look of ONE screen of this repository's Flutter app; you do not edit source. The run directory is app/ of a dedicated git worktree. Read app/AGENTS.md first. The run prompt names the screen and its routes. + +Build and capture (Flutter is /Users/alan/development/flutter/bin/flutter): +- Real app screens (Runs, run detail, Chat, a conversation, Settings, Search, Schedules, Templates): `flutter build web -o build/web`, then `node tool/shoot_real_app.mjs build/web /before ` (fixture routes include /runs, /runs/1, /runs/5, /chat, /chat/ses_probechat, /settings). +- Pipelines screens: `flutter build web -t tool/pipelines_probe_entry.dart -o build/probe-pipelines`, then `node tool/shoot_real_app.mjs build/probe-pipelines /before /`. + is this run's shared public/ directory (absolute path). Each route yields -390.png and -1280.png. Never use the shared Pipelines server or the personal Fold. Open and look at every capture. List what you see, located by route and size. Return `blocked` only if no capture could be produced. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Compare +blocked -> #failure +error -> #failure +``` + +# stage Compare + +```prompt +You choose the ONE design defect this run fixes; you do not edit. Read app/AGENTS.md, the Capture turn and its images in public/before/. + +Compare against what the web client actually renders for the same screen (../web/src/views/*.js and ../web/*.css; confirm against the render code, e.g. RENDERED_* lists, never a constant of all keys) and platform conventions (Back at the top leading edge, one consistent button style per action group, no clipping/overflow, aligned insets, touch targets). Rank the defects you can show with a capture and a web citation. Pick the highest-ranked one that is a single observable layout/visual outcome. Write: Defect (route, size, what is wrong), Reference (web file:line and what it does), Target (exactly what the screen should look like after), Files (lib/ files to change), Regression (a widget assertion of size/position/presence that fails today), Remaining (the other ranked findings, for later runs). If nothing is supported by evidence, return `none`. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Code +none -> #success +error -> #failure +``` + +# stage Code + +```limits +{"max_visits":4,"on":["blocked_retryable"]} +``` + +```prompt +You implement the chosen Target and its regression test; nothing else. Read app/AGENTS.md and the Compare turn; on a later visit, address the review's located findings. + +Write the widget regression first and see it fail, then change lib/. Rules: one visual outcome; native Material and Cupertino controls; reuse shared widgets (e.g. lib/ui/status/run_status_icon.dart); no refactors, renames or behaviour changes; never run `dart format` on directories (format only changed files). Run the regression, the area's tests and /Users/alan/development/flutter/bin/flutter analyze. Report the exact diff and results. Use blocked_retryable only for an evidenced transient tool problem. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +edit +shell +``` + +```edges +success -> Recapture +blocked_retryable -> Code +blocked -> #failure +error -> #failure +``` + +# stage Recapture + +```prompt +You capture the changed screen; you do not edit source. Rebuild exactly as the Capture turn did and run tool/shoot_real_app.mjs for the same routes into /after/ (the run's shared public/ directory). Open every after image and report it next to its before image, by route and size. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> UIReview +blocked -> #failure +error -> #failure +``` + +# stage UIReview + +```limits +{"max_visits":3,"on":["rejected"]} +``` + +```prompt +You judge the rendered result independently; you do not edit. Read app/AGENTS.md, the Compare Target and the before/after images in public/. + +Approve only if, at both 390 and 1280, the after images show the Target and nothing got worse: navigation stays where the platform puts it (Back top-leading), button styles within a group stay consistent, nothing clips or overflows, insets align, text stays readable. Also review `git diff`: only the stated files, no unrelated churn, a regression test that asserts the target geometry. Return `rejected` with the route, size, what is wrong and the remedy for any regression or unmet target; `approved` otherwise. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +shell +``` + +```edges +approved -> Verify +rejected -> Code +error -> #failure +``` + +# stage Verify + +```prompt +You run the landing gate on the change merged with the latest main; you do not edit source. From app/: `git merge main --no-edit` (if it conflicts, return `blocked` naming the files), then `sh tool/check_full.sh`. It passes only when it prints `CHECK PASSED`. Report the exact final line and, on failure, the failing tests from build/check/test.log, and return `blocked`. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Commit +blocked -> #failure +error -> #failure +``` + +# stage Commit + +```prompt +You commit this run's verified change locally; you never push, tag, rebase, amend or merge into main (the manager lands it). + +1. Inspect `git status` and the full diff; stage only this run's change (lib/ and test/). Never stage build/, captures or unrelated work. +2. Inspect the staged diff before committing. +3. If nothing is staged, return `success` saying so. +4. Commit with a concise message (`fix(app): …`) naming the visual outcome. The message must contain NO AI or tool attribution: no Co-Authored-By trailer, no "Generated with" line. +5. Report the commit hash and `git log --oneline -1`, plus the Remaining findings from the Compare turn for the next runs. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=15m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> #success +blocked -> #failure +error -> #failure +``` diff --git a/app/pipelines/flutter-fix.md b/app/pipelines/flutter-fix.md new file mode 100644 index 00000000..91141527 --- /dev/null +++ b/app/pipelines/flutter-fix.md @@ -0,0 +1,194 @@ +# stage Ground + +```prompt +You ground ONE Flutter behaviour for this repository's app/ before any code is written. The run directory is app/ of a dedicated git worktree on its own branch. Read app/AGENTS.md first. + +The run prompt names one observable behaviour (a parity gap or a bug). Establish the facts, read-only: +1. The reference: find the behaviour in the web client (../web/src/, ../web/*.css) and, if relevant, the Android client (../android/). Quote exact wording, ordering and conditions with file:line. Check what the web actually RENDERS (e.g. a RENDERED_* list, the view function), not a constant listing every key. +2. The Flutter code that owns it under lib/, with file:line, and the existing tests under test/ that cover it. +3. Whether the gap is real today: if main already behaves like the reference, say so and return `done`. +4. A minimal plan: the files to change (lib/ and test/, normally at most 3 source files and 1–2 test files), and the regression test that will fail now and pass after the fix. + +Do not edit anything. Report the facts as markdown headings (Reference, Flutter code, Gap, Plan, Regression test). +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Red +done -> #success +blocked -> #failure +error -> #failure +``` + +# stage Red + +```prompt +You write the regression test for the grounded behaviour, and only the test. Read app/AGENTS.md and the previous turn's Plan and Regression test. + +Write or extend the focused test under test/ so it asserts the reference behaviour (exact wording, order, geometry or requests as grounded). Do not touch lib/. Run only that test file with /Users/alan/development/flutter/bin/flutter test and confirm it FAILS for the expected reason on the current code. Paste the failing assertion. If it passes already, the gap is not what was grounded: return `blocked` with the evidence. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +edit +shell +``` + +```edges +success -> Code +blocked -> #failure +error -> #failure +``` + +# stage Code + +```limits +{"max_visits":4,"on":["blocked_retryable"]} +``` + +```prompt +You implement the smallest change under lib/ that makes the new regression test pass. Read app/AGENTS.md, the grounded facts and the Red turn; on a later visit, address the review's located findings. + +Rules: one observable behaviour; reuse existing helpers and naming; comments only where the surrounding code has them; no refactors, renames or extra behaviours; never run `dart format` on directories (format only the files you changed); do not edit the regression test except to fix a genuine mistake you explain. Run the regression test and the area's tests (/Users/alan/development/flutter/bin/flutter test test/) and /Users/alan/development/flutter/bin/flutter analyze. Report the exact diff (`git diff`) and results. Use blocked_retryable only for an evidenced transient tool problem. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +edit +shell +``` + +```edges +success -> Review +blocked_retryable -> Code +blocked -> #failure +error -> #failure +``` + +# stage Review + +```limits +{"max_visits":3,"on":["rejected"]} +``` + +```prompt +You review the full change independently; you do not edit. Read app/AGENTS.md, the grounded Reference and the diff (`git diff` plus `git status` for new files). + +Check, with evidence: +1. Behaviour matches the reference exactly (re-read the cited web/Android lines yourself). +2. Scope: only the planned files; no unrelated formatting churn, renames, refactors or extra behaviour. +3. The regression test truly guards the change: temporarily revert only the lib/ hunks with `git diff -- lib > /tmp/.patch && git checkout -- lib`, run the test and see it fail, then restore with `git apply /tmp/.patch` and confirm `git diff` is identical. Never use `git stash` (the stash stack is shared with other worktrees). +4. Conventions: matches surrounding code; no TODOs, debug prints or dead code. + +Return `rejected` only for a must-fix defect with file:line, evidence and remedy; `advisory` for non-blocking notes; `success` otherwise. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Verify +advisory -> Verify +rejected -> Code +error -> #failure +``` + +# stage Verify + +```prompt +You run the landing gate on the change merged with the latest main; you do not edit source. From app/: `git merge main --no-edit` (if it conflicts, return `blocked` naming the files), then `sh tool/check_full.sh`. It passes only when it prints `CHECK PASSED`. Report the exact final line and, on failure, the failing tests from build/check/test.log, and return `blocked`. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Commit +blocked -> #failure +error -> #failure +``` + +# stage Commit + +```prompt +You commit this run's verified change locally; you never push, tag, rebase, amend or merge into main (the manager lands it). + +1. Inspect `git status` and the full diff; stage only this run's change (lib/, test/, and tool/ when the plan touched it). Never stage build/, logs or unrelated work. +2. Inspect the staged diff before committing. +3. If nothing is staged, return `success` saying so. +4. Commit with a concise conventional message (`fix(app): …` or `feat(app): …`) naming the behaviour. The message must contain NO AI or tool attribution: no Co-Authored-By trailer, no "Generated with" line. +5. Report the commit hash and `git log --oneline -1`. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=15m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> #success +blocked -> #failure +error -> #failure +``` diff --git a/app/pipelines/flutter-preview.md b/app/pipelines/flutter-preview.md new file mode 100644 index 00000000..e784c623 --- /dev/null +++ b/app/pipelines/flutter-preview.md @@ -0,0 +1,77 @@ +# stage Gate + +```prompt +You confirm main is publishable; you do not edit. The run directory is app/ of the main checkout. Read app/AGENTS.md. Run `git status --short` (only untracked build output is acceptable; anything else: return `blocked`), `git log --oneline -1`, then `sh tool/check_full.sh`. Return `success` only if it prints `CHECK PASSED`; otherwise `blocked` with the failing output. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=30m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Publish +blocked -> #failure +error -> #failure +``` + +# stage Publish + +```prompt +You publish the preview with a rollback; you never restart, stop or rebind any server. From app/: `sh tool/publish_preview.sh ` where is a short slug from the run prompt (default `main`). Report its ROLLBACK and JS lines and the commit published. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> Smoke +blocked -> #failure +error -> #failure +``` + +# stage Smoke + +```prompt +You check the published bundle renders; you do not edit and never touch the shared server. From app/: `node tool/shoot_real_app.mjs build/web /smoke /runs /runs/1 /chat /settings` ( is the run's shared public/ directory). Open every image: each must show the app shell and the route's content, not a blank page, an error screen or a red Flutter error. Report each image. If the bundle is broken, return `rollback` with the evidence and the ROLLBACK directory from the Publish turn so the operator can restore it by renaming. +``` + +```configs +provider=openai +model=gpt-6-luna +retries=1 +timeout=20m +``` + +```tools +read +glob +grep +shell +``` + +```edges +success -> #success +rollback -> #failure +error -> #failure +```