DEV Community

Cover image for OpenSpec (Part 2): Fixing and Extending a Brownfield App, One Change at a Time
rosidotidev
rosidotidev

Posted on Edited on

OpenSpec (Part 2): Fixing and Extending a Brownfield App, One Change at a Time

At the end of the first OpenSpec article I promised to move from theory to practice: take an existing application, one that was not born with OpenSpec, and run real changes through the loop. This is that article.

The application is MemoIt, the one I built with BMAD in the second BMAD article: 7 epics, 22 stories, a PRD, an architecture spine, a UX specification. I do not repeat how OpenSpec works or how BMAD built the app. I focus on what happens when the first meets the second. As always, what follows is a personal view, not a verdict.

The code is on my GitHub: MemoIt. The branch is openspec-lab-1.

Let's Start From the Problem

MemoIt v1 was done. It had a complete set of documents and a working app, and then, as it always happens, I started to use it. Improvements started to appear: first something that bothered me, then a detail I did not like, then something that was wrong in the product itself, then three things I wanted.

This is the normal life of software, and it is where I think the cost of a method becomes visible. BMAD is built for the first half of that life: from a vague idea to a working app. It asks for a brief, a PRD, a UX, an architecture, epics and stories. For "the floating button covers the last card" I would not open that machine again. Going back to a prompt without any structure is the other option, and it brings back the problem from the first article: three sessions later nobody remembers what was agreed.

So the question of this article is a practical one: can OpenSpec carry the second half of the life of an app, the one made of small changes, without asking me to document everything first?

Setup: Code Without the BMAD Skills, With the BMAD Outcome

This is the part I want to describe carefully, because it is the one I did not find written anywhere. I do not repeat how to install OpenSpec, it is in the first article. The question here is different: how do I get a branch with the code and the documents that BMAD produced, but without the BMAD skills that would compete with the new workflow?

The lab branch: one tag, one branch, and a clear line between BMAD behaviour and BMAD knowledge

BMAD lives in the repository in three places, and they are not the same kind of thing:

  • The skills (.claude/skills/bmad-* and their copy in .agents/skills/bmad-*). This is behaviour. Some of them trigger on their own: bmad-build fires when a feature is requested, and it would compete with openspec-propose.
  • The configuration (_bmad/). It is inert without the skills.
  • The documents (_bmad-output/): brief, PRD, UX, architecture spine, epics, story specs, retrospectives. This is knowledge, and it is the reason the project is brownfield.

I considered three options:

  1. Remove all of BMAD. The cleanest test, but OpenSpec would have to rebuild everything from the code. It drops exactly what makes the project brownfield.
  2. Keep everything. Realistic for a team that lives with two methods, but it becomes impossible to tell which tool produced what.
  3. Remove the skills, keep the documents as read-only documentation. This is what I chose.

I think option 3 is the honest simulation of what happens in a real company: the old method left documents behind, and the new one has to live with them. The four steps are these.

Step 1: Tag the baseline, branch, remove the skills (and only the skills):

git tag -a bmad-v1.0.0 -m "MemoIt v1 built with BMAD" && git push origin bmad-v1.0.0
git switch -c openspec-lab-1 && git push -u origin openspec-lab-1
git rm -r .claude/skills/bmad-* .agents/skills/bmad-*
git commit -m "lab setup: remove BMAD skills"
Enter fullscreen mode Exit fullscreen mode

Three details matter. A plain git push does not push tags, so the tag has its own push. The skills commit deleted 740 files and left _bmad/ and _bmad-output/ untouched: it is a commit of its own because it is the one I will revert at the end, when I merge the branch into main and revert only the setup commits. This way "the code is good" and "the method is good" stay two separate decisions. And it missed six BMAD agents for GitHub Copilot in .github/agents/, which I removed in a second lab setup commit, so search the whole repository for bmad before you trust the first removal.

Step 2: Install OpenSpec and init, in their own commit. The installation is in the first article. Here I only pinned version 2.0.0, to keep the article reproducible, and ran init with --no-copilot-cloud, because otherwise it also configures a Copilot cloud agent that I did not need with Claude. Both tools write into the same two skill folders, but the names do not collide: bmad-* on one side, openspec-* on the other. This is why a revert of the setup commits restores BMAD next to OpenSpec without conflicts.

Step 3: Write the project context by hand (the step that makes the old documents useful):

openspec init writes a skeleton config.yaml and nothing else: no command fills it in. I wrote it myself, and I followed the bar set by the skeleton's own comment: only constraints an agent cannot infer by reading the code. The stack stays out, because package.json already says it.

context: |
  MemoIt is a brownfield project: v1 was planned and built with BMAD.
  Its planning documents are in _bmad-output/planning-artifacts/ and are the
  source of truth for intent and decisions. Read the relevant parts; never
  convert them into OpenSpec specs.
    - Architecture decisions (AD-1..AD-18): .../ARCHITECTURE-SPINE.md
    - Requirements (FR-n): .../prd.md
    - Look and behavior: .../DESIGN.md and .../EXPERIENCE.md
  Hard constraint (AD-3): no server code, ever.

rules:
  proposal:
    - State what is out of scope
    - Name the ADs and PRD requirements the change touches
  design:
    - Cite the AD each decision relies on or changes
  tasks:
    - End with running npm run check
Enter fullscreen mode Exit fullscreen mode

The list of ADs is linked, not copied, so it cannot drift from the spine. AD-3 is the one exception, and it is stated in full: the code shows that there is no server, but it does not show that adding one is forbidden. The lint check only catches it after the code is written.

This is the bridge between the two methods. BMAD left the knowledge in _bmad-output/, and config.yaml makes every OpenSpec artifact read it. A few changes later I added a second hard constraint, which I describe in the sharing change.

Step 4: Do not back-fill the specs (the decision I would defend the most):

After init, openspec/specs/ is empty, and I left it empty. I did not reconstruct baseline specs from the PRD or from the code. The brownfield guide of OpenSpec says it plainly: you write specs only for what you are about to change. The BMAD documents have two roles on this branch: background for every artifact, through context, and material for exploration, which I point to before proposing a change. From here on, one commit per change, archive included.

Six Changes, Same Loop

Here is the whole lab in one picture, before the details. Six changes, six commits, and at the end six capabilities in openspec/specs/, with 61 requirements and 148 scenarios, none of them written upfront. In order: replace the floating buttons with an inline Add button (the bug), item rows as bounded cards (the polish), a daily trend in the Report (the specification misunderstanding), and then the three features: sharing Categories between Users, Edit and Delete on every Item row, and Items that keep working offline. The cards change has no section of its own: it comes back in "Where the Agent Stopped".

I did not apply the loop in the same way every time. The first changes started from /openspec-explore, the later ones from a command that carried the decisions. Let me show the interesting cases, not all six in the same detail.

Six changes on MemoIt: bug, polish, misunderstanding and three features

Replace FABs With an Inline Add Button

The report was simple: the "New category" and "Add item" buttons, both floating, cover the last card in the list, so the last Item cannot be edited with a tap.

Step 1: Explore (a thinking mode, it writes nothing):

/openspec-explore
The New category and Add item FABs cover the last card in the list,
on mobile and on desktop. Find the root cause.
Enter fullscreen mode Exit fullscreen mode

Explore found it in the CSS: the FAB is position: fixed at bottom: 96px, and the page bottom padding is exactly 96px, which clears the navigation bar, not the FAB. The obvious fix was a bigger padding. I rejected it and asked for a simple "+" next to the search field instead. The rest of the session refined the choice, one question at a time: where, how it behaves on a wide screen, and whether it stays pinned (it does not).

Step 2: Propose (the plan, in one pass):

/openspec-propose replace-fabs-with-inline-add-button
Enter fullscreen mode Exit fullscreen mode

The four artifacts came out valid under openspec validate --strict, and the first capability appeared in openspec/specs/: create-actions. The proposal also declared a deviation from the BMAD UX documents (the FAB pattern in EXPERIENCE.md).

Then something happened that I did not expect. In explore we had sketched the smaller search field at 40px. While writing the design, propose read the architecture spine and found AD-17: touch targets must be at least 48 by 48 px. The design sets the field to 48px everywhere and removes a 40px override that was already a quiet violation in v1. The correction is in the design (D3) and it was reported to me. It was not applied silently.

This is the whole point of putting the BMAD documents in context. The architecture decision I wrote a week earlier was checked against a plan I made in a chat that morning. The check is simple: the plan cites the AD, and a wrong number does not survive the citation.

Fix Report Daily Trend

This is the change I would show to anyone who asks me why specs matter.

I reported that two Values entered on two consecutive days showed on the Report as a single point, whose value was their sum. I expected a daily trend, one point per day. /openspec-explore found that the code did exactly what it was designed to do: series.ts groups Values into weekly or monthly buckets and sums each bucket, and the default is the month. The rule comes from the PRD, FR-12: "weekly or monthly aggregation (sum)". In the PRD it was marked [ASSUMPTION]. Nobody had ever confirmed it.

So it was not a coding bug. It was a specification misunderstanding: summing fits quantities that accumulate (expenses), not measurements (weight), which is what I track. The review triage of the in-memory prototype had even listed "sum aggregation for weight-like data" as low and deferred. Nothing carried it forward to the real app.

The options from explore, and the choice:

  1. One point per Value, with no grouping at all.
  2. A daily grouping as the default, next to weekly and monthly; each bucket shows the latest Value in it. Chosen.
  3. Daily grouping, with each bucket showing the average.
  4. A rule per Category (sum, latest or average).

I chose the second because it fixes the reported case, keeps the chart identical to the data when there is one Value per day, and stays readable on long periods. The fourth stays available for a later change, only if expenses ever need tracking.

Here is the command I ran after a /clear:

/openspec-propose fix-report-daily-trend
The Report must show a daily trend by default, next to the existing weekly and monthly
groupings. Each point is the latest Value in its day, week or month, never a sum.
This corrects a specification misunderstanding: FR-12 assumed a weekly/monthly sum
(see the [CORRECTED 2026-11-15] notes in the PRD and in AD-8).
Enter fullscreen mode Exit fullscreen mode

A lesson I had to learn: the name after /openspec-propose means nothing to the tool. The CLI uses it only as a folder name. What gets written comes from the conversation and from the files in the repository. In the same session as the explore, the name alone is enough. After a /clear, pass the description too, or the agent has to guess, and the skill tells it to ask instead.

In the same message I asked for more period filters, "week, month, year, max". Propose did not guess: my sentence could replace the current options or add to them, and that changes visible behavior, so it asked before writing anything. Later, in apply, I asked to change the grouping buttons to Weekly, Monthly, Yearly. Apply pointed out that dropping Daily would bring back the complaint that started the change, and offered four buttons or three. I chose four, with Daily still the default, and the new scope went into proposal, design, spec and tasks before the code.

The BMAD documents followed the fix. The agent never edits _bmad-output/ on its own. Here I asked it to, because if the PRD kept saying "sum", then config.yaml, which names the PRD as the source of truth, would feed the wrong rule into every future artifact. Each edit carries a marker:

[CORRECTED 2026-11-15: specification misunderstanding ...]
[AMENDED 2026-11-15: changed after a fix made with OpenSpec (change fix-report-daily-trend) ...]
Enter fullscreen mode Exit fullscreen mode

The two markers say different things. CORRECTED means the original requirement was a misunderstanding. AMENDED means the requirement was right and changed later. I wanted the history to tell the difference.

Two sources of truth, two jobs: BMAD documents hold the intent, OpenSpec specs hold the behaviour

Share Categories

The most interesting use of explore was not a bug. I asked whether sharing Categories between Users is technically possible. My fear was that storing data per user (users/{uid}/...) made it hard, and the constraint was to find a solution without changing the backend architecture.

The case: every family member keeps a "Spesa" (shopping) list, but only one of them goes shopping. Everyone needs to add to one list, and see the others' changes live.

Explore read firestore.rules, the Firestore backends and the architecture spine before answering. The finding was that the path is not the access. The per-user path only says where the data lives. Who can read it is decided by one rule, and that rule can be widened without moving any data. So sharing needs no server (AD-3 holds), no migration and no new collection: a members field on the Category, new rules, and client code. I chose one shared list, live, and I decided that any Category can be shared, not only the shopping list.

Then I set a rule that applies to every future change, and I put it into config.yaml as a second hard constraint next to AD-3:

Hard constraint, forever: backward compatibility with the data already in
Firestore. Existing documents must keep working unchanged: no migrations,
no moved or renamed paths, every new field optional (absent means the
current behavior), new keys allowed by the rules but never required.
Every proposal and design must state how it stays backward compatible.
Enter fullscreen mode Exit fullscreen mode

I think this is the best example of what config.yaml is for. A decision made in an explore session is gone after the next /clear. Written in the context, it is read by every proposal that follows. The next changes opened with a section about backward compatibility, and the fifth one said "nothing to do" and explained why.

The propose command carried the whole list of decisions from explore, with a pointer to the lab log and the one technical point still open: whether the Item rules can authorize a member's query with get() on the Category, or members has to be copied onto each Item. Propose did not choose. It wrote both options into the design and made an emulator spike the first task, with a stop: if the outcome is the second option, ask me before going on. An unknown that would change the task breakdown became a decision point, not an "open question" at the bottom of a file. The spike chose the first option, and the stop was not needed.

One more detail I like: the first draft of the spec said the rules reject every owner-only action from members, Clear Done included. Writing the rules in the design showed that this cannot be true, because Clear Done is a batch of Item deletes and members may delete single Items. Propose corrected the spec before finishing.

Add Item Row Actions and Add Offline Items

By the fifth change I stopped exploring in the same chat and started to write the command in labelled sections, after a /clear:

/openspec-propose add-item-row-actions
Decided: ...
Proposed defaults, to use unless a document contradicts them: ...
Context found in the code: ...
Documents the change contradicts: ...
Risks to record: ...
Out of scope: ...
Enter fullscreen mode Exit fullscreen mode

Propose took every decided point and every default as written, and then did its own work: it found a third passage of EXPERIENCE.md that the change contradicts, which my command did not name. It also listed the choices it made on its own (a tap on another row only closes the open one, Escape closes a row, a failed delete shows the same message as Item edit), and I read the list and approved it. I could have missed those choices in a chat. In design.md they were reviewable.

The sixth change, offline Items, was the largest: 27 files and 17 requirements. Apply found four things the plan did not foresee, and the end-to-end run found two more. The one I remember: the first design showed the "no network" notice as a fixed box at the top, and the e2e run found that it covered the Save button of the Item form on a phone. No unit test could have said that. The notice became a strip in the page flow.

Two honest notes. The manual checks on a phone and with a screen reader are still on my list, because Playwright cannot test real touch scrolling or the browser back gesture. And the plan did not say everything: the lab log, not the artifacts, holds the four apply discoveries. If I did it again, I would write them into design.md before archiving.

Where the Agent Stopped

The picture is the part I find most useful for someone who is deciding whether to trust this workflow. In six changes there were five moments where the plan, not the agent's first idea, had to give way. In two of them the agent stopped and asked, in two it corrected the plan and told me, and in the last one it was the end-to-end run that found the problem, not a question.

Where the agent stopped: five moments, what it found, what it asked, what was written down

The second one is the clearest example of the guardrail at work.

In the second change (item rows as bounded cards) the accessibility check (axe) flagged two gaps that the new card did not cause: aria-allowed-attr on the priority tiles and 29 controls below the 48px of AD-17. I decided to ship the feature and handle those in a separate change.

Task 2.5 said "verify that axe reports no AA violation". That was no longer true, through no fault of the change, so apply left it unticked and asked: leave it open and archive anyway, reword it, fix the old defects now, or delete the failing rule so the suite goes green. I rejected the last one, because the 48px rule comes from AD-17 and deleting the check would quietly drop an architecture decision. I reworded the task to "this change introduces no new violation" and marked the two failing tests with test.fixme and a FIXME(a11y-baseline) comment, so the rule stays in the code.

I accepted the trade-off knowingly: until the fix lands, no accessibility check runs on any screen. And nothing in OpenSpec remembers that debt: there is no backlog. The third change found the same gap again and needed a one-off manual check. A change exists only once someone proposes it, so deferred work has to live somewhere else. On this branch it lives in the FIXME markers, and I think this is a weak place for it.

What the Process Gave Me

A cost proportional to the size. The first change was 16 files, the sixth 27. None of them needed a PRD, an architecture or a list of epics.

The old decisions kept working. Because BMAD's documents are named in context, AD-17 corrected a plan I made that morning and FR-12 was challenged by a change. The BMAD outcome was not dead documentation.

A gate in the right place. Propose stops before the code, and apply stops when the plan is wrong. Both pauses brought a decision back to me.

Specs I did not have to write upfront. Six capabilities, every one traceable to a real change, and none that nobody needed.

A history that answers "why". Every archived change keeps its proposal, design and tasks: 6 folders with the reasons.

What It Did Not Give Me

The other side, with the same sincerity as before:

No backlog. The accessibility debt came back three times, because nothing outside the archive remembered it. In BMAD, deferred work lives in the epics and in the retrospectives. Here I had to track it in the code.

No approval gate. openspec status tells you which artifacts exist, not whether you read them. In BMAD every step stops for approval, here the discipline is mine. In the sixth change I read the plan less carefully than in the first, and I think that is the real risk of a fluid tool. The same goes for what the agent decides alone: the 40px field was reported, but my review was the only safety net.

The BMAD documents age. I had to amend them three times, by hand, and only because I decided to. OpenSpec does not know that _bmad-output/ exists. If I had not asked, the PRD would still say "sum".

Some knowledge stays in the log. What apply learns on the way lives in the conversation unless I write it down. This article exists because I kept a lab log.

The Role of the Human

Moment What I decided
Explore The option to pursue (inline button, daily default, one shared list)
Propose What goes in the command: scope, defaults, what is out
Review Whether the proposal contradicts a document, and whether to amend it
Apply What to do when the agent stops: widen the change, defer, reword a task
Archive Sync now, and a separate commit
Always Whether the BMAD documents may be touched

Bounded autonomy, not full automation. The first OpenSpec article already said that here nobody forces the stop, and this lab shows both sides of it: the agent stopped because its guardrails told it to, and I stopped because I decided to read.

Takeaways

  1. For a brownfield, remove the competing skills and keep the documents. Tag the baseline first, remove the skills in their own commits, and keep _bmad-output/ as knowledge the agent reads and I amend.
  2. The project context is the bridge. config.yaml makes every change read the old documents, and it keeps the decisions that would otherwise die with the chat.
  3. Do not back-fill the specs, and explore before propose. The specs grew from zero to six capabilities, one change at a time. Explore changed the plan in the first change and answered "is it even possible" in the fourth.
  4. A bug can be a specification misunderstanding. Fix the code and the document that was wrong, and mark the difference between corrected and amended.
  5. Pre-existing debt will surface. Track it somewhere that is not the archive.
  6. Read the plan. Nothing enforces it, and every good moment in this lab came from a pause.

What Comes Next

With this article I have written three series on spec-driven development: GitHub Spec Kit, BMAD and OpenSpec. I am now evaluating what to write next, and there are a few options:

  • Go deeper into one of the three. Each framework has aspects that deserve an article of their own: customizing an existing skill so that it follows the rules of my project, defining a new skill or workflow for a step the framework does not cover, or one feature in depth, such as the OpenSpec schemas and how a workflow can be forked. It would be a practical article, with a real customization from start to end.
  • Add a series on another framework. Collections of skills with no framework around them, such as Addy Osmani's agent-skills and Matt Pocock's skills. I am curious what a method looks like when it is only a set of skills, and I would apply the same approach: one real project, one command at a time, and an honest list of limits.
  • Compare the three frameworks. I have now used Spec Kit, BMAD and OpenSpec on real code. A comparison would look at the same kinds of work, the cost in time and in documents, where the human stays in control, and what each tool leaves in the repository. A personal view, not a verdict, as always.
  • Something else. Other ideas are welcome.

I have no favorite yet. Stay tuned.

Which of these would you like to read? Is there a framework or a question about spec-driven development that you would like me to try on a real project? I would love to read your ideas, and your experience with these tools, in the comments.

Top comments (0)