agentharnesses.dev

A field guide to agentic coding harnesses, for teams that have been told to adopt one.


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.

MaintainerFission AI (lead maintainer Tabish Bidiwale, TabishB)
CategorySpec-driven toolkits
HostsClaude 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
Components6 skills, 6 commands
LicenseMIT
Version1.13.2
Source codehttps://github.com/Fission-AI/OpenSpec
Websitehttps://openspec.dev
Docshttps://github.com/Fission-AI/OpenSpec/tree/main/docs
DeepWikihttps://deepwiki.com/Fission-AI/OpenSpec
Last researched2026-09-28, at commit 79b6aa9

Features

Definitions are on the compare page.

FeatureSupportedNotes
Stages of work it covers
Brainstormingyes/opsx:explore asks one focused question at a time, recommends options, and writes nothing without a yes. Optional, with no fixed end.
Written plansyes/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 firstnoEach task group must land its own tests, but nothing asks for a failing test first. The community anvil schema adds a test plan.
Debugging processnoNo bug process. A fix goes through the same propose, apply, archive steps.
Code reviewpartial/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.
VerificationpartialEvery 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 capturenoArchive merges requirement changes into openspec/specs/, which later sessions read, but that records behavior, not lessons.
Branch to PRno'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 pointnoTwo starting points, /opsx:explore and /opsx:propose. You pick each next command yourself.
Automatic activationyesSkills load from their descriptions. If the agent picked a skill itself in a project without openspec/, it drops OpenSpec and answers normally.
Session-start hooknoNo hooks. It no longer writes to AGENTS.md or CLAUDE.md; openspec update removes blocks older versions added.
Blocking hooksnoNo hooks. The CLI rejects invalid specs on validate and archive, but nothing blocks the agent's tool calls.
SubagentsnoNo subagents. The only agent file is an opt-in profile for GitHub's Copilot cloud coding agent.
Parallel agentsno
Git worktreesno
Adopting it
Multiple hostsyes39 named tools plus a vendor-neutral .agents/skills target, all from one CLI (src/core/config.ts).
Per-project setupyesopenspec 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 extensionsyesProject 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 servicesyesNeeds 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:

  1. 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.

  2. Propose (/opsx:propose <idea>). The agent creates the change with openspec new change, then writes each planning file in dependency order, using the template and instructions from openspec 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.

  3. Apply (/opsx:apply). The agent reads the planning files and works through tasks.md in 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.

  4. Update (/opsx:update). Revises the planning files at any point without touching code.

  5. 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 in openspec/specs/ (/opsx:sync does this step on its own). It checks the merge and moves the change to openspec/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

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.

Files it writes

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

When not to

Sources