Plans

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:

<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 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, or switch Plans in git on in the dashboard’s Settings page.

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

  *
  !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:

.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:

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.

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.