Argent Create Flow

Create an Argent flow

An Argent flow is a replayable sequence in .argent/flows/<name>.yaml. (In this repo, flow files live ONLY at _ai/task/{SLUG}/reproduction/flows/<safe-name>.yaml — the parent skill's flow-storage override governs; pass the file path to argent flow run, never a bare name. The recorder tools described in this skill are unavailable under this storage contract — see "Authoring under the repo flow policy" at the end.)

For a saved QA test case, ticket, or acceptance criterion, load argent-qa-flows first. It adds deterministic setup, acceptance evidence, and two-pass proof.

Read the relevant reference

• Before creating or changing a flow, read Live authoring completely.
• When polishing, composing, or manually reviewing YAML, read Flow YAML. For Vega, read its platform limits before recording remote or keyboard tools.
• Flows run on physical iPhones (an iOS list-devices entry with kind "device"), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as device (CLI --device), and only a connected phone can run. pinch/rotate steps fail there like the live tools. On hardware the flow tree is the describe tree: same ids and roles, no UIView hierarchy. See argent-ios-device-interact for the hardware contract.
• On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read Reliability and recovery.

Non-negotiable rules

1. Record the first walkthrough. Start the recorder before the first launch or in-app action. Do not reconstruct a rehearsed path.
2. Record checks when their states appear. Record await-ui-element live, then convert it during polish. An echo records intent or diagnostic context, not app behavior or a verdict. A screenshot is human evidence, not an executable verdict. For absence, record the same selector as visible, perform the removing action, then record it as hidden.
3. Use semantic targets. Prefer a strict id, then stable text or an accessibility label. Use scroll-to for off-screen elements. Resolve every raw-point warning immediately through the coordinate fallback gate.
4. Prove every screen change. Record a destination-only identity check. During polish, follow it with await: { idle: true }. Stillness does not prove identity, and idle can pass with a warning.
5. Polish only executed behavior. Convert recorded steps without changing their meaning. Record any missing action or structural check live. The only unrecorded insertions are a planned snapshot:, a navigation await: { idle: true }, and the documented Chromium packaging launch:.
6. Replay the final YAML end to end. A normal flow needs one uninterrupted full pass. argent-qa-flows requires two consecutive passes.

Stable selectors

A stable selector is fixed by app code and survives account, data, time, count, order, and every locale and environment the flow supports. Prefer ids such as settings-screen. Do not gate on values such as Today, Item 4, usernames, counters, or timestamps.

Flow-only selector scopes

During polish, use within, after, and next to disambiguate repeated elements. Read Flow YAML: Relational scopes for their frame-based semantics and failure cases.

Workflow

1. Choose the flow type:
   • e2e: the first non-echo step is launch:. The flow controls process start.
   • fragment: there is no leading launch. Declare a precise executionPrerequisite.
2. Follow Live authoring: start, record one verified step at a time, finish, polish, audit, and replay.
3. Report the file, replay command, result, prerequisite or side effects, and every coordinate or raw-gesture exception.

Proactive recording

Before repeating three or more interactions, tell the user and start a recording. Record that run and replay it afterward. A completed path cannot be recorded retroactively.

Repair

When replay fails, follow Reliability and recovery. Inspect the first divergence, correct the smallest justified unit, audit, and replay the full flow. Stop after two unsuccessful correction cycles. Never weaken a requested check to obtain a pass.

Authoring under the repo flow policy (bundle adaptation)

The recorder tool trio (flow-start-recording / flow-add-step / flow-finish-recording, with flow-add-echo) is keyed by name + absolute project_root and always writes its take to <project_root>/.argent/flows/<name>.yaml — no flag exists to redirect it, and no temporary .argent/flows directory may be created as a workaround. This repo requires flow YAML to live ONLY at _ai/task/{SLUG}/reproduction/flows/<safe-name>.yaml, so the recorder is unavailable under this storage contract. Author and edit the YAML directly with your file tools at the repo path, following the schema, directives, selectors, and audit rules in Flow YAML and the walkthrough discipline in Live authoring (execute each step live as you build it, per that reference's guidance, instead of the recorder capturing it). argent flow run <path.yaml> needs no .argent/flows directory. Do not invent recorder flags, and never write .argent/ anywhere in this repo.

The live-authoring reference's .argent/flows wording describes upstream defaults; read it for recorder mechanics and replay-repair rules, and apply the path override above.