Spec, Plan, Build workflow

Spec, Plan, Build is the built-in workflow of OpenDucktor. A task gets a spec, a plan, a build, a QA review, and then your review. For the board, the task details, and the actions that every workflow shares, see Tasks and workflows.

Steps and rolesCopy Anchor Link

The workflow has four agent steps, then your approval. Each step saves an artifact that the next step reads, and the task moves to the next lane.

The workflow in actionCopy Anchor Link

export function useSearchShortcut(openSearch: () => void): void;

export function useSearchShortcut(openSearch: () => void): void;

if (target.closest(textFields)) return;
event.preventDefault();
openSearch();

Issue typesCopy Anchor Link

Spec and planCopy Anchor Link

1. On the card in Backlog, select Start Spec, then Start session.
2. Answer the questions of the Spec agent. When it saves the Specification, the task moves to Spec Ready.
3. Read the Specification in the Artifacts tab. To change it, ask the Spec agent in its session, or edit it.
4. Select Start Planner. When the Planner saves the Implementation Plan, the task moves to Ready for Dev.
5. Read the Implementation Plan, then select Start Builder. On the session page, this button shows Start Implementation.

A later save of the spec or the plan does not move the task.

To let the Builder work until a goal is met, turn on Goal mode in the start dialog. See Work toward a goal.

BuildCopy Anchor Link

The Builder writes the code and the tests in the task worktree, then commits on the task branch. While it works, the task is in In Progress. When it finishes, it sends the Build Completed workflow event with a summary note, and the task moves to AI Review.

Blocked tasksCopy Anchor Link

When the Builder needs your input, it sends the Build Blocked workflow event with the reason in its note. The task moves to Blocked / Needs Input.

1. On the card, select Open Builder.
2. Read the note on the Build Blocked card, then answer in the session.

When the Builder continues, it sends Build Resumed, and the task goes back to In Progress.

QA reviewCopy Anchor Link

In AI Review, select Request QA Review. The QA agent checks the build against the spec and the plan, then saves a QA Report with its verdict:

• Approved: the task moves to Human Review.
• Rejected: the task goes back to In Progress, and its card shows the QA Rejected badge.

QA review is optional. To skip it, open the menu next to the main button, then select Approve Task or Request Changes.

Fix a QA rejectionCopy Anchor Link

1. Select Address QA Feedbacks.
2. In the dialog, select Reuse existing to continue the Builder session, or Start fresh. You can also turn on Goal mode.

The Builder fixes the findings. Then the task goes back to AI Review.

Human reviewCopy Anchor Link

In Human Review, read the changes in the Diffs tab and the QA Report in the Artifacts tab. To comment on a line of the diff, see Review the work.

Approve a taskCopy Anchor Link

On the task card, select Approve Task. On the session page, the main button is Generate Pull Request until the task has a pull request. Approve Task is then in the menu next to it. The Builder writes the pull request in a fork of its last session. For each approval choice, see Approve a task.

Request changesCopy Anchor Link

You can request changes in AI Review or Human Review.

1. Select Request Changes. If the main button shows another action, open the menu next to it.
2. In Your feedback, describe the changes, then select Request changes.
3. In the dialog, select Reuse existing to continue the Builder session, or Start fresh. You can also turn on Goal mode.

When the Builder session starts, the task goes back to In Progress. If you cancel the session start, the task keeps its lane, and the form keeps your feedback. While a session of the task runs, the session page cannot request changes, and the menu shows Wait for the current session to finish.

If the task has an approved QA Report, it goes back to Human Review when the Builder finishes. QA does not run again. To run QA on the new build, select Request QA Review.

Lanes and movesCopy Anchor Link

Agents move a task when they save an artifact or send a workflow event. You move it with an action.

Some moves are not in the diagram:

• A task or a bug in Backlog goes to Ready for Dev when the Planner saves its plan, or to In Progress when the Builder starts.
• Build Completed moves a task to Human Review instead of AI Review when its last QA Report is Approved.
• QA can also run in Blocked / Needs Input and Human Review. Its verdict moves the task as in AI Review.
• Request Changes also works in AI Review.
• Close Task, Reset Task, and Reset Implementation can move a task from most lanes. See Reset, close, or delete a task.

Actions of each laneCopy Anchor Link

The card shows the main action of its lane. The menu next to it and the task details list the other actions that the task allows now.

Reset ImplementationCopy Anchor Link

Reset Implementation starts the build again from the plan. It is in the More menu of the task details, in In Progress, Blocked / Needs Input, AI Review, and Human Review.

It deletes the Builder and QA sessions, the QA reports, and the pull request link. It keeps the spec, the plan, the other artifacts, and the worktree. If a direct merge waits for its push, it also deletes the record of that merge. The merge commit stays on the local target branch.

The task goes back to Ready for Dev. If the task has no plan, it goes back to Spec Ready when it has a spec, or else to Backlog.

Autopilot rulesCopy Anchor Link

Spec, Plan, Build has five Autopilot rules. With all of them on, you start the first agent and approve the task. Autopilot starts the other steps.

Settings shows each rule by its event. Each rule has one action:

• When a task progresses to Spec Ready: Start Planner starts the Planner in a fresh session.
• When a task progresses to Ready for Dev: Start Builder starts the Builder in a fresh session.
• When a task progresses to AI Review: Start QA continues the last QA session of the task, or starts a fresh one.
• When a task is rejected by QA: Fix QA Rejection continues the last Builder session, or starts a fresh one, to fix the findings.
• When a task progresses to Human Review: Generate Pull Request forks the last Builder session to create or update the pull request. It needs a Git provider.

Autopilot never starts a session in Goal mode.

Only an agent sends these events: a spec save in Backlog, a plan save in Backlog or Spec Ready, a finished build, and a QA verdict. Reset Implementation, a direct merge, and Request Changes start nothing. After Request Changes, the next finished build sends the AI Review or the Human Review event.

When QA rejects a taskCopy Anchor Link

With the QA rejection rule and the AI Review rule on, the Builder fixes the findings, and then QA reviews the task again.

By default, QA reviews the fix in its last session. To give each QA review a new session, turn on Always start QA reviews in a fresh session.

This loop has no limit. If QA reports the same findings again, set the QA rejection rule to Disabled. To fix the findings yourself, see Fix a QA rejection.

NextCopy Anchor Link