This walkthrough takes one change all the way through: describing it, reviewing the agent’s proposal, running its tasks one by one, and finishing with sync, archive and merge. The project is Vitrino, a small classifieds marketplace; the change adds full-text search to listings. Your project will differ, the clicks won’t.

Before you start, make sure installation and setup is done: the plugin is installed, an agent is configured, and the project has an openspec/ folder.

1. Describe the change

Open the Spec Explorer (left tool window), click + on its toolbar and choose New OpenSpec Change. An editor tab opens with one hint — Describe your proposal – the change to implement in your project — and a Markdown editor.

Write what you want, the way you’d brief a colleague:

Add full-text search to listings.

Buyers should find listings by words in the title and description, not only
by category. Search is a text field on the listings page; results keep the
existing filters and sorting. Ranking: title matches first, then description.
Use the database we already have — no new search service.

Press Propose change (or Shift+Enter). There is no field for the change id — OpenSpec derives it from the proposal, here add-full-text-listing-search.

If you’d rather think it through with the agent first, Run Explore starts an exploration session over the same draft instead: the agent investigates the codebase and discusses options with you in the log’s chat, without writing a change. Propose when you’re ready.

2. Watch the proposal being written

An Agent Log tab opens. The agent reads the project, and you see each thing it does as a card: files it reads, commands it runs, and the files it writes — as condensed diffs. A new row, add-full-text-listing-search, appears in the Spec Explorer as soon as the change directory exists, and fills in as documents land.

The run ends with a completion card listing what was created:

openspec/changes/add-full-text-listing-search/
  proposal.md                          why, what, and what is out of scope
  design.md                            the technical approach (optional)
  specs/listing-search/spec.md         a spec delta: ADDED requirements
  specs/listing-management/spec.md     a spec delta: MODIFIED requirement
  tasks.md                             the implementation checklist

The Explorer row now reads 0/4 Tasks — proposed, nothing run yet.

3. Review the documents

This is the point of the whole exercise: catch the wrong turn here, not in a pull request.

Expand the change in the Spec Explorer and open proposal.md. Then the deltas under specs/, then tasks.md. The Spec Cockpit on the right follows whatever you open; its Docs tab lists the change’s documents and, for each delta, the main spec it modifies (or new capability).

Suppose the delta puts ranking in the database layer and you want it in the query service instead. Put the caret on the requirement, click the balloon icon that appears in the gutter, type the comment and press Shift+Enter. The comment sits under the line as an inline card and is counted in the Cockpit’s Comments tab.

Now press Refine Spec in the Cockpit. The agent gets your comments with the pointers to the exact lines, rewrites the affected documents, and the log’s completion card shows what changed. Repeat until the proposal says what you mean. When it does, there is nothing to press — you simply move on to running it.

4. Run the first task

Open tasks.md. It is a checklist in numbered sections, and each section is one run:

## 1. Search index
- [ ] 1.1 Add a full-text index migration for listings(title, description)
- [ ] 1.2 …

## 2. Search query
…

A banner over the file says Step 0 of 4 completed with a Run next step link; the Cockpit shows the same list with a ▷ on every row. Click either.

The first run of a change asks where its code should go:

“add-full-text-listing-search” has not run a step yet. Where should its steps run? Continue in current branch · Create Worktree · Cancel

Choose Create Worktree. SpecBuddy creates a git worktree on a feature/add-full-text-listing-search branch — outside the project directory — and every task of this change runs there from now on. Your own working tree stays exactly as it is. (The choice is remembered per change; see Worktrees and git for the alternative.)

The Agent Log switches to the task: the agent implements section 1, ticking its checkboxes as it goes. If it needs a permission or has a question, a card appears in the log and the IDE notifies you — answer there. The Explorer row shows Running: ## 1. Search index.

5. Review the diff

When the agent stops, the change is in Review. The Cockpit’s Live tab shows the task with a check mark, its duration and file count, and — below the list — the files this run changed, with added/removed line counts. Double-click a file to open its diff. You can comment in the diff viewer exactly as in the editor.

You have three ways forward:

  • Move on — click ▷ on the next task (or Run next step in the banner). Running the next task keeps this one’s result; there is no separate “accept” button.
  • Refine — the row’s refine control offers Refine Code (re-run this task with your comments; the plan stays), Refine Plan and Code (revise this section of tasks.md, then re-run it), or Rollback Code and Refine Plan (undo the code first, then revise the section).
  • Rollback — undo the task’s changes to the exact pre-run state. Only the last completed task can be rolled back, since undoing an earlier one would pull the rug from under the later ones.

The done row’s check mark turns into a warning if you later edit that section of tasks.md: the task ran against a plan that has since changed — run it again to refresh.

6. Run the rest

Work through tasks 2–4 the same way. If the plan looks solid and you’d rather review at the end, ▷▷ Run All in the Cockpit runs every pending task in sequence, moving on automatically between them; the queued rows are marked, and Cancel from here on any of them stops the chain after the task before it. Clicking ▷ on a later task offers Run all steps up to this step for the same reason.

7. Finish the change

Every task done, the Cockpit header offers Sync and archive (a split button: Sync alone updates openspec/specs/ from the deltas; Archive moves the change under openspec/changes/archive/). Press it. This is an agent run like the others, with its own log.

Its completion card knows the change lives in a worktree and offers Commit & Merge, Commit or Merge. Commit & Merge commits the worktree, merges feature/add-full-text-listing-search into the branch your project has checked out, and removes the worktree when the merge is clean. Want a different target? Choose branch… on the Cockpit’s Merge control lists your local branches.

The change now sits in the Explorer’s Archive section — with its whole history intact: every run, every diff, in the Cockpit’s History tab. Your openspec/specs/listing-search/spec.md is the new source of truth for that capability, and master has the code.

Where to go next