Independent decision guide

vs OpenSpec

Both preserve AI-assisted work as Markdown in your repository. They solve different primary problems: workflow-agent manages delivery across tickets; OpenSpec manages agreement about system behavior.

Compared against workflow-agent’s repository and OpenSpec 1.14.1 documentation · reviewed 12 October 2026

The short answer

Choose the source of truth you actually need.

Choose workflow-agent when your pain is decomposing a change, sequencing deployable tickets, verifying implementation phases, and resuming delivery. Choose OpenSpec when your pain is agreeing on requirements and scenarios, maintaining living product specs, or standardizing a customizable spec process across tools and teams.

Do not run both for the same change.

Two proposals, two task lists, and two completion states create drift. Pick one owner; use the other only for a clearly separate concern.

Jump to Snapshot Developer flow Artifacts Pros & cons Scorecard Decision guide Sources
01 · Snapshot

Same medium, different center of gravity

Both are local-first, agent-driven, Git-friendly, and use plain files. The important distinction is what each treats as durable truth.

Dimensionworkflow-agentOpenSpec
Primary jobTicket lifecycle and implementation executionSpec-driven agreement and change management
Durable truthActive ticket location and artifacts; dated SUMMARY.md records preserve terminal outcomes and rationaleCurrent behavior in openspec/specs/; proposed deltas in changes
Core unitA change containing one or more independently deployable ticketsA change containing proposal, behavioral deltas, design, and tasks
Default pathnew → discover → breakdown → specify? → plan → implement → complete → archiveexplore? → propose → apply → sync? → archive
Workflow characterExplicit ticket states, optional just-in-time behavior specification, and independently verified plan phasesFluid artifact graph; artifacts can be revised at any time
Requirements modelConcise ticket criteria plus optional confirmed ticket-level SPEC.md user stories, scenarios, protected behaviors, and exclusionsNormative requirements plus concrete scenarios; delta specs merge into baseline specs
Planning modelDetailed phased PLAN.md with specification traceability plus concise PLAN-BRIEF.mdproposal.md, delta specs, design.md, and checklist-style tasks.md
Progress modelTicket folders move through draft, todo, in-progress, done; terminal changes distill into one date-stamped summaryCheckboxes in tasks.md; full active changes move into date-stamped archives
Review & verificationOptional plan and implementation reviews; phase and final verification required by the workflowPlanning review is human-driven; /opsx:verify is optional and not in the default core profile
ToolingOne Agent Skill; no service or package runtimeNode CLI plus generated skills/commands for selected assistants
CustomizationEdit the skill references and Markdown templatesProject config, artifact rules, custom schemas, templates, and global overrides
IsolationBuilt-in opt-in Git worktree setup on any commandNo equivalent change-level worktree workflow in the compared core documentation
Cross-repo planningRepository-localStores support shared and cross-repo planning; documented as beta
Installation costnpx skills add … --skill wf; requires a skills-capable agentGlobal npm/Homebrew CLI, Node ≥20.19 for npm, then openspec init
TelemetryNo telemetry mechanism documentedAnonymous command name/version telemetry is on by default; opt-out supported

“No equivalent” means no feature documented in the reviewed official workflow pages; it is not a claim that an agent cannot use normal Git worktrees alongside OpenSpec.

02 · Daily development flow

What using each one feels like

workflow-agent asks you to manage delivery explicitly. OpenSpec asks you to make behavior explicit, then keeps planning artifacts fluid while the implementation evolves.

workflow-agent

Change → tickets → verified phases

  1. Open a workspace

    wf new creates a change with context, status, and four ticket-state folders.

  2. Clarify the work

    wf discover turns notes into goals, scope, constraints, risks, and rollout context.

  3. Split delivery

    wf breakdown proposes 1–3 day, independently deployable tickets. You confirm before files are created.

  4. Specify when useful

    wf specify confirms one ticket’s user stories, scenarios, protected behaviors, and exclusions just before planning.

  5. Plan one ticket

    wf plan explores actual code and writes detailed, independently verifiable phases plus a short human brief.

  6. Implement one phase

    wf implement … phase N changes only that phase, runs its verification, and records evidence or deviations.

  7. Complete deliberately

    Optional review checks the code. wf complete checks readiness, final verification, acceptance criteria, and specification coverage before moving the ticket to done.

OpenSpec · core profile

Agreement → implementation → living specs

  1. Explore when uncertain

    /opsx:explore investigates code and options without writing code or artifacts unless you ask.

  2. Propose the change

    /opsx:propose creates proposal, delta specs, design, and tasks in one pass.

  3. Review and revise

    Read the artifacts. Edit Markdown directly or use /opsx:update to reconcile related planning files.

  4. Apply tasks

    /opsx:apply implements unchecked tasks and marks them complete. Re-running resumes from the checklist.

  5. Verify if enabled

    The expanded /opsx:verify checks completeness, correctness, and coherence. It reports rather than blocks.

  6. Sync and archive

    Delta specs merge into current specs, then the full change moves into a date-stamped archive. Incomplete tasks warn but do not block archive.

Practical difference: workflow-agent executes one verified phase at a time, checks readiness when completing tickets, then archives any terminal change as a previewed synthesis with an explicit outcome. OpenSpec is task-checklist driven; its optional verifier reports mismatches, and archive preserves the full artifact set while remaining intentionally non-blocking.
03 · Files and persistence

What survives the chat session

The file shape determines what a future developer—or a fresh agent context—can reconstruct.

workflow-agent

CONTEXT.md

Change-level goals, boundaries, risks, and decisions.

STATUS.md

Derived summary across all tickets; folder location remains authoritative.

TICKET.md

Stable goal, scope, acceptance criteria, dependencies, risk, and technical context.

SPEC.md

Optional confirmed ticket-level user stories, observable scenarios, protected behaviors, and exclusions.

PLAN.md

Code-grounded implementation source of truth, organized into verifiable phases.

PLAN-BRIEF.md

Concise human explanation of architecture, data flow, decisions, rollout, and risks.

PROGRESS.md

Actual changes, commands/results, deviations, blockers, and follow-up work.

REVIEWS.md

Dated optional plan and implementation reviews.

archive/*/SUMMARY.md

Dated terminal outcome, current invariants, lasting decisions, stable code map, limits, evidence, and references.

OpenSpec

proposal.md

Why the change matters, what changes, and expected impact.

specs/**/*.md

ADDED, MODIFIED, REMOVED, or RENAMED requirements with scenarios.

design.md

Technical approach, decisions, and implementation shape.

tasks.md

Implementation checklist and resumable completion state.

.openspec.yaml

Change metadata such as schema and creation date.

openspec/specs/

Durable baseline of current system behavior, updated by sync/archive.

changes/archive/

Date-stamped completed changes preserving all planning artifacts.

History versus current truth: workflow-agent retains detailed execution evidence per ticket. OpenSpec’s distinctive asset is the separate baseline spec set that describes the system after changes are merged.
04 · Strengths and weaknesses

Pros, cons, and hidden costs

OpenSpec · strengths

  • Specs remain useful after delivery. Delta requirements merge into domain-organized baseline specs describing current behavior.
  • Requirements are test-shaped. SHALL-style requirements and concrete scenarios make behavior and edge cases reviewable.
  • Easy iteration. Artifacts remain editable during implementation; /opsx:update reconciles the plan coherently.
  • Broad tool support. openspec init generates tool-specific commands or skills for a large documented matrix.
  • Deep customization. Project context, artifact rules, operation guidance, custom schemas, templates, and global overrides are first-class.
  • Team and multi-repo direction. Stores can centralize plans and shared specs outside code repos, though the feature is beta.
  • Deterministic CLI assistance. The CLI owns scaffolding, status, validation, artifact instructions, and archive mechanics.

OpenSpec · weaknesses

  • Two interaction surfaces. Setup/status use a terminal CLI; implementation flows run as assistant commands whose spelling varies by tool.
  • Verification is not default. The core profile omits /opsx:verify, and verification reports do not block archive.
  • Weaker multi-ticket project model. One change is one work unit; there is no equivalent nested ticket lifecycle with dependency readiness.
  • Spec maintenance is real work. Baseline specs become valuable only if the team keeps deltas accurate and resolves drift before archive.
  • More generated/configured surface. CLI version, profiles, schemas, tool adapters, and generated command files need updates.
  • Telemetry defaults on. Only command names and version are documented as collected, but privacy-sensitive teams must opt out.
  • Fluidity shifts discipline to the team. Incomplete tasks warn rather than block archive; scope control and artifact honesty remain human responsibilities.
05 · Use-case scorecard

Fit by situation

Scores measure out-of-the-box fit, not theoretical capability. 5 = directly modeled; 3 = workable with discipline; 1 = requires a parallel process or substantial customization.

Situationworkflow-agentOpenSpecWhy
Multi-ticket epic5 / 53 / 5workflow-agent directly models decomposition, ticket dependencies, state, and next action.
Behavior/API contract3 / 55 / 5OpenSpec’s normative requirements, scenarios, and delta merge are purpose-built.
One medium feature4 / 55 / 5Both fit; OpenSpec’s core propose/apply/archive path has fewer steps.
Complex refactor5 / 54 / 5workflow-agent’s phased execution evidence and deviation control are stronger; OpenSpec’s design/tasks remain useful.
Product requirements library2 / 55 / 5Only OpenSpec merges delivered deltas into a current behavioral baseline.
Strict completion discipline5 / 53 / 5workflow-agent checks final verification, acceptance criteria, and optional ticket-spec coverage; OpenSpec archive warns but does not block.
Many AI assistants3 / 55 / 5OpenSpec documents and generates adapters across a broad tool matrix.
Custom team process3 / 55 / 5OpenSpec has declarative schemas, config, rules, and templates.
Minimal dependencies5 / 53 / 5workflow-agent is one skill; OpenSpec operates a versioned CLI and generated integration files.
Isolated agent worktree5 / 53 / 5workflow-agent includes worktree selection, validation, routing, and optional dependency setup.
Cross-repo planning2 / 54 / 5OpenSpec Stores target this directly, with beta maturity risk.
Tiny fix3 / 53 / 5Both add overhead. A direct fix may be better when agreement and resumability add no value.
06 · Decision guide

Choose using the failure you want to prevent

Choose OpenSpec if…

  • Vague or drifting requirements are the dominant source of rework.
  • You need a versioned answer to “what does the system do now?”
  • Behavioral scenarios should survive after a feature ships.
  • Many developers and AI tools need the same standardized workflow.
  • Your team wants to design or fork its own artifact graph.
  • Features span repositories or teams and you can accept beta Stores risk.
  • You value fluid plan revision more than enforced lifecycle gates.

Do not choose either by default for trivial work

A one-line typo, dependency bump, or obvious local fix may not justify durable planning files. Use a workflow when misunderstanding, coordination, interruption, or future context loss costs more than the added ceremony.

If both are already installed in one project

Recommended cutover: select one owner per change.

Do not mirror a change into both .workflow/ and openspec/changes/. Their plans and completion state will diverge because neither tool synchronizes the other.

For a delivery-heavy project with external product requirements, use workflow-agent as the change owner and keep product/API contracts in the project’s existing documentation. For a contract-heavy product where current behavior must remain queryable, use OpenSpec as the change owner and rely on your issue tracker for portfolio/ticket status.

If you still need both at repository level, define a hard boundary: for example, OpenSpec owns cross-team behavioral contracts; workflow-agent owns unrelated infrastructure migrations. Never create duplicate artifacts for the same implementation.

07 · Evidence

Sources and scope

Product behavior changes. This comparison uses primary project documentation available on the review date, not marketing comparisons or third-party summaries.