Agent Instructions — project brief cards for Google Flow's Agent Mode

Status. The ephemeral -i / --instruction flag on gflow image t2i / i2i shipped in v0.28.0 (live-verified). The persistent gflow instructions command group, the movie.toml instructions blocks, and the matching gflow_instructions_* MCP tools described here shipped in v0.29.0 (live-verified, credit-free) — this doc now doubles as their spec and reference.

What an instruction card is

In Google Flow's Agent Mode, each project carries a brief — a set of instruction cards the agent consults every time it generates. Each card has:

• a title (human label),
• a guideline text (e.g. "Every image is a flat 2D children's crayon drawing on textured paper"),
• zero or more references — an attached image or a character entity,
• an enabled toggle.

Setting up cards is credits-free — it's a PATCH to the project brief, not a generation. Credits are only spent when you actually generate.

How cards steer generation (mechanism)

Instruction cards apply only on agentic-cohort sessions, and only through the agent's reasoning path: when you make a natural-language request, the agent rewrites the image prompt to fold in every enabled card (live-verified — an enabled "crayon drawing" card turned a style-neutral "a red bicycle" prompt into a crayon bicycle; an attached crayon reference image did the same). A card with enabled = false stays in the brief but is ignored. On a classic-cohort session, cards do not apply and gflow warns.

The three-layer pipeline

1. SET UP   project context   →  gflow instructions add / apply   (credits-free)
2. GENERATE using that context →  gflow image t2i / i2i --project <id>
3. COMPOSE  per-scene context  →  movie.toml [[…instructions.card]]

Agents: always set up the brief (layer 1) before generating (layer 2). The brief is what makes generations consistent across a project.

Ephemeral -i vs persistent cards

	-i "text"	gflow instructions
Scope	one generation	persists on the project brief
Creates	a fresh enabled text-only card each call	managed cards you can toggle/remove/re-sync
References	text only	image or character references
Lookup	never — always creates	by title (case-insensitive, fail-fast on ambiguity)

# Ephemeral: a one-off enabled text card for this generation only.
gflow image t2i "a cat on a chair" -i "flat 2D children's crayon drawing"

gflow instructions command surface

Persistent CRUD over a project's brief cards. Cards are selected by title (case-insensitive, fail-fast on ambiguity) — the ergonomic default — or by the stable server --id for the ambiguous-title / scripting case (list --json surfaces ids). Mirrors gflow character (select by --name or --entity-id).

gflow instructions add   TITLE --text TEXT [--ref REF]... --project ID [--disabled]
gflow instructions list  --project ID [--json]
gflow instructions enable  (TITLE | --id ID) --project ID
gflow instructions disable (TITLE | --id ID) --project ID
gflow instructions rm      (TITLE | --id ID) --project ID
gflow instructions apply   FILE  --project ID   # declarative full-sync (TOML/JSON)
gflow instructions toggle-mode (--on | --off) --project ID

The generic --ref (one attribute for all reference types)

Flow's card reference picker has All / Images / Characters tabs — a reference is an image or a character, and both are ultimately a referenceId. So there is one --ref option (repeatable), not separate --ref-image / --ref-character flags. gflow classifies each value and routes it to the right wire field:

--ref value	Resolves to
local image path (./hero.png)	upload via REST (uploadImage) → media id → imageReferenceMediaIds
generated-image UUID	imageReferenceMediaIds
character id or name	characterReferenceEntityNames

Uploading a new image to an instruction. Flow's reference picker has an "Upload media" button — a card reference can be a brand-new local image, not just an existing project asset. --ref ./local.png covers this using the same REST upload path as gflow image upload (verified: upload → PATCH the card with the returned media id → the image renders as the card's reference). No UI automation of the picker's upload button is required.

# A persistent card that anchors style to a reference image AND a character.
gflow instructions add "Hero look" \
  --text "Match the reference image's art style; keep the hero on-model" \
  --ref ./refs/mood.png \
  --ref hero-character \
  --project 6b714c4e-...

--project semantics

gflow instructions and generation commands take --project <id> to target a specific project's brief. Generation with --project uses that project's active (enabled) cards. Without --project, generation creates a scratch project (so persistent cards only make sense with --project).

apply FILE — declarative sync

gflow instructions apply replaces the project's cards with the file's contents (idempotent full-sync), so a brief can live in version control:

# brief.toml
[[card]]
title   = "Cinematic lighting"
text    = "Volumetric cinematic light from camera-left"
ref     = ["./refs/mood.jpg"]
enabled = true

[[card]]
title   = "Hero"
text    = "Keep the hero on-model"
ref     = ["hero-character"]

Design notes (state, ids, persistence)

• The server is the source of truth. The brief lives in the project's agentInfo (read via flow.projectInitialData, written via PATCH agentInfo). The web UI can edit cards out-of-band, so every list/enable/disable/rm reads the cards live — gflow never caches card state locally (a cache would silently drift).
• Card ids are stable and preserved. Each card carries a server id. Mutating commands are read-modify-write — read the current cards, change one, PATCH the set back keeping every card's existing id (so --id stays valid and enable/disable/rm edit the same card rather than replacing it).
• The local database records provenance, not state. When a generation runs with instructions active, the operation record notes which cards/refs were used (like it already records prompt, refs, and --tool) — for history/repro only. It is never read to drive gflow instructions.
• Declarative intent lives in the file. For apply brief.toml, the version-controlled TOML is the durable copy — not the database.

Typical agent-driven workflow (machine-readable)

1. Discover/choose a project id (gflow instructions list needs --project; find it in the Flow editor URL …/project/<id>/…).
2. gflow instructions apply brief.toml --project <id> — set up the brief (free).
3. gflow image t2i "…" --project <id> — generate using the active cards.
4. Adjust: gflow instructions disable "Cinematic lighting" --project <id>, regenerate.
5. movie.toml per-scene overrides for multi-scene consistency.

DO NOT rely on -i for anything you want to reuse — it's per-generation. PREFER title selection; fall back to --id (from list --json) only when a title is ambiguous. DO set up the brief before generating; cards only apply on agentic sessions.

See also

• USAGE.md — full command reference.
• MOVIE.md — multi-scene movies ([[…instructions.card]] blocks).
• MCP.md — the six gflow_instructions_* MCP tools mirroring this command group.
• LIVE_VERIFICATION_v0.29.0.md — live e2e evidence for the CRUD surface (mechanism, H4 image-reference confirmation). The original plan + spike findings were consolidated and removed when the feature shipped (v0.29.0 release prep).