Drafts & Proposals
Review Spec-Driven Development changes through private drafts, semantic Change Proposals, and approved apply.
Spec-Driven Development separates drafting from canonical lifecycle records. A draft lets an agent or controlled authoring flow prepare changes without changing the shared Feature. A Change Proposal lets a human review and apply only the approved parts.
Private drafts
A private draft belongs to one user or session and starts from a specific canonical Feature version. Other normal workspace members cannot read that draft while it is open.
Drafts are useful because they let the agent work quickly while keeping the review boundary clear:
- The canonical Spec, Plan, Tasks, and Build Notes stay unchanged.
- Draft changes are grouped by lifecycle record instead of saved per token or keystroke.
- A stale draft can be detected if the canonical Feature version changed after the draft started.
- The draft can be abandoned without touching the canonical Feature.
Spec-Driven Development draft writes are structured batches. Agent output can stream in chat or drawers, but durable database writes are grouped by work product and record key.
Preview changes
When a private draft exists, the Feature detail page can show draft state and preview rows grouped by work product. The preview is semantic: it describes changes such as a task update, a spec section update, or a build-note entry addition.
Previewing does not apply anything. It helps reviewers understand what would be proposed before pushing the draft.
Push to a Change Proposal
Pushing a draft creates a Change Proposal when the draft base version still matches the current canonical Feature version.
If the draft is stale, Integrity blocks a clean push and surfaces the version conflict. That protects against applying changes that were authored against an older Feature state.
Review proposal items
A Change Proposal contains semantic proposal items. Each item has:
- a work product such as Spec, Plan, Tasks, or Build Notes
- a record key and change type
- before and after payloads
- a review status
- conflict state when relevant
Reviewers can accept or reject individual items. This keeps review focused on meaningful lifecycle changes instead of raw markdown line diffs.
Examples:
| Proposal item | Meaning |
|---|---|
spec_section.update | A section of the Spec changed. |
plan_phase.create | A Plan phase was added. |
task.update | A task title, status, acceptance criteria, verification, or evidence changed. |
build_note_entry.create | A build-note entry was added. |
Apply approved items
Applying a proposal is transactional. Approved items update canonical planning records together and advance the Feature version. Rejected or pending items do not become canonical.
The apply flow records:
- the approving human actor
- the source draft and proposal
- the new canonical version
- agent provenance when the changes came from an agent workflow
After apply, stale draft/proposal state is reconciled from planning cache invalidation and realtime updates.
Conflict behavior
Spec-Driven Development uses the draft base version and stable record keys to identify stale changes. When another proposal applies first, a draft from the older base version must be reviewed again instead of being applied blindly.
Agents should not write directly to canonical planning records. They should draft, preview, push, and rely on human review/apply.