SpecBuddy drives your coding agent through an OpenSpec change from inside IntelliJ IDEA: the agent proposes the change, you review the documents, then the agent implements the tasks one at a time and every task ends behind a diff you look at before anything moves on.

The loop

YOU Describe the change New OpenSpec Change AGENT Propose proposal · specs · tasks YOU Review the docs comment · refine AGENT · WORKTREE Run one task one section of tasks.md YOU Review the diff refine · roll back · go on AGENT Finish the change sync · archive · merge next task all tasks done
  1. Describe what you want in the New OpenSpec Change tab — a paragraph is enough.
  2. Propose. The agent explores the project and writes the change under openspec/changes/<id>/: a proposal.md, spec deltas for the capabilities it touches, an optional design.md, and a tasks.md checklist.
  3. Review the documents. Read them in the editor, leave inline comments, and ask the agent to refine — before a single line of code is written.
  4. Run one task. Each ## N. section of tasks.md is one run. The agent implements it in a dedicated git worktree, so your own working tree is untouched.
  5. Review the diff. Every run ends in review: the files it changed, a diff per file, and the choice to refine it, roll it back, or move on to the next task.
  6. Finish the change. Sync the spec deltas into your main specs, archive the change, and merge the worktree branch — each as a click, each with a log you can read afterwards.

What you look at

SpecBuddy adds four surfaces to the IDE. You’ll use all of them, but never at once.

SurfaceWhereWhat it is for
Spec ExplorerLeft tool windowEvery change and spec in the project, with its state; start a new change here.
EditorYour Markdown filesA banner over tasks.md with the next action, a status card on every task, gutter icons for comments and spec navigation.
Spec CockpitRight tool windowActions for the current change, the task list, the diff of the last run, documents, comments, history.
Agent LogAn editor tabWhat the agent is doing right now, as it does it — and a chat box to talk to it.

Three things worth knowing up front

The agent works inside the IDE. With an ACP-capable agent — Claude Code, Codex, OpenCode or Cursor — the session is a headless process, and the Agent Log tab is its face: file reads, edits with diffs, commands, questions it asks you, and a chat box. The legacy option of running the CLI in a terminal tab still exists, but this documentation assumes the in-IDE mode.

Code runs in a worktree, not in your working tree. The first time a change runs a task, SpecBuddy asks whether to run in the current branch or to create a dedicated git worktree on its own branch (feature/<change> by default). Choose the worktree and you can keep editing, building and committing in your own tree while the agent works — and merge when the change is done.

Nothing is final until you say so. Every run records a snapshot before and after it, so a task can be rolled back to the exact state it started from, and a proposal or refine can be diffed against what the documents looked like before. The agent never merges into your branch on its own.

Terminology

OpenSpec calls an item of work a task; a few SpecBuddy controls still say step (the same word it uses for its own Markdown-spec format). They mean the same thing: one ## N. section of tasks.md, run as one unit.

Next: Install and set up, then the Quickstart.