@firstpick/pi-skill-patch-md

Agents should invoke this skill to create, update, or implement standardized PATCH.md documents that describe reproducible source code patches.

Packages

Package details

extensionskill

Install @firstpick/pi-skill-patch-md from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@firstpick/pi-skill-patch-md

Package: @firstpick/pi-skill-patch-md
Version: 0.1.3
Published: Jul 18, 2026
Downloads: 68/mo · 17/wk
Author: firstpick
License: MIT
Types: extension, skill
Size: 64.2 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@firstpick/pi-skill-patch-md

A Pi skill and local runner for versioned patch lifecycle packages.

Lifecycle

PATCHCTL=skills/patch-md/scripts/patchctl.mjs
node "$PATCHCTL" status   --patch /path/to/PATCH.md
node "$PATCHCTL" plan     --patch /path/to/PATCH.md
node "$PATCHCTL" apply    --patch /path/to/PATCH.md --plan-hash <reviewed-hash>
node "$PATCHCTL" verify   --patch /path/to/PATCH.md
node "$PATCHCTL" rollback --patch /path/to/PATCH.md --confirm

Schema v2 adds:

a machine-readable patch.manifest.json;
deterministic plan hashes;
runtime/package discovery;
semantic fingerprints and fail-closed version handling;
idempotent, transactional application;
offline verification and receipt-based rollback.

Legacy prose-only documents may be read with patch_md_extract.mjs --no-strict for migration, but cannot be trusted for apply.

Native approval dialog

The package also registers the patch_apply_with_approval tool. After an agent reviews a fresh patchctl plan, it can call this tool with the PATCH.md path and exact plan hash.

The tool:

recomputes the plan and rejects stale or blocked hashes;
displays a native Pi confirmation dialog in TUI or WebUI RPC mode with the patch, targets, writes, risks, and exact hash;
refuses to apply without interactive confirmation;
invokes patchctl apply directly with argument vectors, never shell interpolation;
relies on patchctl to recompute the plan again immediately before transactional mutation.

Selecting Yes applies only that exact reviewed plan. Selecting No, Cancel, closing the dialog, or running without an interactive UI changes nothing. The tool does not install packages or run live-provider verification.

Install

pi install npm:@firstpick/pi-skill-patch-md

Test

npm test