Workplan

A workplan is a structured Markdown document attached to a work item. It captures the intent, approach, and steps for a unit of work.

A workplan provides GitLab Duo agents with an agreed specification and a human-reviewable artifact on the work item. With this context, an agent has more to work from than a short prompt, so it can run the work more accurately.

You create a workplan with GitLab Duo or write one manually. GitLab Duo drafts the workplan from the work item context, and you refine it. Agents then use the workplan as the primary specification for the work.

The workplan is part of the GitLab Duo Agent Platform and the specification-driven development workflow.

The Workplan widget appears on the work item and shows the workplan status:

• Not yet created: The work item has no workplan, and you can create one.
• No workplan: The work item has no workplan, and you do not have permission to create one.
• Ready to view: The work item has a workplan.

When to use a workplan

Use a workplan when you plan to give work to an agent, either by selecting Implement workplan or by providing the plan to a coding agent yourself. A workplan adds the most value when an agent runs the work.

You do not need a workplan for small or well-understood changes, where planning adds more effort than it saves.

Create a workplan

Create a workplan to describe how to complete a unit of work.

Prerequisites:

• Permission to edit the work item.

You can generate a workplan with GitLab Duo or write one manually.

Generate a workplan with GitLab Duo

Prerequisites:

• GitLab Duo Chat turned on.

To generate a workplan with GitLab Duo:

1. On the work item, in the Workplan widget, select Generate workplan.
2. In GitLab Duo Chat, answer the Planner Agent questions until the agent has enough context.
3. Review the proposed plan and approve it.

After you approve the plan, GitLab Duo writes it to the Workplan widget.

Create a workplan manually

To create a workplan manually:

1. On the work item, in the Workplan widget, select More options > Create manually.
2. Optional. From the template dropdown list, select a workplan template.
3. Enter the workplan content. To switch between editors, select Switch to rich text editing or Switch to plain text editing.
4. Select Save changes.

Workplan templates are description templates with filenames that end in .plan.

View a workplan

To view a workplan:

• On the work item, in the Workplan widget, select View workplan.

The workplan opens in a panel and shows the rendered content.

Edit a workplan

Prerequisites:

• Permission to edit the work item.

To edit a workplan:

1. On the work item, in the Workplan widget, select View workplan.
2. In the panel, select Edit.
3. Make your changes.
4. Select Save changes.

To discard your changes, select Cancel.

Regenerate a workplan

Regenerate a workplan to replace its content with a new version from GitLab Duo.

Prerequisites:

• Permission to edit the work item.

To regenerate a workplan:

1. On the work item, in the Workplan widget, select View workplan.
2. In the panel, select More actions ( ) > Regenerate workplan.
3. In GitLab Duo Chat, answer the Planner Agent questions until the agent has enough context.

GitLab Duo replaces the existing workplan with the new version.

Delete a workplan

Prerequisites:

• Permission to edit the work item.

To delete a workplan:

1. On the work item, in the Workplan widget, select View workplan.
2. In the panel, select More actions ( ) > Delete workplan.
3. In the confirmation dialog, select Delete.

This action cannot be undone.

Implement a workplan with GitLab Duo

When a workplan exists, GitLab Duo can implement it in a merge request. GitLab Duo treats the workplan as the primary specification and uses the work item description and comments only for additional context.

Prerequisites:

• GitLab Duo Agent Platform remote flows turned on.

To implement a workplan with GitLab Duo:

• On the work item, in the Workplan widget, select Implement workplan.

Related topics

• GitLab Duo Agent Platform
• Planner Agent
• Description templates
• Work items