OpenSpec explained: turn an AI coding request into reviewable artifacts
Build an OpenSpec readiness inspector as a learning project
Display dependencies and missing evidence without automatically executing the next instruction.
What you will learn
- Make the inspector read-only first
- Reuse the six graph cases
- Demonstrate the distinction that matters
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
- The project is a proposed extension.
- Readiness and evidence need different states.
- Do not auto-execute suggested commands.
Make the inspector read-only first
Build a small local view of artifact IDs, prerequisites and recorded completion state. Show why tasks is blocked when design is missing, even if specs is complete. Use a fixed sample schema before reading real project files.
This is a proposed extension, not an existing dashboard feature claimed from the reviewed implementation. The deliverable is an explanation of readiness, with a separate column for human review and application test evidence.
Reuse the six graph cases
Test the initial proposal, the specs/design fork, the remaining design step, task readiness and all-artifact completion. Add invalid-schema tests only after choosing and reviewing a schema validator; do not assume fromSchema supplies one.
A visible next command should be text for review, not an automatically executed shell string. Treat names and paths as data and keep command execution outside the first version of the exercise.
Demonstrate the distinction that matters
Show a change with every planning artifact present but a failing application test. The interface should say planning complete and implementation unverified or failing. It must not render a single green release badge from the completed artifact set.
Finish with a short fixture report, source revision and a screenshot of the blocked-state explanation. Adding real assistant integration, shared stores or live command execution requires another security and behavior review.
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
Render a synthetic schema without writes.
- 2
Show missing dependencies and independent evidence.
- 3
Demonstrate planning complete with a failing test.
Copy-ready example
{"planning":"complete","implementation":"test-failed","release":"not-verified","nextCommand":"display-only"}Frequently asked questions
Must the prototype call a model?
No. Synthetic graph states are enough for the first version.
What proves the exercise is complete?
Reproducible state cases and a view that never confuses planning with verified implementation.
Sources
- OpenSpec / src/core/artifact-graph/graph.tsSource checked 2026-09-23
- OpenSpec / src/core/change-status-policy.tsSource checked 2026-09-23
- OpenSpec / schemas/spec-driven/schema.yamlSource checked 2026-09-23