openspec-patcher 0.1.0

Apply versioned line patches to OpenSpec skills

openspec-patcher

osp applies versioned, line-based patches to OpenSpec skills without maintaining an OpenSpec fork.

osp install <patch.json>
osp [patch-id]
osp status
osp list
osp restore [patch-id] [-f]

Installed patches are stored per user. A patched project receives an openspec.patch manifest containing immutable skill baselines, active patch references, and rendered hashes.

Patch positions always refer to the original skill content. Every apply or restore rerenders all active patches from that baseline.

Patch Format

{
  "schemaVersion": 1,
  "id": "zh-cn-output",
  "name": "Simplified Chinese output",
  "operations": {
    "1.4.0-1.4.3,1.5.0": [
      {
        "content": "replacement text",
        "positions": [
          {
            "tool": "opencode",
            "skill": "openspec-apply-change",
            "startLine": 12,
            "endLine": 12
          }
        ]
      }
    ]
  }
}

Version selectors accept MAJOR.MINOR.PATCH and inclusive from-to ranges separated by commas. Different selector keys in one patch must not overlap. Every position is resolved through src/openspec_patcher/resources/paths.json; positions for unavailable tools are skipped.

Storage and Recovery

On Windows, installed patches are stored in %LOCALAPPDATA%\openspec-patcher\patches. Linux uses $XDG_DATA_HOME/openspec-patcher/patches (or ~/.local/share), and macOS uses ~/Library/Application Support/openspec-patcher/patches. Set OSP_DATA_DIR to override the location, which is useful for isolated testing.

The project-level openspec.patch stores only active patch IDs and SHA-256 values. The matching patch documents must remain available locally to rerender any patch that stays active. osp restore -f ignores changed current skill hashes and rebuilds from the saved original content; it can overwrite manual skill edits.