Patch MD Skill
When to Use
Use this skill to:
- create or update a patch package;
- migrate a legacy prose-only
PATCH.md to schema v2;
- inspect patch status after package updates;
- plan, apply, verify, or roll back a patch;
- reapply a patch across machines or package layouts.
Required v2 Artifact
A trusted patch package contains:
PATCH.md
patch.manifest.json
scripts/<lifecycle-handler>.mjs
Tests and fixtures are required for package-version or layout-dependent patches.
PATCH.md explains intent, scope, transformations, verification, rollback, and limitations.
patch.manifest.json is the machine-readable source of truth.
- The lifecycle handler discovers actual runtimes and implements semantic, idempotent transformations.
Use PATCH-TEMPLATE.md, TOOL-CALL-SPEC.md, and patch-manifest-v2.schema.json.
App-specific package location
For an app-specific patch, the app's verified configuration/home directory is the canonical package location, normally <app-config>/patches/<patch-id>/.
- Resolve the actual config/home from the app's documented runtime settings, launch options, or verified environment overrides before assuming a default. Ask when the location cannot be established safely.
- Save the complete reconstructable package there:
PATCH.md, manifest, lifecycle handlers, transformation profiles/assets, documentation, and required tests/fixtures. Do not deliver only a note that depends on a checkout, temporary capture, or versioned app-install directory.
- A repository may retain a development mirror, but report the app-config package as the canonical artifact. Keep runtime assets package-relative and verify the copied package independently.
- For T3 Code, use its resolved T3 home (
T3CODE_HOME when configured, otherwise the verified ~/.t3 default), for example ~/.t3/patches/<patch-id>/. Keep patch artifacts outside live userdata; storing a patch never authorizes editing app settings or runtime state.
- Do not silently move existing patches, receipts, or backups. Preserve their explicit state directory for rollback, and use
--state-dir when a separately chosen config-local state directory is intended.
- Patch storage is not patch application. After an app update, run fresh read-only status/plan and obtain plan-bound approval before any installed mutation; never silently reapply.
Lifecycle Commands
Resolve paths relative to this skill directory:
node ./scripts/patch_md_extract.mjs --patch /path/to/PATCH.md --strict
node ./scripts/patchctl.mjs status --patch /path/to/PATCH.md
node ./scripts/patchctl.mjs plan --patch /path/to/PATCH.md
node ./scripts/patchctl.mjs apply --patch /path/to/PATCH.md --plan-hash <reviewed-hash>
node ./scripts/patchctl.mjs verify --patch /path/to/PATCH.md
node ./scripts/patchctl.mjs rollback --patch /path/to/PATCH.md --confirm
Workflow
Choose the lifecycle mode below from the user's request and current patch state. Always enter through strict extraction, use read-only status/plan before mutation, and finish with verification or an explicit blocker report.
Mode A — Create or Migrate
- Discover actual runtime entrypoints, package dependency graphs, and the verified app-config package destination when the target is an app.
- Define stable logical targets instead of user-specific absolute paths.
- Add package support ranges and semantic fingerprints.
- Implement three-way status: applicable, already-applied/upstreamed, or unsupported.
- Add idempotent transformation and postconditions.
- Add offline verification, receipt-based rollback, fixtures, and tests.
- Parse with strict mode and run the package test suite.
Legacy --no-strict parsing is allowed only to extract facts for migration. Never apply from legacy parser output.
Mode B — Status and Plan
- Run strict extraction; stop if
ok=false.
- Run
patchctl status.
- Run
patchctl plan and review every required target, package version, path, before-hash, transformation, and risk.
- Do not proceed when a required target is unsupported or the plan reports drift.
Status and plan must be read-only.
Mode C — Apply
- Obtain explicit user approval for installed/global package mutation when not already requested.
- Apply only with the exact fresh plan hash.
- The handler must prepare and verify all target outputs before committing.
- Use sibling temporary files, restrictive backups, atomic rename, and automatic rollback on commit failure.
- Write a non-secret receipt with package versions and before/after hashes.
- Run offline verification against the exact runtime entrypoints.
Never silently reapply after an update.
Mode D — Verify
Verification must include, where applicable:
- syntax/type checks;
- semantic postconditions;
- actual runtime/package resolution checks;
- no-secret local protocol capture;
- native TUI and RPC/WebUI variants;
- a second apply producing zero writes.
Network, billing, credential, or live-provider checks must be separately identified and approved.
Mode E — Rollback
- Require
--confirm.
- Load the apply receipt.
- Refuse rollback if a target no longer matches the recorded after-hash.
- Restore backups atomically.
- Verify restored before-hashes and archive the receipt.
Verification
After changing this skill or its runner, execute:
npm run check --prefix <pi-skill-patch-md-package-root>
Before depending on a created or migrated patch, also run strict extraction, its fixture/unit tests, patchctl status, and offline patchctl verify. Run the Pi skill evaluator when available. Record any intentionally deferred network, billing, platform, or live-provider checks.
Parser and Manifest Requirements
Strict v2 validation requires:
- every fixed heading exactly once and in canonical order;
- contiguous unique Change indexes;
- complete scope-to-change mapping;
- recursive variable resolution with cycle detection;
- complete shell fences preserved as blocks;
- contained manifest and lifecycle handler paths;
- valid v2 manifest fields, risk metadata, verification, and rollback.
Guardrails
- Prefer upstream fixes or public extension/provider APIs over installed
dist/ edits.
- If
dist/ mutation is unavoidable, resolve from actual executable/runtime entrypoints and fail closed on unknown layouts.
- Never patch every matching package directory blindly.
- Never log credentials, authorization headers, request bodies containing user content, or secret environment values.
- Never execute verification prose as shell commands; use manifest argv steps or reviewed handler code.
- Never claim implementation or verification without file and command evidence.
- Never modify paths outside the reviewed plan.
Output Contract
Report:
- patch ID/version and manifest path;
- status or reviewed plan hash;
- modified targets and before/after hashes;
- verification results;
- receipt or rollback archive path;
- unsupported targets, deferred live checks, and restart requirements;
- the canonical app-config package path and confirmation that all reconstruction files were saved and the copied package was verified (or the exact storage blocker).
1---2name: patch-md3description: Agents should invoke this skill to create, migrate, inspect, apply, verify, or roll back versioned PATCH.md v2 lifecycle packages with machine-readable manifests, deterministic plans, drift detection, and transactional safety.4metadata:5 source: https://skillmd.com/skills/firstp1ck/patch-md6---78# Patch MD Skill910## When to Use1112Use this skill to:1314- create or update a patch package;15- migrate a legacy prose-only `PATCH.md` to schema v2;16- inspect patch status after package updates;17- plan, apply, verify, or roll back a patch;18- reapply a patch across machines or package layouts.1920## Required v2 Artifact2122A trusted patch package contains:2324```text25PATCH.md26patch.manifest.json27scripts/<lifecycle-handler>.mjs28```2930Tests and fixtures are required for package-version or layout-dependent patches.3132- `PATCH.md` explains intent, scope, transformations, verification, rollback, and limitations.33- `patch.manifest.json` is the machine-readable source of truth.34- The lifecycle handler discovers actual runtimes and implements semantic, idempotent transformations.3536Use `PATCH-TEMPLATE.md`, `TOOL-CALL-SPEC.md`, and `patch-manifest-v2.schema.json`.3738## App-specific package location3940For an app-specific patch, the app's verified configuration/home directory is the canonical package location, normally `<app-config>/patches/<patch-id>/`.4142- Resolve the actual config/home from the app's documented runtime settings, launch options, or verified environment overrides before assuming a default. Ask when the location cannot be established safely.43- Save the complete reconstructable package there: `PATCH.md`, manifest, lifecycle handlers, transformation profiles/assets, documentation, and required tests/fixtures. Do not deliver only a note that depends on a checkout, temporary capture, or versioned app-install directory.44- A repository may retain a development mirror, but report the app-config package as the canonical artifact. Keep runtime assets package-relative and verify the copied package independently.45- For T3 Code, use its resolved T3 home (`T3CODE_HOME` when configured, otherwise the verified `~/.t3` default), for example `~/.t3/patches/<patch-id>/`. Keep patch artifacts outside live `userdata`; storing a patch never authorizes editing app settings or runtime state.46- Do not silently move existing patches, receipts, or backups. Preserve their explicit state directory for rollback, and use `--state-dir` when a separately chosen config-local state directory is intended.47- Patch storage is not patch application. After an app update, run fresh read-only status/plan and obtain plan-bound approval before any installed mutation; never silently reapply.4849## Lifecycle Commands5051Resolve paths relative to this skill directory:5253```bash54node ./scripts/patch_md_extract.mjs --patch /path/to/PATCH.md --strict55node ./scripts/patchctl.mjs status --patch /path/to/PATCH.md56node ./scripts/patchctl.mjs plan --patch /path/to/PATCH.md57node ./scripts/patchctl.mjs apply --patch /path/to/PATCH.md --plan-hash <reviewed-hash>58node ./scripts/patchctl.mjs verify --patch /path/to/PATCH.md59node ./scripts/patchctl.mjs rollback --patch /path/to/PATCH.md --confirm60```6162## Workflow6364Choose the lifecycle mode below from the user's request and current patch state. Always enter through strict extraction, use read-only status/plan before mutation, and finish with verification or an explicit blocker report.6566## Mode A — Create or Migrate67681. Discover actual runtime entrypoints, package dependency graphs, and the verified app-config package destination when the target is an app.692. Define stable logical targets instead of user-specific absolute paths.703. Add package support ranges and semantic fingerprints.714. Implement three-way status: applicable, already-applied/upstreamed, or unsupported.725. Add idempotent transformation and postconditions.736. Add offline verification, receipt-based rollback, fixtures, and tests.747. Parse with strict mode and run the package test suite.7576Legacy `--no-strict` parsing is allowed only to extract facts for migration. Never apply from legacy parser output.7778## Mode B — Status and Plan79801. Run strict extraction; stop if `ok=false`.812. Run `patchctl status`.823. Run `patchctl plan` and review every required target, package version, path, before-hash, transformation, and risk.834. Do not proceed when a required target is unsupported or the plan reports drift.8485Status and plan must be read-only.8687## Mode C — Apply88891. Obtain explicit user approval for installed/global package mutation when not already requested.902. Apply only with the exact fresh plan hash.913. The handler must prepare and verify all target outputs before committing.924. Use sibling temporary files, restrictive backups, atomic rename, and automatic rollback on commit failure.935. Write a non-secret receipt with package versions and before/after hashes.946. Run offline verification against the exact runtime entrypoints.9596Never silently reapply after an update.9798## Mode D — Verify99100Verification must include, where applicable:101102- syntax/type checks;103- semantic postconditions;104- actual runtime/package resolution checks;105- no-secret local protocol capture;106- native TUI and RPC/WebUI variants;107- a second apply producing zero writes.108109Network, billing, credential, or live-provider checks must be separately identified and approved.110111## Mode E — Rollback1121131. Require `--confirm`.1142. Load the apply receipt.1153. Refuse rollback if a target no longer matches the recorded after-hash.1164. Restore backups atomically.1175. Verify restored before-hashes and archive the receipt.118119## Verification120121After changing this skill or its runner, execute:122123```bash124npm run check --prefix <pi-skill-patch-md-package-root>125```126127Before depending on a created or migrated patch, also run strict extraction, its fixture/unit tests, `patchctl status`, and offline `patchctl verify`. Run the Pi skill evaluator when available. Record any intentionally deferred network, billing, platform, or live-provider checks.128129## Parser and Manifest Requirements130131Strict v2 validation requires:132133- every fixed heading exactly once and in canonical order;134- contiguous unique Change indexes;135- complete scope-to-change mapping;136- recursive variable resolution with cycle detection;137- complete shell fences preserved as blocks;138- contained manifest and lifecycle handler paths;139- valid v2 manifest fields, risk metadata, verification, and rollback.140141## Guardrails142143- Prefer upstream fixes or public extension/provider APIs over installed `dist/` edits.144- If `dist/` mutation is unavoidable, resolve from actual executable/runtime entrypoints and fail closed on unknown layouts.145- Never patch every matching package directory blindly.146- Never log credentials, authorization headers, request bodies containing user content, or secret environment values.147- Never execute verification prose as shell commands; use manifest argv steps or reviewed handler code.148- Never claim implementation or verification without file and command evidence.149- Never modify paths outside the reviewed plan.150151## Output Contract152153Report:154155- patch ID/version and manifest path;156- status or reviewed plan hash;157- modified targets and before/after hashes;158- verification results;159- receipt or rollback archive path;160- unsupported targets, deferred live checks, and restart requirements;161- the canonical app-config package path and confirmation that all reconstruction files were saved and the copied package was verified (or the exact storage blocker).