Skip to content

OpenSpec workflow

The OpenSpec method for changing an existing codebase. Explore the code, then write a proposal, a delta spec per capability, a design and tasks.

Updated View as Markdown

The OpenSpec workflow follows the OpenSpec method for changes to an existing codebase. It splits the change by capability, meaning each part of the system it touches, and writes a delta spec for each one. Files are saved in the OpenSpec folder layout. In the picker it is OpenSpec generate-brownfield (v1).

At a glance

  • Best for: Changes that touch several parts of a system, or teams that follow OpenSpec
  • Project type: Brownfield (or Auto)
  • Stages: Explore → Proposal → Specs → Solution → Tasks
  • Files: proposal.md, specs/<capability>/spec.md (one per capability), design.md, tasks.md
  • Folder: openspec/changes/<change-id>/, where the change ID is a short name such as add-oauth-login

Before you start

Connect your codebase before you start the session: run the local MCP server’s reverse command, or mount the folder in your browser’s Local Workspace. See Let MySpec read your code. If neither is connected, the AI stops and asks you to connect one.

Stages

Like every Brownfield workflow, OpenSpec asks its questions up front, in Explore. Each later stage goes from Generating to Review.

Explore

The AI reads your codebase to learn its architecture and conventions before it proposes anything. It may ask a few questions about what should change, the scope and any constraints, and it names the change.

The session can’t leave Explore until the AI has read real files from your code. Mounting a folder isn’t enough on its own: the AI must actually open files or list folders.

Proposal

Generating writes proposal.md: Why, What Changes, the Capabilities the change touches (split into new and modified ones) and the Impact.

Review checks that the proposal is complete, stays a proposal (no design or tasks yet) and lists the capabilities clearly, because the next stage writes one file per capability.

Specs

Generating writes one delta spec.md per capability, in specs/<capability>/. Each uses up to four sections: ADDED, MODIFIED, REMOVED and RENAMED Requirements. Every added or modified requirement says what the system SHALL do, with at least one scenario written as WHEN … THEN ….

Review checks the delta format, that every requirement has a scenario, and that every capability in the proposal has its spec.

Solution

Generating writes design.md: the context, goals and non-goals, the decisions taken and the risks and trade-offs.

Review checks that the design is complete and consistent with the proposal and the delta specs.

Tasks

Generating writes tasks.md: a checklist of implementation tasks, grouped by capability.

Review checks the checklist format and that every capability is covered.

Tips

  • Name the parts of the system you expect to change. It helps the AI split the proposal into the right capabilities.
  • Going back. /goback returns to a spec stage and regenerates from there. You can’t go back to Explore.

When to pick another workflow

For a smaller change, MySpec brownfield is faster: one proposal and one requirements delta, with tasks only if you want them.

See Spec files for what each file contains.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close