Working in a session
Where to start the agent, which directory answers which question, and what a first session actually looks like.
The skills are installed and /ff appears in the command list. This page is the part between that
and your first walkthrough: where to stand, what the CLI reads from where, and the one mistake that
produces a confident wrong answer.
For the complete sequence from Studio sign-in and API key creation through publishing, use From sign-in to a published flow. This page explains how the agent finds its workspace.
Start the session in the workspace
Open your agent in the directory that holds .fixtureframe/ — not its parent, and not the folder
you happened to be in.
cd ~/code/acme
claude # or cursor, or whicheverTwo separate things depend on it, and only the first one is obvious:
- Skill discovery.
.claude/skills/belongs to the project it was written into. Claude Code finds it when it starts there and not when it starts one directory up. - Every command the agent then runs.
ffresolves its workspace from the working directory unless told otherwise, and reads.envfrom that workspace rather than from wherever you are standing. Start somewhere else and the control plane URL, the API key and the cached survey are all invisible — not as an error, but as a command that runs and finds nothing.
Check that /ff and /ff-context appear in the command list, then ask the agent to run ff doctor and ff session status. They report the workspace configuration and saved authentication state.
If the agent has to run from somewhere else, --directory and FIXTUREFRAME_PROJECT_DIR both name
the workspace explicitly — see Configuration for the full resolution order and
for why FIXTUREFRAME_PROJECT_DIR is the one setting that cannot live in .env.
Two directories, and they are often not the same one
Most commands ask one question of one place. ff suggest asks two questions of two places, and
conflating them is the most common way to get a confident wrong answer out of this tool.
| Directory | Holds | Named by |
|---|---|---|
| Workspace | .fixtureframe/, the cached survey, the environment, .env | --directory, else where you are |
| Source | the product's code — the end-to-end tests a catalogue is gathered from | --source, else source in the config, else where you are |
They are the same folder when you document the application you are standing in. They are not when the workspace is a documentation repository, or when a hosted product's code lives in a different checkout — which is the ordinary case, not the exotic one.
The source fallback resolves against the current directory, not against the workspace. So ff suggest --directory ~/acme-docs run from anywhere else scans that somewhere else, reports zero candidates, and the message blames the
repository.
Write it down once instead of relying on anyone remembering a flag. In
.fixtureframe/config.json:
{
"schema_version": "1.0",
"environment": "staging",
"source": "../acme-app"
}Relative, and resolved against the workspace — so it means the same thing on every machine, which an absolute path in a committed file would not.
ff suggest prints both directories in its header for exactly this reason. If the Source: line is
not the repository you expected, that is the whole diagnosis.
Your first session
Assuming ff init has run, the environment exists, and ff session init has saved your app sign-in.
1. Survey the product. Nothing downstream is better than this, so it goes first:
Survey staging so we have a vocabulary to work from.
The agent runs ff survey. It signs in, walks the product read-only, and caches what it found. It is
on the free side of the permission table deliberately — it
takes minutes and it never acts on what it finds. Expect the agent to narrate it rather than run it
silently.
2. Organize the app context.
/ff-context Use the staging survey to create .fixtureframe/APP_CONTEXT.md.
Describe the user jobs, related capabilities and any missing detail-screen evidence.Review the context. Use a targeted ff survey --seed with verified routes if a selected detail
screen is missing, then update the context. A second survey is not required when the evidence is sufficient.
3. Ask what is missing, if you need suggestions.
What walkthroughs are missing for this product?
ff suggest gathers the end-to-end tests and the surveyed screens, subtracts what is already
published, and hands the agent both the candidates and the survey itself. The agent ranks, names and
writes you a catalogue. Prune it — a wrong row costs you the second it takes to delete it, which is
the whole reason this is a safe use of a model.
4. Build one. Take an accepted row and point at it:
Build "Add an environment, narrow what runs reach". Customer-facing, screenshots and an HTML demo.
From here it is the loop in The agentic pipeline: confirm the beats, the agent writes a
brief and a Playwright script, ff brief and ff lint run free and constantly, and ff script asks
before it opens a browser. Use --session --local-only for saved-session capture, then review the
frames and a fresh replay before publishing. Create a data profile when the flow needs variable
inputs; the workflow guide
explains what profile creation does and does not automate.
Skipping step 1 is the mistake worth naming. Without a survey, ff lint refuses outright and ff suggest can only
offer what your browser tests prove — which for most repositories is nothing. Neither failure looks like a failure.
What you should see in the transcript
A well-behaved session is legible. The gates are in the CLI rather than in the model's manners, so what you are watching for is not whether it obeyed but whether you can tell what it did.
| Sign | Meaning |
|---|---|
ff lint run repeatedly while a script is written | Working as designed — it is free and answers in milliseconds |
An approval prompt before ff script or ff publish | The permission table is in effect |
ff diagnose after a failed capture | Reading the failure rather than re-running to see if it passes |
A re-run of ff script with no edit in between | Worth interrupting. A capture that failed twice will fail a third time |
When the survey goes stale
A survey taken before a redesign is worse than none: ff lint checks names against a product that
has moved, and ff suggest proposes flows for screens that no longer exist. The survey records the
revision it was taken at, and ff suggest says so when they differ.
Re-survey after any UI change you would describe as a redesign, and after any release you would write release notes for. It is one command per environment, not one per flow.