Track a PLAN.md roadmap: milestones, deadlines and progress

The Plan tracker reads a Markdown plan such as PLAN.md from your project checkout and turns its checkboxes, milestones and dates into progress, status and overdue warnings. Agents can write the plan and take a milestone once its prerequisites are done.

The Plan tracker sits at the bottom of each Project screen. It reads a Markdown plan that lives in the project’s checkout – PLAN.md unless you choose another file – and turns its checkboxes into progress: how much is done, which milestone is late, and which sprint is holding it up. The file stays the source of truth. You and your agents keep editing it like any other file; the dashboard only reads it.

How the plan reaches the dashboard

1. The project’s runner looks for the tracked file in the project folder and at the root of each of the project’s repositories, at most every 30 seconds.
2. When the file has changed, the runner uploads a read-only snapshot. With workspace end-to-end encryption on, the snapshot is encrypted on the runner and decrypted in your browser.
3. The dashboard parses the snapshot in your browser and checks for a newer one every 30 seconds while the tab is open, or at once when you press Refresh plan. A snapshot older than ten minutes is marked stale.

Nothing is ever written back: the tracker cannot edit the file, and the snapshot is never copied into a checkout. Owners and admins choose the tracked file under the source button, as a Markdown path relative to the project folder and repository roots. When more than one machine or repository reports a copy, pick the checkout to read there. The source panel opens by itself when no readable plan is found.

What counts as progress

Only explicit Markdown checkboxes count: - [ ] is remaining work, - [x] is done, and nested items count once each. A plan with no checkboxes shows Progress unknown, not 0%, and stays readable under Formatted plan. Words such as “Done”, status tables, story points and estimates are left as prose; code blocks, HTML comments and YAML frontmatter are ignored.

The format

Any Markdown plan works. These optional lines add structure:

# Project plan

## Milestone: First release
ID: first-release
Target: 2026-11-01

### Sprint: Foundation
ID: foundation
Start: 2026-10-05
Target: 2026-10-16

- [x] Define the scope
- [ ] Build the prototype | target: 2026-10-12

### Sprint: Release preparation
ID: release-preparation
Depend on: foundation
Start: 2026-10-19
Target: 2026-10-30

- [ ] Review the interface
- [ ] Publish the release

Dates show planned timing, never completion. Invalid or duplicate dates, reversed ranges and sprints outside a milestone produce line-numbered warnings. The tracker’s Plan format guide has the full rules and the same copyable example.

Reading the tracker

• Summary. One status word for the whole plan (On track, Overdue, Complete), a sentence naming the late milestone and the sprint holding it up, a Needs attention list, status counts and overall progress.
• Milestone cards. Sprints are nested inside their milestone, and each card leads with its status as an icon and a word. On a dated card a tick marks how much of the Start–Target range has passed; Behind pace (estimate) appears when progress trails it by ten points or more, and overdue work grows a tail sized by how late it is.
• Tasks. Select a card to list its tasks as All, Remaining or Done, overdue first. Complete milestones fold away; plans with more than six milestones also get a Needs attention filter.
• Formatted plan shows the whole file as written.

Agents and the plan

Ask an agent opens a plan-writing session: describe the project, what should be delivered and by when, then pick the runtime and model. The agent writes or revises the tracked file in this format, directly in the project checkout. It keeps completed work and history, and asks when scope, dates or prerequisites are unclear rather than inventing them. The session runs on the project’s runner, or the group runner that serves it, outside the normal task flow: no review or pull request follows it, and opening the dialog queues nothing.

Handoff on a milestone or sprint opens the New task dialog with a brief to finish that group, so it runs like any other task with your usual review steps. Handoff stays disabled until every prerequisite named in Depend on has all of its checkboxes checked, child sections included. Sprints inherit their milestone’s prerequisites. A missing or circular ID, or a stale snapshot, blocks handoff too; check off finished work in the file, let the runner sync it, then press Refresh plan.