OpenSpec Explained: A Guide for AI Coding Teams

Teams running Claude or a similar assistant across dozens of sessions hit a familiar wall. The artificial intelligence (AI) forgets decisions made two prompts earlier and reintroduces bugs it already fixed, and the reasoning behind an architecture choice disappears with it.

OpenSpec keeps agents aligned by storing that intent in version-controlled proposals, delta specs, designs, and tasks instead of transient chat history. Some teams reach for a workaround first, a handwritten PROJECT_STATE.md in the repo that survives between conversations, which points to the same underlying gap. When requirements live only in chat history, earlier decisions vanish the moment the context window fills. A lightweight spec framework like OpenSpec can sit alongside formal requirements management best practices when repo-level planning needs governed traceability on top of it.

Why AI Coding Agents Need Durable Intent

Fission-AI maintains OpenSpec’s public GitHub repository and distributes it as a Node Package Manager (npm) package for AI coding assistants. It’s an open-source, lightweight framework built around a structured specification workflow. Agents read proposal.md, delta specs, design.md, tasks.md, and archived change folders before they touch a line of code.

The project describes its own approach as fluid and brownfield-friendly, scaling from personal projects to larger engineering programs. For software teams running AI agents, those planning files stay available for later review long after the chat session that produced them ends.

How Does Spec-Driven Development Preserve AI Context?

Spec-driven development (SDD) inverts a long-standing relationship. SDD makes authoritative specifications that guide code and treats code as derivative. As AI coding tools become common in professional software development, specification discipline becomes the control surface for implementation decisions.

Once agents write a meaningful portion of the code, specifications give large language models the behavioral contract they need to generate reliably. Chat state disappears once the session ends, but a written spec doesn’t.

Why Vibe Coding Breaks Down on Complex Projects

In vibe coding, a developer prompts iteratively without structured documentation. Andrej Karpathy popularized the term and, a year on, said the approach was best suited to throwaway weekend projects rather than production systems.

The AI coding failure modes show up fast at scale. In production-style vibe-coded applications, teams can find missing Cross-Site Request Forgery (CSRF) protections, weak security headers, exposed secrets, and other critical security issues. Regenerating code without a versioned specification record adds technical debt on top of those security gaps.

Why Middle-of-Session Details Get Lost

Multi-day AI coding work depends on decisions scattered across dozens of prompts, and as context windows fill, models tend to favor tokens at the start and end while the middle gets dropped. OpenSpec’s change artifacts sit next to the code in version-controlled files instead, so the record doesn’t depend on what the model remembers. For regulated product teams, those files create a clearer upstream signal for the traceability record auditors expect.

How Does the OpenSpec Workflow Work?

OpenSpec organizes everything under an openspec/ root with two directories that carry the entire model. Planning artifacts stay co-located with code, and reviews use normal git workflows, so teams never have to reconstruct decisions from chat logs.

What Goes Inside a Change Folder?

The specs/ folder holds current source-of-truth specifications organized by domain. The changes/ folder holds proposed modifications, each in its own named subfolder, following a fixed artifact sequence.

proposal.md: Captures the change intent and scope.
delta specs: Describe the requirements and scenarios that define what is changing, with scenarios attached to each requirement.
design.md: Documents the technical approach, or how the change gets built.
tasks.md: Lists the implementation steps.

Delta specs use small diffs with explicit markers such as ADDED, MODIFIED, REMOVED, and RENAMED. The diff itself carries the change, which keeps the workflow practical for brownfield systems where a team can specify a change before documenting the whole application.

How Do Teams Propose, Apply, and Archive Changes?

OpenSpec’s core profile uses slash commands to keep planning, implementation, and archival steps distinct. A typical flow moves through explore, propose, apply, sync, and archive, giving the AI agent explicit steps instead of a loose chat transcript.

Command	Purpose
/opsx:explore	Think through ideas before committing (optional)
/opsx:propose	Create the change folder and generate all planning artifacts
/opsx:apply	Implement the tasks from the change
/opsx:sync	Merge delta specs into main specs (optional)
/opsx:archive	Archive the completed change

/opsx:propose generates every artifact in one step. /opsx:apply works through the task list, checks items off, and prompts the user to pick a change when several are active.

Archiving folds the work back into truth. It checks artifact and task completion, offers to sync delta specs if that hasn’t happened, and moves the change folder into a dated archive path. Teams needing tighter control can add commands like /opsx:new, /opsx:continue, /opsx:verify, and /opsx:bulk-archive from the expanded profile.

Which AI Assistants Work With OpenSpec?

OpenSpec works with many AI assistants through slash commands, including Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Amazon Q Developer, Gemini, and JetBrains Junie. Integration runs through tool-specific slash commands and config file placement. Claude Code uses commands like /openspec:proposal, GitHub Copilot reads from .github/prompts/, and Amazon Q uses an @openspec-proposal syntax. The framework needs a current Node.js runtime and no Model Context Protocol (MCP) dependency to run.

When Should We Use OpenSpec?

Use OpenSpec when AI coding work needs repo-level planning artifacts and a full requirements platform that belongs outside the code repository. Its lightweight footprint and delta-based model fit iterative work on existing systems well. Teams still need to decide where the official requirements record lives.

Brownfield Work Comes Before Greenfield Builds

OpenSpec is built around brownfield adoption, for codebases that already exist and need current-behavior discovery before any planning artifact gets written. For those projects, the recommended pattern runs /opsx:explore first, reviews that output, then uses /opsx:continue to step through proposal, spec, design, and tasks one artifact at a time. Greenfield work is supported too, since the default /opsx:propose command generates the full artifact set in one step, though OpenSpec doesn’t define a greenfield-specific workflow of its own.

Does OpenSpec Fit Solo Work and Cross-Team Programs?

For a solo developer, the workflow stays inside a single repo. OpenSpec’s default step generates four core planning artifacts per change, a smaller starting set than more heavily templated alternatives, which fits its lighter, delta-based approach.

Cross-team work changes the problem. A feature can span the application programming interface (API) server and the web app, with changes in a shared library. In that case, OpenSpec uses Stores, a planning repo of its own that carries the same specs-and-changes shape as git push. Before standardizing on it, review current repository activity, issue responsiveness, and pull request (PR) backlog.

How Does OpenSpec Compare to Spec Kit and BMAD-METHOD?

OpenSpec sits in a crowded field of dedicated SDD tooling, including GitHub’s Spec Kit toolkit and the community-built BMAD-METHOD framework. OpenSpec asks for less ceremony, focuses on brownfield work, and stays compatible with whatever AI tool a team already uses.

The three tools differ most in model, workflow, fit, and runtime:

Dimension	OpenSpec	Spec Kit	BMAD-METHOD
Developer	Fission-AI	GitHub	bmad-code-org (community)
Spec model	Delta specs (diffs)	Full Markdown artifacts	Story files
Workflow	Change-centric, fluid	Linear phased workflow with gates	Agile-style cycle
Best fit	Brownfield, lightweight	Structure and traceability	Full software development lifecycle, greenfield
Runtime	Node.js	Python	Tool-agnostic

OpenSpec vs. Spec Kit

Spec Kit uses a linear phased process, Spec to Plan to Tasks to Implement, with explicit gates between phases. It produces full Markdown artifacts at each stage with rich templates and quality checklists, and it creates a git branch automatically. OpenSpec leaves branch creation to the team.

OpenSpec writes delta specs that show only what’s changed, with markers such as ADDED, MODIFIED, and REMOVED, and then merges the completed changes into a source-of-truth document at archive time. Spec Kit provides teams with more explicit structure for spec quality, plan quality, and verification discipline; OpenSpec keeps the workflow lighter.

Spec Kit fits better when a repo-level workflow needs stronger gates. OpenSpec fits better when the goal is a minimal but persistent structure. Readers evaluating this workflow should decide whether the repo-level spec layer also needs to connect to a governed requirements record.

OpenSpec vs. BMAD-METHOD

BMAD-METHOD takes a different shape. It simulates a full agile team through named AI personas, including Analyst, Product Manager (PM), Architect, User Experience (UX) Designer, Scrum Master, Dev, and BMad Master as the orchestrator. The Scrum Master agent creates detailed story files carrying architectural context, implementation guidelines, embedded reasoning, and testing criteria for the Dev agent.

BMAD covers the full software development lifecycle (SDLC) and extends into game development and creative work through expansion packs. That coverage comes with a heavier tradeoff. Its extensive per-persona context drives up token consumption per request compared with a lighter, delta-based workflow, and file-based context passing can interrupt handoffs.

BMAD fits greenfield projects that want a simulated agile team and detailed planning. OpenSpec fits brownfield codebases and solo developers that need lightweight alignment around versioned specs.

Getting OpenSpec Into an Existing Repo

The Massachusetts Institute of Technology (MIT) License lets teams inspect OpenSpec’s open-source workflow before adopting it. Installation needs a current Node.js runtime and a few minutes in the terminal. Run npm, then openspec init in the project, and it drops into whatever AI coding assistant the team already runs.

If the codebase is mature and the agent keeps losing the thread mid-session, the brownfield-first, delta-based model is a low-friction starting point. For systems engineers and Quality & Regulatory Affairs groups, OpenSpec only earns its place if its output connects to the traceability record auditors expect.

How Jama Connect Can Connect OpenSpec Outputs to Governed Traceability

OpenSpec’s proposals and delta specs aren’t a governed requirements record on their own. Jama Connect® adds the product context layer by mapping AI-generated planning artifacts to approved requirements, verification evidence, and version-controlled baselines. Its Traceability Information Model (TIM) defines the specification framework a change should satisfy before it counts as done, and its Model Context Protocol (MCP) Server can expose that governed context to the tools agents already use.

Connecting an OpenSpec change folder to that framework closes a specific gap:

Specification framework: The TIM defines the relationships a change should touch, so a proposal or delta spec can be checked against the governed record.
AI-generated artifact auditability: Suspect flagging surfaces when an AI-assisted change affects a downstream requirement, test case, or risk item that hasn’t been reviewed.
Versioned governance: Any change a requirement undergoes through the MCP Server is written to that requirement’s version history, the same field-level record of who changed what, when, and why that governs every other edit in Jama Connect. Baselines and electronic signatures then give the change folder’s history a formal, auditable counterpart outside the repo.

Our end-to-end requirements traceability practices can help you evaluate what evidence should connect. Teams can use Jama Connect for requirements baselining across governed changes, electronic signatures, audit trails, test management, risk management, and industry frameworks aligned to standards such as International Organization for Standardization (ISO) 26262. Those capabilities help Quality & Regulatory Affairs teams demonstrate which approved requirement an AI-assisted change came from, what verification covers it, and what changed since the last baseline.

Building OpenSpec Into a Governed Traceability Workflow

OpenSpec’s repo artifacts capture what an AI agent was asked to build and why. On their own, they can’t confirm that work traces back to an approved requirement or a tested outcome, which is the gap that trips up teams shipping AI-generated code in regulated environments. Connecting those artifacts to a governed traceability record, whether that lives in Jama Connect or another platform, is what closes it.

If you want to see how that connection works, you can start a Jama Connect trial.

Frequently Asked Questions About OpenSpec

What is the difference between OpenSpec and traditional requirements documents?

OpenSpec produces lightweight, version-controlled delta specs that describe only what a change affects, stored alongside code for AI agents to read. A formal requirements management platform like Jama Connect captures the complete requirements set with baselines, traceability, and audit history. OpenSpec works as a planning layer; requirements management remains the system of record.

Does OpenSpec replace a requirements management platform?

No. OpenSpec authors specifications and plans AI coding work, while a requirements management platform handles baselining, electronic signatures, and multi-level traceability for regulated programs. OpenSpec isn’t positioned as a replacement for dedicated application lifecycle management (ALM) or requirements management (RM) tooling.

Can OpenSpec work with regulated or compliance-heavy projects?

Yes, as an upstream specification layer. Every change ties back to a versioned spec, and folders are archived with date stamps for an audit trail. Regulated industries still need downstream traceability and inspection-ready evidence, which teams typically get by pairing OpenSpec with a platform such as Jama Connect.

Is OpenSpec open-source?

Yes, under the MIT License, so teams can inspect the repo-level workflow before adopting it. It requires a current Node.js runtime and installs via npm, pnpm, yarn, or bun, making it easy to test within an existing repo before expanding to team use.

Author
Recent Posts

Mario Maldari

Director of Product and Solution Marketing at Jama Software

Mario Maldari is Director of Product and Solution Marketing at Jama Software, where he focuses on requirements management and systems engineering solutions for regulated industries. He brings over 2 decades of experience across solution architecture, technical pre-sales, and software quality, and holds patents in traceability and structured data. Before moving into product marketing, he worked directly with engineering teams to solve compliance and requirements challenges.

How OpenSpec Keeps AI Coding Agents From Losing Context