run-flow

name	run-flow
description	Run a single named flow by name. Faster than /swift-assist:test when you're debugging one broken screen and don't want to wait for the full suite.
argument-hint	<flow-name> [--approve] [--json]

Swift Assist: Flow

Run a single named flow from grantiva.yml by name - capture its screenshot, compare against the baseline, and report pass or fail. Use this when you're iterating on one screen and don't want to run the entire test suite.

Usage

/swift-assist:run-flow login
/swift-assist:run-flow landmark-detail
/swift-assist:run-flow checkout --approve
/swift-assist:run-flow settings --json

Command Options

• <flow-name>: Name of the screen to test (required). Must match a name: entry in grantiva.yml
• --approve: Immediately approve the captured screenshot as the new baseline if the run succeeds
• --json: Output result as JSON

Difference from /swift-assist:test

/swift-assist:test runs all flows sequentially - useful for a full suite check, but slow when you're fixing one thing. /swift-assist:run-flow runs exactly one screen and reports immediately, making it fast to iterate on a failing screen without waiting for the other 11 to finish.

Prerequisites

1. App must be running in the simulator
2. Grantiva runner must be active (grantiva runner start)
3. grantiva.yml must have a screens: section with at least one entry
4. A baseline must exist for the named screen (unless using --approve to set one)

What This Command Does

Phase 1: Resolve the Flow Name

Read grantiva.yml to find all defined screens:

cat grantiva.yml

Match the provided <flow-name> against the name: fields in the screens: section. Matching is case-insensitive and tolerates hyphens vs. spaces (e.g., landmark-detail matches Landmark Detail).

If no match is found, list available screen names and stop:

No screen named "landmrk-detail" found in grantiva.yml.

Available screens:
  landmarks
  landmark-detail
  favorites
  settings
  edit-landmark
  caching-demo

Did you mean: landmark-detail?

If the input is ambiguous (partial match on multiple names), list the candidates and ask the user to be more specific.

Phase 2: Capture the Screen

Run Grantiva's capture pipeline targeting only the matched screen. Use the screen's name field as reported in grantiva.yml:

grantiva diff capture --screen "<SCREEN_NAME>" --scheme=<SCHEME> --simulator="<SIMULATOR>" --no-build

The --no-build flag assumes the app is already running. Grantiva will navigate the path defined for that screen (the path: steps in grantiva.yml) and take a screenshot at the end.

While the capture runs, use computer use to watch the simulator and verify the navigation succeeds.

If the capture fails (navigation error, element not found, app crash), report the failure immediately with the full error and stop:

Capture failed: element "login-button-continue" not found

The navigator could not complete the path for screen "login":
  tap: login-textfield-email       -> OK
  type: "[e-mail]"         -> OK
  tap: login-button-continue       -> FAILED (element not found)

Check that:
  1. The app is on the expected starting screen (try relaunching)
  2. The accessibility identifier "login-button-continue" is applied to the button
  3. Run /swift-assist:doctor to audit current identifiers

Phase 3: Compare Against Baseline

If --approve was NOT specified, run the comparison:

grantiva diff compare --screen "<SCREEN_NAME>"

This compares the newly captured screenshot against the stored baseline in .grantiva/baselines/.

If no baseline exists for this screen, stop and prompt:

No baseline found for "login".

Run with --approve to capture and set a baseline:
  /swift-assist:run-flow login --approve

Or run /swift-assist:vrt --baseline to set baselines for all screens.

Phase 4: Visual Review with Computer Use

If a diff was detected, use computer use to view both images side by side and describe what changed:

1. Open the baseline: .grantiva/baselines/<screen-name>.png
2. Open the capture: .grantiva/captures/<screen-name>.png
3. Note specific visual differences (layout shifts, color changes, missing elements, new elements)

Phase 5: Report Result

Pass:

Flow: login
Result: PASS

  Diff: 0.3% (threshold: 2%)
  Screenshot: .grantiva/captures/login.png
  Duration: 8s

Fail:

Flow: login
Result: FAIL

  Diff: 12.4% (threshold: 2%)
  Screenshot: .grantiva/captures/login.png
  Baseline:   .grantiva/baselines/login.png
  Duration: 9s

Visual differences detected:
  - "Sign in" button moved down 18px
  - Email field placeholder text changed from "Email" to "Email address"

To approve this as the new baseline:
  /swift-assist:run-flow login --approve

To investigate what changed in source:
  git diff HEAD -- <path-to-login-view-file>

Phase 6: Optional Auto-Approve

If --approve was specified and the capture succeeded, approve immediately:

grantiva diff approve --screen "<SCREEN_NAME>"

Confirm:

Flow: login
Result: APPROVED

  New baseline saved to .grantiva/baselines/login.png
  Commit this file to update the CI baseline:
    git add .grantiva/baselines/login.png
    git commit -m "Approve login baseline"

Important Rules

1. NEVER auto-approve without the --approve flag - always require explicit intent
2. Use --no-build unless the user explicitly requests a rebuild (which is slow)
3. If the flow name has a close match but not an exact match, suggest the closest one - do not silently use the wrong screen
4. Report the diff percentage and threshold so the user knows how close to the limit they are
5. If the app is not running or the runner is disconnected, stop and tell the user to run /swift-assist:init or /swift-assist:build
6. Prefer /swift-assist:test in your output suggestions when the user needs to run the full suite