Add PatchMD fork maintenance workflow

.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.

.agents/skills/update-with-patch-md/SKILL.md

@@ -0,0 +1,66 @@
+---
+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-<timestamp>` 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 downstream bytes from conflict stage 3 outside the
+   worktree with `git cat-file -p :3:<path>`. 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.
+
+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. 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
+
+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.

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.

PATCH.md

@@ -0,0 +1,46 @@
+# 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:
+
+- 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
+maintainers should copy the entry below for each deliberate customization.
+
+<!--
+### customization-id
+
+- **Status:** active
+- **Intent:** What outcome should this customization provide?
+- **Why:** Why does this fork need behavior that upstream does not provide?
+- **Behavior:** What observable requirements must remain true?
+- **Scope:** Which files, packages, or subsystems are involved?
+- **Reconstruction:** How should a future developer or agent rebuild the intent
+  on newer upstream code? Include constraints, not a full code patch.
+- **Retire when:** Optional for temporary fixes. What observable check proves
+  upstream now satisfies this intent?
+- **References:** Optional commits, issues, or upstream pull requests.
+-->
+
+## 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.

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
+<https://github.com/ElliotDrel/PATCH-md>. It is inspired by Theo Browne's
+[patch.md idea](https://www.youtube.com/watch?v=G1xqTjoihfo&t=1970s).