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.
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.
Sign in
Sign in with the same MySpec account you use in the browser:
npx -y @myspec/mcp-server loginStart the bridge
From a terminal, point --root at your project folder:
npx -y @myspec/mcp-server reverse --root /path/to/your/projectKeep it running
Leave the command running for the whole session. Start it before you start the session.
- Only one bridge runs per account.
- Point
--rootat 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 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.
Start a Brownfield Generate session
Connect your codebase
Start the reverse bridge or mount a folder, as described above.
Open a new chat
In your project, under Chats, select the Generate tab, then Chat.
Choose a workflow
Under Generate methodology, choose one of the workflows in the table below. MySpec brownfield is listed first and selected by default.
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. The 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 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.
Edit specs for an existing codebase
To change Brownfield specs later, start an Edit session. 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.