---
title: "Work on an existing codebase"
description: "Let MySpec read your code, then write a change proposal and requirements for a Brownfield project."
---

> 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.

# Work on an existing codebase

A **Brownfield** project is one where you change an existing codebase instead
of building from scratch. MySpec reads your code first, then writes specs that
describe the change: what is added, changed or removed, and why.

You choose the project type when you create the project. For a Brownfield
project the description is optional, because MySpec learns about the product
from the code. See [Projects](/guides/projects/).

## Let MySpec read your code

Brownfield sessions must read real files from your codebase before they write
anything. There are two ways to share it. Set one up before you start the
session.

| | Local MCP server (`reverse`) | Local Workspace |
|---|---|---|
| Where it runs | A terminal on your machine | Your browser tab |
| You need | Node.js 22 or later | Chrome or Edge |
| Set it up | Run a command before the session | Mount a folder in the file explorer |

If a folder is mounted in the browser, the AI reads from it. Otherwise it uses
the `reverse` bridge. If neither is connected, the AI stops and asks you to
connect one. It doesn't guess what your code does.

While the AI reads, the chat shows cards such as **Pack codebase**,
**Local read** and **Local grep** (from the bridge), or **Reading local
workspace** (from the browser).

### Use the local MCP server

The `reverse` command of the local MCP server lets MySpec's AI read one folder
on your machine, and nothing outside it.

1. **Sign in**

   Sign in with the same MySpec account you use in the browser:

   ```bash
   npx -y @myspec/mcp-server login
   ```
2. **Start the bridge**

   From a terminal, point `--root` at your project folder:

   ```bash
   npx -y @myspec/mcp-server reverse --root /path/to/your/project
   ```
3. **Keep it running**

   Leave the command running for the whole session. Start it **before** you
   start the session.

- Only one bridge runs per account.
- Point `--root` at the project folder, never your home directory. Common
  secret files are skipped by default, but the AI can still ask for one, and it
  can read anything else in the folder. Keep credentials out of it.

See [Share a local folder for Brownfield projects](/mcp/local-server/#share-a-local-folder-for-brownfield-projects)
for details.

### Use the Local Workspace in your browser

In the chat's file explorer, find **Local Workspace** and select **Mount
folder**, then choose your project folder and allow access. The AI reads files
through your open browser tab, so keep the tab open while it works. Browsers
that can't open a local folder show **Requires Chrome or Edge 86+** instead.

See [Share a folder from your computer](/guides/attachments/#share-a-folder-from-your-computer).

## Start a Brownfield Generate session

1. **Connect your codebase**

   Start the `reverse` bridge or mount a folder, as described above.
2. **Open a new chat**

   In your project, under **Chats**, select the **Generate** tab, then
   **Chat**.
3. **Choose a workflow**

   Under **Generate methodology**, choose one of the workflows in the table
   below. MySpec brownfield is listed first and selected by default.
4. **Describe the change**

   MySpec fills the message box with a starting request that ends with "Then
   help me to make a change request to improve:". Finish the sentence with the
   change you want, then send.

| Methodology | Shown in the picker as | Stages |
|---|---|---|
| MySpec brownfield | **MySpec generate-brownfield (v1)** | Interview → Proposal → Requirements, with an optional Tasks stage |
| OpenSpec | **OpenSpec generate-brownfield (v1)** | Explore → Proposal → Specs → Solution → Tasks |

### Which workflow to pick

- **MySpec brownfield** is the shorter workflow. It writes a proposal and a
  requirements delta that lists added, removed and changed requirements. Use
  it for most changes.
- **OpenSpec** follows the OpenSpec method. It writes one delta spec per part of
  the system the change touches, plus a design and a task list, and saves them
  in the OpenSpec folder layout.

### How stages run

Brownfield workflows ask their questions up front, in the Interview or Explore
stage, while the AI reads your code. After that, each stage goes from
**Generating** to **Review**: you approve the draft, then act on the AI review,
exactly as in a Generate session. See
[Review each spec file](/guides/generate-sessions/#review-each-spec-file). The
[spec depth](/guides/generate-sessions/#spec-depth) you pick limits both the
question rounds and the review rounds.

`/goback` works for the spec stages. You can't go back to Interview or Explore;
start a new session instead.

## The MySpec brownfield workflow

| Stage | What it produces |
|---|---|
| Interview | The AI reads your codebase and asks focused questions about the change you want. No spec file is produced yet. |
| Proposal | `proposal.md`: why the change is needed, what changes, the technical solution (library, flow, data model and API changes) and its impact. |
| Requirements | `requirements.md`: a requirements delta grouped by the modules the change affects. Each entry is an added (`AR-`), removed (`BR-`) or changed (`CR-`) requirement. |
| Tasks (optional) | `tasks.md`: a numbered implementation checklist based on the proposal and requirements. |

After you accept the Requirements review, the AI asks **How would you like to
proceed?** and recommends either stopping or continuing to Tasks, with its
reason. Choose **Follow AI advice** or **Ignore AI advice**; each label says
whether it completes the session or proceeds to Tasks. If you skip Tasks, the
completion card says "Tasks phase skipped." The header marks the Tasks stage as
optional.

Files are saved under `specs/<bundle>/`, where the bundle is a short name for
the change, such as `add-oauth-login`.

## The OpenSpec workflow

| Stage | What it produces |
|---|---|
| Explore | The AI reads your existing codebase to understand its architecture and conventions before proposing any change. It may ask a few questions. No spec file is produced yet. |
| Proposal | `proposal.md`: the change to make and why, based on what it learned about your codebase. It names each capability (part of the system) the change touches. |
| Specs | Delta spec files describing exactly which requirements are added, modified, removed or renamed, one `spec.md` per capability. |
| Solution | The technical approach (context, goals, decisions, risks and trade-offs), saved as `design.md`. |
| Tasks | `tasks.md`: a checklist of implementation tasks, grouped by capability. |

The session can't leave Explore until the AI has read files from your code.
Files are saved under `openspec/changes/<change-id>/`, where the change ID is a
short name such as `add-oauth-login`.

[Spec files](/spec-files/) describes each file in more detail.

## Finish and build

Finishing works as for any Generate session. Because a Brownfield session
describes a change, the Lovable, Bolt and Replit buttons are hidden;
**Generate AI Prompt** writes a change request for your coding agent instead.
See [Finish a session and build](/guides/finishing-a-session/).

## Edit specs for an existing codebase

To change Brownfield specs later, start an [Edit session](/guides/edit-sessions/).
In a Brownfield project, MySpec uses **MySpec edit-brownfield (v1)**: "Edit
specs against an existing codebase → describe changes → review edits."

This edit workflow reads the code related to your change before it edits any
spec, so connect your codebase first, as for a Generate session. If it can't
read your code, the AI asks you to connect it and waits.

Source: https://docs.myspec.dev/guides/brownfield/index.mdx