Phase guidance

Steering without code

The agent finished the build, eyeballed the output, and asked you to merge — with two tests still red and lint complaining. The transitions are right: you’ve gated ship behind a green check, so it physically can’t merge a broken build. But before it got there it burned a turn doing the wrong thing, because nothing told it what this state is actually for. It sees transitions and context, but not what matters here.

Phase guidance fixes this. Each state can carry two fields:

• goal — a short description of what the model should focus on right now. Think of it as a headline.
• guidance — longer instructions about how to reason about the choices available. Think of it as a briefing.

Both are optional. Use one or both depending on how much steering the model needs at that point.

What it looks like in YAML

states:
  verifying:
    goal: Confirm the suite is green before requesting review
    guidance: >
      You're looking at the latest test and lint results.
      If any test failed, go to fix -- do not request review
      on a red suite. Only request review when failingTests is
      0 and the linter is clean. Check the failingTests count
      and lintErrors fields before deciding.
    transitions:
      fix:
        title: Go back and fix failures
        target: implementing
      request_review:
        title: Open a PR for review
        target: awaiting_review

What the model receives

When the model calls flowgate.query({workflowId}) (get) or flowgate.command({workflowId, transition}) (submit) and lands on a state with guidance, the response includes a guidance object:

{
  "state": "verifying",
  "guidance": {
    "goal": "Confirm the suite is green before requesting review",
    "instructions": "You're looking at the latest test and lint results. If any test failed, go to fix -- do not request review on a red suite. Only request review when failingTests is 0 and the linter is clean. Check the failingTests count and lintErrors fields before deciding."
  },
  "context": {
    "failingTests": 2,
    "lintErrors": 1
  },
  "links": [
    { "transition": "fix", "title": "Go back and fix failures" },
    { "transition": "request_review", "title": "Open a PR for review" }
  ]
}

The model sees the goal, the reasoning instructions, the relevant context, and the available actions — all in one response. It doesn’t have to guess what this phase is about.

Guidance vs. prefill

flowgate has two ways to shape what the model does at a given state:

• guidance shapes reasoning — what to focus on and how to think about the decision.
• prefill shapes arguments — pre-populating input fields for the next transition so the model doesn’t have to construct them from scratch.

They complement each other. Guidance says “here’s what matters.” Prefill says “here’s a starting point for your input.” Use guidance when the model needs to understand why it’s making a choice. Use prefill when you want to reduce the mechanical work of assembling arguments.

Searchable by design

Both goal and guidance fields are indexed by flowgate.query({query}) search. When a model searches for “tests” or “review” or “lint,” workflows with matching guidance text surface in the results.

This means your guidance doubles as documentation for discovery. A well-written goal like “Confirm the suite is green before requesting review” helps the model find this workflow when it’s looking for a test-and-review loop. You don’t need to duplicate that information in tags or descriptions — though you can if you want redundancy.

Tips for writing good guidance

Keep goals under 10 words. The model uses them to quickly orient. “Confirm the suite is green before review” works. “Confirm that the full test suite and linter pass before deciding whether to open a pull request for human review” is too long for a headline.

Be specific in instructions. “Review the results and make a decision” doesn’t help. “If failingTests is above 0, go to fix. Otherwise, request review.” does. The model can reason better when you give it concrete thresholds, field names, and criteria.

Reference context fields by name. If the context contains failingTests, mention that exact field in the guidance. The model will look for it.

Skip guidance on obvious states. A terminal state called done doesn’t need a goal of “The workflow is complete.” Save guidance for states where the model actually has a non-trivial decision to make.