# The plan command

> Print what each PR should be on GitHub, without changing anything.

<!-- Generated by website/scripts/sync-agent-guide.mjs from the "The plan command" section of AGENT-GUIDE.md. Do not edit: change AGENT-GUIDE.md and re-run it. -->

`local-review plan` prints what each PR in a stack should be on GitHub: its branch, its base, and its exact title and body. An agent publishes from it, so publishing is mechanical. The full flag list is in the [CLI reference](/reference/cli/).

:::note[From the agent guide]
This page is the [agent guide](/agents/agent-guide/#the-plan-command)'s "The plan command" section, word for word. Agents read the whole guide with `npx local-review guide`.
:::

The plan command is read-only: it never writes, pushes or calls GitHub. Run it from anywhere:

```sh
local-review plan <project> [--repo <name>] [--stack <n>] [--include-follow-on] [--format md|json|yaml]
local-review plan my-feature --repo my-service --stack 1
```

It lists each PR in scope, in order, with:

- the commit, its readiness (`Status: draft|ready|published`), and the branch with its status;
- the base: the previous PR's branch, or the repo's base (remote prefix stripped, e.g. `main`) for the first PR;
- the title, and the **exact full body**: project intro, stack note, `---`, PR description, the same as the UI's
  "Full body" button;
- any recorded `github:` info;
- the images the body shows (`images[]` in JSON: `name`, `file`, `url`), and those in its comments for GitHub;
- its **comments for the GitHub PR**, the threads the reviewer marked `publish: true` (`publish_threads[]` in JSON:
  `id`, `path`, `line`, `side`, `start_line`, `start_side`, `outdated`, `resolved`, `comments[]` with `author` and
  `body`, and `published`, null until you've posted it). `path` null is a general comment; a `path` with `line`
  null is about the whole file.

It warns about anything that needs fixing first: unresolved `starts_at` selectors, PRs without a branch, `missing`
and `moved` branches, and stacks that still contain draft PRs (only the reviewer can clear that one, by marking them ready). `--format json` is for scripts, e.g. `jq -r '.prs[0].body'`.
It also warns when a live PR's recorded `github.base` differs from the plan's base (retarget the PR, or check the
order), and when a prs file with a `github:` record and no `landed:` has a commit that's now in the repo base: it
landed upstream but wasn't frozen (do that now; "After merges"). And for each image (`assets/<name>`) in a body with
no published URL, since GitHub can't show a file on this machine ("Images" under "Materializing"). Where a URL is
recorded, the body already has it in place of `assets/<name>`. And for comments for GitHub: one that's outdated
(its lines aren't in the diff any more, so it goes in the review's body), an image in one with no published URL, and
a PR that's already on GitHub with comments not posted yet.

In a linked project ("Linked projects") whose range in a repo starts where the predecessor's ends, the first PR there
is based on the **predecessor's top PR's branch** instead (`base_from: predecessor`; the others are `repo-base` and
`previous-pr`), with a warning while that PR isn't published: publish the predecessor first.

Landed (merged) PRs are never planned, with no warnings of their own; the first live PR's base is the repo base. A
note lists them ("Skipped 9 landed (merged) PRs …"); in JSON, `excluded_landed[]` (`repo`, `prs`).

Follow-on stacks are left out by default, with none of their warnings, and a note says so ("Excluded 1 follow-on
stack (2 PRs: …); use --include-follow-on"). `--include-follow-on` plans them too (the first one's base is the
previous PR's branch, as for any stack). `--stack <n>` naming a follow-on stack plans it, with a note that it's a
follow-on. In JSON: `scope.include_follow_on`, `excluded_follow_on[]` (`repo`, `stack`, `title`, `prs`), `notes[]`,
and `stack.follow_on` on each PR.
