> ## Documentation Index
> Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan file

> One plan, in `./.graph/plans/` or `~/.config/graph/plans/`, run with `graph plan run` and called by agents and other plans as `plan__<identifier>`.

| File type | Location |
| - | - |
| YAML | `./.graph/plans/<identifier>.yaml` (project) `~/.config/graph/plans/<identifier>.yaml` (global) |

Unknown keys are a load error. For completion in your editor, start the file with `# yaml-language-server: $schema=https://raw.githubusercontent.com/tylerdavis/graph/main/docs/schemas/plan.schema.json`.

## Fields

**version** `integer`

The file version the document is written in. Omitted means 1; `graph plan migrate` brings a file to the current version.

**identifier** `string` *required*

Letters, digits, `_` and `-`. The plan is called as `plan__<identifier>`, and a plan with a built-in plan's identifier replaces it.

**name** `string` *required*

Display name.

**description** `string` *required*

What the plan does. Agents read it when choosing tools.

**exemplars** `string[]`

Example requests the plan handles, added to its tool description.

**requires\_servers** `string[]`

MCP servers the steps use. The plan is hidden from the catalog while any of them isn't configured.

**input\_schema** `object`

JSON Schema for the plan's inputs, validated before any step runs. Steps reference inputs as `{{input.<field>}}`.

**steps** `object[]` *required*

The steps, run in order.

**steps.\[].id** `string` *required*

Unique across the plan, including steps inside bodies. Later steps read the result as `{{<id>.<field>}}`. Can't be `input`, `item`, `index`, `accumulator` or `length`.

**steps.\[].tool\_name** `string` *required*

A catalog tool (`<server>__*`, `user__*`, `builtin__*`, `plan__*`, `agent__*`) or a control step (`exit`, `route`, `filter`, `map`, `reduce`, `agent`, `ask`).

**steps.\[].input** `object` *required*

The tool's input. String values are templates over `input` and earlier results; a control step's input is described on its page.

**steps.\[].reasoning** `string`

Why the step exists, for people reading the plan.

**output\_schema** `object`

JSON Schema for the result of an output plan. Its `properties` must match the keys of `finish.output`.

**finish** `"silent" | object` *required*

How the plan ends, and what it returns: `silent`, `output` or `solver`.

**finish.output** `object`

Returns this map as JSON, each template filled from step results. No model call.

**finish.solver** `object`

A model call writes the answer as prose, returned as `{answer}`.

**finish.solver.query\_to\_answer** `string` *required*

What the answer should say, as a template.

**finish.solver.system\_prompt** `string`

Extra system prompt for the solver call.

**finish.solver.data** `object`

What the solver sees, as a map of templates over step results.

```yaml Example theme={null}
version: 2
identifier: weekly_changes
name: Weekly changes
description: Summarizes the commits merged since a git ref.
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as the last release tag
steps:
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{input.base}}'
    head: HEAD
- id: nothing_shipped
  tool_name: exit
  input:
    when:
      value: '{{commits.count}}'
      op: eq
      to: 0
    status: success
    message: Nothing merged since {{input.base}}
finish:
  solver:
    query_to_answer: Summarize what changed, grouped by theme.
    data:
      commits: '{{commits.commits}}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.