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..d6e4fdfdcc6 --- /dev/null +++ b/.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-` 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:`. 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. 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..37dfa2394df --- /dev/null +++ b/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. + + + +## 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).