An OpenSpec change starts as a few sentences and becomes a directory of documents. SpecBuddy owns the round trip — draft, propose, read, comment, refine — and keeps the agent out of your code until you’re done.

The New OpenSpec Change tab

Spec Explorer → + → New OpenSpec Change opens a Markdown editor tab with two buttons:

  • Propose change (primary; Shift+Enter) — sends the draft to the agent as /opsx:propose. The agent creates openspec/changes/<id>/ and writes the proposal, the spec deltas, an optional design and the task checklist in one run.
  • Run Explore — sends the same draft as /opsx:explore. The agent investigates the code and thinks the problem through with you in the log’s chat; nothing is written to openspec/. Use it when you are not yet sure what the change should be, then propose from what you learned.

Both buttons are disabled while the draft is empty or a launch is in flight. The tab is not closed until the launch has actually reached the agent, so a refused launch — no agent configured, OpenSpec CLI missing, another operation running on the project — never loses your text. Closing the tab yourself discards the draft.

There is deliberately no change id field: /opsx:propose derives the id from the proposal, and SpecBuddy has no say in it.

What makes a good draft

The agent reads the whole project before writing, so the draft’s job is intent and boundaries, not implementation:

  • what should be true afterwards, from the user’s point of view;
  • what stays as it is (“keep the table output as the default”);
  • what is out of scope;
  • constraints that aren’t discoverable from the code — a library you don’t want, a deadline for a migration, a team convention.

Two paragraphs are usually right. If it needs a page, it is probably two changes.

What a proposal produces

openspec/changes/<id>/
├── proposal.md            Why, What Changes, Impact
├── design.md              technical approach — only when the change needs one
├── specs/
│   └── <capability>/
│       └── spec.md        a delta: ADDED / MODIFIED / REMOVED requirements
└── tasks.md               ## 1. … sections of - [ ] checkboxes

Each file under specs/ is a delta: not a whole spec, but the requirements this change adds, modifies or removes in one capability. On sync they are merged into openspec/specs/<capability>/spec.md; a capability that does not exist there yet is created. The Cockpit’s Docs tab lists each delta with the main spec it targets, or new capability.

While the agent writes, the change appears in the Spec Explorer as soon as its directory exists and fills in file by file. The run’s completion card lists the documents it created or changed, and the Cockpit’s History tab records the run with a before/after snapshot you can diff later.

Reviewing

Open the documents from the Explorer (expand the change) or from the Cockpit’s Docs tab. Read proposal.md first — it says why and what — then the deltas, then tasks.md.

Inline comments

Place the caret on a line, or select a range, and a balloon icon appears in the gutter. Click it, type, press Shift+Enter (or Save). The comment is shown as an inline card under the line, with Edit and Delete, and follows the text as you edit above it. Comments work in any Markdown document of the change, and in the diff viewer.

All pending comments of the change are listed in the Cockpit’s Comments tab; clicking one jumps to it.

Refine

Refine Spec in the Cockpit header sends the agent back over the change with your comments — each with the file, line range and the quoted text — and asks it to revise the documents. Code is untouched. The completion card in the log shows which documents changed and lets you diff each against its pre-refine state.

With the setting Submit review comments automatically off (the default), a small comment submit tab opens first so you can include or exclude individual comments — Send with comments or Continue without comments. With it on, all pending comments go along.

You can also refine from the chat box in the log: “Move the ranking into the query service, and drop task 4 — we already have that migration.” A chat turn that asks for changes to the documents is treated as a refine, recorded in history the same way.

Adding a requirement

Sometimes the right fix is not a comment but a new requirement. Write it directly into the delta — deltas are plain Markdown, and you own them as much as the agent does. Hand edits are picked up by the next run, and the Explorer’s task count follows tasks.md as you save it.

Delta specs and main specs cross-reference through gutter markers:

  • In a delta, a MODIFIED requirement shows a marker: Go to requirement in main spec jumps to the same requirement in openspec/specs/<capability>/spec.md.
  • The first heading of a delta shows a marker whenever the main spec exists: go to it, or Show diff against main spec to see exactly what this change alters.
  • In a main spec, the title shows a marker listing the active changes that target this capability; pick one to open its delta.

Two things to avoid while reviewing

  • Don’t rename ## sections in tasks.md after a task has run. A task’s run history — its snapshot, its diff, its done state — is keyed by the section heading text. Rename a heading and that task looks as if it never ran. Editing the checkboxes under a heading is fine; the task is marked outdated so you know it ran against an older plan.
  • Don’t run openspec commands by hand in a terminal while a SpecBuddy session is live on the same change. Two writers on one change directory is a race nobody wins. Between sessions it is fine — SpecBuddy reads the files, it doesn’t cache them.