docs(app): Flutter fix, design and preview pipeline definitions

This commit is contained in:
2026-10-23 13:20:09 +01:00
parent f38689b7bd
commit 80f4692ec6
4 changed files with 510 additions and 0 deletions
+31
View File
@@ -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/<file>.md` then
`pipelines submit pipelines/<file>.md --name "<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/<slug> tmp/flutter-<slug> main`
and `flutter pub get` in its `app/`.
2. `pipelines run "Flutter fix" --workspace tmp/flutter-<slug>/app --prompt "<one behaviour, with what you already know>"`.
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.
+208
View File
@@ -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 <public>/before <routes…>` (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 <public>/before /`.
<public> is this run's shared public/ directory (absolute path). Each route yields <route>-390.png and <route>-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 <public>/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
```
+194
View File
@@ -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 <file> 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/<area>) 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/<run>.patch && git checkout -- lib`, run the test and see it fail, then restore with `git apply /tmp/<run>.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
```
+77
View File
@@ -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 <name>` where <name> 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 <public>/smoke /runs /runs/1 /chat /settings` (<public> 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
```