How to ask

Start with the app/environment, intended viewer and outcome. The agent can gather app context and propose evidence-backed coverage; you do not need to write a complete product specification. Use App context for reusable facts and the workflow guide for the command sequence.

You also do not need a slash command — asking in a sentence reaches the same skills, and carries things no flag expresses. See Skills and commands for the conversational equivalents.

Passing CLI switches through an agent prompt

Include the switches after the slash command, alongside the task:

/ff-script Capture .fixtureframe/flows/operator-tour.mjs against staging using --session --local-only.

You can also include the exact terminal command you want the agent to use:

/ff-script Run ff script .fixtureframe/flows/operator-tour.mjs --environment staging --session --local-only

The text after a slash command is an instruction to the agent. The agent interprets it, checks the command's supported options and prerequisites, and constructs the CLI invocation. Switches are not automatically forwarded by the slash-command host. The skill still follows its authoring checks and the authorization already agreed for the task.

Recording with a saved session

Agent prompt

/ff-record Help me record staging using the saved session and --local-only.

Corresponding terminal command

ff record --environment staging --local-only

Run interactive recording in your own terminal and demonstrate the flow in the browser. The agent can prepare the command and help review the result.

ff record restores an available saved session automatically; it does not need --session. ff survey also restores it automatically. Both accept --fresh to opt out. ff script and ff run require --session explicitly to reuse saved authentication. Save or renew the session first with ff session init --environment staging when needed.

Warm start beats cold start

A cold start describes the walkthrough from nothing. A warm start points at something specific — a test, a help article, a diff, a catalogue entry — and asks for that.

Warm start is better here for the same reason it is better anywhere, and for one more: the agent is then transforming evidence you supplied rather than inventing the thing that has to be true. Every part of this product that works does the first. The part that was abandoned did the second.

Warm sources, roughly in order of how much they carry:

1. An existing help article. It already contains the beats, in your own words, for the same audience. Nothing else comes close.
2. An end-to-end test. Proves the path is walkable; says nothing about what it is for.
3. A catalogue entry from ff suggest, with its path line.
4. A diff or a pull request, when documenting something you just built.

The one field you cannot skip

Beats — the ordered steps, in your own words.

1. Open Settings → Environments
2. Add an environment
3. Name it and give it a base URL
4. Narrow what runs may reach
5. Save

Everything else in a brief may be defaulted. Beats may not, and the tooling enforces it rather than trusting anyone to remember: the schema refuses beats marked inferred, and ff script refuses to open a browser when nobody has confirmed them.

You do not have to type them from scratch. The agent will propose them from whatever evidence you pointed at. Your job is to read five lines and say yes, or fix one.

What you will be asked

Only consequential missing information, using answers already supplied and bundling related questions.

That last one catches people out and is worth taking seriously. A walkthrough of inviting a teammate creates a real invitation on every replay, forever.

Say what it costs before it costs it

Video is the slowest and most expensive output — it bills a voice vendor per second and an avatar vendor per take. If you want a deck narrated for internal review, screenshots and an HTML demo may be the whole answer. Ask for video when you want video.

Worked examples

Orientation with selective depth.

/ff-script Use APP_CONTEXT.md to orient a new operator to the main sections.
For each, state the question it answers and show representative proof. Give
complex areas a detail example; defer full procedures. Propose the scope before
capture, use the saved session, and review the replay artifacts before publishing.

Too vague. The agent will interview you, which is fine but slow.

Make a demo of user management.

Enough to start. Names a source; the agent proposes beats from it and asks you to confirm.

Turn e2e/team.spec.ts into a customer-facing walkthrough — screenshots and an HTML demo, against staging.

One-shot. Beats supplied, so there is nothing to invent and nothing to interview for.

Customer-facing walkthrough of inviting a teammate, against staging, screenshots + HTML demo. Beats: open Settings → open Team → enter their address → choose a role → send the invitation. It leaves a real invitation in the sandbox.

Warm and specific, the best shape. Points at prose you already wrote for the same readers.

We have a help article at docs/help/inviting-teammates.md. Build the flow it describes, keep its wording, and tell me anywhere the article no longer matches the product.

That last request also does something none of the others do: it detects drift. If the article says "Settings → Team" and the survey says "Settings → People", you have just found a stale article, which is usually worth more than the video.

How much detail is worth it

More specification buys fewer rounds, up to a point. Beats are always worth stating. Output kinds are worth stating because they cost money. Everything else — pacing, cards, presenter placement, narration wording — is easier to adjust on a draft you can see than to specify in advance.

Ask for the draft early, then edit.

What the agent will not do

• Invent beats, or proceed when you have not confirmed them
• Open a browser, spend a vendor call, or publish without your approval
• Write the flow definition itself — it writes a script and lets the recorder produce the flow
• Loosen a locator to make a failing capture pass
• Rewrite your speaker notes, your article's wording, or a catalogue entry you edited