OpenSpec Apply Resume
$opsx-apply-resume is the explicit handoff capability behind
/dhpk:opsx-apply-resume. It snapshots enough live state to cross a context
boundary and restores it later; the live worktree remains the source of truth.
$SKILL_DIR denotes the physical directory containing the selected SKILL.md;
it is path notation, not an ambient environment variable or repository-root
lookup. Resolve it once before invoking a package-local helper and keep the
consumer's current working directory unchanged.
When to Use
- An explicit invocation requests Save while a long-running apply session is
approaching its context limit.
- An explicit invocation requests Resume after a context/session boundary.
- A previous handoff is in
saved or consuming state and needs recovery.
When NOT to Use
- Creating, designing, verifying, or archiving an OpenSpec change.
- Replacing the external
openspec-apply-change Skill or modifying its files.
- Reverting, deleting, or stashing uncommitted work to make a handoff look
clean.
Host and package resolution
- Use one Host-neutral handoff path on every Host:
.scratch/<change-id>/apply-resume.md; do not add a public host flag. On
resume, when that file is absent, read the legacy
.claude/artifacts/apply-resume/latest.md, then
.dhpk/artifacts/apply-resume/latest.md. Without a change ID, resume
selects the single .scratch/*/apply-resume.md in saved or consuming
state (archived consumed-*.md files are ignored); when none exists it
tries the two legacy files, else asks.
- Resolve the handoff path once and pass it explicitly to every package-local
helper and context loader. Resolve helper executors from
"$SKILL_DIR/scripts/"; helpers must never rediscover a path from their
current directory or a parent/peer Skill. A missing
helper/reference is BLOCKED_RESOURCE_MISSING. The helpers' built-in default path is a legacy fallback for direct manual use only; this Skill always passes the resolved path.
- Load only Save or Resume
after phase detection. Keep optional providers undisclosed until their
branch is selected.
Workflow
- Interpret the requested task: saving current apply progress selects Save;
restoring saved progress selects Resume. Optional
save and resume
words express the same tasks. With only a change ID, detect the phase.
Parse an optional change-id; priority is argument, latest visible apply
invocation, then the Host's native selection prompt. If no change can be
selected, stop BLOCKED.
- Run the package-local phase detector with the explicit handoff path. Honor
the requested phase after checking existing state: a recent save is a
confirmation boundary;
consuming is a recovery boundary.
- Follow exactly one phase reference. Save writes a new handoff file; Resume
loads it, validates the change, and archives it only after successful
continuation.
- Keep optional commit, precommit, compact, and memory providers visibly
optional. Their absence or failure never erases live files or invalidates a
handoff summary.
- Hand successful continuation to the available canonical
openspec-apply-change Skill. Claude may use native Skill dispatch; Codex
invokes the available projected skill directly. If it is unavailable,
report UNAVAILABLE and keep the handoff recoverable; never edit the
external skill or substitute /opsx:apply as a Skill ID.
Host boundary
Claude may recommend /fork, /new, and /model in its save report. Codex
does not require or emit those Claude commands: its report names the next
session/turn and optional model metadata without changing models. Both Hosts
must preserve the same handoff frontmatter, phase states, optional-provider
semantics, and live-worktree rule.
Output
Return:
Phase → Save | Resume → explicit handoff path → change-id
State → saved | consuming | consumed | BLOCKED | UNAVAILABLE | NOT_RUN
Evidence → commit/precommit/compact/memory/provider details
Next action → one recoverable Host-appropriate continuation
Include commit: SKIPPED when no explicit commit was requested; it is valid
evidence, not a failure. A failed apply leaves the handoff in consuming
state for manual recovery. Redact observation content, credentials, and
private paths beyond the declared artifact path.
Verification
References
- references/save.md — snapshot, optional gates, and
handoff write contract.
- references/resume.md — load, context fallback,
consuming state, external continuation, and archive contract.
1---2name: opsx-apply-resume3argument-hint: '[<save-or-resume-task>] [<change-id>]'4description: 'Save and resume a long-running OpenSpec apply session from a live worktree, preserving optional gates and host-specific handoff artifacts. Not for: starting a new proposal, changing the external OpenSpec workflow, or treating a commit as a prerequisite. Output: a saved/resumed handoff report with lifecycle and next-action evidence.'5disable-model-invocation: true6metadata:7 source: https://skillmd.com/skills/hmj1026/opsx-apply-resume8 dhpk-capability-id: dhpk.skill.opsx-apply-resume9 dhpk-name-style: portable-skill10 dhpk-invocation-class: explicit-only11 dhpk-next:12 PASS: none13 FAIL: none14 BLOCKED: none15 NOT_RUN: none16 UNAVAILABLE: none17---1819# OpenSpec Apply Resume2021`$opsx-apply-resume` is the explicit handoff capability behind22`/dhpk:opsx-apply-resume`. It snapshots enough live state to cross a context23boundary and restores it later; the live worktree remains the source of truth.24`$SKILL_DIR` denotes the physical directory containing the selected `SKILL.md`;25it is path notation, not an ambient environment variable or repository-root26lookup. Resolve it once before invoking a package-local helper and keep the27consumer's current working directory unchanged.2829## When to Use3031- An explicit invocation requests Save while a long-running apply session is32 approaching its context limit.33- An explicit invocation requests Resume after a context/session boundary.34- A previous handoff is in `saved` or `consuming` state and needs recovery.3536## When NOT to Use3738- Creating, designing, verifying, or archiving an OpenSpec change.39- Replacing the external `openspec-apply-change` Skill or modifying its files.40- Reverting, deleting, or stashing uncommitted work to make a handoff look41 clean.4243## Host and package resolution44451. Use one Host-neutral handoff path on every Host:46 `.scratch/<change-id>/apply-resume.md`; do not add a public host flag. On47 resume, when that file is absent, read the legacy48 `.claude/artifacts/apply-resume/latest.md`, then49 `.dhpk/artifacts/apply-resume/latest.md`. Without a change ID, resume50 selects the single `.scratch/*/apply-resume.md` in `saved` or `consuming`51 state (archived `consumed-*.md` files are ignored); when none exists it52 tries the two legacy files, else asks.532. Resolve the handoff path once and pass it explicitly to every package-local54 helper and context loader. Resolve helper executors from55 `"$SKILL_DIR/scripts/"`; helpers must never rediscover a path from their56 current directory or a parent/peer Skill. A missing57 helper/reference is `BLOCKED_RESOURCE_MISSING`. The helpers' built-in default path is a legacy fallback for direct manual use only; this Skill always passes the resolved path.583. Load only [Save](references/save.md) or [Resume](references/resume.md)59 after phase detection. Keep optional providers undisclosed until their60 branch is selected.6162## Workflow63641. Interpret the requested task: saving current apply progress selects Save;65 restoring saved progress selects Resume. Optional `save` and `resume`66 words express the same tasks. With only a change ID, detect the phase.67 Parse an optional `change-id`; priority is argument, latest visible apply68 invocation, then the Host's native selection prompt. If no change can be69 selected, stop `BLOCKED`.702. Run the package-local phase detector with the explicit handoff path. Honor71 the requested phase after checking existing state: a recent save is a72 confirmation boundary; `consuming` is a recovery boundary.733. Follow exactly one phase reference. Save writes a new handoff file; Resume74 loads it, validates the change, and archives it only after successful75 continuation.764. Keep optional commit, precommit, compact, and memory providers visibly77 optional. Their absence or failure never erases live files or invalidates a78 handoff summary.795. Hand successful continuation to the available canonical80 `openspec-apply-change` Skill. Claude may use native Skill dispatch; Codex81 invokes the available projected skill directly. If it is unavailable,82 report `UNAVAILABLE` and keep the handoff recoverable; never edit the83 external skill or substitute `/opsx:apply` as a Skill ID.8485## Host boundary8687Claude may recommend `/fork`, `/new`, and `/model` in its save report. Codex88does not require or emit those Claude commands: its report names the next89session/turn and optional model metadata without changing models. Both Hosts90must preserve the same handoff frontmatter, phase states, optional-provider91semantics, and live-worktree rule.9293## Output9495Return:9697```text98Phase → Save | Resume → explicit handoff path → change-id99State → saved | consuming | consumed | BLOCKED | UNAVAILABLE | NOT_RUN100Evidence → commit/precommit/compact/memory/provider details101Next action → one recoverable Host-appropriate continuation102```103104Include `commit: SKIPPED` when no explicit commit was requested; it is valid105evidence, not a failure. A failed apply leaves the handoff in `consuming`106state for manual recovery. Redact observation content, credentials, and107private paths beyond the declared artifact path.108109## Verification110111- [ ] Host path and explicit handoff path were resolved before helper calls.112- [ ] Exactly one phase ran and its state transition is recorded.113- [ ] Live worktree truth and uncommitted files were preserved.114- [ ] Optional provider states are distinct from required apply evidence.115- [ ] External OpenSpec continuation used an available canonical skill only;116 no external skill or alias was modified.117- [ ] The terminal state and one next action are explicit.118119## References120121- [references/save.md](references/save.md) — snapshot, optional gates, and122 handoff write contract.123- [references/resume.md](references/resume.md) — load, context fallback,124 consuming state, external continuation, and archive contract.