A task is one ## N. section of tasks.md. Running it means the agent implements every checkbox in that section — and nothing outside it — then stops for review.

What a task is

OpenSpec writes tasks.md as numbered sections of fine-grained checkboxes:

## 1. Search index
- [ ] 1.1 Add a full-text index migration for listings(title, description)
- [ ] 1.2 Extend ListingRepository with a search query

## 2. Search API
- [ ] 2.1 …

A single checkbox is a line-or-two edit; a section is a coherent piece of work with a natural review point. So SpecBuddy runs sections: each gets its own snapshot before and after, its own diff review, its own rollback point. The agent ticks the checkboxes as it completes them, and the section is done when all of them are.

The prompt the agent receives is /opsx:apply scoped to the section — implement only this section, tick each checkbox as you complete it, stop as soon as the section is complete, do not modify the proposal, deltas or tasks.md otherwise.

Starting a run

Three places, same result:

• Editor banner over tasks.md: Step 2 of 4 completed · Run next step.
• Cockpit (Live tab): ▷ on a task row runs that task; ▷ in the header runs the next pending one.
• Task card in the editor: every section heading in tasks.md carries a small status card with the same run control.

Before the first run of a change, SpecBuddy asks where the code should go — current branch or a dedicated worktree. See Worktrees and git.

Tasks don’t have to run in order. Clicking ▷ on task 3 while 2 is pending offers Run this step or Run all steps up to this step. Skipping is legitimate when sections are independent; the agent only ever sees the section you point it at.

Running several in a row

• ▷▷ Run All in the Cockpit header runs every pending task in sequence.
• Run all steps up to this step on a task row runs the pending tasks before it, then it, and stops.

Between tasks the chain does not pause for review — the previous task’s result is kept and the next one starts. The tasks still queued are marked Queued in the Cockpit; Cancel from here on a queued row stops the chain after the task before it, and Cancel Auto-Run — stops after: … in the header cancels the rest. Cancelling never interrupts the task that is currently running.

Run All is a bet that the plan is good. It usually is, once you’ve read it — but the first change on a new codebase is a poor place to make it.

While it runs

• The Agent Log tab shows the run live; a Stop button in its header cancels the current turn. See The Agent Log.
• The Cockpit’s status chip says Running, the Explorer row Running: ## 2. Search API, and the task card in the editor RUNNING.
• If the agent asks a question or requests a permission, the Explorer icon switches to awaiting input, the IDE shows a notification, and the log has the card to answer. A task can wait like this indefinitely — it does not time out.
• Another run on the same change is refused while one is live (Another action is already in progress for this change). Runs on different changes are independent and can proceed in parallel, each in its own worktree and log.

Task states

A done row keeps its actions: Refine stays available on every done task; Rollback only on the last completed one. See The review gate.

Re-running a done task

The re-run control on a done row runs the section again from the current state — it does not roll back first. Use it after editing the section by hand (the outdated case) or when a later task revealed the earlier one was incomplete. If you want the code as it was before the task, roll back, then run.

Keep the headings stable

Run history is keyed by the section heading text — ## 2. Search API, verbatim. Rename or renumber a heading and SpecBuddy sees a new, never-run task where the old one used to be; the old run’s snapshots are still in History, but the row loses its done state. Reword checkboxes freely; leave the ## lines alone once a task has run.