Repository navigation
How to update specifications during the apply phase? #684
Description
Before running /opsx-apply, all specs (proposal.md, design.md, spec.md, task.md) looked good to me. However, after applying a few tasks, I noticed the generated code was incorrect or unexpected, due to insufficient clarification or missing specific details. Therefore, I need to add content or update the spec files.
I’m wondering if there are any recommended practices or standard ways to update the spec files?
Reacted by LanxiangWang, xiao, Lei Jiang, carlfriedrich, Nik, Karolis, Oleg Kulyk, chengxuanli00, T.H.Wu, greyovo and 3 more
Activity
21st-connector commentedon Feb 9, 2026
Task completed.
The enrichment comment has been posted on issue #684. Here's a summary of what was included:
Key findings:
OpenSpec explicitly supports mid-apply spec updates — the docs and code confirm a "fluid, not phase-locked" philosophy where artifacts can be edited anytime.
Recommended workflow: Pause apply, edit the artifact files directly in the change directory, then re-run
/opsx:apply. The apply command re-reads all context files fresh each invocation (src/commands/workflow/instructions.ts:336-353).5 related issues identified — Clarify command (update existing artifacts before continue) #673, Best workflow to fix mistakes in a completed change? #618, When refining the specs, can we add a command? #264, Simple agents.md rule for updating existing spec without triggering whole openspec creation process #119, and [FEAT] Feedback loop / rework based on review #141 all touch on the same concern. There's a recognized gap around having a dedicated command to streamline re-entering planning mode to update a specific artifact.
Provided a mapping table of what type of insight goes into which artifact file (specs, design, proposal, tasks).
Comment URL: #684 (comment)
View full conversation
Powered by 1Code
21st-connector commentedon Feb 9, 2026
Issue Enrichment
Thanks for the question! This is a common workflow concern. Here's what the codebase and docs say about updating specs during the apply phase.
Short Answer: Edit Directly, Then Continue
OpenSpec explicitly supports updating artifacts during implementation. From the Getting Started guide:
The OPSX philosophy is "actions, not phases" — there are no phase gates preventing you from editing specs mid-apply. From the OPSX docs:
Recommended Workflow
/opsx:applysessionopenspec/changes/<your-change>/proposal.md— if scope needs updatingopenspec/changes/<your-change>/specs/<capability>/spec.md— if requirements need clarificationopenspec/changes/<your-change>/design.md— if technical approach needs adjustmentopenspec/changes/<your-change>/tasks.md— if tasks need to be added/removed/reworded/opsx:applyagain. It reads context files fresh each time (src/commands/workflow/instructions.ts:336-353) and picks up from incomplete tasks.You can also use
/opsx:exploreto think through what needs changing before editing, or use/opsx:continueto have the AI regenerate a specific artifact.What the Apply Phase Reads
Each time
/opsx:applyruns, it loads all existing artifacts as context files (seesrc/commands/workflow/instructions.ts:336-353), so any edits you make to specs, design, or proposal will be picked up on the next apply invocation. The default apply instruction fromschemas/spec-driven/schema.yaml:151-153is:Where to Capture Different Types of Changes
From the skill templates:
specs/<capability>/spec.mdspecs/<capability>/spec.mddesign.mdproposal.mdtasks.mdRelated Issues
This is a recurring question in the community:
There's an open gap around a dedicated command for "re-enter planning mode to update a specific artifact" (as noted in #673 and #264). Today the workflow is manual editing + re-running apply, which works but isn't as streamlined as it could be.
docs: close recurring gaps (existing projects, editing changes, unins…
docs: comprehensive overhaul — discoverability, explore-first, and cl…
docs(openspec): propose add-update-workflow — graph-driven /opsx:upda…
docs(openspec): propose add-update-workflow — graph-driven /opsx:upda…
docs: comprehensive overhaul — discoverability, explore-first, and cl…
feat(skills): propose /opsx:update planning-artifact update skill (Fi…
合并英文上游 v1.6.0-beta.1 + 双语解析保住 + 增量汉化 (#5)
clay-good commentedon Jul 23, 2026
Closing, this is both supported and documented.
Editing artifacts mid-apply is expected, not a workaround. Pause, update the spec (either by hand or with
/opsx:update, which also reconciles the other artifacts so they do not contradict the change you just made), then continue with/opsx:apply. Apply rereads the artifacts every run, so it builds against the new plan rather than the one it started with./opsx:updateshipped in #1278 and is in the default profile as of v1.6.0. The guide is Editing & Iterating on a Change.