PatchMD is a draft convention for keeping customized software updatable.
A root PATCH.md records the intent behind deliberate changes made to a
fork. The code and Git commits remain the implementation. The document gives a
future developer or AI agent enough context to preserve, adapt, or retire those
changes when upstream moves on.
customize -> record intent -> update upstream -> repair if needed -> review
PatchMD is a proposal, not an established standard. It is inspired by Theo's "A letter to tech CEOs" talk, the predictable-file approach of AGENTS.md, and a working fork-maintenance workflow first developed in gbrain. An early project-specific experiment also exists in T3 Code PR #3146.
When you customize a fork:
- Change the application normally and commit the work normally.
- Add or update a
PATCH.mdentry describing the outcome you intended. - Later, update from upstream using normal Git mechanics first.
- If a patch conflicts or has become obsolete, use its recorded intent to repair or retire it.
- Verify and review the result before pushing or deploying it.
PATCH.md is not a diff, lockfile, or substitute for version control. It
explains why the fork differs so the implementation can change safely.
Run this from the root of your fork. Either path ends the same way: the
install-patch-md skill sets PatchMD up.
The skill installs itself first, then runs. Give your agent this prompt:
Read and follow this skill, then set up PatchMD in this repo:
https://raw.githubusercontent.com/ElliotDrel/PATCH-md/v0.2.1/skills/install-patch-md/SKILL.md
If the skills are already in the repo, this is all you need:
Use the install-patch-md skill to set up PatchMD in this repo.
npx patch.md-intent
This copies the three skills into .agents/skills/ (symlinked into
.claude/skills/) and drops the template in, then tells you to run the setup
skill.
install-patch-mdinstalls the skill files, createsPATCH.md, inventories existing customizations, and — with your approval — wires PatchMD into how the fork already commits and updates.modify-with-patch-mdrecords intent while making custom changes.update-with-patch-mdrebases onto upstream, resolves conflicts from recorded intent, verifies, and reports.
Install can also set up optional triggers — agent instructions, a pre-commit
warning, and a CI check — so a change to upstream-owned code without a PATCH.md
update is surfaced instead of slipping through.
Record intentional changes to upstream-owned behavior that the fork needs to keep. Do not record formatting-only edits, generated files, lockfile churn, environment files, ordinary dependency updates, or unrelated local additions.
Keep entries about outcomes, not old code. One entry may cover several files or commits when they implement one customization.
SPEC.md defines Draft 0.2.1. The format is intentionally small:
- one root
PATCH.md; - one stable ID per customization;
- plain-English intent, rationale, behavior, scope, and reconstruction guidance;
activeandretiredlifecycle states;- normal Git commits as the implementation record.
See examples/ for complete files.
- The PatchMD mentality explains the principles and the boundaries behind the convention.
- Origins and inspiration traces the idea to
Theo Browne (
@t3dotgg), his original video, and related conventions. - The gbrain reference implementation documents the exact working fork workflow that informed the first draft.
- Development guide explains repository structure, validation, and design boundaries.
- Release guide documents npm trusted publishing and the verified release process.
Draft 0.2.1 is open for practical feedback from people maintaining downstream forks. The format will change only when real use exposes a problem.
MIT