Workplan

Design for the Workplan, the Markdown artifact on a work item that captures the How of the work and is consumed by downstream agents.

Read more about SDD in Spec-Driven Development.

Maturity: Mature

Summary

The Workplan is a Markdown document attached to a work item. It is the core artifact of the SDD flow: shaped by humans and agents, then consumed downstream by Duo Developer or any other agent.

The work item description (the spec) captures the Why and the What. The Workplan captures only the How. Changes to the Why or What belong in the description, and the Workplan follows from it. Updating the generation prompt so the Workplan focuses on the How is tracked in issue 630891.

Epic: WS-2: Crafting the user journey of spec to code

User documentation: Workplan

Naming

The plan is named Workplan, written as one word. The parent widget is named Implementation. AgentPlan is the legacy code name and still appears in the backend and in GraphQL. Aligning the backend naming, including API compatibility, the database table, and object storage paths, is tracked in issue 630474.

Data model

Workplans are stored in a separate table, work_item_agent_plans, joined to the work item by work_item_id. The issues table is too large to extend directly. The Workplan content and the readiness score feedback can be stored in object storage, so reading them can cost a network round-trip. Avoiding that round-trip when only content existence is needed is tracked in issue 616229.

The table also stores whether AI planning is enabled for the work item (ai_planning_enabled) and the readiness score.

API surface

The Workplan is exposed through the WorkItemWidgetAgentPlan GraphQL widget type. Main fields:

Field	Description
`aiPlanningEnabled`	Whether AI planning is turned on for the work item.
`content`, `contentHtml`	The Workplan Markdown and its rendered HTML. Resolvable for only one work item per request.
`generationStatus`	Status of the most recent `workplan/v1` flow: `NOT_STARTED`, `GENERATING`, `NEEDS_INPUT`, `COMPLETED`, `CANCELED`, or `FAILED`.
`questions`, `openQuestionsCount`	Flow-note threads across all workplan runs, ordered oldest first, with answered state and open count based on thread resolution. Resolvable for only one work item per request. See question navigation and its current limitations.
`readinessScore`, `readinessScoreFeedback`, `readinessScoreFeedbackHtml`	The readiness score, its Markdown explanation, and rendered HTML. Feedback is resolvable for only one work item per request and is fetched when the readiness drawer opens.

The async flow is started and resumed with the WorkItemGenerateWorkplan and WorkItemResumeWorkplan mutations. See Async workplan flow.

The Workplan is also readable and writable through the MCP work item tools, so external agents and tools can use it.

The Implementation widget is hidden by default. A user turns on AI planning for a work item by selecting Plan. After that, the widget shows:

The Workplan status: not yet created, reviewing the work item, generating, awaiting input, ready for review, canceled, or failed.
The readiness level, after a score exists.
Open-question count and navigation while the flow awaits input.
Actions to view, edit, regenerate, and delete the Workplan, and to Implement it.

Starting or resuming a flow opens its session in the Duo drawer. This includes Plan, Generate, Regenerate, Try again, and Continue. The generated Workplan opens only when requested, so completing a background run does not interrupt the user. A direct session shortcut on the status indicator remains a follow-up in issue 631233.

The Workplan opens in a side panel. A user can also create a Workplan manually, optionally from a template. Workplan templates are description templates with filenames that end in .plan.

Showing the Implementation widget only when a user starts the AI-driven flow was decided in issue 605174. After planning is turned on, it cannot be turned off.

Generation

Plan starts the async workplan/v1 flow, which refines the work item, asks clarifying questions when needed, and writes the Workplan. See Async workplan flow and Human in the loop.

Permissions and feature gating

Licensed feature: The Workplan is available in the Premium and Ultimate tiers and reuses the ai_workflows licensed feature.
Work item types: Issues and tasks, including issues with child tasks.
User permissions: Creating and editing a Workplan requires permission to update the work item. Generation also passes through the CI flow permission, create_duo_workflow_for_ci, which currently requires Developer or above. The frontend and work item mutations still check update_work_item, so showing an action does not guarantee the user can run it. Aligning generation, resume, and implementation permissions is tracked in issue 634208.
Duo availability: Generating a Workplan requires the Duo Agent Platform and the workplan/v1 foundational flow to be available. Disabling the Plan button when the foundational flow is unavailable is planned in issue 629825; the button does not yet check flow availability.

Open follow-ups:

Load Workplan content on demand and use a content-existence field for widget state
Show Workplan creation and update timestamps
Direct-to-implementation entry from the Plan button
Closed-work-item behavior for planning controls. The Implement button is already hidden on closed items; the remaining planning controls are separate follow-ups.
Add a hasAgentPlan type policy once the widgets field is retired

Decisions

Date	Decision	Who
2026-03-30	The plan is not a standalone entity. It is a widget on the work item.	Workshop
2026-03-31	Output format is Markdown, shaped by work item templates.	@fredericcaplette
2026-04-09	Use sync Duo Chat for AI interactions on the work item. Superseded by the async workplan flow.	@vanessaotto, @fredericcaplette
2026-04-09	Markdown over YAML for simplicity and human readability.	@fredericcaplette, @vanessaotto, @timzallmann
2026-04-09	Named “Agent plan” for the first iteration. Superseded by Workplan.	@izzychu, @fredericcaplette
2026-04-16	Stored in a separate table joined to the work item (issues table too large to extend).	@fredericcaplette
2026-04-16	AI Gateway will expand the existing work item tool (not create a new tool) to read and write the plan.	@fredericcaplette
2026-04-16	Content is stored and served as raw Markdown. No structured schema or YAML front matter.	@fredericcaplette
2026-09-09	The widget appears only after a user turns on AI planning for the work item.	WS-2
2026-09-22	The plan is named Workplan, written as one word. The parent widget is named Implementation.	@nickbrandt, @brendan777

Last modified October 20, 2026: Update Spec-Driven Development design document (0259db05)

View page source - Edit this page - please contribute.