Planning Substrate
Understand the planning lifecycle and roadmap substrate behind Spec-Driven Development.
The planning substrate behind Spec-Driven Development stores Projects, Specs, Plans, Tasks, Build Notes, Change Proposals, and the roadmap graph that explains how Projects relate.
Use Spec-Driven Development in the workspace sidebar for daily navigation. The underlying database still uses the historical project_file_* table and realtime namespace; that is an internal storage boundary, not a separate workspace navigation surface.
Spec-Driven Development is not a general file manager. In this release you create Projects and Initiatives; Projects get the standard lifecycle work products, and Initiatives group Projects for roadmap planning. You cannot create arbitrary folders, custom files, or generic document nodes.
How the substrate is reached
The visible workspace navigation is:
Spec-Driven Development
Initiatives
Projects
TimelineThe dedicated Initiatives and Projects pages render full-width tables. Timeline opens the current roadmap entry point backed by planning roadmap state. The old /project-files route family has been retired; use the Spec-Driven Development routes instead.
Every Project has one home placement in the tree:
- A Project with a primary initiative membership is shown under that Initiative.
- A Project with no active initiative membership is shown under Unassigned.
- A Project that belongs to more than one Initiative is shown once at home and appears elsewhere only as a muted linked reference back to its home row.
What a Project contains
Each Project is a durable container with an immutable slug, editable title, lifecycle status, canonical version, and standard work products.
| Work product | What it is for |
|---|---|
| Spec | Problem, goals, scope, workflows, data model, permissions, docs impact, and architecture impact. |
| Plan | Implementation phases, dependencies, checkpoints, testing strategy, and closeout work. |
| Tasks | Phase-grouped checklist items with acceptance criteria, verification, and evidence. |
| Build Notes | Implementation decisions, changed files, verification commands, and skipped checks. |
| Proposals | Semantic changes pushed from private drafts for review and apply. |
| Activity | Version, proposal, and seed/MCP-managed local repo sync metadata history. |
Integrity stores the Spec, Plan, Tasks, and Build Notes when a lifecycle command synchronizes the repository packet. A connected coding agent can read the stored copies, but the Project detail page does not display them yet. See Lifecycle documents.
What an Initiative contains
An Initiative is a roadmap container for related Projects. It does not have its own Spec, Plan, Tasks, or Build Notes packet. It exists to help teams inspect sequencing, dependencies, scope, and status across Projects that already carry their own lifecycle evidence.
Initiatives include roadmap views:
| View | What it is for |
|---|---|
| Graph | Default relationship map for deciding what is blocked, ready, current, superseded, or carried forward. |
| Gantt | Planned and actual planning-owned roadmap dates. |
| Outline | Parent/child decomposition only. Cross-cutting links are not forced into the tree. |
| Log | History events for initiative, membership, relationship, date, supersession, and export changes. |
See Roadmap Graph for details.
Open lifecycle work
- Open a workspace.
- Expand Spec-Driven Development in the workspace sidebar.
- Open Initiatives or Projects for the full-width tables.
- Open an Initiative or Project to inspect its roadmap context.
The planning graph is semantic, not a file explorer:
Spec-Driven Development
Initiatives
initiative-slug
feature-slug
Unassigned
feature-slugProject rows open Project detail, which shows Overview, Activity, and Issues. Initiative rows open Initiative detail with the scoped Project list and planning context.
Create a Project
- Open Spec-Driven Development -> Projects.
- Use the create action when it is available for your role.
- Enter the Project title.
- Create the Project.
Integrity creates the Project slug and standard lifecycle work products. The slug stays immutable so proposals, local snapshot metadata, and audit history have a stable identity.
Work with roadmap membership
Workspace admins can manage roadmap membership from Spec-Driven Development controls:
- Right-click an Initiative to add an existing Project.
- Right-click a Project to move its home Initiative, link it to another Initiative, or remove it from one or all Initiatives.
- Right-click a linked reference to go to the home Project, make the current Initiative the home, or unlink it.
Membership changes are roadmap state, not lifecycle record edits. They are permission-gated and reconcile through planning roadmap realtime updates.
How authoring works
Spec-Driven Development is designed for chat-assisted authoring and human review. In this release, broad Spec and Plan authoring is draft-backed and proposal-backed rather than a free-form manual editor that mutates canonical records directly.
The normal lifecycle is:
- An agent or controlled authoring flow creates a private draft.
- Draft changes are persisted as structured batches.
- The draft is pushed to a Change Proposal.
- A human reviews semantic proposal items.
- Approved items are applied to the canonical Project version.
- MCP-managed local repo sync can write repo files when explicitly invoked outside the web app.
Do not treat repo markdown as a second source of truth. Planning records are canonical inside the app; local repo file sync is handled outside the web app by the MCP bridge.