Bug Report: spec-driven schema dependency order

[gabinoguera]

Bug: In schemas/spec-driven/schema.yaml, the design artifact only requires proposal, allowing it to be generated in parallel
with specs. This contradicts the documented sequence proposal → specs → design → tasks.

Impact: /opsx:continue offers design before specs are written, so the design document is created without spec requirements as
input.

Fix (line 110-111 of schema.yaml):

Before

- id: design
  requires:
    - proposal

After

- id: design
  requires:
    - proposal
    - specs

Rationale: Design documents explain HOW to implement — they need the specs (WHAT to build) as input. The schema's own
description says proposal → specs → design → tasks, and the instruction field for design says "Reference the proposal for
motivation and specs for requirements."

[21st-connector]

Task completed.

The comment has been posted on issue #695. Here's a summary of what I found and commented:

Confirmed bug: The design artifact in schemas/spec-driven/schema.yaml:110-111 only requires proposal, but the schema's own description (line 3), workflow docs, and the design artifact's instruction text (line 107: "Reference the proposal for motivation and specs for requirements") all indicate it should also require specs.

Key findings in the comment:

• Three internal contradictions within schema.yaml itself that confirm the bug
• The proposed fix in the issue is correct — add specs to the design artifact's requires list
• A documentation inconsistency in docs/concepts.md that would also need updating
• Two potentially related/duplicate issues: Generation order seems reversed between design and spec #692 (same symptoms) and Artifacts generation order #674 (closed, may be incomplete fix)
• A test fixture in test/core/artifact-graph/state.test.ts:153-156 that mirrors the buggy behavior and would need updating

---

View full conversation

Powered by 1Code

[21st-connector]

Issue Analysis

Confirmed Bug

The dependency definition for the design artifact at schemas/spec-driven/schema.yaml:110-111 is inconsistent with the documented workflow. The design artifact only requires proposal, but should also require specs.

Three sources within this file contradict the current requires definition:

Location	What it says
Line 3 (description)	proposal → specs → design → tasks — sequential ordering
Line 107 (design instruction)	"Reference the proposal for motivation and specs for requirements."
Lines 110-111 (requires)	requires: [proposal] — missing specs

Because design and specs both only depend on proposal, the artifact graph allows them to run in parallel. This means /opsx:continue can offer to generate design.md before any spec files exist, producing a design document that cannot reference the spec requirements its own instructions tell it to use.

Proposed Fix

The fix in the issue description is correct. At line 110-111 of schemas/spec-driven/schema.yaml:

# Current (line 110-111)
    requires:
      - proposal

# Should be
    requires:
      - proposal
      - specs

This makes the actual dependency graph match the documented sequence: proposal → specs → design → tasks.

Documentation Inconsistency

Note that docs/concepts.md (around lines 379-386) explicitly documents the current (incorrect) behavior as intentional, showing design and specs running in parallel from proposal. If the schema is fixed, that documentation section and its ASCII dependency diagram should also be updated to reflect the sequential ordering.

Meanwhile, docs/workflows.md (line 21) shows the correct sequential flow: proposal ──► specs ──► design ──► tasks.

Possibly Related Issues

• Generation order seems reversed between design and spec #692 — "Generation order seems reversed between design and spec" — appears to describe the same root cause from a user-facing perspective.
• Artifacts generation order #674 (closed) — "Artifacts generation order" — previously addressed artifact ordering; this may be a regression or incomplete fix.

Affected Tests

test/core/artifact-graph/state.test.ts:153-156 uses a test schema where design requires only [proposal], mirroring the current (buggy) behavior. This test fixture would need updating if the fix is applied, to ensure the test graph reflects the corrected dependency chain.

[clay-good]

Confirmed, and fixed in #1465 — with one deliberate difference from the proposed patch.

The reason /opsx:continue offered design before specs was not the requires list on its own: specs and design both require only proposal, so they became ready at the same time, and the graph broke that tie alphabetically ("design" < "specs"). openspec status listed design first and nextSteps recommended openspec instructions design, so agents wrote design.md before any spec existed.

#1465 breaks ties by the order the schema declares its artifacts, so spec-driven now runs proposal → specs → design → tasks exactly as its description says — and custom schemas get the same behavior for free.

design.requires was left as [proposal] on purpose. Adding specs would mark design blocked until specs exist, and drafting design early is legitimate (the instruction says to reference the specs "once written"). If a maintainer prefers the harder dependency, #1173 tracks that question.