Roadmap Graph
Use Spec-Driven Development roadmap relationships, Graph, Gantt, Outline, Log, Lineage, and PNG exports.
The Planning roadmap graph is the roadmap substrate behind Spec-Driven Development. It shows how feature work relates over time: which shipped work enables active work, which Features are children or follow-ups, which dependencies block progress, what was superseded, and what context was carried forward.
Roadmap graph state is app-owned. Repo Specs can carry lightweight metadata hints for import or agent context, but the Spec-Driven Development database is the source of truth once roadmap state exists.
Spec-Driven Development complements Notion. Notion remains the backlog and priority planning hub; Spec-Driven Development owns execution relationships, roadmap dates, traceability events, and visual evidence.
Initiatives
An Initiative groups related Spec-Driven Development Features for roadmap planning. Initiatives do not have their own Spec, Plan, Tasks, or Build Notes. The Features inside them still carry the durable lifecycle evidence.
Use Initiatives for work such as:
- a product area or delivery theme
- a release slice
- a dogfooding roadmap
- a dependency cluster that should be explained together
The compatibility planning navigator has two top-level folders:
| Folder | Meaning |
|---|---|
| Initiatives | Initiative folders and the Features homed inside them. |
| Unassigned | Features with no active Initiative membership. |
A Feature can belong to more than one Initiative, but it appears as a full row only under its home Initiative. Other Initiative memberships appear as muted linked references back to the home row.
Feature relationships
Relationships are typed graph edges between Features.
| Type | Use it when |
|---|---|
parent_child | One Feature decomposes, extends, patches, or follows up another. One primary parent can be selected for tree rendering. |
depends_on | The source Feature needs the target Feature before it can land. The inverse is shown as "blocks". |
extends | The source Feature builds on the target without becoming a child. |
supersedes | The source Feature materially replaces or revises the target's shipped contract. |
touches | The source Feature changes or affects another area without owning it. |
related_to | The Features have useful context but no ordering or ownership. |
carried_forward_from | Follow-up work remains valid after a parent was superseded and is carried to the successor. |
High-impact relationship changes require a reason. That includes supersession, carry-forward, and primary parent changes.
Supersession does not automatically delete or obsolete children. Child disposition is an explicit review decision: carry forward, keep attached, promote, or obsolete with a reason.
Graph view
Graph is the first and default Initiative view. It renders a dense relationship map with typed edges, status styling, blocker/ready badges, and an in-canvas legend.
Graph starts in Now scope: the selected or current in-progress Feature plus one upstream and one downstream hop. Switch to All when you need the full Initiative graph.
Use Graph to answer:
- What can move next?
- What is blocked?
- What shipped foundation enables this work?
- Which Feature superseded or carried forward another?
- Where do cross-cutting touches exist?
Click a node to open relationship context. Use Open lineage to jump to that Feature's Lineage tab inside the current lifecycle shell.
Gantt, Outline, and Log
Roadmap views answer different questions:
| View | Best for | Notes |
|---|---|---|
| Gantt | Planned and actual timing. | Dates are planning-owned and can be set manually or through approved proposals. They do not sync from Notion in v1. |
| Outline | Parent/child decomposition. | Only parent_child relationships are shown, so cross-cutting links are not forced into a fake tree. |
| Log | Why roadmap state changed. | Relationship, date, carry-forward, supersession, membership, and export events appear as traceability history. |
Workspace admins can edit dates from Gantt and relationships from the relationship panel. Normal workspace members can read roadmap state.
Lineage tab
Every Feature has a Lineage tab. Lineage uses the same graph renderer as the Initiative Graph, but the scope is centered on one Feature.
Lineage shows:
- parent chain and children
- dependencies and blockers
- supersedes and superseded-by context
- touched and related work
- carried-forward follow-ups
Lineage is useful when you need to explain why a Feature exists before reading its Spec, Plan, Tasks, or Build Notes.
Exports
Workspace admins can use the export icons on an Initiative to download:
- a PNG of the current visual view
- a management snapshot PNG with the title, summary, graph counts, timeline summary, blockers, and follow-ups
Exports are local downloads. They do not create public share links. Export metadata is recorded so the Log can show export history.
Feature creation and property controls appear only when your current access allows editing. If access changes while an editor is open, it closes; reopen it after editing access is restored.
Permissions
planning roadmap graph state is workspace-scoped.
| Action | Who can do it |
|---|---|
| Read Initiatives, relationships, dates, events, and exports | Workspace members |
| Create/update Initiatives | Workspace admins |
| Add or remove a Feature from an Initiative | Workspace members who can edit Features |
| Set, change, or clear Feature Start and Target dates | Workspace members who can edit Features |
| Add/remove relationships or change roadmap structure | Workspace admins |
| Apply approved roadmap proposals | Workspace admins |
| Download roadmap PNG exports | Workspace admins |
The UI hides or disables mutation controls for users without permission, and database RLS enforces the same boundary.
Repo metadata and seeding
Repo Specs may include a Project Files Metadata block with hints such as Initiative, parent, relationship type, related Features, and roadmap date placeholders. Those hints help agents and controlled seed tools bootstrap roadmap state.
After the graph is seeded or edited in the app, the planning database remains authoritative. Do not treat the repo metadata block as a live sync source or a hidden parallel roadmap model.