OpenSpec explained: turn an AI coding request into reviewable artifacts
Deploying OpenSpec across a team: CLI versions and generated guidance
Treat package upgrades and per-project instruction refreshes as two separately reviewed changes.
What you will learn
- There is no application server to invent
- Pilot upgrades with a saved diff
- Restore both sides of the integration
Before you start
- Basic Git and Node knowledge
- A disposable sample repository
Display dependencies and missing evidence without automatically executing the next instruction.
Key takeaways
- CLI and generated guidance can drift.
- Stores are documented as beta.
- Rollback must preserve human-authored plans.
There is no application server to invent
The documented starting point is a Node CLI plus files in a project. A team rollout therefore begins with supported Node versions, package versions and selected assistant integrations, not a speculative Docker service or public endpoint.
Record the command source and installation method. A globally upgraded CLI and older generated project guidance can coexist; the README explicitly calls for openspec update inside each project after upgrading the package.
Pilot upgrades with a saved diff
Choose a small repository and preserve the existing generated files before updating. Review new commands, profile changes and local customizations in Git. Confirm that the team knows which instructions are generated and which are maintained by hand.
The README offers standalone planning stores for shared and cross-repository plans, but labels them beta. Introducing one changes ownership and synchronization decisions; do not add that dependency to a first single-repository trial without a concrete need.
Restore both sides of the integration
If an upgrade changes the workflow unexpectedly, restore the reviewed guidance and the previously recorded CLI version. Keep any legitimate proposal edits separate from regenerated tool files so rollback does not erase planning work.
No team rollout was executed for this series. Verify package availability, tool compatibility and generated diffs in your environment before standardizing a version. The fixed source commit is an analysis reference, not proof of a matching published binary.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inventory Node, CLI and assistant versions.
- 2
Pilot package upgrade and guidance refresh separately.
- 3
Document a version-and-files rollback.
Copy-ready example
rollout:
node_minimum: 20.19.0
cli_version: record-installed-version
guidance: reviewed-git-diff
pilot: disposable-repository
rollback: previous-cli-and-guidanceFrequently asked questions
Do I need a web server?
Not for the documented local CLI starting workflow.
Does upgrading npm refresh every repository?
The README directs users to run openspec update inside each project.
Sources
- OpenSpec / README.mdSource checked 2026-09-23