feat(skills): propose /opsx:update planning-artifact update skill #1278
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| schema: spec-driven | ||
| created: 2026-06-29 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| # Design: `/opsx:update` — a thin update skill | ||
|
|
||
| ## Context | ||
|
|
||
| OPSX models a change as a small DAG of planning artifacts. Each schema declares artifacts with `requires` edges ([schemas/spec-driven/schema.yaml](../../../schemas/spec-driven/schema.yaml)); `ArtifactGraph` ([src/core/artifact-graph/graph.ts](../../../src/core/artifact-graph/graph.ts)) topologically sorts them, and `openspec status --change <id> --json` already reports, per artifact: its `status` (`done`/`ready`/`blocked`), its `outputPath`, and — via the top-level `artifactPaths` map — its `resolvedOutputPath` and `existingOutputPaths`, plus the change's `schemaName` and `isComplete`. The two path fields differ in a way that matters for a write operation: `existingOutputPaths` is the concrete files that exist on disk (for a glob artifact such as `specs/**/*.md`, the glob already expanded to real files); `resolvedOutputPath` is the change-dir-joined declared path, which for a glob artifact is still the glob (`.../specs/**/*.md`) and is therefore **not** a write target. `/opsx:update` edits the files in `existingOutputPaths`. `openspec list --json` lists changes by recency. | ||
|
|
||
| That is everything an update skill needs. The artifacts are a handful of markdown files on disk; the agent can read them. So `/opsx:update` is built as a thin skill over the **existing** CLI, in the same shape as `continue-change.ts` (select change → `openspec status --json` → act). | ||
|
|
||
| This proposal began larger — a reverse-dependency graph API, content digests, a baseline ledger, a `reconcile` write op, a `status --impact` selector. Review feedback ([PR #1278](https://github.com/Fission-AI/OpenSpec/pull/1278)) was that this over-builds: coding agents tend to over-complicate skills, and the feature should work off the existing `status` command with as little new code as possible. This design follows that steer. | ||
|
|
||
| ## Goals / Non-Goals | ||
|
|
||
| **Goals** | ||
| - A `/opsx:update` action that revises a change's existing planning artifacts and keeps them coherent with one another. | ||
| - Drive it from the artifact set and paths the CLI already reports — zero hardcoded artifact names — so custom schemas work. | ||
| - Edit planning artifacts only; never touch code. Confirm every edit with the user. | ||
| - Add as little code as possible: one skill template, no changes to the graph engine, the `status` command, or the metadata schema. | ||
|
|
||
| **Non-Goals** | ||
| - A new top-level `openspec update*` CLI verb (name is taken; see Naming). | ||
| - Automatic, unattended regeneration (the user always confirms). | ||
| - Content digests, a drift/staleness signal, a baseline ledger, a `reconcile` op, or a `status --impact` selector (see "Why not the heavier machinery"). | ||
| - Regenerating *code* from updated artifacts — that is `/opsx:apply`'s job; `/opsx:update` stops at the plan and hands off. | ||
| - Cross-change audit ([#247](https://github.com/Fission-AI/OpenSpec/issues/247) in full) — a later proposal; this change is intra-change. | ||
|
|
||
| ## The skill, written by hand | ||
|
|
||
| Working backwards from "what is the minimal instruction set," here is the skill body in sketch form. It is short on purpose — few tokens, few commands: | ||
|
|
||
| ``` | ||
| Revise a change's planning artifacts and keep them coherent. Never edit code. | ||
|
|
||
| 1. Resolve the change. | ||
| - If named, use it. Else infer from context; if unclear, run `openspec list --json` | ||
| and ask the user to choose (most-recently-modified first). Never auto-select. | ||
|
|
||
| 2. Get the artifacts. | ||
| - Run `openspec status --change "<id>" --json`. | ||
| - Read `artifacts[]` (ids + status) and the `artifactPaths` map. These come from the | ||
| active schema — do not assume the artifact ids or paths. | ||
| - The files to edit are `artifactPaths.<id>.existingOutputPaths` (already glob-expanded | ||
| for artifacts like `specs/**/*.md`). Do not write to `resolvedOutputPath`: for a glob | ||
| artifact it is still the glob pattern, not a real file. | ||
|
|
||
| 3. Understand the request. | ||
| - If the user named a change ("the design now uses X"), that is the starting edit. | ||
| - If they only said "update" / "make this coherent," treat it as a coherence review. | ||
|
|
||
| 4. Read and reconcile. | ||
| - Read the artifact(s) the request touches and the other existing artifacts in the change. | ||
| - Apply the requested edit. Then check every other existing artifact against it — in any | ||
| direction (an edit to design may require revising the proposal, not only the tasks) — | ||
| and note what is now inconsistent, missing, or contradictory. | ||
| - Do not invent artifacts that don't exist yet; point the user to `/opsx:continue` to create them. | ||
|
|
||
| 5. Confirm and apply, one artifact at a time. | ||
| - Show each proposed revision and why. Write only after the user confirms. | ||
| - When a substantial rewrite is needed, `openspec instructions <artifact> --change "<id>" --json` | ||
| gives that artifact's rules/template to follow. | ||
|
|
||
| Guardrails: | ||
| - Planning artifacts only. If the plan now implies code changes, stop and point to `/opsx:apply`. | ||
| - Use artifact ids/paths from `openspec status`; never branch on literal proposal/specs/design/tasks names. | ||
| - If the request changes the change's *intent* rather than refining it, recommend `/opsx:new` | ||
| (the "Update vs. Start Fresh" heuristic, docs/opsx.md). | ||
| ``` | ||
|
|
||
| The `spec-driven` artifact names may appear once, as a worked *example* of how to apply step 4, exactly as `continue-change.ts` does today — but the control flow reads ids from the CLI, so the skill never branches on those names. A template test asserts there is no name-based branching (the anti-[#777](https://github.com/Fission-AI/OpenSpec/issues/777) guard). | ||
|
|
||
| ## Decisions | ||
|
|
||
| ### 1. Bidirectional coherence, not downstream propagation | ||
| The artifact graph has a build *order*, but "what needs updating after an edit" is not strictly downstream. If `design` changes, the `proposal` it elaborates may need to change too; if `tasks` reveal a missing capability, the `specs` may need a new requirement. The skill therefore reads the change's artifacts and reconciles them in whatever direction the edit demands. Build order is still useful as a default *reading* order and for presenting fixes, but it is not a constraint on which artifacts may be revised. This is why the design does not add a one-directional `getDownstream` / `--impact` primitive: it would encode the wrong model. | ||
|
|
||
| ### 2. Lean on the existing `status` command | ||
| `openspec status --change <id> --json` already returns the artifact set, per-artifact status, and, in the `artifactPaths` map, the on-disk paths. The skill writes to `artifactPaths.<id>.existingOutputPaths` — the concrete files, glob-expanded — and deliberately not to `resolvedOutputPath`, which for a glob artifact is the pattern itself and not a file. That is everything the skill needs to know what exists and where it lives; no new CLI field is required. Picking the change reuses `openspec list --json`, exactly like `/opsx:continue`. No new CLI surface is introduced. | ||
|
|
||
| ### 3. Why not the heavier machinery (digests, ledger, reconcile, impact) | ||
| The first draft proposed SHA-256 content digests, a per-change baseline ledger in `.openspec.yaml`, an `openspec reconcile` write op, a derived drift signal, and a `status --impact` selector — so the CLI could tell the agent *which* artifacts are stale without the agent reading them. | ||
|
|
||
| Rejected for v1, because the cost outweighs the need: | ||
| - The artifacts are a few markdown files. An agent that is going to *rewrite* them must read them anyway, so computing staleness for it saves little and adds a stateful subsystem (a ledger that `status` must not mutate, a separate write verb, scheme-versioning for forward-compat, cross-platform digest canonicalization, and the round-trip tests for all of it). | ||
| - A digest/ledger only earns its keep when something must judge staleness *without* reading content — e.g. unattended drift detection across many changes ([#247](https://github.com/Fission-AI/OpenSpec/issues/247) cross-change, [#846](https://github.com/Fission-AI/OpenSpec/issues/846) tracking files). Those are out of scope here. When one of them becomes concrete, this machinery can be designed against that real need. | ||
|
|
||
| So `/opsx:update` v1 has the agent read the change's artifacts and judge coherence directly. If, after using it, a deterministic signal proves necessary, the smallest first step is to expose the schema's `requires` edges on `status --json` (a single additive field, no new command) — and only then consider digests. | ||
|
|
||
| ### 4. Naming: `/opsx:update` skill, not `openspec update` CLI | ||
| `openspec update [path]` already regenerates AI tool/skill files ([src/cli/index.ts](../../../src/cli/index.ts)). Overloading it would give one verb two unrelated meanings. The artifact-update action is therefore the **skill** `/opsx:update`, with no new `openspec` verb at all. Considered and rejected: `openspec regen --from <artifact>` ([#705](https://github.com/Fission-AI/OpenSpec/issues/705)) — a mutating CLI verb that rewrites artifacts duplicates the skill's job and bypasses user confirmation; the value is in the agent's semantic revision, not a CLI rewrite. | ||
|
|
||
| ### 5. Guardrails (the part that makes it the requested command) | ||
| - **Planning artifacts only.** The skill's write targets are the artifact paths from `status`; if a revision implies code changes it stops and points to `/opsx:apply`. This directly answers [#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)'s complaint that the manual workaround edits code. | ||
| - **Schema-driven.** Ids and paths come from `status`; no branching on literal `proposal`/`specs`/`design`/`tasks`. Works for custom schemas ([#777](https://github.com/Fission-AI/OpenSpec/issues/777), [#666](https://github.com/Fission-AI/OpenSpec/issues/666)). | ||
| - **Confirm each edit.** One artifact at a time, shown before writing. | ||
| - **Intent guard.** A revision that changes intent rather than refining it is redirected to `/opsx:new` (the "Update vs. Start Fresh" heuristic, [docs/opsx.md](../../../docs/opsx.md)). | ||
|
|
||
| ## Risks / Trade-offs | ||
|
|
||
| - **No deterministic staleness signal.** With no digest/ledger, the skill relies on the agent reading the artifacts to spot incoherence. Trade-off accepted: an agent that rewrites prose must read it anyway, and a content-blind signal earns its cost only for use cases this change excludes (Decision 3). | ||
| - **Coherence quality depends on the agent.** Mitigated by confirming every edit and by keeping scope to one change's artifacts (a small, readable set). | ||
| - **Skill drifts back to hardcoding artifact names.** Mitigated by a template test asserting the control flow reads ids from `status` JSON and contains no name-based branching. | ||
|
|
||
| ## Migration Plan | ||
|
|
||
| Additive and backward-compatible. One new skill template behind the expanded-workflow profile; one docs row. No existing command changes behavior; no schema or graph changes. The superseded stub (`add-artifact-regeneration-support`) is removed or folded in the same PR to avoid two competing proposals in the tree. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| ## Why | ||
|
|
||
| OPSX names **four** first-class actions — "create, implement, **update**, archive — do any of them anytime" ([docs/opsx.md:52](../../../docs/opsx.md)). Three ship as commands. **`update` does not exist.** The only mechanism offered is *"edit the files manually"* — and when you edit one artifact, nothing helps you keep the rest of the change coherent. Worse, the manual workaround lets the agent edit **code** when the user only wanted to revise the **plan** ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)). | ||
|
|
||
| This is the most-requested missing capability in the tracker. It is one gap with several faces, and the fix is small: a thin `/opsx:update` skill that revises a change's planning artifacts and keeps them coherent with each other, built on the **existing** `openspec status` / `openspec list` commands. No new graph engine, no digests, no ledger — just an agent that reads the change's artifacts and updates what needs updating, with the user's confirmation. | ||
|
|
||
| ## What Changes | ||
|
|
||
| The whole feature is a single new workflow skill, `/opsx:update`. Written by hand, its instruction set is short: | ||
|
|
||
| 1. **Understand the request** — what the user wants to revise (or, with no specific ask, "review this change for coherence"). | ||
| 2. **Get the artifacts** — run `openspec status --change <id> --json`. Its `artifactPaths` map reports, per artifact, which files exist and where: `existingOutputPaths` is the concrete file list to edit — already expanded for glob artifacts like `specs/**/*.md`. (`openspec list --json` to pick the change when it isn't given.) | ||
| 3. **Read and revise** — read the relevant artifacts, make the requested edit, then check the change's **other** artifacts against it and propose any follow-on edits needed to keep the plan coherent. | ||
| 4. **Confirm and apply** — show each proposed revision, write only after the user confirms. | ||
|
|
||
| Two guardrails make it the command the cluster asked for: | ||
|
|
||
| - **Planning artifacts only, never code.** If a revised plan implies code changes, it hands off to `/opsx:apply` ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)). | ||
| - **Schema-driven, not name-driven.** Artifact ids and paths come from `openspec status`, so the skill works for custom schemas, not just the default `proposal → specs → design → tasks` ([#777](https://github.com/Fission-AI/OpenSpec/issues/777), [#666](https://github.com/Fission-AI/OpenSpec/issues/666)). | ||
|
|
||
| **Coherence is bidirectional.** Earlier framing treated update as strictly "downstream" propagation. That is wrong: in `proposal → specs → design → tasks`, editing `design` can require revising `proposal` too. The skill reads the change's artifacts and reconciles them in whatever direction the edit demands, rather than assuming a fixed flow. | ||
|
|
||
| ### Deliberately not built (yet) | ||
|
|
||
| Per the steer to introduce as little code as possible, and only when there is a defined need, this change does **not** add: a reverse-dependency graph API, content digests / staleness signals, a `.openspec.yaml` baseline ledger, an `openspec reconcile` write op, a drift report, or a `status --impact` selector. The agent reads the change's artifacts directly — a handful of markdown files — which is enough to judge coherence. If a future, concrete need emerges (e.g. unattended drift detection across many changes), exposing the schema's `requires` edges on `openspec status --json` is a one-field additive follow-up. It is out of scope here. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
|
|
||
| - `opsx-update-skill`: A new `/opsx:update` workflow skill that revises a change's existing planning artifacts and keeps them coherent with one another. It reads the artifact set and paths from `openspec status`, reviews related artifacts in any direction (not only downstream), edits planning artifacts only and never code, and confirms each edit with the user. | ||
|
|
||
| ## Impact | ||
|
|
||
| - `src/core/templates/workflows/update-change.ts` (**new**) — the `openspec-update-change` skill template and the `/opsx:update` command template, mirroring the structure of `continue-change.ts`. Reads artifact ids and paths from `openspec status --json`; embeds no artifact-name patterns. | ||
| - Skill/command registration + the expanded-workflow profile that already lists `continue`, `ff`, `verify`, … so `/opsx:update` installs alongside its siblings. | ||
|
Contributor
There was a problem hiding this comment. Would this be part of the default workflow or the expanded workflow? I'm leaning towards having it included as part of the default. WDYT?
Collaborator
Author
There was a problem hiding this comment. Agreed, default happy path seems easiest for users.
Collaborator
Author
There was a problem hiding this comment. Encoded in be92e8a: |
||
| - `docs/opsx.md` — add a `/opsx:update` row to the command table and a short "Updating a change" usage note. | ||
| - `openspec/changes/add-artifact-regeneration-support/` — the in-repo proposal-only stub for this gap is superseded; retire it or fold its notes into design. | ||
| - No changes to `src/core/artifact-graph/*`, `src/commands/workflow/status.ts`, or `ChangeMetadataSchema`. The skill uses `openspec status` / `openspec list` as they exist today. | ||
|
|
||
| ## Issues addressed | ||
|
|
||
| Verified against `Fission-AI/OpenSpec` on 2026-06-30. | ||
|
|
||
| Closes (the missing-update-action family): | ||
|
|
||
| - [#1188](https://github.com/Fission-AI/OpenSpec/issues/1188) — "Add a command to update proposal, design and task" (and stop it editing code). Delivered as `/opsx:update`, planning-artifacts-only. | ||
| - [#705](https://github.com/Fission-AI/OpenSpec/issues/705) — "Rebuild downstream artifacts from a modified upstream." Delivered as the skill's read-and-reconcile pass over the change's artifacts. | ||
| - [#673](https://github.com/Fission-AI/OpenSpec/issues/673) — "clarify": update existing artifacts without auto-advancing the build frontier. `/opsx:update` revises in place and never creates the next artifact. | ||
| - [#247](https://github.com/Fission-AI/OpenSpec/issues/247) — "review and update all change proposals." Delivered as the within-a-change coherence review; cross-change audit is a separate, later proposal. | ||
|
|
||
| Answers (questions whose honest answer today is "no command exists"): | ||
|
|
||
| - [#694](https://github.com/Fission-AI/OpenSpec/issues/694), [#684](https://github.com/Fission-AI/OpenSpec/issues/684), [#618](https://github.com/Fission-AI/OpenSpec/issues/618) — "which command regenerates a document after the flow progressed / after apply?" → `/opsx:update`. | ||
| - Discussion [#1206](https://github.com/Fission-AI/OpenSpec/discussions/1206) — the official answer becomes `/opsx:update`. | ||
|
|
||
| Supersedes: | ||
|
|
||
| - `openspec/changes/add-artifact-regeneration-support` (in-repo, proposal-only stub) — same problem, replaced by this skill. Its hardcoded-filename dependency tracking and metadata-file staleness mechanism are dropped in favor of letting the agent read the artifacts. | ||
|
|
||
| Delineated from adjacent commands (distinct surfaces — coordinate, don't collide): | ||
|
|
||
| - [#702](https://github.com/Fission-AI/OpenSpec/pull/702) `/opsx:clarify` — resolves ambiguity *within one artifact* via Q&A; a complementary upstream step. `/opsx:update` then reconciles the change's artifacts with each other. | ||
| - [#1251](https://github.com/Fission-AI/OpenSpec/pull/1251) `/opsx:review`, [#880](https://github.com/Fission-AI/OpenSpec/issues/880) — review the *implementation (code)* against the plan. `/opsx:update` is the mirror image: it keeps the *plan* coherent and never touches code. | ||
| - [#783](https://github.com/Fission-AI/OpenSpec/issues/783) — cross-artifact quality review. The skill's coherence pass is the lightweight form of this; a deterministic `validate`-side check is a separate proposal. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder what should happen if the change is already built out, or the changes are implemented, but we want to add or update something to that change proposal. I don't think it should implement anything for sure, but perhaps we should provide some guidance on the next step after the update.
Maybe account for any intelligent next-step guidance as part of the skill?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good call — added (be92e8a). The skill now ends with a next-step guidance step: after applying confirmed revisions it reports where the change stands and recommends the next command —
/opsx:continueif artifacts are missing,/opsx:applywhen the change was already implemented (the code may no longer match the revised plan),/opsx:archivewhen everything is done. Guidance only — it never implements, mirroring the hand-offcontinue-change.tsalready uses. Spec'd as a new "Next-Step Guidance" requirement with an "updating an already-implemented change" scenario, plus a template test (3.5).