Project graph
Use Spec-Driven Development roadmap relationships, Graph, Gantt, Outline, Log, and PNG exports.
The Planning roadmap graph is the roadmap substrate behind Spec-Driven Development. It shows how project work relates over time: which shipped work enables active work, which Projects 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, history events, and visual evidence.
Initiatives
An Initiative groups related Spec-Driven Development Projects for roadmap planning. Initiatives do not have their own Spec, Plan, Tasks, or Build Notes. The Projects 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 Projects homed inside them. |
| Unassigned | Projects with no active Initiative membership. |
A Project 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.
Project relationships
Relationships are typed graph edges between Projects.
| Type | Use it when |
|---|---|
parent_child | One Project decomposes, extends, patches, or follows up another. One primary parent can be selected for tree rendering. |
depends_on | The source Project needs the target Project before it can land. The inverse is shown as "blocks". |
extends | The source Project builds on the target without becoming a child. |
supersedes | The source Project materially replaces or revises the target's shipped contract. |
touches | The source Project changes or affects another area without owning it. |
related_to | The Projects 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.
In the current Project relationship controls, Related is the non-blocking connection. Completing, canceling, or archiving a blocking Project converts each incoming depends_on edge to Related. That conversion leaves the dependent Project's status and dates alone, and reopening the blocker does not recreate the dependency. The Project table can filter by Blocked by, Blocking, Related, or With relations; its relation badge counts open blockers in red, then the Projects each one blocks and its related Projects.
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 Project 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 Project superseded or carried forward another?
- Where do cross-cutting touches exist?
Click a node to open relationship context.
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 roadmap history. |
Workspace admins can edit dates from Gantt and relationships from the relationship panel. Normal workspace members can read roadmap state.
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.
Project 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 Initiatives | Workspace members and admins |
| Edit Initiative metadata, including owner, Team, status, dates, and existing label assignments | Workspace members |
| Add or remove a Project from an Initiative | Workspace members who can edit Projects |
| Set, change, or clear Project Start and Target dates | Workspace members who can edit Projects |
| 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 Projects, 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.