The MySpec Workflow

The four-file bundle

MySpec generate-workflow (greenfield) · myspec-greenfield-v1

Stage by stage

1. Interview. A Product Interviewer asks one to five focused multiple-choice questions per round - the problem, product type, target users, the two or three key journeys, MVP scope - and deliberately nothing technical. Two or three rounds is typical. It ends by naming the session and the bundle (a kebab-case folder name).
2. Constitution → constitution.md. Collect gathers technology, architecture, testing, coding-standard, and security constraints; generate writes the nine-section constitution; review checks every constraint traces to an answer.
3. Requirements → requirements.md. A Business-Analyst collect loop keeps asking until the requirement list is complete (up to six rounds); generate writes FR-/NFR- entries with EARS+ criteria and requirement diagrams; review rejects untestable or technology-laden requirements.
4. Solution → solution.md. Collect asks about the options the constitution left open; generate produces the architecture with flowchart, ER, sequence, and C4 diagrams; review checks constitution compliance and requirement coverage.
5. Tasks → tasks.md. Collect asks about your team structure; generate writes milestones of sized tasks with estimates, a Gantt timeline, and a QA verification milestone; review checks every requirement has a task.
6. Complete. The bundle is stored as versioned revisions and ready for hand-off.

The brownfield change flow

MySpec generate-brownfield · myspec-brownfield-v1

A much leaner sibling for existing code: no constitution or solution stage, because the codebase already embodies both. Instead:

1. Interview that reads your code. The Brownfield Interviewer packs the repository (local_pack_codebase), greps and reads the areas your answers point at, and asks only where a real gap exists. It cannot advance until real files were read - connect your code by mounting a folder (Chrome) or running npx -y @myspec/mcp-server reverse --root ..
2. Proposal → proposal.md: Why, What Changes, a Technical Solution with flow and schema diagrams, Impact - every claim grounded in files it read.
3. Requirements delta → requirements.md coded AR- (add), BR- (remove, with file:line), CR- (change, old criterion struck through).
4. Tasks (optional). After the delta is approved the workflow asks whether you want a task plan traced to the AR/BR/CR codes, or would rather hand the delta straight to your coding agent.

Folder layout

specs/
├── invoice-tracker/            # greenfield bundle (kebab-case name set in the interview)
│   ├── constitution.md
│   ├── requirements.md
│   ├── solution.md
│   └── tasks.md
└── add-oauth-login/            # brownfield change
    ├── proposal.md
    ├── requirements.md         # Requirements Delta: AR-/BR-/CR-
    └── tasks.md                # optional

Spec paths are rooted at specs/. Downloaded through the MCP server they mirror into a gitignored .specs/ folder, so the copy your agent reads never collides with files you commit.

What the specialist passes add

• C4 diagrams in solution.md, when your organisation switches them on - a Context diagram of the system among its users and neighbours, and a Container diagram of the deployable units named exactly as the modules and infrastructure sections name them.
• Requirement diagrams in requirements.md - Mermaid requirementDiagram blocks for FRs and NFRs, capped at 20 nodes each (25 on the brownfield workflow).
• Project-Manager delivery plan in tasks.md - man-day estimates per task, totals in the overview, and a Gantt timeline against the team you described.
• QA verification milestone in tasks.md - one verification task per functional requirement, negative paths included.
• Skill recommendation - after the interview, up to six curated skills (framework, domain, or your organisation's custom skills) are suggested; the one you pick shapes every later file.

From bundle to code

The bundle is the contract your coding agent builds from. With the MySpec MCP server connected, the agent reads the files itself and writes its own updates back as reviewable revisions; without it, download the ZIP and drop the files into .specs/.

# Cursor / Claude Code, with the MySpec MCP server connected
"List my projects, then download every spec file of 'invoice-tracker' into .specs/."
"Implement task 3 from .specs/invoice-tracker/tasks.md strictly according to
 solution.md and constitution.md. Cite the FR ids in the PR description."

Need to change something later? The Edit workflow (greenfield or brownfield) takes the files you reference, your description of the change, and proposes each edit as a diff you accept, refine, or discard - keeping the four files coherent with each other.