PatchReceipt

Verify the change. Capture the proof. Ship the receipt.

PatchReceipt is a one-file Agent Skill for reproducible before-and-after evidence. It guides Claude Code, Codex, Cursor, Pi, or OpenCode to verify the behavior with the strongest available project test or connected tool, capture screenshots or recordings, add rectangular subject annotations, and produce a hash-verified PR-ready proof bundle.

Use it for:

• web changes verified with project Playwright tests, Playwright MCP, or Chrome DevTools MCP;
• Android changes verified with Compose, Espresso, UI Automator, or instrumentation tests plus adb capture;
• iOS changes verified with XCTest/XCUITest plus iOS Simulator capture;
• PNG, JPEG, or MP4 visual comparisons; and
• executable before/after HTTP or API behavior.

One SKILL.md. No PatchReceipt package, SDK, hosted service, or account required.

Install the skill

Download the immutable standalone/patch-receipt/SKILL.md, or ask your coding agent:

Install the PatchReceipt skill from
https://raw.githubusercontent.com/vivekparekh8/patch-receipt/2f3e1396107d25f7e878b642e6e4698ef57bae5d/standalone/patch-receipt/SKILL.md
for this project.

Use the correct skill directory for this agent. Refuse if the destination already exists.
Inspect every destination ancestor and refuse symlinks or Windows reparse points.
Verify that the source and copied file have the same SHA-256 hash.

Agent	Project installation	User installation
Claude Code	.claude/skills/patch-receipt/SKILL.md	~/.claude/skills/patch-receipt/SKILL.md
Codex	.agents/skills/patch-receipt/SKILL.md	~/.agents/skills/patch-receipt/SKILL.md
Cursor	.cursor/skills/patch-receipt/SKILL.md	~/.cursor/skills/patch-receipt/SKILL.md
Pi	.pi/skills/patch-receipt/SKILL.md	~/.pi/agent/skills/patch-receipt/SKILL.md
OpenCode	.opencode/skills/patch-receipt/SKILL.md	$XDG_CONFIG_HOME/opencode/skills/patch-receipt/SKILL.md or ~/.config/opencode/skills/patch-receipt/SKILL.md

Codex, Pi, and OpenCode also discover the shared .agents/skills location. Restart the agent if a newly created top-level skill directory is not detected in the current session.

Host releases can change discovery behavior. These paths follow current host documentation but have not been independently exercised on every host/version.

Ask for verified proof

Web with Playwright

Use the patch-receipt skill to verify this checkout fix with the existing targeted
Playwright test. Capture the same named PNG checkpoints before and after, box the
changed control, record role-specific assertions, and produce verified proof.md.

Web with Chrome DevTools MCP

Use the patch-receipt skill with the connected Chrome DevTools MCP to verify this
local responsive-layout change. Use an isolated profile, check the DOM and console,
capture matched viewport screenshots, annotate the affected card, and disclose any
verification or recording limitation.

Android

Use the patch-receipt skill to run the targeted Android UI test on the selected
emulator, capture before-and-after screenshots with adb, record video only if the
gesture matters, and produce a sanitized verification ledger and receipt.

iOS Simulator

Use the patch-receipt skill to run the targeted XCUITest on the selected iOS
Simulator, capture matched screenshots with simctl, highlight the changed subject,
and create verified before-and-after proof. Do not change signing or Apple accounts.

Backend/API

Use the patch-receipt skill to prove that POST /v1/items returns 400 before this
change and 201 after it. Use local test servers, redact secrets, compare the JSON
response, and produce a verified HTTP receipt.

How the skill chooses evidence

Surface	Behavioral authority	Capture
Web	Existing targeted Playwright test first; Playwright MCP or Chrome DevTools MCP when connected	PNG checkpoints; project Playwright recordVideo only when motion matters
Android	Existing Compose, Espresso, UI Automator, or instrumentation test	adb screencap; bounded adb screenrecord
iOS	Existing XCTest/XCUITest target or test plan	iOS Simulator simctl screenshot or bounded recordVideo
API	The same approved HTTP request with role-specific status/JSON expectations	Redacted response captures and assertion summary
Existing media	No executed behavior claim unless separately verified	Reviewed PNG/JPEG/MP4 inputs

The skill discovers available capabilities; it does not silently install, upgrade, configure, or start an MCP server, browser debugging port, emulator, simulator, SDK, or dependency. If automation is unavailable, it can process reviewed manual media but records verification as not-run.

What you get

.patchreceipt/<id>/
├── recipe.json
├── source/
│   ├── before.png, .jpg, or .mp4
│   └── after.png, .jpg, or .mp4
└── output/
    ├── before-annotated.png or .mp4
    ├── after-annotated.png or .mp4
    ├── comparison.png or .mp4
    ├── preview.gif                 # video proof
    ├── before-http.json            # HTTP proof
    ├── after-http.json             # HTTP proof
    ├── verification.json           # executed web/mobile checks
    ├── receipt.json
    ├── SHA256SUMS
    └── proof.md

verification.json separates the scenario's declared before/after expectations from observed results. A failing before assertion can be expected evidence; overall verification passes only when both roles match their declarations.

proof.md is ready for a pull request. receipt.json records the claim, acquisition conditions, annotations, normalization, tools, assertions, hashes, and limitations. SHA256SUMS detects later changes to the evidence.

Requirements

Always:

• a coding agent with project and local-tool access;
• ffmpeg and ffprobe for image/video normalization; and
• Git when commit context should appear in the receipt.

Only for the selected verification surface:

• an existing project Playwright setup or connected Playwright/Chrome DevTools MCP;
• adb plus an explicitly selected Android emulator/device; or
• Xcode command-line tools plus an explicitly selected booted iOS Simulator.

Node.js is not required for the standalone skill itself.

Safety and privacy

• Project tests remain the behavioral authority; browser/device connections provide interaction and capture.
• Signed-in browser profiles, stored authentication, non-local environments, physical devices, installs, permission changes, app-data clearing, and state-changing interactions require explicit approval.
• Chrome DevTools MCP can expose every open page and may enable usage statistics or CrUX lookups. Prefer an isolated profile with --no-usage-statistics and --no-performance-crux.
• Device serials, simulator UDIDs, stable target hashes, browser profile paths, cookies, signing identities, provisioning profiles, Apple accounts, usernames, home paths, and complete private URLs must never be persisted. The CLI ledger schema rejects opaque-label violations, common private paths/URLs, and secret-shaped fields; the final manual privacy review remains required.
• Android commands always select a single target. Temporary recordings use cryptographically random absent paths; exact remote files, partial local captures, recorders, and staging directories are cleaned on every exit. iOS Simulator capture follows the same failure-cleanup rule.
• iOS support currently targets Simulator. Physical iOS screenshots may be accepted as reviewed manual XCTest attachments, but portable physical-device capture is not claimed.
• Source media remains unchanged; annotations and comparisons are derived files.
• Logs, accessibility snapshots, console/network summaries, traces, logcat, and .xcresult are supplementary evidence—not visual proof.
• Production-like, non-local, account-connected, or state-changing actions require approval immediately before execution.
• No proof assets are uploaded and no PR is changed without separate publication approval.

Read the complete SKILL.md before using sensitive media, accounts, browsers, APIs, or devices. See SECURITY.md for reporting.

Receipt format

Standalone receipts declare:

{
  "format": "patch-receipt-agent/v1",
  "mode": "agent-driven"
}

The standalone format is explicit about agent-driven execution and does not claim compatibility with the stricter deterministic CLI receipt schema. The repository also includes that CLI and a bundled skill for teams that need deterministic media/HTTP processing. A CLI recipe can declare "verification": {"path":"verification.json"}; the CLI then validates role-compatible before/after checkpoints and privacy-safe metadata, copies the ledger into atomic staging, binds its digest and result into receipt.json, checks it with patchreceipt verify, and includes it in publication. Failed or not-run ledgers preserve diagnostic output but exit nonzero by default; --allow-failed must be explicit.

Contributing

npm ci
npm run check
npm test
npm run validate:skill
npm pack --dry-run

See CONTRIBUTING.md, the acceptance gates, and the release plan.

License

MIT © 2026 Vivek Parekh. FFmpeg and connected test/device tools are external and retain their own licenses.