From 77d0970094680f410aa97eb5601927b570ca373b Mon Sep 17 00:00:00 2001 From: Elliot Drel Date: Fri, 3 Jul 2026 19:48:53 +0200 Subject: [PATCH 1/4] Add PatchMD fork maintenance workflow --- .agents/skills/modify-with-patch-md/SKILL.md | 36 +++++++++++ .agents/skills/update-with-patch-md/SKILL.md | 63 ++++++++++++++++++++ AGENTS.md | 7 +++ PATCH.md | 44 ++++++++++++++ docs/operations/patch-md.md | 35 +++++++++++ 5 files changed, 185 insertions(+) create mode 100644 .agents/skills/modify-with-patch-md/SKILL.md create mode 100644 .agents/skills/update-with-patch-md/SKILL.md create mode 100644 PATCH.md create mode 100644 docs/operations/patch-md.md diff --git a/.agents/skills/modify-with-patch-md/SKILL.md b/.agents/skills/modify-with-patch-md/SKILL.md new file mode 100644 index 00000000000..9d74f6a9da2 --- /dev/null +++ b/.agents/skills/modify-with-patch-md/SKILL.md @@ -0,0 +1,36 @@ +--- +name: modify-with-patch-md +description: Make a deliberate downstream change while recording its intent. Use when customizing upstream-owned behavior in a T3 Code fork that contains PATCH.md. +--- + +# Modify with PatchMD + +Make the requested change normally and keep its intent durable. + +## Establish scope + +1. Read `AGENTS.md` and root `PATCH.md`. +2. Confirm the change deliberately customizes upstream-owned behavior. +3. Reuse an entry for the same intent or choose a stable kebab-case ID. + +Do not record formatting, generated files, lockfile churn, environment +configuration, ordinary dependency updates, or independent additions that +upstream cannot overwrite. + +## Implement and record + +Use T3 Code's existing architecture. Add or update one feature-centered entry +with `Status`, `Intent`, `Why`, `Behavior`, `Scope`, and `Reconstruction`. +Temporary fixes should include `Retire when`. Describe outcomes and constraints, +not source patches. + +## Verify + +Run every applicable command in `PATCH.md`'s Verification section. Re-read the +diff and entry together and fix any mismatch or failure caused by the change. + +## Commit and report + +When commits are authorized, keep the implementation and intent update in the +same logical commit. Otherwise leave both for the user's commit workflow. Never +push without approval. Report the behavior, entry, checks, and ambiguity. diff --git a/.agents/skills/update-with-patch-md/SKILL.md b/.agents/skills/update-with-patch-md/SKILL.md new file mode 100644 index 00000000000..a11135069c6 --- /dev/null +++ b/.agents/skills/update-with-patch-md/SKILL.md @@ -0,0 +1,63 @@ +--- +name: update-with-patch-md +description: Update a customized T3 Code fork from upstream without losing intent. Use for update, upgrade, rebase, sync, upstream conflicts, or retiring patches when root PATCH.md exists. +--- + +# Update with PatchMD + +Rebase ordinary fork commits onto upstream, resolve conflicts from `PATCH.md` +intent, preserve displaced content, and verify before handoff. + +## Hard rules + +1. Never discard uncommitted work. +2. Create a recoverable Git ref before rewriting history. +3. Preserve conflicted downstream files as exact Git blob bytes before choosing + upstream. +4. Reconstruct intent, not old text. +5. Ask before reconstruction, retirement, push, or deployment. +6. Roll back when required verification fails. + +## Preflight + +Read `AGENTS.md` and `PATCH.md`. Confirm the repository root, branch, clean +working tree, upstream remote and branch, active entries, and verification +commands. Stop if dirty. Fetch upstream and stop if it has no new commits. +Create `backup/pre-patchmd-update-` at `HEAD`; do not continue if the +ref cannot be created. + +## Rebase + +Rebase downstream commits onto upstream. For each content conflict: + +1. Record `REBASE_HEAD`, its subject, and unmerged paths. +2. Save each path's exact bytes from the backup ref outside the worktree with + `git cat-file`; record downstream deletions explicitly. +3. Keep the upstream-based side (`--ours`) as the safe baseline. During rebase, + `--theirs` is the downstream patch. +4. Continue, or skip an empty commit. + +Write a manifest containing the repository, upstream ref, backup ref, conflict +paths, patch commits, subjects, and backup locations. Abort and restore the +backup ref on an unsupported rebase state. + +## Audit intent + +Review every active entry, including cleanly replayed work. Classify it as +preserved, satisfied upstream, needs reconstruction, or ambiguous. Evaluate +`Retire when` first. Show evidence and obtain approval before changing code or +retiring an entry. Compare new upstream code, backed-up downstream code, +`PATCH.md`, and the original commit. Never guess. + +## Verify or roll back + +Run all applicable `PATCH.md` verification commands. If a required check fails, +abort any rebase, reset the branch to the backup ref, preserve recovery files, +and report the failure and locations. + +## Review + +Report upstream commits received, downstream commits replayed or skipped, every +customization's classification, checks, recovery locations, and branch state. +Stop before push or deployment unless explicitly approved. Re-fetch and use +`--force-with-lease`, never `--force`, for rewritten history. diff --git a/AGENTS.md b/AGENTS.md index 380a9202683..be6fda66cf3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,13 @@ - If changing native mobile code, `vp run lint:mobile` must also pass. - Use `vp test` for the built-in Vite+ test command and `vp run test` when you specifically need the `test` package script. +## PatchMD + +Downstream forks can record deliberate changes to T3 Code-owned behavior in +root `PATCH.md`. When making such a customization, use +`.agents/skills/modify-with-patch-md/SKILL.md`. Before rebasing a customized +fork onto upstream, use `.agents/skills/update-with-patch-md/SKILL.md`. + ## Project Snapshot T3 Code is a minimal web GUI for using coding agents like Codex and Claude. diff --git a/PATCH.md b/PATCH.md new file mode 100644 index 00000000000..efd05a324a1 --- /dev/null +++ b/PATCH.md @@ -0,0 +1,44 @@ +# PATCH.md + +This file records the intent behind deliberate customizations made by a +downstream T3 Code fork. Code and Git commits are the implementation; this file +explains what must survive an upstream update. + +## Upstream + +- Repository: `https://github.com/pingdotgg/t3code` +- Branch: `main` + +## Verification + +Commands that must pass after a customization or upstream update: + +- Install: `pnpm install` +- Check: `vp check` +- Typecheck: `vp run typecheck` +- Native mobile changes: `vp run lint:mobile` + +## Active customizations + +No downstream customizations are recorded in the upstream repository. Fork +maintainers should copy the entry below for each deliberate customization. + + + +## Retired customizations + +Move or copy retired entries here, set `Status` to `retired`, and explain why +the customization is no longer needed. Do not delete its history. diff --git a/docs/operations/patch-md.md b/docs/operations/patch-md.md new file mode 100644 index 00000000000..542b8f2b749 --- /dev/null +++ b/docs/operations/patch-md.md @@ -0,0 +1,35 @@ +# Maintaining a customized T3 Code fork with PatchMD + +PatchMD keeps the reason for downstream changes available after upstream code +moves or is rewritten. Git remains the implementation record. Root `PATCH.md` +records the outcome each customization must preserve. + +## Customize + +Use `.agents/skills/modify-with-patch-md/SKILL.md` when deliberately changing +T3 Code-owned behavior in a downstream fork. Keep the code and its intent entry +in the same logical commit. Entries describe observable behavior and +reconstruction constraints rather than old source text. + +## Update + +Use `.agents/skills/update-with-patch-md/SKILL.md` before rebasing the fork onto +`pingdotgg/t3code:main`. The workflow requires a clean tree and recovery ref, +tries normal Git replay first, preserves displaced bytes, prefers new upstream +code during uncertainty, audits every active intent, and verifies the result. + +Conflicts are semantic work. Compare the new upstream implementation, previous +downstream implementation, and matching intent. Rebuild the outcome on the new +architecture only after approval. If upstream now satisfies the outcome, remove +redundant downstream behavior and mark the entry `retired` with a reference. + +## Review and adoption + +An update is complete only after the repository's checks pass and the +maintainer has reviewed which customizations were preserved, reconstructed, +retired, or left unresolved. The workflow never pushes, deploys, force-pushes, +or deletes recovery data without approval. + +PatchMD is a draft convention maintained at +. It is inspired by Theo Browne's +[patch.md idea](https://www.youtube.com/watch?v=G1xqTjoihfo&t=1970s). From eea98143806d15d1fef626eb10aa58882f18772e Mon Sep 17 00:00:00 2001 From: Elliot Drel Date: Fri, 3 Jul 2026 19:53:48 +0200 Subject: [PATCH 2/4] Clarify PatchMD conflict recovery --- .agents/skills/update-with-patch-md/SKILL.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.agents/skills/update-with-patch-md/SKILL.md b/.agents/skills/update-with-patch-md/SKILL.md index a11135069c6..70ef4a2c407 100644 --- a/.agents/skills/update-with-patch-md/SKILL.md +++ b/.agents/skills/update-with-patch-md/SKILL.md @@ -31,8 +31,10 @@ ref cannot be created. Rebase downstream commits onto upstream. For each content conflict: 1. Record `REBASE_HEAD`, its subject, and unmerged paths. -2. Save each path's exact bytes from the backup ref outside the worktree with - `git cat-file`; record downstream deletions explicitly. +2. Save each path's exact downstream bytes from conflict stage 3 outside the + worktree with `git cat-file -p :3:`. Record downstream deletions + explicitly. The backup ref remains the whole-branch rollback point; its + branch-tip blob is not a substitute for the commit currently replaying. 3. Keep the upstream-based side (`--ours`) as the safe baseline. During rebase, `--theirs` is the downstream patch. 4. Continue, or skip an empty commit. @@ -51,9 +53,9 @@ retiring an entry. Compare new upstream code, backed-up downstream code, ## Verify or roll back -Run all applicable `PATCH.md` verification commands. If a required check fails, -abort any rebase, reset the branch to the backup ref, preserve recovery files, -and report the failure and locations. +Run all applicable `PATCH.md` verification commands. If a required check fails +while a rebase is active, abort it. Otherwise reset the branch to the backup +ref. Preserve recovery files and report the failure and locations. ## Review From 75897ca5c54d09760b3f36fd2e96d90bf528f9ba Mon Sep 17 00:00:00 2001 From: Elliot Drel Date: Fri, 3 Jul 2026 19:58:23 +0200 Subject: [PATCH 3/4] Separate PatchMD bootstrap from verification --- PATCH.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/PATCH.md b/PATCH.md index efd05a324a1..37dfa2394df 100644 --- a/PATCH.md +++ b/PATCH.md @@ -13,11 +13,13 @@ explains what must survive an upstream update. Commands that must pass after a customization or upstream update: -- Install: `pnpm install` - Check: `vp check` - Typecheck: `vp run typecheck` - Native mobile changes: `vp run lint:mobile` +Bootstrap dependencies with `pnpm install --frozen-lockfile` when the checkout +is not already installed. This setup step is not a verification result. + ## Active customizations No downstream customizations are recorded in the upstream repository. Fork From 44afb7994a8e88f72eb9d9bcb6e0eec79d7dd66b Mon Sep 17 00:00:00 2001 From: Elliot Drel Date: Fri, 3 Jul 2026 20:03:28 +0200 Subject: [PATCH 4/4] Scope PatchMD rollback to failed checks --- .agents/skills/update-with-patch-md/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/update-with-patch-md/SKILL.md b/.agents/skills/update-with-patch-md/SKILL.md index 70ef4a2c407..d6e4fdfdcc6 100644 --- a/.agents/skills/update-with-patch-md/SKILL.md +++ b/.agents/skills/update-with-patch-md/SKILL.md @@ -53,9 +53,10 @@ retiring an entry. Compare new upstream code, backed-up downstream code, ## Verify or roll back -Run all applicable `PATCH.md` verification commands. If a required check fails -while a rebase is active, abort it. Otherwise reset the branch to the backup -ref. Preserve recovery files and report the failure and locations. +Run all applicable `PATCH.md` verification commands. On a required-check +failure, abort an active rebase; if the rebase already finished, reset the +branch to the backup ref. Preserve recovery files and report the failure and +locations. Keep the updated branch when every required check passes. ## Review