flow-ui-driver-instructions

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- flow-instructions-sentinel: flow-ui-driver-instructions -->

# UI-driver instructions

These instructions are read by the UI-driver subagent that `/flow-verify`'s
SKILL.md (or `/flow-pr-review` Step 8c.iii) spawns via the Task tool. The
subagent runs in an isolated context — its MCP tool calls, launch subprocess
output, and captures assembly stay inside its own session and are never
returned to the caller. The only outputs it produces are the side effects on
the worktree (the committed manifest self-improvements, the captures JSON)
and the structured artifact it writes to disk
(`.flow-tmp/ui-driver-result.json`), plus a brief one-paragraph summary it
returns on completion.

The drive procedure itself — probe, launch, per-route/per-viewport MCP
sequence, noise filter, self-improving manifest persist-back, teardown — is
the shared body already documented in
[`../flow-pipeline/references/ui-smoke-pass.md`](../flow-pipeline/references/ui-smoke-pass.md).
This file does not reproduce that procedure; it cites it by relative path so
the two cannot drift, and adds only what is specific to running that
procedure INSIDE a spawned, isolated sub-agent rather than inline in the
calling skill's own context: the spawn-prompt inputs, the artifact contract,
and the two responsibilities the caller does not do for you (the
`evidence_paths[] → ui_screenshots[]` mapping, and the `fix_context[]`
assembly).

## Inputs

The wrapper passes you these inputs in its spawn prompt:

- `ENVELOPE_PATH` — the absolute path to the `flow-ui-validate` verdict
  envelope the caller already resolved (a `ran:true` ready or bootstrap
  envelope; the caller does the probe → bootstrap-inference step before ever
  spawning you, so you only ever receive a drivable envelope).
- `MANIFEST_PATH` — the absolute path to `.flow/ui-validation.json`.
- `WORKTREE` — the absolute worktree path (your working directory).
- `SLUG` — the pipeline slug, resolved by the caller from `FLOW_SLUG` /
  `~/.flow/state/<slug>.json` / the worktree basename (env-only chain — see
  "Never read tmux pane state" below).
- `ARTIFACT_PATH` — the absolute path to write the result artifact
  (`.flow-tmp/ui-driver-result.json` under the worktree).
- `CAPTURES_PATH` — the absolute path to write the per-route/per-viewport
  captures JSON (`.flow-tmp/ui-captures.json` under the worktree).
- `MODE` — optional. Absent for the `/flow-verify` default drive (drive the
  full manifest route set). Set to the literal `items` by the
  `/flow-pr-review` 8c.iii caller (the older literal `visual-appearance` is
  still accepted as an alias and means the same thing), always paired with a
  checklist item list in the same spawn prompt where each item is tagged
  `appearance`, `behavior` or `capture`: drive only the routes needed to cover
  those items, apply `ui-smoke-pass.md`'s per-viewport `## UI traits to
verify` rubric, follow its `## Item-driven drive` section for the per-kind
  procedure and bounds, set each `fix_context[]` entry's optional `item` field
  to the checklist item it maps evidence back to, and write one
  `item_results[]` entry per item (see step 4 below). An untagged item under
  the alias is `appearance`.
- `SECTIONS` — optional: the literal `on`, passed when verify's pre-drive
  `flow-ui-critique gate` returned `run:true`. After an `ok:true` ASSEMBLE,
  and before teardown, follow `ui-smoke-pass.md`'s `## Section capture
(critique loop)` and record `section_shots[]` / `route_snapshots[]`.
  Absent means no section capture, at no cost. `MODE: sections` is the loop's
  one re-drive: the full drive plus that capture regardless of ASSEMBLE's
  outcome (`CALLER` stays `verify`). You capture; you never judge.
- `CALLER` — optional: `review-8c` from the `/flow-pr-review` 8c.iii caller;
  absent means `verify` (the `/flow-verify` smoke pass). Stamped into the
  artifact as `caller` so the merge gate can tell the two writers of the same
  path apart.
- `PREFLIGHT` — optional: the `flow-ui-preflight` envelope the caller already
  ran. When it says `ready: false`, do not launch anything: write the artifact
  with `ran: false`, `ok: false`, `skipped_reason: "dependency-unready"`.
- `SKILL_DIR` — the absolute skill base directory. Resolve
  `../flow-pipeline/references/ui-smoke-pass.md` relative to this path, not
  the worktree you `cd`'d into.

## 1. Load context

- Read the envelope at `ENVELOPE_PATH` for `meta.launch`, `meta.env`,
  `meta.baseUrl`, `meta.port`/`meta.ports`, `routes[]`, `loginUrl`,
  `credentialEnvVars`, and `meta.viewports`.
- Read `../flow-pipeline/references/ui-smoke-pass.md` end to end before
  driving anything — "Launch and drive", "Design-fidelity sub-pass",
  "Teardown", "Fix-loop routing", "Noise filter", and "Self-improving
  manifest" are all load-bearing, not optional background.

## 2. Drive

Follow `ui-smoke-pass.md`'s "Probe and skip (and bootstrap)" and "Launch and
drive" sections verbatim — that shared file carries the canonical
per-route/per-viewport drive-MCP call sequence (issue #318 de-duplicated it
into one shared reference; do not re-copy it here). In short: bring the
launch up with one standalone call, `flow-spawn --detach --class default
--stdout <WORKTREE>/.flow-tmp/ui-launch.out --stderr
<WORKTREE>/.flow-tmp/ui-launch.err --slug <SLUG> --cwd <WORKTREE>
--from-envelope <ENVELOPE_PATH>`, every placeholder written as a literal
absolute path or the slug (the helper reads `meta.launch`/`meta.env` from the
verdict file and applies `meta.env` to the launch process only — never a
`.env.local`/`.env`/config file); the literal stderr
`flow-spawn: unknown flag: --cwd` or `unknown flag: --from-envelope` (an older
install) means `skipped_reason: "app-launch-failed"` with "flow-spawn too old —
run flow install --upgrade" in the summary; any other `flow-spawn:
--from-envelope: …` refusal (e.g. no meta object, an unresolved `{{PORT}}`)
means `app-launch-failed` quoting that message as the cause — never another
launch form, and always put the cause in the summary (the supervisor relays it
as the skip reason). Then open a per-pipeline isolated page keyed on `SLUG`, run the Login step when the
manifest declares a login wall — credential presence is checked with
`flow-ui-login check` (names only), and the seeded local test account's
values come from `flow-ui-login test-account` — then drive each
route × each declared viewport per `ui-smoke-pass.md`'s "Launch and drive"
section.

Login recipe (a manifest with a login wall):

1. Run `flow-ui-login test-account --manifest <abs>/.flow/ui-validation.json
--worktree <abs>` as its own standalone foreground Bash call (absolute
   paths, no pipe, no redirect, no env-var prefix, no `cd … &&`, no
   background). It reads only the committed, unmodified
   `.flow/ui-validation.json`, so a bootstrap must commit the manifest before
   logging in (exit 2 `manifest-not-committed` / `manifest-not-in-worktree`
   otherwise). Exit 3 means the account is missing: record
   `credentials-unavailable`. Exit 2 with `non-local-base-url` means the

From gavingolden/flow, MIT.

More from gavingolden/flow