The OpenSpec Workflow

What OpenSpec is

OpenSpec is an open-source SDD toolkit built for brownfield work. Instead of one monolithic spec it maintains living specs per capability under openspec/specs/, and every change is a self-contained folder under openspec/changes/. Its CLI validates a change's structure, and archiving a finished change merges its deltas into the baselines, so the specs never drift from the code. Its slash commands (/opsx:…) drive the same steps from an AI coding agent.

MySpec's OpenSpec workflow produces that change folder - with the codebase actually read, the capabilities validated, and every file reviewed before you see it.

Explore → proposal → specs → design → tasks

OpenSpec generate-brownfield · openspec-brownfield-v1

1. Explore. The Brownfield Explorer packs the whole repository first (local_pack_codebase), then greps and reads the modules the change touches, and asks focused multiple-choice questions only where a real gap exists. It sets a kebab-case change id (add-oauth-login, rename-billing-module; archive is reserved) and cannot advance until real files were read - mount a folder in Chrome or run npx -y @myspec/mcp-server reverse --root ..
2. Proposal → proposal.md: Why, What Changes, Capabilities (new and modified), Impact. The capability list is a contract: each name must be a stable domain or module identifier (webapp, user-auth; ≤3 words, ≤25 characters), never the feature itself.
3. Specs → one delta spec.md per capability at specs/<capability>/spec.md, using the exact delta headers and WHEN / THEN scenarios the OpenSpec validator enforces. Generate → review per file; the stage ends only when every capability has an approved delta.
4. Design → design.md. The platform normalises OpenSpec's legacy design stage to solution, so the stepper labels this stage "Solution" while the file it writes is still design.md: Context, Goals / Non-Goals, Decisions, Risks / Trade-offs. Optional in OpenSpec; brief for small changes.
5. Tasks → tasks.md: one numbered group per capability with N.M checkbox tasks, at planning level - the workflow never implements the change.

Folder layout and the CLI round-trip

openspec/
├── specs/                               # long-lived capability baselines
│   ├── webapp/spec.md
│   └── platform/spec.md
└── changes/
    ├── add-session-rename/              # <change-id>: kebab-case verb phrase
    │   ├── proposal.md
    │   ├── design.md                    # optional
    │   ├── tasks.md
    │   └── specs/
    │       ├── webapp/spec.md           # one delta per capability named in the proposal
    │       └── platform/spec.md
    └── archive/                         # reserved: the CLI moves applied changes here

Spec paths for this workflow are rooted at openspec/; the MCP server's download_spec_file keeps that root beneath .specs/ (.specs/openspec/changes/…), so move or symlink the change folder into your repo's openspec/changes/ before running the CLI.

# after MySpec has written the change and you have pulled it into the repo
openspec validate add-session-rename     # delta headers + scenarios check out
# implement the tasks with your coding agent, then
openspec archive add-session-rename      # merges the deltas into openspec/specs/<capability>/spec.md
# or drive the same steps from your editor with /opsx:apply and /opsx:archive

OpenSpec vs the MySpec brownfield flow

Implementing the change

Once the change folder is in your repository, your coding agent works task group by task group, ticking N.M boxes, and you archive the change with the OpenSpec CLI when it ships. Through the MySpec MCP server the agent can also update the files as reviewable revisions while it works - passing expected_version so nobody's edit is overwritten.