Jonathon's AI Wiki

OpenSpec — Spec-Driven Vibe-Coding Framework with Iterative Continue/Sync (Three-Tool Taxonomy)

11 min read

Source: “OpenSpec Will Change How You Vibe Code Forever” YouTube tutorial, ~12-min, youtube.com/watch?v=nFq4POtqom4, fetched 2026-05-03. Auto-captions normalized for “OpenSpec” (caption: “Open Spec”), “BMad” (caption: “B Mad”), “GitHub Spec Kit” (caption: “Spec Kit”), “Obra” (creator’s name for the Superpowers framework — equals Jesse Vincent’s superpowers). Creator name not in transcript.

A practical introduction to OpenSpec, a spec-driven coding framework that produces a proposal.md + design.md + tasks.md + specs/ artifact set per change, then validates and applies the spec, then archives the change while keeping a living root specs/ directory in sync. The video’s most reusable contribution is a three-tool taxonomy of vibe-coding frameworks that places OpenSpec alongside its peers — useful for any operator deciding which framework to install. Concrete worked example: migrating a recipe-app’s design system from Claude Design mockups to actual code, using Chrome MCP for visual validation, runtime ~2 hours autonomous + ~1–2 hours of approval gates. Sister to Superpowers (the SDLC enforcement leg of the same taxonomy) and to the AITmpl BrainGrid entry (the PRD-planner leg upstream of Claude Code).

Key Takeaways

  • Three-tool taxonomy of vibe-coding frameworks (the most quotable contribution). Source argues this lets you pick the right tool for the job rather than installing all of them.

    CategoryExamplesMental modelWhen to reach
    1. Spec-drivenOpenSpec, GitHub Spec KitHuman orchestrates, agent assists. The spec IS the primary artifact.New to AI coding, or feature complexity is high → forces clarity before code
    2. SDLC enforcement[[claude-ai/superpowers-skills-frameworkObra/Superpowers]], compound engineeringWorkflows that enforce best practices (TDD red-green-refactor, plan-first, isolated environments). Process matters more than artifact.
    3. Autonomous pipelineBMad, GSD ([[claude-ai/six-best-claude-code-skills-businessGet-Done plugin]])Define + walk away. Heavy on subagent orchestration and “let it run.”

    Crossover happens — but author argues OpenSpec sits firmly in category 1 with explicit chaining hooks into category 2 (you can call Superpowers’ worktree skill from OpenSpec) and limited overlap with category 3.

  • OpenSpec’s primary artifact set per change. Each change produces:

    • changes/<id>/proposal.md — the what + why (what’s changing, the changelog framing)
    • changes/<id>/design.md — the how at architecture level (primary architecture decisions, tokens migration approach, component-build conventions, app routing changes)
    • changes/<id>/tasks.md — the how at implementation level (phase-by-phase ordered task list)
    • changes/<id>/specs/<concern>/ — per-concern spec files with explicit user-story scenarios (e.g., bookmarks.md, discovery-page.md, following.md, design-system-migration.md)

    The specs/<concern>/ artifacts are the persistent contract — when you later modify behavior, OpenSpec checks against them and forces you to reconcile if you broke something.

  • Five-stage standard workflow. explore (optional, callable any time) → propose (generates proposal + design + tasks + specs) → validate (manually invokable; can call any MCP for verification, e.g., Chrome browser MCP) → apply (executes the tasks) → archive (syncs change specs into root specs/). Plus three new commands (next bullet) for iterative work.

  • new + continue as the iterative-planning unlock. Instead of generating proposal + design + tasks all at once via propose, run new <change-id> to scaffold the change folder, then continue to draft each piece step by step. After each artifact is drafted, you can review it, ask questions, run explore to deepen understanding, then resume continue. Why this matters: spec-driven approaches normally lock you in too early — OpenSpec lets new information rewrite the plan as you go without losing the structure. Source explicitly contrasts this with GitHub Spec Kit’s more rigid “you should already know what you’re building” approach.

  • Slice vs single-change as the first iterative-planning question. continue will surface: “Do you want one huge change with everything in it, or sliced changes (each with its own proposal/specs/tasks)?” Sliced is slower but preserves audit boundaries. Source picked sliced for a backend migration to ensure no logic was missed.

  • fast forward as the “trust the spec, run the rest” command. Once the plan is solid, fast forward skips the per-stage approval gates and runs proposal → specs → tasks → apply → archive autonomously. Stays on the rails (still records artifacts; still enforces specs); just stops asking for confirmation between stages. Useful when the human is ready to step away.

  • sync as the documentation-drift killer. When a change touches existing functionality (e.g., updating a public-profile feature), sync (called automatically during archive) merges the change’s spec into the root specs/<concern>.md so the documentation always reflects current behavior. Source argues this is one of the most undervalued features: “A lot of people complain about how it’s difficult to manage the documentation of their app over time. And this is how Open Spec helps you manage that.” Closes the spec-as-living-doc gap that most coding agents leave open.

  • validate is where vision-checking lives. Author asked OpenSpec to add a verification step using Chrome browser MCP to visually compare the rendered UI against design mockups. Source emphasizes: “A lot of these tools, they tend to functionally describe how something should work but they do not often describe visually how the thing really needs to look.” Adding a visual-check step is what turns “spec said this should work” into “spec said this should work AND it actually looks right.” Echoes the Sam Witteveen self-QA-via-vision pattern from Claude Design.

  • Concrete worked example: design-system migration. Author had a recipe-app he’d already vibe-coded one version of. Mockups in Claude Design looked dramatically better than what was in code. Used OpenSpec to bridge the gap: explore (with extra context paste), propose (generated bookmarks + discovery + following + design-system-migration specs), validate (Chrome MCP vs Claude Design mockups), apply (~2 hours autonomous after toggling auto-mode), archive. Output: discovery page rendered close to mockup (sidebar spacing slightly off; recipe page transformed from “vanilla” to magazine-style); user-profile page closer but with accent-color drift on action buttons. Quote: “For doing such a large-scale refactor of the design system, it got very close to what we were asking it to do.”

  • Chains with other frameworks rather than replacing them. Author runs Obra/Superpowers’ worktrees skill before OpenSpec to spin up the work tree, run baseline tests, ensure clean state. “Just because you’re using one of these doesn’t mean you can’t use the others.” Practical chain: Worktrees → OpenSpec explore/propose → OpenSpec apply (runs tests via Superpowers’ TDD primitives) → /ultrareview before merge. Validates the six-best-skills curator’s “compose, don’t centralize” philosophy.

  • Onboarding skill is built-in. Source line 124–127: openspec onboard walks new users through their first feature manually. Author skipped it for the demo to show all stages explicitly but recommends it for newcomers. Pairs with Jeff’s Cowork starter templates as a class of “the framework ships its own getting-started experience.”

  • Two-hour autonomous run was 3–4 hours wall-clock with approval gates. Important calibration: source used auto-mode (Claude Code’s research-preview auto-mode, available since W13) to skip approval gates partway through. Without auto-mode, approval gates roughly doubled wall-clock time. Operator implication: budget for either patient sit-with-the-agent time OR auto-mode-with-supervision, not both.

  • Persistent specs/ directory becomes a moat. As the codebase grows, the root specs/ directory accumulates a complete, machine-readable description of every feature’s intended behavior. Future changes get checked against it; documentation drift is impossible because archive enforces sync. This is the same compounding-context argument as the Cowork Jarvis tutorial but for code-level features rather than personal-context: every change makes the system easier to extend, not harder.

How OpenSpec compares with peers (curator’s framing extended)

FrameworkCategorySpec formatLiving docs?Autonomous?Best for
OpenSpec1 — spec-drivenproposal + design + tasks + specs/Yes via sync + archiveOptional via fast forward + auto-modeEstablished projects, design migrations, anywhere doc drift is expensive
GitHub Spec Kit1 — spec-drivenCustom templatesLimitedLimitedGreenfield with clear PRD
BrainGrid1 — spec-driven (PRD-as-upstream)PRD documentsLimited (upstream of code)NoPre-Claude-Code planning surface
Superpowers (Obra)2 — SDLC enforcementTDD red-green-refactorTests-as-docsLimitedProduction code; multi-week features
Compound engineering2 — SDLC enforcementProcess-drivenLimitedLimitedWorkflow discipline more than doc capture
BMad3 — autonomous pipelineWorkflow-definedNoYes (define + walk away)Repeatable scope, token-cheap
GSD plugin3 — autonomous pipelineSubagent-fleet outputNoYesLong-context-rot work, runs subagents in parallel

Source’s punchline: spec-driven (cat. 1) is the right starting point for non-developers, because the ceremony of writing the spec is exactly the discipline they need. SDLC enforcement (cat. 2) is for developers shipping production code. Autonomous pipeline (cat. 3) is for work where token cost is cheaper than human attention.

Implementation

Tool/Service: OpenSpec — install via npm; run openspec init (also accessible as opsx short alias) inside a project. CLI mode + Claude Code chaining.

Setup:

  1. Install the package: npm install -g openspec (per source line 113; exact package name not transcribed; verify on the project’s GitHub before installing).
  2. Move into your project: cd <project>.
  3. Run openspec init, choose your environment (Claude Code, Cursor, etc.).
  4. Optional: openspec onboard for a guided first feature.

Standard commands (from the source — exact CLI flags not all spelled out aloud):

openspec explore        # optional; reason about the change before locking in
openspec propose        # generate proposal + design + tasks + specs in one shot
openspec validate       # invoke validators (e.g., chrome MCP for visual check)
openspec apply <id>     # execute tasks for the change
openspec archive <id>   # sync change specs into root specs/ + move to archive
openspec new <id>       # scaffold a change for iterative drafting
openspec continue       # advance to the next stage of an in-progress change
openspec fast-forward   # run remaining stages without approval gates
openspec sync           # called by archive; reconcile change specs into root specs/

Cost: OpenSpec itself is free / open source (verify license on GitHub). Token cost during a run depends on Claude Code model and effort — author was on auto-mode for the long-run portion; specific spend not stated.

Integration notes:

  • Chain with Superpowers’ worktrees skill at the start to ensure clean baseline before OpenSpec proposes a change.
  • Boot Claude Code with --chrome flag so validate can drive Chrome via MCP for visual verification.
  • auto-mode halves wall-clock time once you trust the plan; pair with fast forward for end-to-end autonomy.
  • Source-derived from Claude Design mockups → OpenSpec → real code is a viable pattern; mirrors the Claude Design handoff pattern but adds spec rigor.
  • Per-change archive preserves history; future changes can grep prior decisions.
  • Don’t run BrainGrid AND OpenSpec for the same change — both are category-1 spec-driven; pick one. BrainGrid is upstream-of-Claude-Code (PRD planning); OpenSpec is inside-Claude-Code (per-change specs).

Try It

  • Run openspec init in a small existing project and use openspec explore to talk through one upcoming change before generating any specs.
  • For a UI-heavy change: pair with Chrome MCP and ask validate to compare rendered output against a design mockup. The visual-check step is the single biggest accuracy upgrade in the source.
  • For first-time users: run openspec onboard instead of jumping into manual stages.
  • Compare the iterative new + continue flow against Superpowers’ brainstorming skill — same principle (don’t lock the plan in too early), different surface.
  • For Intermediate Course Module 6 (Claude Code Bridge) readers: this is a candidate add-on tool for Builder-track participants who want spec discipline without giving up vibe-coding agility.
  • Test sync on a change that modifies an existing feature; verify the root specs/<concern>.md file actually gets updated and that re-running spec validation catches a deliberately-broken behavior.
  • For the 2026 AIOS Pattern — OpenSpec is a candidate “code-track sister” to the personal-context-track frameworks (Cowork Jarvis, Simon Scrapes, Nate Herk AIS-OS); both apply rule-stacking + persistent-spec patterns at different layers.

Open Questions

  • Author identity not stated. Style consistent with a Claude Code creator running a free + paid community; references “playlist of other breakdowns of tools like this one.” No name in transcript.
  • OpenSpec npm package name unverified. Source says “install via this command” but doesn’t say the command aloud. Verify on the official GitHub before installing — could be openspec, @openspec/cli, or similar.
  • OpenSpec author / publisher not in transcript. Open-source repo location not stated. Worth a 6-question vetting pass before WEO Council recommendation.
  • Chrome MCP MCP-name disambiguation. Source mentions “Chrome browser extension MCP” — likely the same family of Chrome-driving MCPs available in Claude Code’s plugin ecosystem. Pin exact identifier (chrome-devtools-mcp, playwright-mcp for headless, etc.) before recommending.
  • fast forward-to-auto-mode interplay. Both skip approval gates but at different layers — fast forward is OpenSpec-stage skipping; auto-mode is Claude Code’s per-tool-call approval skipping. Open whether using both together creates double-redundant skip behavior or compounds.
  • GSD-vs-GSD disambiguation. Source places “GSD” in the autonomous-pipeline category alongside BMad. The same name appears in six-best-skills as a Claude Code plugin and in Simon Scrapes’ nine-component AIOS as a planning framework. May be one artifact viewed at three abstraction levels (planning framework → Claude Code plugin implementation → autonomous pipeline framework). Tracking the canonical GitHub repo would resolve.
  • sync behavior on conflicting concerns. What happens if two simultaneous changes touch the same root specs/<concern>.md file? Source doesn’t show a merge conflict scenario.
  • Long-term archive bloat. After many changes, archive/ accumulates large amounts of historical material. Source doesn’t discuss pruning or compaction strategy for archive/.

Graph View

Backlinks