Add PatchMD fork maintenance workflow

[ElliotDrel]

Summary

• add a root PATCH.md intent manifest for downstream T3 Code customizations
• add agent skills for recording customization intent and safely updating from upstream
• route agents through those skills from AGENTS.md
• document the intent-first update, conflict, retirement, verification, and approval model

Why

Long-lived T3 Code forks need to preserve the reason behind deliberate downstream changes after upstream code moves or is rewritten. Git remains the implementation record; PATCH.md records the observable outcome and reconstruction constraints.

This replaces #3146 with the current PatchMD Draft 0.2.1 mentality: normal Git first, exact recovery data before conflict resolution, upstream as the safe baseline during uncertainty, semantic reconstruction with approval, explicit retirement, and no push or deployment without approval.

Inspired by Theo Browne's patch.md idea: https://www.youtube.com/watch?v=G1xqTjoihfo&t=1970s

Validation

• git diff --check
• full repository checks delegated to fresh GitHub CI because the local Windows dependency tree was locked during Node 24 relinking; no runtime source or dependency files changed

---

Note

Low Risk
Documentation and agent guidance only; no application runtime, auth, or dependency changes.

Overview
Introduces PatchMD, a convention for long-lived T3 Code forks to record why deliberate downstream changes exist and how to preserve them across upstream updates—without replacing Git as the source of truth.

Adds root PATCH.md with upstream pointer (pingdotgg/t3code:main), required verification commands (vp check, typecheck, optional mobile lint), and a structured template for active/retired customization entries (intent, behavior, reconstruction, retire-when).

Adds two agent skills under .agents/skills/: modify-with-patch-md (scope, implement, verify, and commit intent alongside code) and update-with-patch-md (preflight backup ref, rebase onto upstream, preserve conflicted downstream bytes, audit intent, verify or roll back, no push without approval).

AGENTS.md now routes agents to those skills for customizations and upstream rebases. docs/operations/patch-md.md documents the human-facing customize/update/review model for fork maintainers.

^{Reviewed by Cursor Bugbot for commit 44afb79. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add PatchMD fork maintenance workflow with agent skills and documentation

• Adds PATCH.md as a root-level template for recording deliberate downstream customizations, including upstream repo reference, verification commands, and active/retired customization sections.
• Adds two agent skills: modify-with-patch-md for making and recording intentional changes, and update-with-patch-md for rebasing a customized fork onto upstream updates.
• Adds an operations guide at docs/operations/patch-md.md and a PatchMD section in AGENTS.md referencing the new skills.

^{Macroscope summarized 44afb79.}

Summary by CodeRabbit

• Documentation
  • Added guidance for recording and preserving intentional custom changes in a fork.
  • Introduced clear update and modification workflows, including verification steps and approval checks.
  • Added templates for tracking active and retired customizations, plus a reference note for the overall process.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation for a "PatchMD" convention used to track deliberate downstream customizations in a T3 Code fork. It introduces a PATCH.md scaffold, an AGENTS.md pointer section, two agent skill docs (modify/update workflows), and an operations documentation page.

Changes

PatchMD Documentation

Layer / File(s)	Summary
PATCH.md scaffold and AGENTS.md pointer PATCH.md, AGENTS.md	Adds upstream metadata, verification commands, and active/retired customization templates in PATCH.md; adds an AGENTS.md section referencing PatchMD and skill docs.
Modify and update skill definitions .agents/skills/modify-with-patch-md/SKILL.md, .agents/skills/update-with-patch-md/SKILL.md	Defines step-by-step processes for recording deliberate customizations and for safely rebasing onto upstream while preserving patch intent.
Operations documentation page docs/operations/patch-md.md	Documents the PatchMD workflow, rebase/conflict handling, acceptance criteria, and links to related conventions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Poem

A rabbit scribbles notes with glee,
"PATCH.md" now sets us free,
Skills for modify, skills for rebase,
Intent preserved in every case,
Hop along, docs in place! 🐇📄

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is clear, concise, and accurately summarizes the main change: adding a PatchMD fork maintenance workflow.
Description check	✅ Passed	The description covers what changed, why, and validation well; it only loosely follows the template and omits the checklist/UI sections.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ElliotDrel]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77d0970094

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 77d0970. Configure here.}

[macroscopeapp]

Approvability

Verdict: Approved

Documentation-only changes adding PatchMD workflow guides and templates for fork maintenance. No runtime code or configuration is affected.

^{You can customize Macroscope's approvability policy. Learn more.}

[ElliotDrel]

@coderabbitai review

@codex review

[coderabbitai]

@ElliotDrel I'll review the latest changes now.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@PATCH.md`:
- Around line 12-18: The verification list currently includes pnpm install,
which is a mutating bootstrap step rather than a stable gate. Update the
verification guidance so the required checks are only the non-mutating commands
referenced in the section, such as vp check and vp run typecheck, and move pnpm
install into a separate bootstrap/setup step or replace it with a frozen install
check if needed. Keep the change within the Verification section of PATCH.md so
the modify/update flow does not treat install as a pass/fail verification.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: da44d52a-9dff-4bd9-ad4a-befa5c2b9033

📥 Commits

Reviewing files that changed from the base of the PR and between cabc93b and 77d0970.

📒 Files selected for processing (5)

• .agents/skills/modify-with-patch-md/SKILL.md
• .agents/skills/update-with-patch-md/SKILL.md
• AGENTS.md
• PATCH.md
• docs/operations/patch-md.md

Dismissing prior approval to re-evaluate 75897ca

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eea9814380

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Dismissing prior approval to re-evaluate 44afb79