Migrating From OpenSpec to GSD: When It's Worth It

7 min read
Spec-Driven DevelopmentGSDOpenSpecAIClaude Code

If you've been shipping features with OpenSpec for a few months and keep running into the same wall on longer changes, you're probably starting to wonder about GSD. I get asked this question at least once a week: "Is it worth migrating from OpenSpec to GSD?"

The honest answer: sometimes. Not always. This post walks through what actually changes when you switch, which migrations pay off, and which ones are premature. If you want the fundamentals first, start with what is spec-driven development and the three-tool comparison.

The Real Reason People Switch

Nine times out of ten, the migration question comes from one specific pain: context rot on longer changes. You write a clean OpenSpec proposal, run /opsx:apply, the agent starts strong, and by task 6 or 7 it's forgetting decisions from task 2. Variables get renamed inconsistently. Approaches that failed earlier get retried. The agent behaves like it's operating on polluted context, because it is.

This isn't an OpenSpec defect. OpenSpec is a specification layer. It hands the change folder to your agent and trusts it to execute. If your agent's context window degrades over a long task sequence, OpenSpec doesn't intervene. It can't — that's not its job.

GSD's job is exactly that intervention. It spawns a fresh subagent per task, injects an anchor message that marks the task boundary, and prunes the conversation history back to that anchor before every LLM call. Task 7 runs with the same context quality as task 1. Context rot is architecturally solved.

If you're feeling context rot weekly, GSD is worth the migration. If you're shipping clean 3–4 task changes with OpenSpec and your agent never drifts, you probably don't need it.

What You Keep

The conceptual model transfers almost directly. Both tools share the same core DNA:

  • Specs as the contract. Both tools make the spec the source of truth. A GSD phase plan and an OpenSpec change folder are morphologically similar — proposal, specs, tasks, verification.
  • Archive-on-merge. OpenSpec archives completed changes into specs/. GSD archives completed phases into .planning/completed/. Same philosophy, different folder.
  • Brownfield tolerance. GSD's /gsd:map-codebase plays a role similar to OpenSpec's /opsx:onboard — reverse-engineer the current state into structured context before planning changes against it.

The mental model you built on OpenSpec is not wasted. Most of it maps directly to GSD. That's why migrations are smoother than teams expect.

What Changes

The biggest shifts, in rough order of impact:

1. Execution Becomes Orchestrated

OpenSpec's apply step hands the change to the agent and steps back. GSD's execute phase spawns fresh subagents per task (or per wave of parallel tasks), each with its own context, each with injected task-specific state.

Practically, this means:

  • Your main Claude Code context stays cleaner — it's the orchestrator, not the implementer
  • Parallel tasks actually run in parallel, not serially within a single context
  • A failed task doesn't poison the context of the next task

The downside: you're locked into Claude Code as your agent. GSD's orchestration primitives rely on Claude Code's Task tool to spawn subagents. If your team uses Cursor or Copilot primarily, GSD doesn't serve you.

2. Git Operations Become Deterministic

OpenSpec leaves branch management to you. You create the feature branch, commit when you feel like it, merge when ready.

GSD enforces a git discipline that took me a week to appreciate: one branch per phase, one atomic commit per task, squash merge at phase completion. The gsd_manage tool handles all of it. You never type a git command during execution.

This discipline is valuable because it's enforced. With OpenSpec I occasionally committed three tasks worth of work in a single commit because I forgot. With GSD that's impossible — the tool won't let you.

3. Verification Moves From Structural to Behavioral

OpenSpec's /opsx:validate is a structural check. Does the proposal have the right sections? Are the specs formatted correctly? Does each task reference a spec?

GSD's verification ladder goes deeper. It checks:

  • Static — files exist, imports wire up, no stub returns
  • Command — the build passes, tests pass, lint clean
  • Behavioral — specific truths from the spec actually hold in the running code
  • Human UAT — the feature works as the spec described when a human uses it

This isn't always better. On a small change, the structural check is enough and the behavioral ladder is overkill. On a larger change, the behavioral ladder catches what structural checks miss.

4. The Output Weight Grows

An OpenSpec change is ~250 lines of markdown. A GSD phase plan is 500–1000 lines plus per-slice PLAN.md files. More artifacts means more review surface. For solo work that's fine. For team work where a human has to read the plan, it can become expensive.

What You Give Up

Three real losses worth naming:

Agent Portability

OpenSpec supports 24+ agents. You can move a change folder between Claude Code and Cursor mid-feature. GSD is Claude Code-centric. The orchestration primitives don't work elsewhere. If part of your value proposition to your team or client is "pick your agent," you're trading that away.

Lightness

OpenSpec's four-phase state machine is deliberately light. GSD has more ceremony — discuss phase, plan phase, execute phase, verify phase, each with its own sub-artifacts. For a 2-hour change you don't need most of it. GSD has /gsd:quick and /gsd:fast modes for small changes, but the default workflow is heavier.

Your Existing Archive

OpenSpec archives live in openspec/specs/. GSD phase archives live in .planning/completed/. The formats are different. You don't lose the information, but you lose the ability to run OpenSpec tooling against your existing archive. This is fine on a forward-only basis, but if you're attached to the archive as living documentation, plan for the cutover.

Migration Playbook

If you've decided the switch is worth it, here's the playbook I'd follow:

Step 1 — Run the two tools side-by-side for two weeks. Don't migrate existing changes. Start new changes in GSD. Leave in-flight OpenSpec changes on OpenSpec. The goal is calibration — how does GSD feel on your codebase, not on a demo repo?

npx @gsd-build/cli@latest init

This creates .planning/, drops the default PROJECT.md stub, and registers /gsd:* commands with Claude Code.

Step 2 — Port PROJECT.md from your OpenSpec constitution or README. GSD's PROJECT.md plays a similar governance role to Spec Kit's Constitution or a well-written OpenSpec README. If you wrote one for OpenSpec, most of it transfers:

# Project: ClientCRM

## Stack
- Next.js 16, React 19, Tailwind v4
- Postgres (Supabase), Prisma
- Vercel deployment

## Principles
- All user-facing strings route through i18n
- API contracts are versioned; breaking changes require a new path
- Migrations are one-way in production

## Non-Negotiables
- Authentication uses Clerk; no custom auth
- Secrets live in Vercel env; never in code

Step 3 — Let /gsd:map-codebase scan your repo. This is GSD's equivalent of /opsx:onboard. It writes codebase maps into .planning/codebase/ that GSD uses as context for every future phase. Run it once, edit any sections that are wrong, commit.

Step 4 — Ship three small changes in GSD. Not one. Three. The first change is slow — you're learning the command surface. The second is faster. The third is where you start to feel whether GSD's discipline is earning its weight on your work. If after three changes you're still fighting the tool, don't migrate. Keep OpenSpec for the foreseeable future.

Step 5 — Archive OpenSpec, not delete. Leave openspec/ in the repo. Don't reformat old specs into GSD's schema — that's pure churn. New work goes into .planning/. Old work lives in openspec/ as historical reference. Both trees coexist fine.

When Not To Migrate

I've talked half a dozen teams out of migrating. The patterns:

  • You use Cursor or Copilot as your primary agent. GSD assumes Claude Code. If you switch, you're also switching your agent.
  • Your changes are short and shallow. If every OpenSpec change you ship is 3–4 tasks and archives cleanly, GSD's orchestration primitives are solving a problem you don't have.
  • Your team has multiple engineers using different agents. OpenSpec's portability is genuinely valuable here. GSD's Claude-specificity would fracture your workflow.
  • You've just finished building OpenSpec muscle memory. If your team only recently got comfortable with OpenSpec, adding a new tool resets the learning curve. Defer six months and revisit.

When To Migrate

Conversely, the patterns where the migration consistently pays off:

  • You're solo or in a small team where everyone uses Claude Code. GSD's depth of integration is wasted on teams that don't commit to a single agent. Claude Code + GSD is where the combined value lives.
  • You ship longer features — 8+ tasks. Context rot becomes measurable past 6 or 7 tasks. GSD's context pruning is the direct fix.
  • You're starting a greenfield project. Migration cost is zero because there's no history. Start GSD from day one if the project is Claude Code-centric.
  • You've outgrown OpenSpec's structural validation. If you keep having "the spec looked fine but the implementation was wrong" moments, GSD's behavioral verification earns its weight.

The Honest Summary

OpenSpec is a lightweight specification layer that respects your agent's autonomy. GSD is an execution orchestrator that takes that autonomy back in exchange for reliability. Neither is universally better. The right tool is the one whose opinions match your constraints.

If context rot is your pain, migrate. If agent portability is your pain, don't. If you're not sure which is your pain, keep using OpenSpec for three more months, then decide.

For the deeper architectural reasons behind GSD's design, see the GSD architecture deep-dive. For the comparison including Spec Kit, see the three-tool comparison. And if you want my production setup, it's on the tools and stack page.

Evaluating the migration or already in the middle of it? Reach out — happy to trade notes on how the tools behave on real codebases.