Async workplan flow

Read more about SDD in Spec-Driven Development.

Maturity: Still defining

Summary

The async workplan flow refines a work item and generates its Workplan in the background, without Duo Chat. It replaces the earlier plan for an interactive builder, a Duo Chat and live preview UI for iterating on a plan. Instead of one user shaping one plan in a chat session, a user can start several flows in parallel, leave the page, and come back when a flow needs input. Collaboration happens in the work item discussions. See Human in the loop.

Epic: WS-3: Crafting the Workplan. The initial work plan refinement loop is complete; follow-ups continue in the workstream.

Requirements

1. Agents make their own suggestions. When a question comes up, the flow does not stop at the first unknown. It lists its questions, gives options for each, and states its recommendation. This supports both users who trust the agent’s recommendations and users who want to review and iterate before handoff.
2. Notifications are mandatory. When the flow needs input, the user must be notified.
3. Research happens upfront. The Workplan contains as much research as possible, so cheaper models can implement it and humans can review it accurately.
4. Parallel work is considered. If tasks should be done by different sub-agents, the Workplan says so.

Flow

sequenceDiagram
    actor User
    participant WI as Work item
    participant Rails as GitLab Rails
    participant DAP as Duo Agent Platform (workplan/v1)

    User->>WI: Select Plan
    WI->>Rails: WorkItemGenerateWorkplan
    Rails->>DAP: Create and start workflow (runs in CI)
    DAP->>WI: Read work item, comments, and project
    alt Decision needed
        DAP->>WI: Post clarifying question and mention user
        DAP-->>Rails: Status input_required (NEEDS_INPUT)
        User->>WI: Reply to question
        User->>WI: Select Continue
        WI->>Rails: WorkItemResumeWorkplan
        Rails->>DAP: Resume with eligible replies or best-assumptions instruction
    else More context needed
        DAP->>WI: Ask user to expand the description
        DAP-->>Rails: Pause at context_gate
        User->>WI: Update description and select Continue
        WI->>Rails: WorkItemResumeWorkplan
        Rails->>DAP: Resume research with the original goal
    end
    DAP->>WI: Write Workplan
    opt Readiness scoring available
        DAP->>WI: Read plan and context, write score and feedback
    end
    DAP-->>Rails: Status COMPLETED

1. A user selects Plan. The frontend calls the WorkItemGenerateWorkplan mutation.
2. Ai::DuoWorkflows::GenerateWorkplanService starts the workplan/v1 foundational flow for the work item’s project. The flow runs in CI through the Duo Agent Platform. The goal only names the target work item. The flow’s system prompt in AI Gateway defines the plan format, how to handle ambiguity, and when to ask questions.
3. Research gathers requirements, comments, and repository context through GitLab API tools, then passes its findings to the planner. Either stage can post a clarifying question, mention the user, and pause in the input_required state.
4. For clarifying questions, a user replies and selects Continue. The frontend calls WorkItemResumeWorkplan, which forwards eligible replies from users with a project role above Guest. Only flow notes with question payloads are included as questions; progress notes and context requests are excluded. Thread resolution is not required to resume, and unanswered questions do not block it. If there are no eligible replies, the flow is instructed to continue with its best assumptions.
5. If the description lacks enough context to research, either stage routes to context_gate. The user expands the description and selects Continue. The resume service sends the original goal, so research reads the updated work item instead of treating a missing reply as permission to guess. This is implemented in merge request 257208.
6. The planner writes the Workplan and posts a completion comment. When readiness scoring is available, the same flow continues into a scoring stage that writes the score and feedback.

The widget shows progress through generationStatus: NOT_STARTED, GENERATING, NEEDS_INPUT, COMPLETED, CANCELED, or FAILED. Cancellation is distinct from failure (merge request 258021). Starting or resuming a run opens its session in the Duo drawer.

Lifecycle and safety

• Single flow per work item: Only one workplan flow in a non-terminal state can exist per work item. An exclusive lease prevents two concurrent requests from both starting a flow.
• Concurrent flows across work items: Flows on different work items can run at the same time, so a user can refine several work items in parallel.
• Permissions: The work item mutations check update_work_item, but starting a CI flow additionally requires create_duo_workflow_for_ci (currently Developer or above). Resume checks work-item update permission and project remote-flow availability, and keeps the original flow owner’s identity. These boundaries are not yet aligned; the role policy is tracked in issue 634208.
• Answer eligibility: The resume service excludes replies from Guest and lower roles and collects eligible replies regardless of thread resolution. This differs from the question counter, which uses thread resolution. Aligning the two for Guest-authored answers is tracked in issue 631546.
• Project work items only: The flow runs in CI, so group-level work items are not supported.
• Tool approvals: Tools the flow uses must be approved in advance, so the flow does not stop for tool approvals. A dedicated workplan tool may be needed to limit which tools are approved.
• Human input gates: Research, planning, and context gates use external interaction: the user acts on the work item and resumes explicitly. They are not requests to approve or reject a tool call in the session drawer.
• Observability: The flow is instrumented with LangSmith. Tracking events are tracked in issue 631134.

Open work

• Make Workplan research a sub-agent the planner delegates to
• Hand the open questions to the flow at trigger time
• Pass the triggering user in the goal
• Automatically start planning for work items created through Duo Chat
• Post flow comments as resolvable discussions, together with work item UI support for resolving a discussion before its first reply

Decisions

View page source - Edit this page - please contribute.