Skip to main content
The Roadmap view gives you a bird’s-eye perspective of a project’s milestones and phases, and bridges to the GSD spec-driven development framework when the project has a .planning/ directory.
Roadmap view

​
Opening the Roadmap

Open any project, then click the Roadmap tab in the top view tabs. The view has three stacked sections:
  1. Project Overview — summary of .planning/PROJECT.md plus current state (when GSD is initialized)
  2. .planning/ Roadmap — GSD file-based roadmap, phase list with per-phase actions
  3. Milestones — classic DB-backed milestones and phases, independent of GSD
If the project has no .planning/ directory, only the Milestones section is shown.

​
Project Overview panel

When .planning/PROJECT.md exists, a collapsible card appears at the top of the Roadmap:
  • Header: project name (the H1 of PROJECT.md) + a short summary line + the current_phase badge from STATE.md
  • Expanded: current phase / current step from STATE.md + the full raw PROJECT.md and STATE.md contents
Use this to quickly remind yourself what the project is about, and where the GSD workflow currently stands, without leaving the Roadmap tab.

​
Structured phase description

Phase descriptions in ROADMAP.md usually follow a convention:
Instead of dumping this as raw markdown, the view parses it into dedicated sections with icons and badges: Markdown tables anywhere in the description are rendered as actual HTML tables with zebra rows and an emphasized first column — no more raw | --- | lines.

​
Phase actions

Each phase row shows a state-machine action button based on its status:

pending / planning (no PLAN.md yet)

Plan Phase — kicks off a Claude agent that researches how to implement the phase and writes PLAN.md files under .planning/phases/phase-N/. Progress streams in-place.

has PLAN.md files (no tasks yet)

Generate Tasks — parses the PLAN.md files and creates board tasks with wave-based dependencies. The queue picks them up immediately.

completed

Verify — creates a /gsd:verify-work task that re-checks the implementation against the success criteria.

failed

Retry — re-runs task generation from the existing PLAN.md files.

​
Preview parsed tasks

Before committing to Generate Tasks, expand the phase and click Preview parsed tasks. The view fetches the parsed task list from PLAN.md without creating anything, and shows:
  • Tasks grouped by wave (wave N runs after wave N-1)
  • Per task: type badge · name · plan file · files touched · done criteria
Review the list; if it looks right, click Generate N tasks inside the preview to commit. You can close the preview with the × if you want to edit the plans first.

​
.planning/ roadmap header

Above the phases, the .planning/ Roadmap card header shows:
  • Overall progress bar (completed / in-progress / failed / pending)
  • Current phase + current step (from STATE.md)
  • Refresh button to re-read the files from disk
  • Raw toggle — pre-formatted view of the entire ROADMAP.md if you want to see the source

​
Health check

The Roadmap toolbar has a Health button that calls gsd_health_check and reports whether the .planning/ directory is healthy, degraded, or broken — useful after manual edits.

​
Todos

The Todos button lists every todo captured under .planning/todos/pending and .planning/todos/done with their area and preview. Use /gsd:add-todo in a Claude session to capture ideas; they’ll show up here for later review.
GSD integration is optional. Projects without a .planning/ directory still get the Milestone section — you can create milestones, add phases, and run AI planning on a phase without using GSD at all.