Documenting agreement with AI coding assistants before writing code
Instructing an AI to write code immediately after deciding on a feature can lead to unexpected results. This tool organizes requirements and design proposals into Markdown files before any code is written, ensuring that humans and AI are aligned. OpenSpec is a tool that adds specification specs readable by AI coding assistants to your project.
The flow of spec-based development
OpenSpec divides the development process into four stages: explore, propose, apply, and archive. First, the /opsx:explore command is used to explore ideas, where the AI analyzes the current codebase and suggests the optimal approach. Next, using /opsx:propose generates a change folder, and the proposal, requirements specification, technical design, and task list are written as Markdown files. At this stage, developers can review and modify the plan written by the AI. Finally, executing /opsx:apply allows the AI to implement the code according to the task list, and completed changes are stored in the archive via /opsx:archive.
Sharing plans across teams
This tool is useful not only for personal projects but also in team environments. When developing features that span multiple repositories, the plan is stored in a separate repository called a 'store'. This store becomes a single source of truth readable by the entire team and all AI agents through git push. The platform team owns the requirements specification, and the product team can reference it in read-only mode, preventing the problem of scattered wiki documents. Since the store feature is currently in beta, it is recommended to start by referring to the guide.
Installation and initial setup
To use OpenSpec, a version of Node.js 20.19.0 or higher is required. On macOS or Linux, it can be installed via Homebrew by running the brew install openspec command. If using npm, run npm install -g @fission-ai/openspec@latest. This process can also be delegated to an AI coding assistant; selecting one of the 30+ supported tools automatically sets the slash command format suitable for that tool.
Pre-use considerations
This tool yields the best results when used with models that have high reasoning capabilities. The README recommends Codex 5.5 and Opus 4.7 for both planning and implementation. It is also important to clear the context window before starting implementation, and context hygiene must be maintained during the session. OpenSpec collects anonymous usage statistics, but only records command names and versions, not personal information or file contents. It is automatically disabled in CI environments and can be manually disabled via configuration files or environment variables if desired. The license is MIT, and when contributing, an OpenSpec change proposal must be written before adding new features or structural changes.
