---
title: "MySpec brownfield workflow"
description: "The short workflow for changing an existing codebase. The AI reads your code, then writes a change proposal, a requirements delta and, if you want, 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.

# MySpec brownfield workflow

The **MySpec brownfield** workflow specs a change to code that already exists.
The AI reads your codebase first, then writes only what the change needs. It is
the default for Brownfield projects and suits most changes. In the picker it is
**MySpec generate-brownfield (v1)**.

## At a glance

- **Best for:** Most changes to an existing codebase: a feature, a fix, a refactor
- **Project type:** Brownfield (or Auto)
- **Stages:** Interview → Proposal → Requirements, then an optional Tasks stage
- **Files:** `proposal.md`, `requirements.md` (a delta) and, if you run Tasks, `tasks.md`
- **Folder:** `specs/<bundle>/`, where the bundle names the change, such as `add-oauth-login`

## Before you start

Connect your codebase **before** you start the session. You have two options:

- Run the local MCP server's `reverse` command in a terminal, pointed at your
  project folder.
- Mount the project folder in your browser's **Local Workspace** (Chrome or
  Edge).

See [Let MySpec read your code](https://docs.myspec.dev/guides/brownfield/#let-myspec-read-your-code)
for both. If neither is connected, the AI stops and asks you to connect one. It
never guesses what your code does.

## Stages

Brownfield stages have no **Collecting** step: the AI asks its questions in the
Interview, while it reads your code. Each later stage goes from **Generating**
to **Review**.

### Interview

The AI reads your codebase and asks focused questions about the change: what
should behave differently, what is in and out of scope, and any constraints.
The chat shows its reading as cards such as **Pack codebase**, **Local read**
or **Reading local workspace**.

The session can't move on until the AI has read real files from your code.

### Proposal

**Generating** writes `proposal.md`:

- **Why** the change is needed and **What Changes**.
- A **Technical Solution**: library or framework changes, core flow changes,
  data model or database schema changes, and breaking API changes.
- **Impact**: the call sites affected, what is out of scope, and anything the AI
  could not verify in your code.

**Review** checks that the solution is grounded in the code the AI read, that
diagrams are valid, and that the change stays in scope, touches no more than it
must and reuses what exists.

### Requirements

**Generating** writes `requirements.md` as a **requirements delta**: only what
changes, grouped by the modules the change affects. Each entry is one of:

| Code | Meaning |
|---|---|
| `AR-001` | An added requirement |
| `BR-001` | A removed requirement, with a reference to where your code implements it today |
| `CR-001` | A changed requirement: what changes and why, with the old acceptance criteria struck through |

**Review** checks the delta format and codes, the grouping by module, and that
every entry matches the proposal and your code.

### Decide whether to write tasks

After you accept the Requirements review, the AI asks **How would you like to
proceed?**. It recommends either stopping here or continuing to Tasks, and says
why. Choose **Follow AI advice** or **Ignore AI advice**; each label says
whether it completes the session or goes on to Tasks.

If you stop, the completion card says "Tasks phase skipped." The header always
marks Tasks as optional.

### Tasks (optional)

**Generating** writes `tasks.md`: milestones of implementation tasks based on
the proposal and requirements, ending with a dependency graph.

**Review** checks that every requirement is covered, that tasks match the
proposal and your code, and that the plan doesn't grow beyond the change.

## Tips

- **Name the change in your first message.** MySpec starts the message with a
  request that ends with "Then help me to make a change request to improve:".
  Finish the sentence.
- **Skip Tasks when your coding agent plans for itself.** Many agents work well
  from a proposal and a requirements delta alone.
- **Going back.** `/goback` returns to Proposal or Requirements and regenerates
  from there. You can't go back to the Interview.

## When to pick another workflow

Use [OpenSpec](https://docs.myspec.dev/workflows/openspec/) when the change touches several parts of
the system and you want one delta spec per part, a separate design and grouped
tasks, or when your team follows the OpenSpec method.

To change these specs later, use
[MySpec edit for brownfield](https://docs.myspec.dev/workflows/edit-brownfield/).

Source: https://docs.myspec.dev/workflows/myspec-brownfield/index.mdx
