OpenSpec explained: turn an AI coding request into reviewable artifacts
OpenSpec architecture: a dependency graph drives artifact readiness
Trace the default proposal, specs, design and tasks through schema, graph, state and next-step policy.
What you will learn
- Read dependencies rather than a slogan
- Separate graph logic from output detection
- Follow the next-step decision
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
- specs and design share the proposal prerequisite.
- Preferred order differs from a dependency edge.
- Edit-root metadata is not OS isolation.
Read dependencies rather than a slogan
The default schema gives proposal no prerequisites. Both specs and design require proposal; tasks requires specs and design. Although the displayed sequence is linear, the dependency structure contains a fork and a join.
That distinction matters for custom workflows. Declaration order can recommend specs before design without making design depend on specs. A reader should distinguish a preferred next artifact from a hard prerequisite.
Separate graph logic from output detection
ArtifactGraph holds IDs, dependencies and declaration positions. It computes build order, ready artifacts and blocked dependencies. The state module inspects a change directory and delegates output checks to artifactOutputExists.
Those responsibilities are separate from reading a document for correctness. A ready artifact means dependencies are recorded as complete; it does not prove the resulting requirement is accurate or its corresponding test exists.
Follow the next-step decision
resolveNextStep selects the first ready artifact and constructs its instructions command. When all planning artifacts are complete, it constructs an apply-instructions command to inspect implementation progress. A selected store ID is carried into those commands.
buildActionContext reports a repository root and allowed edit roots as workflow metadata. This data is useful guidance, but the inspected function does not create an operating-system sandbox or enforce filesystem permissions.
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
Draw the schema fork and join.
- 2
Identify graph state separately from document quality.
- 3
Trace readiness into the next-step command.
Copy-ready example
proposal -> specs -> tasks
proposal -> design -> tasks
state -> ready artifacts -> instructions commandFrequently asked questions
Must design wait for specs in this schema?
Both require proposal; tasks requires both. Declaration order recommends specs first.
Does ready mean correct?
It describes dependency readiness, not semantic correctness or passing tests.
Sources
- OpenSpec / schemas/spec-driven/schema.yamlSource checked 2026-09-23
- OpenSpec / src/core/artifact-graph/graph.tsSource checked 2026-09-23
- OpenSpec / src/core/artifact-graph/state.tsSource checked 2026-09-23
- OpenSpec / src/core/change-status-policy.tsSource checked 2026-09-23