Harnesses > Spec-driven toolkits
OpenSpec
Draft. This entry has not been checked against its sources yet.
A CLI plus generated skills and slash commands for 39 coding agents that has the agent write a proposal, requirement changes, a design, and a task checklist for each change before coding, then folds the requirement changes into specs kept in the repository when the change is archived.
| Maintainer | Fission AI (lead maintainer Tabish Bidiwale, TabishB) |
|---|---|
| Category | Spec-driven toolkits |
| Hosts | Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Factory Droid, Pi, oh-my-pi, Cline, Kiro, Qwen Code, Kimi Code CLI, Antigravity, Hermes Agent, Amazon Q Developer, Auggie (Augment CLI), IBM Bob, Command Code, CodeArts, CodeBuddy, Continue, CoStrict, Crush, Devin Desktop (formerly Windsurf), ForgeCode, iFlow, Junie, Kilo Code, Lingma, MiniMax Code, Mistral Vibe, Qoder, Rovo Dev, SourceCraft Code Assistant, Trae, ZCode, Zed, Zoo Code |
| Components | 6 skills, 6 commands |
| License | MIT |
| Version | 1.13.2 |
| Source code | https://github.com/Fission-AI/OpenSpec |
| Website | https://openspec.dev |
| Docs | https://github.com/Fission-AI/OpenSpec/tree/main/docs |
| DeepWiki | https://deepwiki.com/Fission-AI/OpenSpec |
| Last researched | 2026-09-28, at commit 79b6aa9 |
Features
Definitions are on the compare page.
| Feature | Supported | Notes |
|---|---|---|
| Stages of work it covers | ||
| Brainstorming | yes | /opsx:explore asks one focused question at a time, recommends options, and writes nothing without a yes. Optional, with no fixed end. |
| Written plans | yes | /opsx:propose writes proposal.md, requirement deltas, design.md (only when needed), and tasks.md to openspec/changes/<name>/, and may not edit code. |
| Test first | no | Each task group must land its own tests, but nothing asks for a failing test first. The community anvil schema adds a test plan. |
| Debugging process | no | No bug process. A fix goes through the same propose, apply, archive steps. |
| Code review | partial | /opsx:verify (expanded profile only) has the same agent check the code against the specs and design. It is advisory and archive does not require it. No reviewer subagents. |
| Verification | partial | Every task in tasks.md must name its check (a test, command, or observable result), but no step requires running it and showing output. The CLI's all-done message says 'Consider running tests'. |
| Learning capture | no | Archive merges requirement changes into openspec/specs/, which later sessions read, but that records behavior, not lessons. |
| Branch to PR | no | 'It never commits, branches, pushes, or pulls' (docs/team-workflow.md). The docs suggest one branch and PR per change. |
| How it runs | ||
| Single entry point | no | Two starting points, /opsx:explore and /opsx:propose. You pick each next command yourself. |
| Automatic activation | yes | Skills load from their descriptions. If the agent picked a skill itself in a project without openspec/, it drops OpenSpec and answers normally. |
| Session-start hook | no | No hooks. It no longer writes to AGENTS.md or CLAUDE.md; openspec update removes blocks older versions added. |
| Blocking hooks | no | No hooks. The CLI rejects invalid specs on validate and archive, but nothing blocks the agent's tool calls. |
| Subagents | no | No subagents. The only agent file is an opt-in profile for GitHub's Copilot cloud coding agent. |
| Parallel agents | no | |
| Git worktrees | no | |
| Adopting it | ||
| Multiple hosts | yes | 39 named tools plus a vendor-neutral .agents/skills target, all from one CLI (src/core/config.ts). |
| Per-project setup | yes | openspec init writes the skills, commands, and openspec/config.yaml into the repository. Each person installs the CLI, and the workflow profile is a per-user setting. |
| Team extensions | yes | Project context and per-artifact rules in openspec/config.yaml; custom schemas in openspec/schemas/ via openspec schema fork. Generated skill files are overwritten on update. |
| No extra services | yes | Needs Node.js 20.19 or later. Anonymous telemetry (command names and version) is on by default; OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1 turns it off. |
How it works
The workflow
OpenSpec has two parts: an openspec command-line tool, installed globally, and the skills and slash commands that openspec init writes into each agent's directory. The skills do the reading and writing. They call the CLI to find out which planning files exist and which can be written next, to fetch the template and instructions for each file, and to validate the result. Each piece of work is a change: a folder under openspec/changes/<name>/.
The default loop, as docs/team-workflow.md lays it out, runs on a branch you create yourself:
Explore (optional,
/opsx:explore). A thinking mode. The agent reads the code, asks "one focused question at a time", explains which decision each question unlocks, and recommends an option when the evidence supports one. It must not write code, and it writes change files only after you answer yes to a direct question. Decisions are kept in the conversation.Propose (
/opsx:propose <idea>). The agent creates the change withopenspec new change, then writes each planning file in dependency order, using the template and instructions fromopenspec instructions <artifact> --json:proposal.md: why, what changes, which capabilities are new or modified, and the impact.specs/<capability>/spec.md: requirement changes under ADDED, MODIFIED, REMOVED, or RENAMED headings. Each requirement uses SHALL or MUST and has at least one WHEN/THEN scenario.design.md: only for cross-cutting, risky, or ambiguous changes.tasks.md: numbered checkboxes, each naming how to check it.
The skill "authorizes planning only" and stops so you can review the plan.
Apply (
/opsx:apply). The agent reads the planning files and works throughtasks.mdin order, ticking a box only when the task's behavior is fully implemented. It pauses on an unclear task, a design problem, work beyond the plan, or an error, and suggests updating the planning files rather than quietly changing the plan.Update (
/opsx:update). Revises the planning files at any point without touching code.Archive (
/opsx:archive). Warns about unfinished planning files or tasks and asks you to confirm, then offers to merge the requirement changes into the main specs inopenspec/specs/(/opsx:syncdoes this step on its own). It checks the merge and moves the change toopenspec/changes/archive/YYYY-MM-DD-<name>/.
The docs suggest committing the change with the code, opening a pull request, and archiving after it merges. OpenSpec does none of the git steps.
An expanded profile adds six more commands: /opsx:new (create the change folder only), /opsx:continue (write the next planning file), /opsx:ff (write all remaining planning files), /opsx:verify (check the code against the change), /opsx:bulk-archive (archive several changes and flag two that change the same capability), and /opsx:onboard (a guided first change on your own codebase).
Components
How the counts were made: a local build of the researched commit ran openspec init --tools claude in an empty repository, with default settings. It wrote these files, and the counts above use them:
.claude/skills/openspec-{propose,explore,apply-change,update-change,sync-specs,archive-change}/SKILL.md
.claude/commands/opsx/{propose,explore,apply,update,sync,archive}.md
openspec/config.yaml
openspec/specs/.gitkeep
openspec/changes/archive/.gitkeep
- 12 workflows, each generated as a skill and, on hosts that have a command format, as a slash command with the same text. The default
coreprofile installs 6 of them. Selecting all 12 withopenspec config profilegives 12 skills and 12 commands on Claude Code. Codex and several other hosts get skills only. - No subagents, hooks, or MCP servers. Choosing GitHub Copilot can also add an agent profile and setup workflow for GitHub's cloud coding agent (
.github/agents/openspec.agent.md,.github/workflows/copilot-setup-steps.yml). This is opt-in and off by default. - The CLI, which does the mechanical work:
initandupdategenerate the agent files;new change,status, andinstructionstrack the planning files and hand out their templates;list,show, andviewbrowse changes and specs;validatechecks their format;archivevalidates, merges requirement changes into the main specs, and moves the folder;schemaforks or creates workflows;store(beta) keeps planning in a separate repository. - One built-in schema,
spec-driven, which defines the four planning files, their order, templates, and writing instructions (schemas/spec-driven/schema.yaml).
How it steers the agent
There are no hooks, so nothing blocks a tool call. The CLI supplies state and checks format; everything else is instructions.
- The CLI holds the state.
openspec status --jsonmarks each planning file ready, blocked, done, or skipped. The skills treat theinstructionfield fromopenspec instructionsas "the authoritative guidance" and "always re-read them from disk". - Boundaries in the wording. Propose: "The user request that selected or triggered this workflow authorizes planning only... Do not edit project code." Explore: "you must NEVER write code or implement features." Update: "Never edit code."
- Asking first. Explore asks a yes/no question in a separate message before writing. Apply pauses rather than guess. Archive asks before going ahead with unfinished tasks, but does not block on them.
- Format checks.
openspec validaterejects a requirement without SHALL or MUST or without a scenario, and a change with no requirement changes unless it is markedskip_specs: true.openspec archivevalidates before merging and refuses a MODIFIED requirement that drops a scenario the main spec still has. The sync skill runsopenspec validate --specsand must "not claim the sync succeeded" if it fails. - Checklists. The CLI counts ticked boxes in
tasks.md, and propose tracks the planning files in the host's todo list. - No surprise setup. In a project without
openspec/, a skill the agent picked on its own drops OpenSpec and answers normally; one you asked for stops and asks before runningopenspec init. - The README recommends clearing the context before implementation.
Files it writes
- Change folders:
openspec/changes/<name>/with.openspec.yaml(schema and date),proposal.md,specs/<capability>/spec.md,design.md, andtasks.md. - Archive:
openspec/changes/archive/YYYY-MM-DD-<name>/, the same folder after it is archived. - Main specs:
openspec/specs/<capability>/spec.md, each with a purpose and its current requirements, updated on every sync or archive. - Project config:
openspec/config.yamlwith the schema name and optional project context, per-file rules, and guidance for apply and archive. - Custom schemas:
openspec/schemas/<name>/, if you make one. - Agent files: for example
.claude/skills/openspec-*/and.claude/commands/opsx/, rewritten byopenspec update. - Per-user settings:
~/.config/openspec/config.jsonholds the profile, delivery mode (skills, commands, or both), and telemetry choice.
The FAQ says to commit the whole openspec/ folder. Later sessions read the main specs: explore lists them with openspec list --specs, and the proposal instructions require reading related specs before choosing which capabilities to change. There is no lessons or memory file.
Install
Install the CLI once per machine. It needs Node.js 20.19 or later:
npm install -g @fission-ai/openspec@latest
or brew install openspec. pnpm, yarn 1, bun, deno, and Nix also work (docs/installation.md). Then, in each project:
openspec init
init asks which tools to set up; openspec init --tools claude,cursor or --tools all skips the question. It prints the command form for each tool: /opsx:propose in Claude Code and Gemini CLI, /opsx-propose in Cursor and GitHub Copilot, @opsx-propose in Amazon Q, and $openspec-propose in Codex. To add the six expanded commands, run openspec config profile, then openspec update. After upgrading the CLI, run openspec update in each project.
Host notes from docs/supported-tools.md: Codex gets skills only, in .agents/skills/. Hermes needs the project's .hermes/skills added to its config. MiniMax Code gets global skills only. Copilot CLI does not read the generated prompt files; the IDE extensions do. The skills alone, without the CLI, can be added with npx skills add Fission-AI/OpenSpec, but they call the CLI throughout.
When to choose it
- You want every change to start from a written plan you review before any code: why, which requirements change, a design when needed, and a checklist.
- You want specs in the repository that describe the system's current behavior and are updated as each change is archived. The README says it is "built for brownfield not just greenfield".
- Your team uses different agents. One
openspec initsets up any of 39, and the plans are plain Markdown any of them can read. - You want to change the process itself: add planning files, rewrite templates, or add rules per file, in files committed with the code.
When not to
- You want the harness to direct implementation: test-first, a debugging process, review by subagents, or proof that tests pass. OpenSpec covers planning, task tracking, and keeping specs current.
/opsx:applyworks through the checklist and stops there. Community schemas such assuperpowers-bridgeandanviladd some of this. - You want subagents, parallel agents, or worktrees. Everything runs in the main session.
- You want hard gates. The CLI checks spec format and counts checkboxes; the rest is instructions, and archive goes ahead after warnings once you confirm.
- You want no setup differences between teammates. The workflow profile lives in each person's global config, so
openspec updaterun by two people can install different command sets. - You do not want telemetry on by default. It sends command names and the version to
edge.openspec.devuntil you opt out.
Sources
- Fission-AI/OpenSpec at 79b6aa9:
README.md,docs/(supported-tools, team-workflow, reviewing-changes, customization, cli, opsx, faq, installation),skills/*/SKILL.md,schemas/spec-driven/,src/core/(init.ts,config.ts,profiles.ts,shared/skill-generation.ts,command-generation/adapters/,validation/,specs-apply.ts,github-copilot/cloud-agent.ts),src/telemetry/,MAINTAINERS.md,CHANGELOG.md. Component counts come from running a local build of this commit. - openspec.dev (named in
website/README.md, not read) - DeepWiki was not used: it was unreachable from the research environment.