feat(skills): propose /opsx:update planning-artifact update skill

[clay-good]

Status

Proposal approved and now implemented in this PR (per @TabishB's "either is fine" — implementation commit f5ed1bb). Full suite green locally (the 17 zsh-installer failures are a known local oh-my-zsh environment issue); openspec validate add-update-workflow --strict passes; tasks all checked off.

What was missing (the motivation)

OPSX names four first-class actions — "create, implement, update, archive" (docs/opsx.md) — and shipped three. Revising a plan meant hand-editing files, with nothing keeping the change's other artifacts coherent, and nothing stopping the agent from editing code when you only meant the plan. Most-requested gap: #1188, #705, #673, #247 (intra-change), #694/#684/#618, discussion #1206.

What it does

One thin skill, openspec-update-change (/opsx:update), over the existing CLI — no new commands, graph, or schema code:

Piece	Where
Skill + command template	src/core/templates/workflows/update-change.ts (mirrors continue-change.ts)
Default install	update joins ALL_WORKFLOWS and the core profile (maintainer call on-thread)
Registration	init, profiles, skill-generation, tool-detection, profile-sync-drift
Docs	opsx.md row + "Updating a change" note, commands.md reference section, supported-tools.md
Superseded stub	openspec/changes/add-artifact-regeneration-support/ removed

The skill: resolve the change → openspec status --change <id> --json → read artifacts → apply the edit → reconcile the other existing artifacts in any direction → confirm each write → end with next-step guidance (/opsx:continue / /opsx:apply / /opsx:archive), never acting on it.

Guardrails (each pinned by a template test in test/core/templates/update-change.test.ts): planning artifacts only, code hands off to /opsx:apply; ids/paths come from status JSON, never hardcoded artifact names (anti-#777); writes go to existingOutputPaths, never a glob resolvedOutputPath; missing artifacts defer to /opsx:continue; intent changes redirect to /opsx:new.

Proof it works

• openspec init --tools claude (built CLI) now generates .claude/skills/openspec-update-change/SKILL.md and .claude/commands/opsx/update.md in the default core profile.
• Walked the skill's exact CLI calls on a scratch spec-driven change: list --json → status --change --json (ids, statuses, artifactPaths with glob-expanded existingOutputPaths) → instructions design --json — all return the fields the skill relies on.
• 1,778 tests pass, including new template-guardrail tests, core-profile coverage in init/update/config tests, and regenerated golden parity hashes.

Notes

• Change-scoped by design: skill name follows openspec-<verb>-change; command stays /opsx:update (the /opsx: namespace already means change-scoped). Happy to rename the command to /opsx:update-change if preferred.
• No deterministic staleness machinery (per review steer); if one proves necessary later, the smallest step is exposing schema requires edges on status --json.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added /opsx:update to revise an existing change’s planning artifacts in place.
  • The new flow helps keep related artifacts consistent and suggests next steps like /opsx:continue, /opsx:apply, or /opsx:archive.

• Documentation

  • Updated command references and workflow docs to include /opsx:update and how to use it.
  • Added guidance on when to update versus start a fresh change.

• Bug Fixes

  • Expanded core workflow support so the new update command is recognized across profiles and tool detection.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new /opsx:update workflow package, registers it across core workflow/profile plumbing, documents its planning-artifact-only behavior, and updates tests to cover the new skill and command surfaces.

Changes

/opsx:update Workflow

Layer / File(s)	Summary
Change package and docs openspec/changes/add-update-workflow/*, docs/commands.md, docs/opsx.md, docs/supported-tools.md	Defines the new workflow package, update skill requirements, implementation tasks, and user-facing command/documentation updates.
Runtime workflow wiring src/core/*, openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md	Adds the update workflow and command to core profile sets, template generation, tool detection, and the new update-change template module.
Tests and command references test/**/*	Updates profile, generation, parity, config, and command-reference tests to expect the new workflow and skill directory.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• Fission-AI/OpenSpec#424: Adds earlier workflow skill-template support in the same template system extended here.
• Fission-AI/OpenSpec#442: Extends shared OPSX command-template infrastructure that this PR also updates.
• Fission-AI/OpenSpec#698: Introduces parity coverage patterns that this PR expands for the new update templates.

Suggested reviewers: TabishB

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the new /opsx:update planning-artifact workflow skill and matches the main change.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

This is the right shape for the proposal: graph impact and drift belong in deterministic CLI data, while the skill only does confirmed planning-artifact rewrites. Main implementation note is to ship this in layers, impact set first and digest-ledger audit second, so the stateful reconciliation piece does not block the core update workflow.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (6)

openspec/changes/add-update-workflow/design.md (2)

99-137: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify scheme version comparison in forward-compat design.

The data contracts specify that digests compare "only same-scheme" and that "unrecognized or older" schemes report unknown. However, the design doesn't define how "older" is determined — by exact string inequality, parsed version number, or some other ordering. For a deterministic system, explicit comparison rules matter:

Is the intent that only exact string matches are comparable, and any scheme tag that doesn't match the current one exactly is treated as unknown? Or is there a defined ordering (e.g., v1 < v2)?

Recommend stating explicitly: "Only digests with the exact same scheme tag as the current canonicalization are compared; any mismatch (including different version suffixes) is treated as unknown." This eliminates ambiguity and matches the deterministic philosophy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/design.md` around lines 99 - 137, The
forward-compat section in the data contracts leaves scheme comparison ambiguous,
especially around what “older” means. Update the `Digest scheme tag &
forward-compat` wording to explicitly define comparison rules for
`ArtifactStatus.digest`, `baselines.scheme`, and drift handling: only exact
scheme-tag matches against the current canonicalization are comparable, and any
mismatch or unrecognized tag must yield `unknown`. Keep the guidance aligned
with `reconcile` and the `drift`/`driftFrom` behavior so implementers have one
deterministic rule.

---

9-10: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep the update flow schema-driven
src/core/templates/workflows/continue-change.ts still hardcodes proposal → specs → design → tasks in both the skill and command templates, despite the guardrail to use the schema’s artifact sequence. Remove both copies so the new skill follows the CLI JSON ids/edges instead.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/design.md` around lines 9 - 10,
`continue-change.ts` still hardcodes the `proposal → specs → design → tasks`
workflow in both the skill and command template copies, which conflicts with the
guardrail to use the schema’s artifact sequence. Remove both duplicated prose
blocks and update the template logic so it reads artifact ids and edges from the
CLI JSON instead of assuming fixed names or ordering, keeping the behavior
aligned with the schema-driven workflow.

openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md (1)

92-111: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Clarify baseline recording behavior when the user rejects a revision.

The spec states that baseline is recorded "after the skill has applied and confirmed a revision" (line 109). Consider adding an explicit scenario for when the user rejects a proposed revision, to ensure implementers do not record a baseline for an unapplied edit:

+#### Scenario: Rejected revision does not record baseline
+
+- **WHEN** the user rejects a proposed revision for an artifact
+- **THEN** no baseline is recorded for that artifact
+- **AND** the artifact remains in its previous drift state

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md` around
lines 92 - 111, Add an explicit scenario under the User-Confirmed Incremental
Application requirement to cover rejection of a proposed revision: when the user
does not confirm the artifact change, the `/opsx:update` skill must not write
the change and must not record the drift baseline. Update the spec near the
existing Confirm before writing and Records the drift baseline after an applied
edit scenarios so implementers clearly distinguish confirmed/applied edits from
rejected proposals.

openspec/changes/add-update-workflow/specs/cli-artifact-workflow/spec.md (1)

18-64: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Define drift semantics for root artifacts with no upstream dependencies.

The spec does not specify how drift behaves for artifacts that have no direct upstreams (root artifacts in the dependency graph). With no upstreams to compare, drift is arguably always clean (nothing to drift against) or unknown (no meaningful baseline). Consider adding an explicit scenario:

+#### Scenario: Root artifact with no upstreams
+
+- **WHEN** an artifact has no direct upstream dependencies
+- **THEN** its drift status is `clean` (nothing to drift against)
+- **AND** recording a baseline stores an empty upstreams map

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/specs/cli-artifact-workflow/spec.md`
around lines 18 - 64, The drift semantics for root artifacts with no direct
upstream dependencies are undefined in the current spec, so add an explicit
scenario in the content-digest/drift section of cli-artifact-workflow/spec.md
covering this case. Update the Requirement or scenarios around openspec status
--json and baseline recording to state whether a root artifact with no upstreams
reports drift as clean or unknown, and ensure the wording aligns with the
existing drift states used by the status JSON model.

openspec/changes/add-update-workflow/specs/artifact-graph/spec.md (1)

22-45: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Clarify deterministic tie-breaking in diamond scenario.

The diamond scenario states "B and C before D" but does not specify an ordering between B and C. The downstream consumer (graph.ts:68-113) uses sorted queues for determinism. Consider adding explicit language that when multiple artifacts are ready simultaneously, they are ordered lexicographically by id (or by some other stable rule) to ensure cross-platform determinism.

 #### Scenario: Diamond downstream order
 
 - **WHEN** artifacts form a diamond (A → B, A → C, B → D, C → D) and getDownstream("A") is called
-- **THEN** the result includes B and C before D
+- **THEN** the result includes B and C before D
+- **AND** when B and C are both ready at the same step, they are ordered lexicographically by artifact id for determinism

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/specs/artifact-graph/spec.md` around
lines 22 - 45, Clarify the downstream ordering rule in the Transitive Downstream
Query spec so the diamond scenario is deterministic when B and C are both ready
before D. Update the requirement/scenario text in the artifact graph spec to
state the tie-breaker used by graph.ts’s getDownstream logic, such as
lexicographic ordering by artifact id, so the topological order is fully
specified across platforms.

openspec/changes/add-update-workflow/tasks.md (1)

17-24: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer symbol references over fragile line numbers in task cross-references.

Task 3.2 references src/cli/index.ts:488 as the registration point. Line numbers become stale quickly; prefer referencing by command registration symbol or pattern (e.g., status command registration in src/cli/index.ts) so the task remains valid after unrelated edits.

- (`src/commands/workflow/status.ts`, registered at `src/cli/index.ts:488`)
+ (`src/commands/workflow/status.ts`, registered alongside other workflow commands in `src/cli/index.ts`)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/tasks.md` around lines 17 - 24, Task 3.2
hard-codes a line number for the status command registration, which will drift
as the file changes. Update the task text to reference the `status` command
registration symbol/pattern in `src/cli/index.ts` (and `StatusOptions` /
`workflow status` for context) instead of a specific line, so the
cross-reference stays stable after unrelated edits.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openspec/changes/add-update-workflow/specs/artifact-graph/spec.md`:
- Around line 46-79: The missing-output digest rule is inconsistent with the CLI
spec, so update the Artifact Content Digest requirement and the Missing Output
scenario to use one explicit representation everywhere (either omit digest or
emit null) and mirror that same wording in the CLI spec. Also extend Artifact
Content Digest with a scheme/version prefix requirement so digests carry an
identifier such as a canonicalization version tag, making future hashing changes
detectable. Keep the wording aligned across the affected spec sections so
implementers have one unambiguous contract.

In `@openspec/changes/add-update-workflow/tasks.md`:
- Around line 25-33: Task 4.4 references the “Update vs. Start Fresh” heuristic,
but the heuristic is not defined anywhere in this scope. Add a clear reference
in the tasks to the canonical document or spec section that defines this
heuristic, or inline the formal rule in the `4.4 Encode the intent-change guard`
item so the `/opsx:update` guardrail can point to an exact source. Keep the
wording aligned with the surrounding `update-change.ts` /
`getOpsxUpdateCommandTemplate()` workflow guidance.

---

Nitpick comments:
In `@openspec/changes/add-update-workflow/design.md`:
- Around line 99-137: The forward-compat section in the data contracts leaves
scheme comparison ambiguous, especially around what “older” means. Update the
`Digest scheme tag & forward-compat` wording to explicitly define comparison
rules for `ArtifactStatus.digest`, `baselines.scheme`, and drift handling: only
exact scheme-tag matches against the current canonicalization are comparable,
and any mismatch or unrecognized tag must yield `unknown`. Keep the guidance
aligned with `reconcile` and the `drift`/`driftFrom` behavior so implementers
have one deterministic rule.
- Around line 9-10: `continue-change.ts` still hardcodes the `proposal → specs →
design → tasks` workflow in both the skill and command template copies, which
conflicts with the guardrail to use the schema’s artifact sequence. Remove both
duplicated prose blocks and update the template logic so it reads artifact ids
and edges from the CLI JSON instead of assuming fixed names or ordering, keeping
the behavior aligned with the schema-driven workflow.

In `@openspec/changes/add-update-workflow/specs/artifact-graph/spec.md`:
- Around line 22-45: Clarify the downstream ordering rule in the Transitive
Downstream Query spec so the diamond scenario is deterministic when B and C are
both ready before D. Update the requirement/scenario text in the artifact graph
spec to state the tie-breaker used by graph.ts’s getDownstream logic, such as
lexicographic ordering by artifact id, so the topological order is fully
specified across platforms.

In `@openspec/changes/add-update-workflow/specs/cli-artifact-workflow/spec.md`:
- Around line 18-64: The drift semantics for root artifacts with no direct
upstream dependencies are undefined in the current spec, so add an explicit
scenario in the content-digest/drift section of cli-artifact-workflow/spec.md
covering this case. Update the Requirement or scenarios around openspec status
--json and baseline recording to state whether a root artifact with no upstreams
reports drift as clean or unknown, and ensure the wording aligns with the
existing drift states used by the status JSON model.

In `@openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md`:
- Around line 92-111: Add an explicit scenario under the User-Confirmed
Incremental Application requirement to cover rejection of a proposed revision:
when the user does not confirm the artifact change, the `/opsx:update` skill
must not write the change and must not record the drift baseline. Update the
spec near the existing Confirm before writing and Records the drift baseline
after an applied edit scenarios so implementers clearly distinguish
confirmed/applied edits from rejected proposals.

In `@openspec/changes/add-update-workflow/tasks.md`:
- Around line 17-24: Task 3.2 hard-codes a line number for the status command
registration, which will drift as the file changes. Update the task text to
reference the `status` command registration symbol/pattern in `src/cli/index.ts`
(and `StatusOptions` / `workflow status` for context) instead of a specific
line, so the cross-reference stays stable after unrelated edits.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1d39db6b-11f6-42b7-9ffe-74007d8814fc

📥 Commits

Reviewing files that changed from the base of the PR and between 546224e and ae743a4.

📒 Files selected for processing (7)

• openspec/changes/add-update-workflow/.openspec.yaml
• openspec/changes/add-update-workflow/design.md
• openspec/changes/add-update-workflow/proposal.md
• openspec/changes/add-update-workflow/specs/artifact-graph/spec.md
• openspec/changes/add-update-workflow/specs/cli-artifact-workflow/spec.md
• openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md
• openspec/changes/add-update-workflow/tasks.md

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Align missing-output digest representation with CLI spec.

The artifact-graph spec says "no digest is reported" (line 78) while the CLI spec allows "omits digest (or reports it as null)" (line 35). Choose one representation and apply it consistently across both specs to avoid implementation ambiguity.

Additionally, the tasks.md (2.1) mentions digest scheme prefixes (e.g., sha256-relpath-v1:) for forward-compatibility, but this requirement does not mention scheme tags. Consider adding a requirement that digests include a scheme/version prefix so that future canonicalization changes are detectable rather than silently mis-compared.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/specs/artifact-graph/spec.md` around
lines 46 - 79, The missing-output digest rule is inconsistent with the CLI spec,
so update the Artifact Content Digest requirement and the Missing Output
scenario to use one explicit representation everywhere (either omit digest or
emit null) and mirror that same wording in the CLI spec. Also extend Artifact
Content Digest with a scheme/version prefix requirement so digests carry an
identifier such as a canonicalization version tag, making future hashing changes
detectable. Keep the wording aligned across the affected spec sections so
implementers have one unambiguous contract.

[TabishB]

This is looking decent, few comments below. I think the main thing to check here is if we're doing too much and if there's a simpler approach?

Could we for example just make it work by using the existing status command?

Coding agents tend to over-complicate things and are not very good at understanding agentic workflows, particularly skills.

I'd maybe see if this proposal can be simplified and what's actually needed to delivery the feature. - Maybe a good way to do this is to work backwards here, by thinking of what should go into the update skills file - whats the minimal instructions sets (both in terms of amount of tokens + commands the agent has to run). If you had to manually write the update skill what would be in there?

[TabishB]

What exactly would reconcile cmd do here? My preference for this is the agent can get back the current status of the change to figure out what else to be updated.

I wouldn't make it too complex to begin with.
The skill should mainly be something along the lines of:

• Understand the user request
• Run command to get status of what artifacts exist:
• Go and read those artifacts to check and see if anything else needs to get updated

^ A bit generalised but should be mainly this. In general we want to try and introduce as a little code as possible -> Only when there's a defined need for it

[clay-good]

Addressed in the b2f8639 rework: the reconcile op (and the digest/ledger machinery behind it) is gone entirely. The skill now does exactly the loop you describe — understand the request, openspec status --change <id> --json for what exists and where, read those artifacts, propose what else needs updating. Zero new commands.

[TabishB]

hmm I wonder how this would work. I'm not sure if downstream only is right approach here.

for example, this is the current technical graph

proposal -> specs -> design -> tasks

If design is updated there's a possibility that the proposal needs to change too

[clay-good]

You were right — addressed in b2f8639. Coherence is now explicitly bidirectional: the proposal calls out that editing design can require revising proposal, the spec has an "upstream artifact may be revised" scenario, and design Decision 1 rejects a downstream-only --impact primitive precisely because it encodes the wrong model.

[clay-good]

Thanks @TabishB — you were right, it was doing too much. I reworked it to do exactly what you described and pushed (b2f8639): work off the existing status command, introduce as little code as possible.

Net result: −476 / +161 lines. The whole feature is now one thin skill.

Simpler approach using the existing status command. openspec status --change <id> --json already returns the artifact set, each artifact's status, and resolved paths (via artifactPaths). That's everything the skill needs. So I cut the entire deterministic spine — the reverse-dependency graph API, content digests, the .openspec.yaml baseline ledger, openspec reconcile, the drift report, and status --impact. The artifact-graph and cli-artifact-workflow spec deltas are deleted. v1 adds no new CLI/graph/schema code — just the skill template + wiring.

"What would reconcile do?" Gone. The skill does what you sketched: understand the request → run status to see what artifacts exist → read them → update what else needs updating, with the user confirming each edit.

Working backwards from the skill file. design.md now has a section — "The skill, written by hand" — with the literal minimal instruction body (resolve change → status → read → reconcile → confirm). Few tokens, few commands. That's the part I'd most value your eyes on.

Downstream-only was wrong. Agreed — if design changes, proposal may need to change too. There's now a Bidirectional Coherence Review requirement: the skill reconciles related artifacts in any direction, with an explicit scenario for revising an upstream artifact. That's also why I didn't add a one-directional getDownstream/--impact primitive — it would bake in the wrong model.

Guardrails kept: planning artifacts only (never code; hands off to /opsx:apply), schema-driven (reads ids/paths from status, no hardcoded proposal/specs/design/tasks), confirm each edit, intent-change → /opsx:new.

If a deterministic staleness signal is ever genuinely needed, the smallest first step is exposing the schema's requires edges on status --json (one additive field, no new command) — noted as out of scope until there's a defined need. Validates clean under openspec validate add-update-workflow --strict.

[coderabbitai]

🧹 Nitpick comments (1)

openspec/changes/add-update-workflow/design.md (1)

30-63: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add language specifier to fenced code block.

The skill body code block lacks a language specifier, triggering markdownlint MD040. Use text or markdown if no syntax highlighting is desired.

-```
+```text

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/add-update-workflow/design.md` around lines 30 - 63, The
fenced code block in the skill body is missing a language specifier, causing the
markdown lint warning. Update the affected fenced block in the design artifact
to include an explicit specifier such as text or markdown, and keep the
surrounding content unchanged so the planning guidance remains coherent.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@openspec/changes/add-update-workflow/design.md`:
- Around line 30-63: The fenced code block in the skill body is missing a
language specifier, causing the markdown lint warning. Update the affected
fenced block in the design artifact to include an explicit specifier such as
text or markdown, and keep the surrounding content unchanged so the planning
guidance remains coherent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e058237e-6ae9-4037-a9fa-66fb044f419a

📥 Commits

Reviewing files that changed from the base of the PR and between ae743a4 and b2f8639.

📒 Files selected for processing (4)

• openspec/changes/add-update-workflow/design.md
• openspec/changes/add-update-workflow/proposal.md
• openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md
• openspec/changes/add-update-workflow/tasks.md

✅ Files skipped from review due to trivial changes (1)

• openspec/changes/add-update-workflow/tasks.md

[alfred-openspec]

Thanks for the simplification. This is much closer to the right shape, but I found one blocker before approving: the proposal now depends on openspec status --change <id> --json returning artifactPaths / resolved paths, and current status --json does not include that field. I checked the PR checkout with openspec status --change add-update-workflow --json; it returns changeName, schemaName, isComplete, applyRequires, and artifacts[] with id, outputPath, status only.

That breaks the core premise that v1 can be implemented with no CLI/status changes while still writing only to resolved artifact paths, especially for glob artifacts like specs/**/*.md. Please either scope the minimal additive status field needed for resolved/existing paths, or update the skill design to resolve paths through an existing command that actually returns them. After that, I think the thin-skill direction is approvable.

[clay-good]

Thanks — you're right that the write target needed pinning down, and I've made it explicit. One clarification on the field itself, then what I changed.

status --change <id> --json does already return resolved/existing paths, but in a top-level artifactPaths map, separate from the artifacts[] array. artifacts[] carries id/outputPath/status (the fields you saw); artifactPaths.<id> carries outputPath, resolvedOutputPath, and existingOutputPaths. It's in formatChangeStatus (src/core/artifact-graph/instruction-loader.ts), landed in #1089, so it's on main. On this change, artifactPaths.specs.existingOutputPaths resolves the specs/**/*.md glob to the concrete specs/opsx-update-skill/spec.md. (If you openspec status an older globally-installed build you'd only see artifacts[] — worth a node dist/cli/index.js status … from the checkout to compare.)

That said, you pointed at a real bug in how I described it: resolvedOutputPath for a glob artifact comes back as .../specs/**/*.md — still a glob, not a file. My draft said "resolved paths" without distinguishing the two, which is a foot-gun. Fixed in 28a0af5:

• The skill now edits existingOutputPaths (concrete, glob-expanded) and explicitly never writes to a glob resolvedOutputPath — stated in proposal step 2, design Context + Decision 2 + the skill body, and the spec.
• Added two scenarios: "Edit the concrete files of a glob artifact" and "A new file under a glob artifact is deferred to /opsx:continue" (so the skill never invents a path from a glob), plus a template test asserting the write target.

Net: no new CLI field needed — the data's already there — and the write contract is now unambiguous for globs. Validates clean under --strict.

[TabishB]

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?

[clay-good]

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:continue if artifacts are missing, /opsx:apply when the change was already implemented (the code may no longer match the revised plan), /opsx:archive when everything is done. Guidance only — it never implements, mirroring the hand-off continue-change.ts already uses. Spec'd as a new "Next-Step Guidance" requirement with an "updating an already-implemented change" scenario, plus a template test (3.5).

[TabishB]

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?

[clay-good]

Agreed, default happy path seems easiest for users.

[clay-good]

Encoded in be92e8a: update goes into ALL_WORKFLOWS and the default core profile in src/core/profiles.ts (proposal Impact + task 1.4, with a profiles test in 3.6), so /opsx:update is part of the default install.

[TabishB]

I'm wondering if we need to be more careful about the skill naming. "Update" might be too generic. I'm thinking about this in two dimensions. Generally, we want very specific skill names.

We also need to consider how this works with future projects. Is the "update" command only related to changes, or can it be applied to any graph? I'm leaning towards making it specific to change proposals for now, and then we can generalize it later.

[clay-good]

Agreed on keeping it specific — pinned in be92e8a (design, Naming). Resolution:

• Scope: change proposals only for v1. "Updating anything other than a change's planning artifacts" is now an explicit non-goal; a future graph type would get its own specific skill then, nothing here blocks that.
• Skill name: openspec-update-change — change-scoped, following the openspec-<verb>-change convention of its siblings (openspec-continue-change, openspec-new-change, …).
• Command: kept /opsx:update because every verb in the /opsx: family already operates on a change (continue, apply, archive — none says -change), so the namespace carries the scope. Happy to rename to /opsx:update-change if you'd rather the command itself say it — one-line change.

[TabishB]

Unrelated, but try and follow the conventional commit standard for PR titles where possible!

[TabishB]

Looks good. Let me know if you want to do the implementation as part of this PR or another PR. Either is fine.

[clay-good]

Looks good. Let me know if you want to do the implementation as part of this PR or another PR. Either is fine.

Thank you, I'll build out in this same PR next.

[clay-good]

Thanks @TabishB! Went with implementation in this PR — f5ed1bb builds out the approved plan: the update-change.ts template, registration across init/profiles/generation surfaces, update in the default core profile, docs, tests (template guardrails + regenerated parity hashes), and retirement of the superseded add-artifact-regeneration-support stub. PR body updated with the details and verification. Ready for a final look.

[clay-good]

Branch is now current with main (merged 65a7233 — website deployment — and a325305 — resolution convergence; no conflicts, full suite green locally, validate --strict passes).

@alfred-openspec your CHANGES_REQUESTED (2026-07-01) is now stale on two counts: (1) the factual blocker was resolved on-thread — status --change <id> --json does return resolved paths via the top-level artifactPaths map (resolvedOutputPath + existingOutputPaths), verified live at the PR base and pinned into the spec in 28a0af5; (2) the skill is now implemented (f5ed1bb) and writes exclusively to existingOutputPaths, with a template test enforcing it. Could you re-review (or a maintainer dismiss) so the merge unblocks?

[alfred-openspec]

Re-reviewed the current branch. My earlier changes-requested review is stale: this now uses the existing top-level artifactPaths contract from status --json, edits only existingOutputPaths, and has tests pinning the no-glob-write / no-frontier-advance guardrails. I also verified the PR checkout with focused template/profile/update tests, validate add-update-workflow --strict, and a live status --json check showing concrete existingOutputPaths for the specs glob. Looks good to merge.