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 asadd-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.
/gobackreturns 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.