Intended order of artifacts when using extended work flow (new, continue not proposal)

[BenNewman100]

What is the Intended order of artifacts when using the extended workflow/profile? (I don't remember the exact term, but I mean when using the new and continue skills/commands instead of the proposal skill (which one-shots all 4 artifacts)?

I thought the intended order was proposal.md, spec-delta, design.md, tasks.md, but Claude is consistently creating the design doc first. when I ask it says the instructions say that task needs both done before it is written, but there is no defined order between spec and design, and design is listed first.

Really, I would like to do is

1. proposal
2. spec and design (same time)
3. [Iterate on those with agent]
4. tasks

Side Notes about OpenSpec:
The concepts/names of the proposal.md and the proposal skill/command, and the in-progress "change" get really muddy. Might I suggest rethinking their names? It makes talking to the agent harder because you have to keep reclarifying the context of what you are talking about.

[clay-good]

There is no defined order between specs and design, and that is deliberate rather than an oversight. The dependency graph in the default schema is:

Artifact	requires
proposal	(nothing)
specs	proposal
design	proposal
tasks	specs, design

Source: schemas/spec-driven/schema.yaml (requires: under each artifact). You can see the same thing live for your own change:

openspec status --change <name> --json

which returns each artifact with its status, its requires edges, and any missingDeps (docs/cli.md).

So specs and design are siblings: both unblock the moment proposal exists, and tasks waits for both. Your desired order is the intended order. /opsx:continue is picking design first only because it is listed first among the ready artifacts, not because anything requires it.

If you want spec first, say so. /opsx:continue specs (or just telling the agent "do the spec delta next") is legal at every point after the proposal exists, and iterating on both before letting tasks generate is exactly the shape the graph was built for.

On the naming: agreed that "proposal the artifact" versus "propose the command" versus "change the in-flight thing" is muddy in conversation. Worth a separate issue so it does not get lost in this answer. Leaving this one open for that discussion.

[alesky78]

This also happens to me with GitHub Copilot, so I don't think it's tied to a specific LLM.

After implementing well over a hundred features with OpenSpec, I think I can offer a quick observation without going too deep into the commands or the reasons why OpenSpec sometimes prefers design over spec.

From what I've seen, if the initial prompt is already highly technical and effectively contains part of the solution, the LLM tends to prioritize the design artifact first because it already has enough implementation context.

@clay-good , if I may add one suggestion: the fact that the order isn't fixed is a problem in itself. However, when reading the official workflow documentation, it isn't immediately obvious that the artifact order is intentionally non-binding. When I first encountered this behavior, I interpreted it as a bug because I expected the workflow to be strictly sequential. I ended up digging into how the LLM interacts with the OpenSpec commands to understand why it was making that choice.

Making this explicit in the documentation would probably save new users from the same confusion.

[clay-good]

Answered above, and the behaviour you hit is now fixed.

You were right that specs and design are siblings in the graph (both requires: [proposal]), but the tie was broken alphabetically — and "design" sorts before "specs". That's why openspec status and nextSteps kept pointing your agent at design.md first, contradicting every doc and the schema's own description.

Fixed in #1465 (merged): ties now break on the order the schema declares its artifacts, which covers openspec status, status --json, nextSteps, blocked by: and instructions' unlocks field. On a fresh change you now get:

[x] proposal
[ ] specs      ◄── first ready
[ ] design
[-] tasks (blocked by: specs, design)

So your desired order — proposal → specs + design → iterate → tasks — is what the tooling now recommends. design.md stays optional and is still writable early if you want it.

Custom schemas get the same guarantee: list artifacts in the order you want them written.

Your naming point (proposal.md vs. the propose skill vs. the change) is fair and better tracked separately — please open an issue for it if it's still biting you.

Closing as fixed; reopen if you still see design recommended first after upgrading.