---
title: "Planner"
description: "Generate a repository-aware implementation plan before code is written, then review and approve it."
canonical: "https://baz.ai/docs/capabilities/planner"
---

# Planner

Generate a repository-aware implementation plan before code is written, then review and approve it.

Planner generates an implementation plan before any code is written. Instead of letting a coding agent jump straight into edits, Planner analyzes the request against the current state of your repositories and produces a plan that a human can read, question, and approve.

<figure><img src="/docs/docs-assets/appdemo-plan-review.png" alt="A plan open for review in Baz" width="1400" height="730"><figcaption>A plan open for review, with its sections, version, and review actions</figcaption></figure>

## Starting a planning session

Planning starts from a coding agent with the [Baz plugin](/docs/basics/plugins) installed:

```
/baz:plan-with-baz
```

The command kicks off a planning run scoped to the task at hand. The agent explores the relevant repositories, including ones you have never cloned, before producing a plan, rather than proposing changes from the prompt alone.

The agent asks you to approve the plan before it starts implementing. Publishing the plan to Baz is opt-in: the agent asks once per session before it uploads.

## Pulling comments back into the CLI

Run `/baz:get-plan-comments` in Claude Code, `get-plan-comments` in Codex, or `/get-plan-comments` in Cursor, from the same session that owns the plan, to bring every comment back into the terminal and update your plan accordingly.

## What a plan captures

A plan has two layers. The top is what a reviewer approves on; the bottom is what an implementer follows.

| Section         | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| Why             | The problem and why it is worth solving now                                        |
| The change      | What behaves differently, with a before and after table and a sequence diagram     |
| Affected repos  | Every repository the change touches                                                 |
| Decisions       | The choices made and the alternatives rejected                                      |
| Open questions  | Ambiguities that need an answer before implementation                               |
| Steps           | The implementation steps, grouped per repository                                    |
| Verification    | How the change should be tested once it is implemented                             |

Surfacing this before implementation turns architectural and sequencing decisions into something reviewers can weigh in on, instead of discovering them after the fact in a diff.

## Finding plans

Plans appear under **Tasks**, next to pull requests. Choose **Plans only** in the type filter to list just plans. Each plan shows its status: pending, approved, implemented, or closed. Plans assigned to you for review appear in **My Tasks**.

## Reviewing and approving a plan

Plan review works like code review, but it happens before the code exists.

### Sharing a plan and requesting review

A plan published from your coding agent lands in Baz, where teammates can open it and review it. Reviewers can be assigned as individual people or as groups. Who can be assigned is based on access to the plan's repositories.

### Commenting on a plan

Select a passage to comment on that exact text, such as a particular file, a step in the change sequence, or an open question, or leave a general comment on the plan as a whole. The plan page places comments beside the content they discuss, so a reviewer reads feedback next to the passage it refers to. The page is also laid out to make long plans easier to navigate.

To act on the feedback, [pull the comments back into your coding agent](#pulling-comments-back-into-the-cli), revise the plan, and publish a new version.

### Versions and outdated comments

Each revision is saved as a new version. When a new version is published, open comments remain visible on it. If the passage a comment was attached to can no longer be found in the new version, the comment is marked **Outdated** instead of being dropped, so feedback does not silently disappear when the plan is rewritten.

### Comparing versions

The comparison view shows what changed between any two versions of a plan, not only consecutive ones. Choose how to read the difference:

| View         | Description                                     |
| ------------ | ----------------------------------------------- |
| Rendered     | The changes shown in the formatted plan         |
| Unified      | A single-column diff of the two versions        |
| Side by side | The two versions next to each other             |

This lets reviewers follow how a plan evolved in response to comments, and check the version they commented on against the one they are approving.

### Diagrams

Plans can include Mermaid diagrams to describe flows, sequencing, or architecture changes. These render inline in the plan view, so reviewers follow the diagram alongside the written plan rather than reading raw diagram syntax.

### Approval

Reviewers approve a plan from the plan page. Approval records a reviewer's sign-off on the approach; it does not block implementation. To ask for changes, comment on the relevant passages.

### Reviewing on mobile

Plans and their comments work on mobile, so a reviewer can read a plan and its discussion away from a desk.

## Plans and pull requests

Baz links a pull request to its plan automatically when the pull request description mentions the plan reference (`PLAN-<n>`) or shares a ticket key with the plan, or when Baz matches them by content. The coding agent can also link them explicitly once the pull request is open. A linked plan is marked implemented.

When a plan is linked, Baz adds a link to the plan in its PR comment, so code reviewers can see the decisions behind the implementation. The review also includes a **Plan Implementation Gaps** section that checks the pull request against the plan.

## Tracking a planning run

Each planning run is recorded as a session, so the steps behind a plan stay inspectable: the context that was assembled, the requirements that were mapped, the risk gate that ran, and the revisions that followed review. See [Sessions](/docs/capabilities/sessions) for how to read a planning session.

## FAQ

<details>

<summary>How do I start a plan?</summary>

Run `/baz:plan-with-baz` from a coding agent with the Baz plugin installed. Planner scopes the run to the task you describe and gathers repository context before drafting the plan.

</details>

<details>

<summary>How do I read plan comments without leaving my coding agent?</summary>

Run `/baz:get-plan-comments` (Claude Code), `get-plan-comments` (Codex), or `/get-plan-comments` (Cursor) from the session that owns the plan. It returns every comment on the plan, so you can address feedback without opening Baz.

</details>

<details>

<summary>Can implementation start before a plan is approved?</summary>

Yes. Approval in Baz records sign-off and does not block implementation. Your coding agent still asks you to approve the plan before it starts editing.

</details>

<details>

<summary>What happens to a plan after feedback?</summary>

Revisions are saved as new versions. Open comments stay visible on the new version, and a comment whose original passage can no longer be found is marked **Outdated** rather than removed. The comparison view shows what changed between any two versions, rendered, unified, or side by side.

</details>

<details>

<summary>Who can I assign as a reviewer?</summary>

Individual people or groups. The available reviewers are based on access to the plan's repositories.

</details>

<details>

<summary>How do code reviewers find the plan behind a pull request?</summary>

When a plan is linked to a pull request, Baz includes a link to the plan in its PR comment.

</details>

<details>

<summary>Does Planner work across repositories?</summary>

Yes. A plan lists every repository the change touches and groups its implementation steps per repository.

</details>
