September 25, 2026
EN
September 14, 2026 · By YasKad
Fission-AI/OpenSpec

OpenSpec: the lightweight spec layer that forces agreement on what to build before writing code

Fission-AI/OpenSpec · 70,314★ · 4,813 forks

OpenSpec is a lightweight specification layer that forces the developer and their code assistant to agree, in writing, on what’s going to be built before a single line of code is written. It’s the main “lightweight” alternative to the spec-driven approach within a tool ecosystem that grew fast starting in 2025.

Disambiguation note: the repository is called OpenSpec (capitalized) on GitHub; the queue row uses openspec. At least one unrelated project shares the name (an OpenAPI/Swagger explorer at openspec.vercel.app), but the repository documented here is Fission-AI/OpenSpec.

A striking cyberpunk tech illustration of a dark-mode development command center for a lightweight spec-driven AI coding framework, in the center a glowing holographic pipeline flows from left to right with five labeled stages: explore, propose, apply, sync, and archive, around the pipeline translucent Markdown documents float in the air, showing clean structured text blocks, requirement scenarios, task checklists, and delta sections marked with ADDED, MODIFIED, and REMOVED, a human developer silhouette and an abstract AI assistant interface stand facing each other, aligned by a shared luminous contract between them, the background is a deep charcoal interface with faint terminal windows, repository folders, git branch lines, and subtle code graphs, neon cyan, electric blue, soft magenta, and amber accents pulse through the composition, the mood is precise, futuristic, and professional, with a sense of agreement before code, ultra-detailed, 8K resolution, cinematic lighting, dark mode, cyberpunk/tech aesthetic, clean vector-inspired holograms, high-end editorial cover image

What OpenSpec is

OpenSpec is a spec-driven development (SDD) framework for AI coding assistants. It’s not a model, an IDE, or a server: it’s a Node.js CLI that generates Markdown files inside the project itself, plus a set of skills and slash commands (/opsx:*) that the AI assistant runs in the chat.

Its purpose is to move agreement on requirements out of the chat history. When requirements only live in a conversation, the assistant fills gaps with assumptions, and the error gets discovered after the code already exists. OpenSpec introduces a verifiable contract: each change is planned in a folder with a proposal, delta specs, design, and task list; the human reviews the plan before anything gets implemented, and when the change is archived, the specs become the description of the system’s current behavior.

The README itself sums up the philosophy in five lines: fluid, not rigid; iterative, not waterfall; easy, not complex; built for brownfield, not just new projects; and scalable from personal projects to enterprises.

Origin

The repository was created on August 5, 2025 by the Fission-AI organization on GitHub. The maintainers declared in MAINTAINERS.md are Tabish Bidiwale (TabishB), lead maintainer, and Clay Good (clay-good), maintainer, with Hari Krishnan (harikrishnan83) as technical advisor. The official site, openspec.dev, carries the mark ”© 2026 Fission,” indicating the project is backed by the Fission company.

The narrative color the consulted sources offer is modest: there’s no viral launch post with an anecdote, unlike other tools in the same niche. The documented trajectory is that of a project that matured steadily: it started experimental in August 2025, became stable with v1.0.0 on January 26, 2026 (a full redesign of the flow around an artifact-based action system, with breaking changes), and has shipped nearly weekly releases since. The project’s lead author, Tabish Bidiwale, published a launch video and maintains the @0xTab profile on X, which the README links for news.

Philosophy and principles

The README and documentation state the following principles, verifiable in the flow’s own code: agree before building (the assistant and the human align on specs before writing code; the error is cheap in the plan, expensive in the implementation); fluid, not rigid phases (any artifact — proposal, specs, design, tasks — can be edited at any time; there are no phase gates blocking progress); plain Markdown, no special syntax (specs are requirements with SHALL/MUST + GIVEN/WHEN/THEN scenarios, human-readable and CLI-verifiable); and tool neutrality (works with 30+ AI assistants by installing the skill or command format each one uses, instead of forcing a single environment).

A tool-neutral AI assistant ecosystem visualization centered on a shared specification hub, in the middle a glowing OpenSpec-style specification core emits structured documents and requirement scenarios, around it numerous AI coding assistant interfaces orbit in a dark space: chat panels, IDE sidebars, terminal clients, MCP tool servers, editor plugins, and agent workspaces, each satellite has a distinct neon color but connects through the same central contract, showing compatibility across many tools rather than one locked environment, thin data lines link the hub to 30+ assistant icons, representing broad integration, the background includes subtle code snippets, command palettes, and repository badges, ultra-detailed, 8K resolution, dark mode, cyberpunk/tech aesthetic, neon accents, high-tech orchestration, clean professional illustration

Brownfield-first: the full application isn’t documented upfront; a spec is written only for what each change touches, and specs grow with real work.

A brownfield-first software architecture scene showing an existing legacy codebase represented as a dense dark circuit-board cityscape, most of the city is muted, stable, and dimly lit, but one specific district is highlighted with bright neon outlines where a new change is being planned, floating above the highlighted area are lightweight specification cards, task lists, and design notes, emphasizing that only the touched parts are specified, small AI assistant probes inspect the relevant modules without overhauling the whole system, the composition communicates iterative, incremental specification work inside real-world projects rather than greenfield perfection, dark mode, cyberpunk/tech aesthetic, ultra-detailed, 8K resolution, neon accents, cinematic depth, clean futuristic visual metaphor

A core concept is the delta spec: each change declares only what it modifies (ADDED, MODIFIED, REMOVED sections) instead of rewriting the whole spec, and on archive, those deltas are merged into the main spec. The archived change stays in openspec/changes/archive/ as auditable history.

A conceptual illustration of delta specifications being merged into a main system specification, on the left a change folder emits small glowing document fragments labeled ADDED, MODIFIED, and REMOVED, in the center a luminous merge funnel combines these fragments into a larger canonical specification document, on the right the updated spec glows as the single source of truth, while the completed change folder is archived into a timestamped historical stack, the visual language uses layered Markdown pages, semantic diff colors, and thin neon connectors, the scene conveys auditable history, incremental evolution, and clean documentation, dark background with subtle blueprint grids, repository icons, and faint git commit nodes, ultra-detailed, 8K resolution, dark mode, cyberpunk/tech aesthetic, neon cyan and magenta accents, precise editorial illustration

How it works

The documented basic flow (core profile, default):

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (optional)
  1. /opsx:explore (optional): a no-commitment “thinking companion” that reads the codebase, weighs options, and turns a fuzzy idea into a concrete plan, without creating any artifact yet.
  2. /opsx:propose <name>: creates openspec/changes/<name>/ with proposal.md (the why and scope), specs/ (deltas with requirements and scenarios), design.md (the technical how), and tasks.md (implementation checklist). The human reviews the plan.
  3. /opsx:apply: the agent implements the tasks; if the design needs adjustments, the artifacts are edited and work continues.
  4. /opsx:sync (optional): merges the deltas into the main specs before archiving, useful for long changes.
  5. /opsx:archive: applies the deltas to the main spec and moves the change to changes/archive/YYYY-MM-DD-<name>/.

A detailed dark-mode terminal scene showing an AI coding assistant interacting with a specification workflow, a sleek command-line interface displays commands such as /opsx:explore, /opsx:propose, /opsx:apply, /opsx:sync, and /opsx:archive in crisp monospace text, to the right a generated project folder unfolds in a holographic tree: openspec/changes/change-name/ contains proposal.md, specs/, design.md, and tasks.md, each file glows with a different neon accent: proposal in cyan, specs in blue, design in violet, tasks in amber, small holographic checkmarks and diff markers appear beside task items, the environment is a dark developer workspace with soft grid lines, floating terminal tabs, and subtle repository metadata, ultra-detailed, 8K resolution, cyberpunk/tech aesthetic, dark mode, neon accents, clean futuristic interface design

There’s an expanded profile (new, continue, ff, verify, bulk-archive, onboard) activated with openspec config profile. The terminal CLI complements the chat with openspec list, openspec show <change> [--diff], openspec validate [--report findings], openspec status --all, openspec view (interactive panel), and openspec feedback.

Also, since the beta, OpenSpec offers Stores: a standalone repository dedicated solely to planning, with the same openspec/ shape (specs and changes) shared via git push like any other repo. It solves the case where a feature spans three repositories, or where a platform team owns the requirements and product teams consume them read-only. openspec store setup <name> and openspec new change <id> --store <name> are the bootstrap commands.

A futuristic illustration of a shared planning repository called a Store, a standalone repository hologram floats above a dark developer environment, containing only specs/ and changes/ folders, with no application source code inside, multiple product team workstations and repository nodes connect to the Store through glowing git push and pull lines, one scenario shows a single feature spanning three repositories, with the central Store coordinating the plan, while platform team and product team nodes access the same specification in read-only or editable modes, the visual is precise and systems-oriented, with repository graphs, branch lines, permission badges, and synchronized document cards, dark mode, cyberpunk/tech aesthetic, ultra-detailed, 8K resolution, neon blue and cyan accents, clean editorial tech style

The ecosystem

Fission-AI organization repositories

Fission-AI/OpenSpec: the main project (this report). Fission-AI/PR-QUEST: a more interactive way to review change requests; 25 stars (October 16, 2025).

The associated commercial product, documented on the official blog, is the OpenSpec Cloud Agent (early access on August 28, 2026): an always-on layer that compares pull requests against the requirements of connected repositories, detects “drift” between code and specs by citing the exact line of both, and can open corrective PRs. A September 11, 2026 update notes that new sign-ups for the early access program are paused while they evaluate the product with participating teams.

A cyberpunk code-review control room showing an always-active cloud agent comparing pull requests against repository specifications, on the left a pull request diff glows with changed code lines, on the right the corresponding specification document displays requirement scenarios and normative statements, in the center an AI drift-detection interface draws bright red and amber connection lines between mismatched code behavior and spec expectations, highlighting the exact line in both documents, a corrective pull request is generated below as a small glowing branch, the atmosphere is vigilant, precise, and automated, like a quality assurance sentinel watching code and requirements in real time, dark mode, ultra-detailed, 8K resolution, cyberpunk/tech aesthetic, neon accents, high-end software engineering visual

Community tools

UIs and visualizers (cataloged in speclib/awesome-openspec, 73 stars): ToruAI/openspec-ui (real-time kanban, 31 stars), oioi555/openspec-webui (interactive web UI, 14 stars), jixoai/openspecui (web UI with live mode and static export, 113 stars), and others like fselich/dossier, MusicAdam/openspec-viewer, sflueckiger/specboard, dansreis/speclens, spekhq/spek.

Editor/agent integrations and plugins: Lumiaqian/openspec-mcp (MCP server with kanban panel), johnnyblabs/intellij-openspec (IntelliJ plugin), Octane0411/opencode-plugin-openspec (160 stars, OpenCode plugin with an “architect” mode), fastknifes/openflow (180 stars, combines OpenSpec and Superpowers), and extensions for Copilot, VS Code/Cursor, Zed, Emacs, and Neovim.

Hybrid flows and community schemas: JiangWay/openspec-schemas (222 stars, includes superpowers-bridge), intent-driven-dev/openspec-schemas (94 stars), MageByte-Zero/spec-superflow (798 stars, fuses with Superpowers), rihebty/flow-kit (400 stars), SYZ-Coder/superpowers-openspec-team-skills (193 stars), sudokar/openspec-plus (190 stars), wenqingyu/ralphy-openspec (182 stars).

Reverse engineering and guides: clay-good/OpenLore (304 stars, formerly spec-gen, from maintainer Clay Good himself, generates specs from existing code), ForceInjection/OpenSpec-practise (614 stars), sohaha/studyzy-OpenSpec-cn (96 stars), and more community guides in Chinese.

A vibrant ecosystem map of community tools surrounding a central specification framework, the composition resembles a dark digital constellation: a central node emits structured Markdown specs, while surrounding nodes represent UIs, visualizers, plugins, schemas, runbooks, and hybrid workflows, some nodes show kanban boards, web interfaces, editor extensions, MCP servers, adversarial review loops, evidence-based retrospectives, and multi-agent team skills, star counts and repository badges appear as subtle glowing chips, but the emphasis is on a thriving open ecosystem, the visual style is dense yet organized, with neon connection paths, floating panels, and a sense of rapid community growth, dark mode, cyberpunk/tech aesthetic, ultra-detailed, 8K resolution, neon cyan, magenta, and violet accents

Official / semi-official status

OpenSpec isn’t a component of a major vendor’s marketplace: it’s a standalone npm package (@fission-ai/openspec) under the MIT license, maintained by Fission-AI. There are three verifiable status signals: stable since v1.0.0 (January 26, 2026, with the “from experimental to stable” transition); de facto adoption in the SDD niche (Hacker News threads show OpenSpec named alongside Spec Kit, Superpowers, and Kiro in spec-driven development discussions); and an associated commercial product (the OpenSpec Cloud Agent signals a business intent beyond the OSS project).

In practice, OpenSpec functions as the lightweight, multi-tool option of the de facto “write specs before code” standard, competing head-on with github/spec-kit (official from GitHub) and Kiro (AWS), as the README itself compares.

Quick-start guide

Installation and first run

Prerequisite: Node.js 20.19.0 or later.

npm install -g @fission-ai/openspec@latest   # also pnpm add -g / bun add -g / yarn global add
openspec --version                            # verify
cd your-project
openspec init                                 # interactive: pick the AI tools you use

Non-interactive options: openspec init --tools claude,cursor, --tools all, --tools none, --profile core. With Nix: nix run github:Fission-AI/OpenSpec -- init.

On completion, openspec init creates the openspec/ structure (with specs/, changes/, and config.yaml), writes the skills and commands for each chosen tool, and prints a “Getting started” line with the exact spelling of the command for your tool. What to expect on first run: two terminal steps, then everything happens in the assistant’s chat. There’s no separate “interactive mode”; the slash command is the entry point to OpenSpec.

Common workflows

  • To propose a feature you already have clear: in the assistant’s chat, run /opsx:propose add-dark-mode; openspec/changes/add-dark-mode/ gets created with proposal.md, specs/, design.md, and tasks.md. Review the plan before continuing.
  • To think through a fuzzy idea before committing: run /opsx:explore, explain the problem, and the agent explores the code, asks questions, and proposes a scope; once done, hand off to /opsx:propose.
  • To implement: run /opsx:apply; the agent works the checklist and checks off each task. If you run out of context, open a new session and re-run /opsx:apply: it reads the artifacts and resumes from the first unchecked task.
  • To review and validate from the terminal: openspec list (active changes), openspec show <change> --diff (only the changed lines), openspec validate <change> (validates spec format). At the end, /opsx:archive merges the deltas into openspec/specs/ and archives the change.

Essential configuration

  1. openspec/config.yaml: the context: key injects text into every planning request; this is where you declare your tech stack and conventions.
  2. Command profile (openspec config profile): core (default) or the expanded profile (adds new, continue, ff, verify, bulk-archive, onboard).
  3. Artifact language: openspec init --language <language> generates specs in another language (headers and the words SHALL/MUST stay in English).
  4. Telemetry: on by default (only command names and version; auto-disabled in CI). Opt-out: openspec config set telemetry.enabled false.
  5. Stores (beta): openspec store setup <name> for multi-repo planning.

Common pitfalls and fixes

  • Typing /opsx:propose in the terminal: the most commonly documented mistake. openspec ... commands run in the terminal; /opsx:... commands are typed in the assistant’s chat.
  • Syntax doesn’t match your tool: /opsx:propose is /opsx-propose in Cursor and GitHub Copilot, @opsx-propose in Amazon Q, $openspec-propose in Codex, and /skill:openspec-propose in Kimi Code. Always use the form printed by openspec init.
  • Command doesn’t show up: usually the files aren’t installed. openspec update only refreshes existing files; if you never ran openspec init, run it and restart the assistant.
  • Old version on PATH: after updating the package, if openspec --version shows an older version, an earlier copy is masking the new one on PATH.
  • Hand-editing code and desyncing the spec: archiving makes your specs the record of truth; before archiving, reconcile. /opsx:verify and openspec show --diff help spot discrepancies.
  • Yarn 2+ has no global: install with npm, pnpm, or bun instead.

Integrations and migration

The openspec/ folder should be committed as source code. For CI: openspec validate --archived checks that all archived changes have every tasks.md task checked off; openspec validate --report findings emits a findings-only report for pipelines. openspec init --copilot-cloud generates files so GitHub’s code agent can use the CLI. The community server Lumiaqian/openspec-mcp exposes the CLI as MCP tools. To migrate from pre-1.0 versions, the old commands were removed; run openspec init to update — active changes, archived ones, and specs are preserved.

Current metrics

Measured: September 14, 2026, GitHub API and npm registry.

MetricValue
Stars68,216
Forks4,689
Open issues per API283
Commits (main branch, approximate)≈843
Main languageTypeScript
LicenseMIT
CreatedAugust 5, 2025
Last pushSeptember 14, 2026
Latest releasev1.13.0, September 9, 2026
npm downloads (week)378,332
npm downloads (month)1,768,196

Top contributors, by contributions: TabishB (518), clay-good (125), openspec-release-bot[bot] (23), github-actions[bot] (20), and dependabot[bot] (16). Caveats: open_issues_count may include open pull requests; the commit count is approximate; and watchers_count from the repository response mirrors the stars field, so it isn’t reported separately.

Community reception

The evidence retrieved shows consistent enthusiasm but also concrete, repeated objections.

In thread 47419539 (“Get Shit Done,” March 17, 2026), recroad wrote: “I use openspec and love it. I’m doing 5-7x with close to 100% of code AI generated, and shipping to production multiple times a day. I work on a large sass app with hundreds of customers.” gbrindisi added: “I like openspec, it lets you tune the workflow to your liking and doesn’t get in the way.” In 46692578 (“Ask HN: Do you have any evidence that agentic coding works?,” January 20, 2026), recroad cited OpenSpec again: “Works pretty great for me… Easily 5x speed minimum.” In 48774782 (“Superpowers 6,” July 3, 2026), wejick wrote: “SDD with openspec hit the right balance for me.”

The most articulate criticism appears in the large thread 47994012 (“Specsmaxxing,” 287 points and 295 comments, May 3, 2026). jochem9, who had used it “for a few months,” warned that “when a spec changes, the AI needs to find the relevant code to change it… in a large codebase it’s very easy to miss something.” alasano was harsher: “I enjoy OpenSpec’s format, but I don’t think maintaining the main specs is worth it. I’ve stopped doing it entirely… When you run the sync process, it keeps drifting until you have duplication and contradictions between specs.” gnatolf, in 47019109 (“Breaking the spell of vibe coding,” February 14, 2026), raised the scale objection: “Once the project grows to a relevant size of complexity, maintaining the specs is just as hard as the problem it solves.”

Developer Dan Clarke published a review on May 8, 2026 after a month of use: he chose it because Spec Kit felt “a bit heavy” to him, highlights the explore mode as a key feature, but notes that in his experience “it’s not really spec-driven… specs are an artifact of the flow, not the starting point.”

Comparison with similar projects

ProposalVerifiable overlapVerifiable difference
github/spec-kit (136,644 stars, Python)Official GitHub kit for SDD with CLI, templates, and integrations.OpenSpec’s README describes it as “comprehensive but heavy: rigid phase gates, lots of Markdown, Python configuration.”
Kiro (AWS)AWS’s agentic IDE that turns natural language into structured specs.The README: “powerful but you’re tied to its IDE and limited to Claude models”; OpenSpec works with 30+ existing tools.
obra/superpowersProcess discipline for code agents, with composable skills.Superpowers imposes execution methodology (TDD, review, worktrees); OpenSpec governs the prior agreement on requirements. The community combines them via schemas.
bmad-code-org/BMAD-METHODAI-driven agile methodology using formal specs as the single source of truth.Team-based approach with roles and formal artifacts; OpenSpec is lighter and more customizable via schemas.

The most useful comparison isn’t by popularity: Spec Kit is the project with the most stars in the niche (136k versus OpenSpec’s 68k), but the README and community comments position OpenSpec as the option when you want lightness, freedom to iterate, and portability across assistants, instead of a prescriptive kit.

How to contribute

CONTRIBUTING.md documents a four-step process, notable for applying the project’s own flow to itself: open a discussion or issue first (every change starts there; “PRs without a linked issue or prior discussion may be closed”); decide whether it needs a change proposal (a fix goes straight to PR; new functionality requires a first, approved OpenSpec proposal); make the change (Node 20.19+ and pnpm; pnpm install, pnpm build, pnpm test, pnpm exec tsc --noEmit, pnpm lint); and open the PR (conventional-commit-style title, link the issue, and if a code agent wrote the code, declare which one).

Use cases

  • Individual developers working with Claude Code, Codex, Cursor, Gemini CLI, or any of the 30+ other assistants can replace the “vague prompt → unexpected code” flow with explore → propose → apply → archive.
  • Multi-repo teams (platform + product) can use Stores (beta) so one team owns the requirements in a shared planning repository, eliminating the out-of-sync wiki.
  • Teams worried about spec↔code drift can enable openspec validate --archived and --report findings as pre-commit/CI hooks, and evaluate the Cloud Agent for drift detection in PRs.
  • Large brownfield projects benefit from the brownfield-first design, with clay-good/OpenLore to generate initial specs from existing code.
  • Teams already using Superpowers or another discipline framework can combine both via community schemas (superpowers-bridge, spec-superflow, openflow), keeping OpenSpec’s artifact governance and the other’s disciplined execution.
  • Teams wanting portability find value in tool neutrality: the same spec flow works across 30+ assistants.

Resources

Note: this article combines the README and official documentation (docs/), MAINTAINERS.md and CONTRIBUTING.md, release notes, the official openspec.dev blog, the GitHub API, the npm registry, the speclib/awesome-openspec list, and Hacker News threads consulted on September 14, 2026. Figures change over time.

Related articles
ChromeDevTools/chrome-devtools-mcp
September 13, 2026

chrome-devtools-mcp: the official server that gives AI agents browser eyes

51,654★
ChrisWiles/claude-code-showcase
September 13, 2026

claude-code-showcase: the copy-paste-ready config that started as a Hacker News comment

6,062★
bmad-code-org/BMAD-METHOD
September 13, 2026

BMAD-METHOD: the agile method that organizes AI agent teams to build software

52,875★

Comments