Index of every page on this site: llms.txt
All skills
fission-ai avatar

/openspec-update-change

@a0993e9
by Fissionfission-ai/openspec75k stars
5,157
Run it yourself

Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Also use when the user says "openspec update change" or "opsx update". If the user means the openspec update CLI command, which refreshes generated files, run that command instead. Never edits code.

Use this Skill: https://skilld.dev/gh/fission-ai/openspec/openspec-update-change

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈114 tokens for metadata: the name and description. ≈2.7k when used: this file.

Description uses 5.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈458 characters, or 5.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Revise a change's existing planning artifacts and keep them coherent. Never edit code.

Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Once selected, treat --store <id> as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run openspec status --change "<name>" --json --store "<id>", not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.

Project check: These steps expect a project that already uses OpenSpec. Before the first step that writes anything (new change, archive, sync specs, or authoring an artifact file), confirm the project has a root: run openspec list --json (with --store <id> when a store is selected, since the store is then the root) and read root. A root object means the project is set up. "root": null means it is not - there is no openspec/ directory here, and a write such as openspec new change would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.

One "root": null is not about setup: when a status error message starts with Declared in or Invalid store declaration in and names this project's openspec/config.yaml (or config.yml), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the store: line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's message and fix.

Otherwise, with no root, what happens next depends on how this workflow was reached:

  • Auto-selected: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or invoking this skill by name. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
  • Explicit OpenSpec request: the user named OpenSpec, named this skill, or invoked this skill by name. Stop before writing and ask how to proceed: set this project up (openspec init), target a store they already have (--store <id>), or continue without OpenSpec for this request. Wait for their answer.

In both branches, never create the root as a side effect: do not run openspec init until the user asks for it, do not hand-create openspec/ files, and do not let a command create it.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Revise existing artifacts. If an artifact is missing, identify it and show the next ready artifact from openspec status --change "<name>" --json.

Steps

  1. Select the change

    If a name is provided, use it. Otherwise:

    • Infer from conversation context if the user mentioned a change
    • Auto-select if only one active change exists
    • If ambiguous, run openspec list --json to get available changes sorted by most recently modified, and ask the user to select one

    When prompting, present the top 3-4 most recently modified changes as options, showing:

    • Change name
    • Status (e.g., "0/5 tasks", "complete", "no tasks")
    • How recently it was modified (from lastModified field)

    Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.

    Always announce: "Using change: <name>" and how to override (e.g., openspec-update-change <other>).

  2. Get the change's artifacts

    openspec status --change "<name>" --json

    Parse the JSON to understand current state. The response includes:

    • schemaName: The workflow schema being used (e.g., "spec-driven")
    • artifacts: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
    • isPlanningComplete: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as isComplete.
    • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context. Use these instead of assuming repo-local paths.

    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.

    The files to edit are artifactPaths.<id>.existingOutputPaths - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. specs/**/*.md), plus any confirmed concrete path allowed under a partly populated glob artifact (step 4). 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 asked for a specific revision ("the design now uses X"), that is the starting edit.
    • If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
  4. Read and reconcile

    • Read the artifact(s) the request touches and the change's other existing artifacts.
    • Draft the requested edit in the conversation, not in files. Work out exactly what it changes; step 5 owns every write. Then check every other existing artifact against the drafted edit - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
    • Note everything that is now inconsistent, missing, or contradictory.
    • Propose revisions to files that already exist (existingOutputPaths). If an artifact has no existing output files and status ready or blocked, note it and show how to create the next ready artifact with openspec instructions "<artifact-id>" --change "<name>" --json. Leave skipped artifacts untouched; do not treat them as missing or defer them to the continue workflow.
    • A glob artifact (e.g. specs/**/*.md) is marked done after at least one file matches, and the continue workflow only handles ready artifacts. When reconciliation identifies a missing file for a glob artifact whose existingOutputPaths is non-empty:
      1. Run openspec instructions "<artifact-id>" --change "<name>" --json and use its instruction and template. Treat context and rules as constraints; do not copy them into the file. If instructions report skipped: true, do not create the file. Read current dependency files from disk; if a required non-skipped dependency is missing, stop and ask the user to restore it first.
      2. Choose a concrete path inside changeRoot that matches artifactPaths.<id>.outputPath and does not already exist. Verify it remains inside changeRoot after resolving any symlinked parent directories. The glob resolvedOutputPath is not a valid target.
      3. Include the new file in step 5's proposed revisions and create it only after the user confirms.
      4. After confirmation, immediately before creation, refresh status and instructions. Verify the artifact is still in scope, not skipped, and partially populated; repeat the concrete-path checks above.
      5. Use a create operation that fails if the target already exists. If instruction delegates creation to another skill or command, invoke it only if it can honor the confirmed path and these guardrails; otherwise stop. If any check fails or the confirmed draft is no longer valid, stop and reconcile with the user rather than replacing existing content or choosing a different path.
    • If the change is already coherent, say so and propose no revisions.
  5. Confirm and apply, one artifact at a time

    • This step performs every artifact write in this workflow; no earlier step edits an artifact.
    • Show each proposed revision and why - including the requested edit drafted in step 4. Write only after the user confirms.
    • If the user rejects a revision, do not write it - leave that artifact unchanged.
    • When a substantial rewrite is needed, get that artifact's rules and template first:
      openspec instructions "<artifact-id>" --change "<name>" --json
  6. Point to the next step (guidance only - NEVER act on it)

    • Artifacts with empty existingOutputPaths and status ready or blocked -> give the CLI command for the next ready artifact.
    • Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; tell the user which implementation tasks need revisiting.
    • Everything done and implemented -> suggest archiving with openspec archive "<name>".

Output

After each invocation, show:

  • Which artifacts were revised (and which proposed revisions were rejected)
  • Any file created under a glob artifact that was already partially populated
  • Missing artifacts deferred to a separate step (ready or blocked, excluding skipped artifacts)
  • Where the change stands and the recommended next skill

Guardrails

  • Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop after revising the plan and identify any code changes it calls for.
  • Use the artifact ids and paths reported by openspec status; never branch on hardcoded artifact names.
  • Edit only the concrete files in existingOutputPaths, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob resolvedOutputPath.
  • Do not advance the build frontier: if an artifact has empty existingOutputPaths and status ready or blocked, create missing artifacts in a separate step. Leave skipped artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose existingOutputPaths is non-empty.
  • Confirm every edit with the user before writing.
  • If the request changes the change's intent rather than refining it, ask for a distinct unused name and recommend openspec new change "<new-change-name>".

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3d3 checks · Risk SAFE
  • Gen Agent Trust Hub4d

    The skill is a specialized tool for managing OpenSpec planning artifacts. It operates within a restricted execution environment, only using a specific command-line tool, and includes strong safety guardrails such as requiring user confirmation for all changes and strictly prohibiting modifications to source code.

  • Socket3d

    No alerts

  • Snyk4d

    Risk: LOW · No issues

Signed by skilld at a0993e9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago
What it can do
Runs commands
compatibility
Requires openspec CLI.
metadata
{
  "author": "openspec",
  "version": "1.0"
}
All 1 allowed tools
Bash(openspec:*)

README badge

README badge for fission-ai/openspec/openspec-update-change