Skip to content
QualityLogic logo, Click to navigate to Home

Why I Added OpenSpec to My OpenGSD Workflow

Home » Blogs/Events » Why I Added OpenSpec to My OpenGSD Workflow

About six months ago, I ran trials with Superpowers, GSD, and Kiro, while another group at QualityLogic tried Spec Kit. I documented my takeaways from these efforts in a blog post. My favorite tool was GSD (now maintained as the community fork OpenGSD) because it provided good situational awareness and let me scale down the required structure to fit the task. Over the past few months, I have developed better insight into how to leverage these frameworks, and in this article, I’ll share how I settled on the combination of OpenGSD and OpenSpec for my typical use cases. I’ll also come back to the question that matters most to anyone responsible for quality: how much assurance you really have when one of these frameworks reports that the work is done.

Before I go further, I need to flag some serious drama in the open-source community around GSD. The original author of GSD abandoned the project after being publicly linked to a memecoin rug pull, raising serious supply-chain security concerns about GSD. Contributors and maintainers forked the codebase, completed a security audit and an independent review, and then transitioned to what is now called OpenGSD. This certainly took some momentum out of GSD, but I still really like the framework. It fits my use cases nicely, and I plan to keep using it!

My Use Case

My development use cases are modest: typically, analytic utilities, message-exchange protocol test suites, static analyzers, and ad hoc testers. In pre-AI scoping terms, these were single-developer efforts with development timelines ranging from weeks to months. With AI coding help, timelines are now more like days to weeks. At the start of most projects, our domain knowledge is limited, so the design tends to evolve as our domain knowledge improves and we get to work with the technologies being tested using early versions of the code.

So, my need for structure is somewhat elastic. I want structure around the initial planning and design process, but I want to be able to pivot without excessive overhead as our understanding of the domain improves. And later in development or post-release, I can’t have fixing a typo take an hour of interaction with the spec-driven development framework.

Except for the quick-and-dirty fix need, OpenGSD still fits the bill from my perspective. As I noted in my prior blog post, I found its design-phase implementation extremely helpful, and the overall process not too burdensome, with the ability to tamp down some of the overhead if the scope of the changes doesn’t warrant the structure. However, it wasn’t flexible enough to handle the “fix a typo” needs. So I went looking for a framework to fill that gap.

Framework Selection Characteristics

The use case for these kinds of frameworks is broadly characterized as greenfield or brownfield development. Greenfield refers to developing a brand-new application, while brownfield refers to making changes to an existing application. Spec-driven development tools that provide a framework for deconstructing a large, complex development effort into more granular components lend themselves to greenfield projects. Spec-driven tools with a narrower focus, perhaps just a simple code change, are more appropriate for brownfield projects. Keep in mind that the real dividing line is the size and uncertainty of the next change, since an existing application can still require a major piece of new development. It’s a matter of using the right tool for the task.

Other metrics that might influence which tool to select include:

  • User community feedback (such as GitHub stars)
  • Industry analyst views (such as the Thoughtworks Technology Radar)
  • Flexibility – Degree of user control over the spec definition process
  • Verification – Enforcement of validation against the spec

The table below distills these characteristics and metrics into a form that was useful in deciding which framework best fit my use case.

Target Change ScopeGreenfield or BrownfieldUser Community (Stars)Analyst ViewFlexibilityVerification
Superpowers    Feature or taskGreenfield-leaning300kAssessLowStrong, TDD
Spec Kit    Feature  Greenfield-leaning141kAssess with caution on documentation sprawlMediumAgent review
BMAD    Whole productGreenfield54kCaution on documentation sprawlMediumAgent review
OpenSpec    Small to medium changeBrownfield72kTrialHighOptional agent review
OpenGSD Core  Project or milestoneBoth depending on change size11.4k*No infoMedium to highVerifier agent
KiroFeatureBothN/ANote about vendor lock-inLow to mediumOptional property tests

*Was around 60k, but the count restarted from zero when the open-source effort reorganized after the departure of the original author.

Table data as of November 2026. In the Analyst View column, Assess and Trial are formal Thoughtworks Technology Radar ratings; the other entries summarize related Radar cautions and commentary. The Flexibility and Verification ratings are my own judgment.

Reading this table against my needs, I saw that the gap I had to fill was the small change to existing code. OpenSpec stood out on that point. It targets small to medium changes, it is the most flexible framework of the group, and it is the only one that Thoughtworks has moved to Trial. So I gave it a try, and I discovered a near-perfect complement to OpenGSD for my use case.

OpenSpec

OpenSpec is a lightweight, configurable framework for creating and managing software specifications that an underlying AI agent will use to generate code. I used OpenSpec within the Claude Code CLI. I had previously written an application that reports near-real-time radio propagation conditions across various amateur radio frequency bands. My coding goal was to make a small update that would let you play back historical propagation conditions over varying time frames and playback speeds. A “change” is the primary scope of work that OpenSpec attempts to address. The definition of a change is a little fuzzy, but think of it as a single PR-sized modification to existing behavior. In my propagation playback use case, almost all the needed plumbing was already implemented in the application; the “change” was to repurpose that plumbing to play back some historical snapshots.

Installing OpenSpec was a one-line npm command to add it to my existing Node.js installation. Once installed, I went to the root of my project and ran “openspec init” from the command line. This initialized a directory structure for OpenSpec artifacts and installed the skills that will guide Claude to follow the OpenSpec framework.

The heart of OpenSpec is a set of skills contained in Markdown files that Claude Code uses to guide its behavior in the context of OpenSpec. Skills can be invoked explicitly via Claude Code slash commands or invoked implicitly by providing Claude with natural-language instructions describing what you would like to do. These are the five skills I used:

  • Explore: Claude attempts to get at the core of the changes you plan to make, while exploring the current codebase as needed to get a rough idea of the context for the changes being discussed. I found this incredibly helpful. It’s not a granular process, more a matter of giving Claude the gist of what you want to do.
  • Propose: The discussion resulting from the Explore process is used as context for Claude to create four OpenSpec Markdown artifacts: Proposal, Spec, Design, and Tasks. These artifacts are human-reviewable and form the basis for an interactive dialog with Claude to refine them until they are ready for implementation.
  • Apply: This is the coding process itself, based on the artifacts created in Propose. For my use case, the coding process ran with very minimal user interaction. Claude did run into one situation where the design was not implementable as written. The design called for storing the propagation snapshots in the application’s existing DuckDB database. During coding, Claude realized the database was single-user, and a comment in the code made it clear that an earlier decision had been made to let only a single process access it to avoid potential deadlocks. Claude proposed two options: set up a second database or store each snapshot in a simple JSON file. We adopted the JSON files, the much simpler solution, and it worked well. The agent laid out the choices, but the decision was mine, and the final spec reflects this mid-stream change.
  • Verify: This is a structured review that compares the specification to the implemented code to check whether all the behaviors specified were implemented. Its findings are advisory and do not block the Archive step. Verify is a review and does not run tests itself, but I found that Claude seamlessly generated tests and ran them as needed.
  • Archive: This is a bit of a bookkeeping process: it moves the Proposal, Design, and Tasks artifacts into an archive folder and updates the standing spec with the changes made during the coding session.

As previously mentioned, the Propose skill creates several Markdown artifacts that guide the code generation. Let me expand on the role each of these artifacts plays:

  • Proposal: This is the change described at the business level: the problem, the intent, what is in or out of scope, and the high-level view.
  • Spec: This documents behavior with Given/When/Then scenarios. This is the enduring artifact.
  • Design: This addresses implementation, including technical approach, architecture decisions, and trade-offs.
  • Tasks: This documents execution: an ordered checklist that the agent ticks off during the Apply step.

I had a very positive experience with OpenSpec. My small project went very smoothly, with minimal overhead and a successful implementation. Claude was writing code within 30 minutes of my starting the effort, and I was testing the implementation by the end of the hour. For comparison, a less complex update I made to the same codebase with GSD a while back consumed most of a day. I did go back and make a few of the “missing comma” changes, with almost zero overhead.

My main criticism is that, in addition to the skills, OpenSpec has a separate command-line administrative interface, which was initially quite confusing. For the most part, I didn’t need to interact with this secondary interface. There were a few other rough edges, such as skills being presented in several different naming formats, and perhaps less situational awareness than OpenGSD provides. These are minor issues once you’ve gotten through a small initial project..

Killer Combo – OpenGSD and OpenSpec

Moving forward, my AI code generation strategy is to use OpenGSD Core for all my greenfield development projects. However, once development is feature-complete and the bulk of the remaining work is bug fixing (brownfield), I will migrate the OpenGSD environment to OpenSpec and use OpenSpec for pre-release bug fixes and ongoing maintenance. I’m inclined not to migrate backward to OpenGSD, even if it means a large update to an existing program, although I haven’t tried this in practice.

The signal to switch is when the design has stopped moving and new work shows up as individual fixes and small enhancements rather than as the next phase of a plan. If I find myself reaching for OpenGSD’s quick path more often than its full planning cycle, it’s time.

To be clear, I have used each of these tools on its own, but I have not yet taken a project through the handoff from one to the other, so what follows is a plan I still need to prove out. The handoff should not waste any of the work done in OpenGSD. The requirements and verification records built up during development become the starting point for OpenSpec’s standing spec, reorganized by capability. The durable project information, such as the technology stack, conventions, and constraints, moves into OpenSpec’s configuration file. The OpenGSD planning artifacts are then frozen as a historical record, and the OpenGSD commands are removed from the project so Claude isn’t taking direction from two frameworks at once. Migrating a project from OpenGSD to OpenSpec should be straightforward, and I’ve developed a prompt to help with this process when the time comes for that step.

Implications for QA

One column in the table deserves a second look: verification. Every framework on the list leaves verification largely in the hands of AI agents. Some are more rigorous about it than others, and some, like OpenGSD, hand the review to a separate verifier agent. That helps, but a second agent working from the same spec inside the same framework is still not independent assurance. OpenSpec’s Verify step is a good example. It checks whether the code matches the spec. It does not tell you whether the spec was right or whether the code works.

I’m not alone in this observation. One very interesting paper written by Sanderson Oliveira de Macedo proposes a taxonomy for comparing spec-driven frameworks across six dimensions: specification, context, roles, execution, validation, and portability. His assessment, which is based on a review of each framework’s documentation and covers the original GSD, found validation to be a weak spot for both GSD and OpenSpec, and found that no framework covers all six dimensions strongly. I’d encourage you to read Macedo’s paper.

For my modest utilities, that is an acceptable risk, since I review the specs and the results myself. For software in regulated industries, I don’t think it is. These frameworks improve the odds that the agent builds the right thing, but independent testing against the requirements is still how you find out whether it did.

I’m not claiming this is a universal solution, as it’s specific to my use case. What I hope you take away from this article is that these spec-driven tools come in many flavors, and it’s worth the effort to select the right tool(s) by following a decision process like the one I’ve outlined.

If you want to follow along as I keep experimenting with these tools, subscribe to our State of AI QA Newsletter.


Migration Prompt: OpenGSD to OpenSpec

Show the full migration prompt
I'm migrating this project from GSD to OpenSpec. GSD's milestone is complete and `openspec init` has already been run. Going forward, OpenSpec's specs will be the source of truth for system behavior, so accuracy matters more than speed. Work in the stages below and stop for my approval at the end of each one. Do not modify application code or tests at any point.

Stage 0: Inventory (read-only)
- Locate GSD's planning directory and list what it contains: project doc, requirements, roadmap, state, phase plans, summaries, verification records, codebase maps. Don't assume file names; report what is actually there.
- Locate everything GSD installed for Claude Code in this repo (commands, agents, skills, hooks, settings entries, CLAUDE.md sections). Separately note anything installed globally under my home directory, but do not touch it.
- Read the OpenSpec files created by init, and run the openspec CLI help so you know the exact spec format and validation command for the installed version.
- Report the inventory and stop.

Stage 1: Propose the capability map
- From GSD's requirements and phase artifacts, propose a set of capabilities to organize specs by. Capabilities describe areas of system behavior (e.g. authentication, billing), not GSD phases.
- For each capability, list which GSD requirements and phases feed it.
- List any GSD requirements that were planned but have no verification record, or that were deferred or dropped. These are excluded from the specs unless I say otherwise.
- Stop for my approval of the map.

Stage 2: Seed the specs
- Write one spec per approved capability under openspec/specs/, in the format the installed OpenSpec version expects. Each requirement gets at least one scenario with an observable outcome.
- Source content only from GSD artifacts that record verified behavior. Do not invent requirements, and do not fill gaps by reading the code. If the artifacts are ambiguous, record the question instead of guessing.
- Keep specs free of implementation detail.
- Write a traceability file at openspec/migration/traceability.md mapping every requirement to its GSD source (file and section).
- Run OpenSpec's validation in strict mode and fix format errors.
- Report the specs written, open questions, and stop.

Stage 3: Config
- Draft openspec/config.yaml context from the durable parts of GSD's project doc: stack, build and test commands, conventions, constraints, off-limits areas. Leave out history, status, and roadmap content. Keep it under about one page.
- Don't duplicate what CLAUDE.md already says; note overlaps instead.
- Show me the draft and stop.

Stage 4: Check specs against the code
- For every requirement, find the implementing code and tests and classify it: matches, partially matches, contradicts, or not found.
- Give me a table: requirement, classification, evidence (file and line), and a one-line description of any difference.
- Do not change specs or code to resolve differences. I will decide each one.
- Also list significant behavior you find in the code that no spec covers.
- Stop.

Stage 5: Retire GSD in this repo
- Propose, as an explicit list of file operations, how to: move GSD's planning directory to a clearly named archive location and mark it as a frozen historical record; remove or disable the repo-local GSD commands, agents, skills, and hooks found in Stage 0; and remove GSD instructions from CLAUDE.md.
- Add a short note to CLAUDE.md stating that OpenSpec is the workflow for this repo and the GSD archive is read-only history.
- Wait for my approval of the list before executing any of it.

At the end, summarize what was done, what remains open, and anything you were unsure about.

Notes on Using It

  • Run Stage 4 in a fresh session. A session that just wrote the specs will tend to see the code as matching them. Paste only the Stage 4 section, with a line saying the specs already exist.
  • Stage 2’s “don’t read the code” rule is deliberate. It keeps the specs as a record of intent, so Stage 4 is a real comparison and not the same reading done twice.
  • Commit after each stage. That gives you a clean diff per step and an easy rollback.
  • The traceability file is outside the specs so it doesn’t interfere with validation. It’s also a useful audit artifact showing where each baseline requirement came from.
  • Global GSD install. If Stage 0 finds one, the commands will still appear in this repo after Stage 5. You’d need to uninstall it yourself or accept that it’s there for other projects.
  • Expect to edit Stage 1. The first capability map usually mirrors the GSD phase structure too closely. Push back until the names would make sense to someone who never saw the roadmap.

Author:

Jim Zuber, Chief Technology Officer

Over the past four decades, Jim Zuber, co-founder and Chief Technology Officer at QualityLogic, has established himself as a leading innovator in developing testing standards and methodologies for industries such as smart energy, imaging, telecommunications, and software technology.

Jim’s career in technology began with his role as co-founder and CTO at Blue Chip Software, where he developed the official simulation software for the American Stock Exchange, co-branded with the Amex itself. The company was successfully acquired by Compton’s New Media in 1986. Following this, Jim co-founded and served as president of Genoa Technology, guiding it to prominence as a trusted provider of test solutions within the computer and telecommunications sectors. The merger of Genoa Technology with Revision Labs Inc. laid the foundation for what would become QualityLogic.

At QualityLogic, Jim has been instrumental in architecting innovative testing products and solutions that have set industry benchmarks. His expertise in creating practical and effective testing methodologies continues to shape QualityLogic’s reputation as a leader in QA and software testing standards.

Jim remains actively engaged in advancing QualityLogic’s technology initiatives, regularly contributing insights and thought leadership in AI technologies, software testing, and industry standards.