OpenSpec
CLI ToolFission-AI/OpenSpec
Spec-driven development (SDD) framework for AI coding assistants.
Overview
OpenSpec adds a lightweight spec layer to AI coding workflows, ensuring human and AI align on requirements before code is written. It provides slash commands for 20+ AI assistants and organizes changes per feature.
README Preview
\n \n \n \n \n \n \n\n\n\n \n \n \n \n\n\n\nThe most loved spec framework.\n\n[](https://github.com/Fission-AI/OpenSpec/stargazers)\n[](https://www.npmjs.com/package/@fission-ai/openspec)\n[](https://github.com/Fission-AI/OpenSpec/graphs/contributors)\n\n\n\nOur philosophy:\n\n```text\n→ fluid not rigid\n→ iterative not waterfall\n→ easy not complex\n→ built for brownfield not just greenfield\n→ scalable from personal projects to enterprises\n```\n\n> [!TIP]\n> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.\n>\n> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)\n\n\n Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.\n\n\n\n\n## See it in action\n\n```text\nYou: /opsx:explore\nAI: What would you like to explore?\nYou: I want dark mode but I'm not sure how to do it cleanly.\nAI: Let me look at your styling setup...\n Cleanest path here: CSS variables + a small theme context,\n with system-preference detection. No new dependencies. Scope it?\nYou: Yes, let's do it.\n\nYou: /opsx:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n\nYou: /opsx:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n\nYou: /opsx:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n\nOpenSpec Dashboard\n\n\n \n\n\n\n\n## Quick Start\n\n**Requires Node.js 20.19.0 or higher.**\n\nInstall OpenSpec globally:\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\nThen navigate to
FAQ (5)
How-toHow to install OpenSpec without Node.js (standalone binary)?
Since v1.15.0, OpenSpec ships a standalone binary that doesn't require Node.js. Install it with:
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iexIf you previously installed via npm, run openspec install to switch to the standalone binary version. Full details are in the installation guide in the repo's docs/installation.md.
TroubleshootingWhy does `openspec validate --strict` pass when a requirement is longer than 500 characters, and how can I enforce the limit in CI?
Upgrade to OpenSpec **1.14.1 or later**. Previously, the overlong-requirement finding was reported as INFO, so openspec validate --all --strict exited with status 0. In 1.14.1+, a requirement description longer than **500 characters** causes strict validation to fail. Run the quality gate with:
openspec validate --all --strictTo fix existing findings, split the long requirement into multiple smaller requirements without changing its semantics; do not simply truncate it. The agent authoring instructions also now document the 500-character limit to prevent new overlong requirements.
TroubleshootingHow do I hide archived changes in `openspec view` so active changes stay visible?
This was a regression introduced by PR #399, which added archived changes to the openspec view dashboard. It is fixed by the PR fix(view): keep archived changes off the dashboard (closing issue #2030). Upgrade OpenSpec to a release containing that fix, then run openspec view again; archived changes will no longer push active work off the screen. As a temporary workaround, use openspec list.
TroubleshootingHow to fix OpenSpec apply skill refusing store-backed changes because allowedEditRoots conflicts with the declaring repo?
In OpenSpec 1.13.1, openspec status --change <name> --json --store plans can incorrectly set actionContext.allowedEditRoots to only the store root, such as /path/to/plans, even though implementation edits must be made in the declaring repo, such as /path/to/app. The generated apply skill then treats the repo context as conflicting with the CLI-controlled value and stops at 0/N tasks.
Fix: upgrade to an OpenSpec release containing the PR fix(status): include the declaring repo in store-backed edit roots (or build from commit 0d814f39 or later). After the fix, verify with:
openspec status --change <name> --json --store plansactionContext.allowedEditRoots should include both roots:
["/path/to/app", "/path/to/plans"]The store root holds planning artifacts, while the declaring repo root holds implementation edits. The mode and output contract remain unchanged.
Temporary workaround: manually override the agent's refusal and explicitly authorize edits in both the declaring repo and store root, clarifying that allowedEditRoots from the buggy status output is not limited to planning artifacts.
TroubleshootingHow to fix OpenSpec circular dependency when 'Archive the change' and 'Verify archived result' tasks block archiving?
Upgrade to OpenSpec 1.14.1+, where openspec instructions apply reports only tracked-task completion instead of declaring the change ready to archive. In tasks.md, keep only work that can finish before archive as - [ ] checkboxes. Move archive-dependent steps to a plain-bullet section so they do not affect task counts:
## Workflow follow-up
- Archive the change after the project's review requirements are satisfied.
- Verify the archived result.The completion message is now: "All tracked tasks are complete. Review or verify the change as appropriate before archiving." state: "all_done", task parsing, validation, archive behavior, and flags remain unchanged. On older stock OpenSpec, you can confirm the warning or use --yes; a stricter custom policy that requires zero incomplete tasks must be updated or the archive-dependent tasks must be moved out of the tracked list.