docs(skills): split argent-create-flow into references and add argent-qa-flows

[hubgan]

Stacked on #728, which now sits directly on #574 rather than on the #715-#726 chain.

Because of that, guidance describing behaviour owned by that chain is not carried here: the recorder's refusal of a vacuous hidden and of await-screen-idle (#724), its cross-tree re-probe warning (#717), the per-step recorded line (#715), and type: failing on unconfirmed focus (#726). Each of those paragraphs states what this base actually does instead. They are worth restoring to the references when that chain lands.

argent-create-flow: ~5,000 words to ~900 plus three references

Every word of that skill loaded on every invocation, whether the task was replaying a two-step fragment or authoring a full regression test. The core skill now routes to three references read on demand:

• live-authoring.md - recording a walkthrough
• flow-yaml.md - the file format and selector vocabulary
• reliability-and-recovery.md - what to do when a step or a replay goes wrong

Nothing is dropped in the split itself - it moves behind a router. (Separately, the claims listed above were rewritten to match this base.)

New skill: argent-qa-flows

Turning a test case, ticket, or acceptance criteria into a repeatable regression test is a different job from recording a path worth replaying, and it was being done by a skill that does not ask for acceptance criteria.

It orchestrates argent-create-flow as its engine, records the first walkthrough live, requires every requested screen and state to be proved with stable evidence, and completes only after the unchanged flow passes twice consecutively.

Proving a navigation

Spelled out here for the first time, and it is two element-level checks rather than a route read:

- await: { visible: { id: settings-screen } } # identity: WHICH screen
- await: { idle: true } # readiness: it stopped moving

Neither implies the other. A dropped tap leaves the source screen perfectly idle, and the destination's elements enter the tree while the transition is still animating over them. So both are required after every screen change, including the one launch: performs, which is where readiness matters most: launch waits for platform automation readiness, not for the app's own loading or splash.

The readiness half is a directive with no live tool behind it, so it joins snapshot: on the short list of insertions allowed during polish.

Routing

The three skills were being confused by name alone, so the rules now draw the line explicitly:

you want	skill
a one-off interactive check, nothing saved	argent-test-ui-flow
a saved, replayable path	argent-create-flow
a saved test with acceptance criteria and two-pass proof	argent-qa-flows

"Record a flow" also stops being ambiguous with screen recording, which is video.

One rule worth calling out

If you may record a flow or QA test, do not interact with the app first - start the recorder before the first launch or in-app action.

A path already walked cannot be recorded retroactively, and re-walking it was one of the more expensive mistakes in practice.

Test

The YAML frontmatter of every bundled skill is parsed in a test, so a malformed new skill fails here rather than at install time.

Review notes

Every concrete claim about await: { idle: true } was checked against the implementation: defaults, the parse-time rejection of a minStableMs that cannot fit inside timeout, the three-read minimum, the hard failure on timeout against the tool's soft settled: false, the absent assert form, and the warning when no screenshot could be read. All 44 anchored internal links resolve.

Duplication was cut where the same rule had accumulated in several files: the "never prove a screen with a shared header / tab bar / positional id" list went from five placements to two, and the "never persist await-screen-idle" rule from three to one.

Three items in argent-device-interact are restored here rather than lost with #727, which is closed: the keyboard tool serves every platform (not just iOS and Android), a hidden note that never matched is a failed check rather than a pass, and await-screen-idle gets a compact entry because three flow references now point at it.

[j-piasecki]

Can the agent record await/assert live?

[hubgan]

No it cannot.

flow-add-step only rewrites three things:

• gesture-tap -> tap:,
• restart-app -> launch:, flow-execute -> run:. A check is recorded as an
• await-ui-element call, stored as a raw tool: step, and converted to await:/assert: during polish. assert: has no live tool at all.

The core skill never mentioned await-ui-element once, and rule 2 said "Record
each check" while listing snapshot:, which has no recorder form at all. Three
fixes:

• rule 2 now names the route and drops snapshot:
• rule 5 says "raw step" instead of "raw action", so the check conversion is clearly allowed, and names the three insertions that have no recorder form
• rule 4 notes identity is recorded live while readiness is a polish insertion