How to update specifications during the apply phase?

[UltraviolenceCYX]

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?

[1code-async]

Task completed.

The enrichment comment has been posted on issue #684. Here's a summary of what was included:

Key findings:

1. OpenSpec explicitly supports mid-apply spec updates — the docs and code confirm a "fluid, not phase-locked" philosophy where artifacts can be edited anytime.

2. 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).

3. 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.

4. 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

[1code-async]

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:

"During implementation, if you discover the design needs adjustment, just update the artifact and continue."

The OPSX philosophy is "actions, not phases" — there are no phase gates preventing you from editing specs mid-apply. From the OPSX docs:

• Actions, not phases — create, implement, update, archive — do any of them anytime
• Dependencies are enablers — they show what's possible, not what's required next

Recommended Workflow

1. Pause the apply — stop the current /opsx:apply session
2. Edit the artifact files directly — open and modify the relevant files in your change directory:
   • openspec/changes/<your-change>/proposal.md — if scope needs updating
   • openspec/changes/<your-change>/specs/<capability>/spec.md — if requirements need clarification
   • openspec/changes/<your-change>/design.md — if technical approach needs adjustment
   • openspec/changes/<your-change>/tasks.md — if tasks need to be added/removed/reworded
3. Resume apply — run /opsx:apply again. 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:explore to think through what needs changing before editing, or use /opsx:continue to have the AI regenerate a specific artifact.

What the Apply Phase Reads

Each time /opsx:apply runs, it loads all existing artifacts as context files (see src/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 from schemas/spec-driven/schema.yaml:151-153 is:

Read context files, work through pending tasks, mark complete as you go. Pause if you hit blockers or need clarification.

Where to Capture Different Types of Changes

From the skill templates:

Insight Type	Where to Capture
New requirement discovered	specs/<capability>/spec.md
Requirement changed	specs/<capability>/spec.md
Design decision made	design.md
Scope changed	proposal.md
New work identified	tasks.md

Related Issues

This is a recurring question in the community:

• Clarify command (update existing artifacts before continue) #673 — Clarify command (update existing artifacts before continue) — directly related
• Best workflow to fix mistakes in a completed change? #618 — Best workflow to fix mistakes in a completed change
• When refining the specs, can we add a command? #264 — When refining the specs, can we add a command?
• Simple agents.md rule for updating existing spec without triggering whole openspec creation process #119 — Simple way to update existing spec without triggering whole creation process
• [FEAT] Feedback loop / rework based on review #141 — Feature request for a feedback loop / rework mechanism

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.