OpenSpec explained: turn an AI coding request into reviewable artifacts
OpenSpec explained: turn an AI coding request into reviewable artifacts
Learn what proposals, behavior specs, designs and tasks contribute before an assistant edits code.
What you will learn
- Keep the agreement outside chat
- Understand the assistant boundary
- Interpret completion carefully
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
- Artifacts preserve decisions outside chat.
- Assistant commands differ from terminal commands.
- Planning completion is not release completion.
Keep the agreement outside chat
OpenSpec stores a change as reviewable Markdown artifacts. A proposal explains the need, specs describe observable behavior, a design records implementation choices and tasks track work. Git can preserve that agreement alongside code.
Consider adding CSV export: the requirement should say which rows are exported and how quoting behaves. Choosing a CSV library belongs in the design. Mixing those two questions makes later implementation changes look like requirement changes.
Understand the assistant boundary
The CLI initializes guidance for a selected coding tool; the assistant uses that guidance to propose and implement changes. Installing OpenSpec does not install a model, supply model credentials or independently verify the resulting application.
The README distinguishes terminal commands from assistant commands. The familiar /opsx:propose spelling varies by tool; Codex uses $openspec-propose. Read the invocation printed by initialization instead of pasting a slash command into a shell.
Interpret completion carefully
At revision 1d35e9, planning completion leads to instructions for inspecting implementation progress. It does not mean tests passed or the feature reached production. Keep planning, implementation and release evidence as separate states.
This series reviews fixed source files and runs six offline checks against the actual graph class. It does not execute the complete CLI, a coding assistant or an application deployment.
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
Choose one observable behavior.
- 2
Separate requirement and implementation choice.
- 3
Assign a reviewer before applying changes.
Copy-ready example
proposal.md: why CSV export is needed
specs/: observable export behavior
design.md: encoding and library choice
tasks.md: implementation and verificationFrequently asked questions
Does OpenSpec write code on its own?
The documented workflow uses your coding assistant and its execution environment.
Was the whole workflow run here?
No. The executed fixture covers the pure graph class only.
Sources
- OpenSpec / README.mdSource checked 2026-09-23
- OpenSpec / schemas/spec-driven/schema.yamlSource checked 2026-09-23
- OpenSpec / src/core/change-status-policy.tsSource checked 2026-09-23