Investigating the OpenSpec OpsX Workflow
When an AI agent is asked to implement a change, conversational momentum makes it easy to start writing code immediately.
I investigated OpenSpec as a way to externalize decisions into files before implementation and compare the result with the specification afterward.
Current documentation uses /opsx:* as the canonical OpsX notation.
The actual invocation name still depends on the AI-tool integration.
Treat the generated command or Skill and the documentation for the installed version as authoritative.
Inspect the artifact flow first
| Stage | Canonical notation | Main artifact |
|---|---|---|
| Explore | /opsx:explore |
Problem, constraints, and options |
| Propose | /opsx:propose <change> |
Proposal, specs, design, and tasks |
| Apply | /opsx:apply |
Code changes corresponding to tasks |
| Archive | /opsx:archive |
Completed change merged into specifications |
The current OpenSpec Getting Started and Commands show implementation as one stage in an artifact workflow.
The Explore documentation describes exploration as a thinking conversation that does not necessarily create code or artifacts.
Skip it when the change has little ambiguity.
1. Investigate the boundary with explore
Do not choose the solution first.
Answer these questions:
- What is the current problem?
- Who is affected?
- Which behavior must not change?
- Which existing implementation is relevant?
- What are the advantages and disadvantages of the options?
- Which assumptions remain unverified?
The unresolved assumptions become input to later research and acceptance criteria.
If investigation changes the problem statement, update the assumptions instead of forcing implementation to match the first conclusion.
2. Create a reviewable proposal
/opsx:propose gathers the proposal, specification delta, design, and implementation tasks.
Review these points before applying it:
- Are goals and non-goals separate?
- Is failure behavior defined as well as the happy path?
- Are compatibility and migration conditions explicit?
- Can the acceptance criteria be verified?
- Does every task correspond to a specification item?
Reviewing before apply reduces the need to rewrite the explanation after implementation.
Also record rejected options and the reasons that cannot be expressed by code alone.
3. Apply one task with verification
Use /opsx:apply to implement and verify agreed tasks one at a time.
A task is not complete merely because code exists.
Completion includes tests, type checks, linting, builds, and required documentation updates.
When an assumption fails, update the proposal, specification, or design instead of forcing the remaining tasks through.
If the current workflow provides an update command or Skill, use the generated name after checking the installed integration.
OpenSpec artifacts remain in the repository, which makes resuming across AI sessions easier.
Treat files as the source of truth rather than conversation history.
4. Return the decision to specifications with archive
/opsx:archive stores the completed change and merges the required specification delta into the main specifications.
Merging code while abandoning the proposal makes its decisions difficult to rediscover later.
Before archiving, confirm that:
- Every task is complete or explicitly deferred
- Verification results satisfy the acceptance criteria
- Differences between implementation and specification are resolved
- Breaking changes and operational procedures are documented
- The handling of temporary artifacts is decided
“Complete” means that specification, implementation, verification, and storage are aligned.
Do not force the full process onto tiny changes
Requiring the same artifact volume for every change can make documentation the goal.
Start with multi-file changes, changes whose specification is easy to interpret differently, and migrations.
For a small bug fix, a goal, acceptance criteria, and tasks may be sufficient.
Use the OpenSpec Overview and FAQ as reference material.
Pin command names, profiles, and artifact locations to the version and AI-tool integration adopted by the project.