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

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSpec workflow

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](https://docs.myspec.dev/guides/brownfield/#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](https://docs.myspec.dev/workflows/myspec-brownfield/) is
faster: one proposal and one requirements delta, with tasks only if you want
them.

See [Spec files](https://docs.myspec.dev/spec-files/#files-for-an-existing-codebase) for what each file
contains.

Source: https://docs.myspec.dev/workflows/openspec/index.mdx
