Skip to content

MySpec brownfield workflow

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.

Updated View as Markdown

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

Navigation

Type to search…

↑↓ navigate↵ selectEsc close