OpenSpec explained: turn an AI coding request into reviewable artifacts
OpenSpec quickstart: specify a small CSV export before applying it
Initialize a disposable project, review generated instructions and write one testable scenario.
What you will learn
- Prepare a reversible trial
- Initialize, then use the selected tool
- Give the scenario an acceptance condition
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
- Initialization writes project guidance.
- latest is a moving installation target.
- Known input makes a scenario checkable.
Prepare a reversible trial
Use a new sample repository or a disposable worktree, preserving all existing uncommitted work. The inspected README requires Node.js 20.19.0 or newer. Record the installed OpenSpec version because its latest package can differ from this source review.
The installation below follows the README and changes the global npm environment. Review that effect before running it. This article supplies a documented procedure, not a claim that package installation or assistant integration was tested.
Initialize, then use the selected tool
Run openspec init inside the trial repository and inspect the resulting file changes. It prints invocation forms for the tools you selected. Enter the proposal command in the assistant interface, not the terminal.
Ask for CSV export with quoted commas and a clear empty-result behavior. Review proposal, specification and design before allowing implementation. The default profile includes explore and propose; expanded commands require a profile change and update.
Give the scenario an acceptance condition
Write a scenario with a known input row and expected escaped output. The schema uses a Requirement heading and a four-hash Scenario heading with WHEN and THEN. A task should name its verification, not merely say implement export.
Stop if initialization modifies an unexpected project or the proposal invents behavior you did not request. Review the diff and restore only the trial changes you own; do not discard unrelated work.
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
Check Node and preserve the original workspace.
- 2
Initialize the trial and inspect the printed invocation.
- 3
Approve the scenario before implementation.
Copy-ready example
node --version
npm install -g @fission-ai/openspec@latest
cd your-trial-project
openspec --version
openspec initFrequently asked questions
Where do I type /opsx:propose?
In a supported assistant, using the spelling initialization prints for that tool.
Should I start in my dirty production checkout?
Prefer an isolated sample or worktree and preserve existing changes.
Sources
- OpenSpec / README.mdSource checked 2026-09-23
- OpenSpec / schemas/spec-driven/schema.yamlSource checked 2026-09-23