# Plans

> Where loop-plan writes plans, how loop-implement finds and ticks them, and whether plans are kept in git.

A plan is a phased implementation document. `loop-plan` writes it, `review-plan` or you approve it, and `loop-implement` carries it out phase by phase, ticking each acceptance criterion it meets. This page covers where plans live, what the files contain, and whether git keeps them.

## Where plans live

`loop-plan` writes each plan to:

```text
<workspace>/.cross-review/plans/<name>-plan.md
```

Before it writes, `loop-plan` runs `cross-review plans --working-dir <workspace>`. That command creates the folder and keeps its `.gitignore` in step with the [Plans in git](#plans-in-git) setting. It prints each plan in the folder as JSON, and the dashboard reads the same folder.

Plans written before this layout (anywhere else in the repository) are not listed on the dashboard. To keep using one, give its path to `loop-implement`.

## Plan formats

The plans command recognizes two kinds of Markdown file in the folder:

| Format      | How it is recognized                                              | Dashboard                                                                        |
| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `loop-plan` | The file has a `## Plan schema` section that says `loop-plan/v1`. | Progress and Plan tabs, with phases, criteria, checkpoints and the progress log. |
| `markdown`  | Any other `.md` file in the folder.                               | Shown as a plain document.                                                       |

A `loop-plan/v1` plan has:

- Phases, each with acceptance criteria. A criterion is ticked (`- [x]`) when `loop-implement` has met it.
- Review checkpoints: the points where `review-impl` runs, and the phases they follow.
- A progress log, which `loop-implement` appends to as it works.
- A plan review section, filled in by `review-plan` or by you.

## Plans in git

Plans are not committed by default. The folder `.cross-review/` ignores itself, and so do plans. Turn on **Plans in git** to commit them:

- Set `track_plans` to `true` in the global or workspace [settings](https://cross-review.tlelabs.com/docs/guides/settings/), or switch **Plans in git** on in the dashboard’s Settings page.

- The plans command then writes this `.gitignore` in `<workspace>/.cross-review/`:

  ```text
  *
  !plans/
  !plans/**
  ```

  With the setting off, the file contains only `*`, which ignores everything in `.cross-review/`, including sessions and settings.

A `.gitignore` you edited by hand is left alone, and the plans command reports it as `custom`.

### A root `.gitignore` can still block plans

If the repository’s root `.gitignore` ignores `.cross-review/`, git does not look inside it. The plans command checks for this, and when it finds such a rule it reports `blocked_by` with a warning:

> Plans in git is on, but a rule ignores new plans in .cross-review/plans/.

To fix it, change the rule to ignore only the contents and add the exception:

```text
.cross-review/*
!.cross-review/plans/
```

### Turning it off later

Turning **Plans in git** off does not remove plans that were already committed. Stop tracking them with:

```sh
git rm --cached <plan file>
```

## Phases and commits

`loop-implement` works through the plan one phase at a time:

1. It stages the plan file only when git does not ignore it. Git decides that (`git check-ignore`), not the setting.
2. It ticks the criteria the phase met and appends to the progress log.
3. It commits the phase with the commit message the plan names for it.

The dashboard finds each phase’s commit by looking for a commit with that subject in the last 2000 commits. If the phase was committed with a different subject, the dashboard shows the phase without a commit.

> **Note:**
>
> With Plans in git off, the plan stays uncommitted. The ticks and the progress log then exist only in your working copy. Commit the plan yourself when you want it in history.

## Follow plans

With **Follow plans** on (`open_plans` set to `true`), each plan that `loop-plan` finishes opens in your browser on its Plan tab. Read it there before you approve it. If the dashboard is not running, it starts in the background and closes itself after 30 minutes with no page open. See [Dashboard](https://cross-review.tlelabs.com/docs/guides/dashboard/).

## Plan states on the dashboard

| State       | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| draft       | The plan is not approved, and no review of it is open.      |
| in review   | The plan is not approved, and a review of it is open.       |
| ready       | The plan is approved, and no criterion is met yet.          |
| in progress | At least one criterion is met, and not every phase is done. |
| done        | Every phase is done.                                        |