To get started with OpenSpec, install its CLI, initialize your project with openspec init, then follow the five-stage workflow: explore, propose, review, apply, and archive. For Node-based installation, the official guide specifies Node.js 20.19.0 or newer. Treat the plan as a checkpoint: review its scope, requirements, and tasks before asking an AI agent to implement it.
Install OpenSpec and check the Node.js requirement
OpenSpec’s installation guide specifies Node.js 20.19.0 or newer for Node-based installation. If you use another installation route, check your active Node version first. The guide also documents package-manager approaches, including Homebrew, which installs Node.js as a dependency, and Nix, whose package includes the runtime. It describes an installation prompt that can delegate setup to an AI assistant. Follow the current commands on the official installation page, since installation methods and requirements may change.
As an Amazon Associate I earn from qualifying purchases.
A version-manager switch can make the openspec command unavailable: the CLI may have been installed under a different Node runtime. Reinstall OpenSpec while the intended Node version is active. The official guide covers this version-manager pitfall.
Initialize OpenSpec in a project
- Open a terminal at the project root.
- Run
openspec init. - Follow the setup prompts to configure the AI tool integration.
- Review the resulting
openspec/directory and workflow files, then commit them through your normal Git process.
Initialization creates the project’s OpenSpec structure and adds workflow files for the selected AI tool. The project setup guide recommends committing these files like other source material. See Set up your project for current setup details.
Know where the project artifacts live
openspec/config.yamlholds project settings and context.openspec/specs/contains descriptions of system behavior.openspec/changes/holds changes in progress.openspec/changes/archive/holds completed change history.
Use the five stages for your first change
The quickstart’s lifecycle is explore, propose, review, apply, and archive. The available commands and workflow depend on the installed profile and AI tool; the stages describe the process, not a universal set of slash commands. The OpenSpec Quickstart includes rate-limiting examples: “Help me explore how rate limiting should work in this app” and “Propose a change to add rate limiting.” Adapt the examples to your actual change.
1. Explore the problem before planning
Discuss the problem and possible approaches with the agent before asking it to create a plan. This stage is for examining the codebase, asking questions, and sketching options. It does not write code unless you ask to record a decision.
2. Propose a change
Once the direction is clear, ask the agent to propose a change. A quickstart example includes proposal.md, a specs/ directory, optional design.md, and tasks.md. Proposing produces the plan, not the implementation.
3. Review the plan before code changes
- Read
proposal.mdto check whether the scope and problem statement match what you intend to change. - Check the requirements in
specs/for clear, testable acceptance criteria. - Compare
tasks.mdwith the requirements to see whether the implementation work is covered.
Correct omissions or misunderstandings here, while the change is still documentation. Moving straight to implementation skips the quickstart’s review checkpoint.
Rank #3
4. Apply the tasks
After reviewing the plan, ask the agent to implement the work from tasks.md. The quickstart recommends starting implementation in a fresh chat session. If work is interrupted, use the task checkboxes to find the first unchecked task and resume there; the checklist, rather than hidden session state, records progress.
5. Archive the completed change
Archive only after all task boxes are checked. Archiving updates the main specs with the completed requirements and moves the full change folder, including its delta spec, into openspec/changes/archive/. The quickstart says the change files are not deleted. Archiving is separate from Git: commit the change folder with the code using your project’s normal Git process. See the quickstart’s archive guidance and the CLI reference.
Understand terminal commands, profiles, and delivery options
OpenSpec has terminal CLI commands as well as commands or workflows exposed through an AI tool. They are related entry points, but their syntax is not interchangeable: a terminal command such as openspec init is not an AI-chat command. The CLI reference lists commands including openspec update, openspec config, openspec list, openspec show, openspec view, openspec validate, openspec archive, openspec new, and openspec status. Consult the current CLI reference for their syntax and usage.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThere is not one command set that fits every setup. The available profile options depend on the OpenSpec release. The profiles guide describes choices such as core versus expanded or custom workflows, and delivery as skills, commands, or both. Check your installed profile before following instructions for an optional workflow. Profiles are configured globally; after changing a profile, update the project so the change takes effect there.
Best Value
Fix missing OpenSpec commands in Claude Code
If Claude Code does not show the expected commands, first distinguish missing project files from commands that exist but are not loading.
- If integration files are missing, run
openspec updatefrom the project to update them. - If the files exist but
/opsx:commands do not appear, update Claude Code and restart it. - If commands still fail to load, set delivery to both skills and commands with
openspec config set delivery both, runopenspec update, and restart Claude Code.
These steps come from the project setup guide; profile and delivery behavior is also covered in the profiles documentation.
Quick Recap
Keep the workflow’s boundaries clear
- Do not ask for implementation before reviewing the proposal, requirements, and task coverage.
- After interruption, resume from the first unchecked item in
tasks.md. - Do not archive a change while tasks remain unchecked; archiving updates the main specs and files the change history.
- Do not treat archiving as a Git commit. Use your normal repository process to commit the code and change folder.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
