Skip to content

Commit 4bad4f6

Browse files
rynfarrynfar
committed
feat: add T3 upstream review skill
1 parent 7110990 commit 4bad4f6

5 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎.agents/skills/review-t3-upstream/SKILL.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
name: review-t3-upstream
3+
description: Review T3 Code upstream changes for selective adoption into Pylon. Use when the user asks what changed upstream, whether Pylon should sync or update, which T3 commits or pull requests are worth adopting, how the forks differ, or asks to integrate selected upstream work. Fetch the protected upstream remote, consult the durable review ledger, group and assess candidate changes, wait for an explicit user decision, and then selectively port approved work with Pylon-first conflict resolution.
4+
---
5+
6+
# Review T3 Upstream
7+
8+
Treat upstream review as a product decision workflow, not a synchronization command. Explain what changed and help the user choose before changing Pylon.
9+
10+
## Preserve the fork invariants
11+
12+
Read `AGENTS.md`, `.agents/upstream-review.md`, and [references/decision-framework.md](references/decision-framework.md) before reviewing candidates.
13+
14+
- Keep `origin` pointed at the private `rynfar/pylon` repository and `pylon` as its product branch.
15+
- Keep `t3code-upstream` and `t3code-fork` fetch-only. Never push to them or re-enable their push URLs.
16+
- Never hard-reset Pylon, replace it with upstream, or merge all of upstream by default.
17+
- Preserve visible Pylon identity and Pylon-specific product behavior. Compatibility identifiers may remain T3-named until deliberately migrated.
18+
- Separate review from integration. Do not edit code, create an integration branch, cherry-pick, merge, commit, or push until the user explicitly selects change sets.
19+
20+
## Phase 1: Preflight the repository
21+
22+
Run from the Pylon repository root:
23+
24+
```bash
25+
git status --short --branch
26+
git remote -v
27+
git branch --show-current
28+
git rev-parse --verify pylon
29+
```
30+
31+
Confirm:
32+
33+
- `origin` fetches and pushes `rynfar/pylon`;
34+
- `t3code-upstream` fetches `pingdotgg/t3code` and has a disabled push URL;
35+
- `.agents/upstream-review.md` contains a `reviewed-through` commit;
36+
- the current checkout belongs to Pylon.
37+
38+
A dirty tree does not block read-only review, but it blocks integration. Never stash, discard, or commit unrelated work to make the tree clean.
39+
40+
If a required remote or ledger is missing, stop and explain the exact repair. Do not silently rewrite source-control configuration.
41+
42+
## Phase 2: Refresh and bound the review
43+
44+
Fetch only the official upstream tracking branch:
45+
46+
```bash
47+
git fetch --prune t3code-upstream main
48+
```
49+
50+
Read the ledger cursor as `<cursor>`, then verify it is still in upstream history:
51+
52+
```bash
53+
git merge-base --is-ancestor <cursor> t3code-upstream/main
54+
```
55+
56+
If that check fails, stop. Report that upstream history or the ledger diverged and investigate before choosing a new cursor.
57+
58+
Collect candidates in chronological order and detect patch-equivalent work already present in Pylon:
59+
60+
```bash
61+
git log --reverse --date=short --format='%H%x09%ad%x09%s' <cursor>..t3code-upstream/main
62+
git cherry -v pylon t3code-upstream/main <cursor>
63+
```
64+
65+
Record the exact upstream head used for the report. Never describe a moving branch without its commit SHA.
66+
67+
## Phase 3: Understand the changes
68+
69+
Group commits into coherent change sets before presenting them. A pull request, a dependency chain, or several commits implementing one behavior should normally be one decision.
70+
71+
For every candidate change set:
72+
73+
1. Inspect the complete commit diff and file list with `git show --stat --summary <sha>` and `git show <sha>`.
74+
2. When a title references a pull request, inspect its description and relevant review context with `gh pr view <number> --repo pingdotgg/t3code` when available.
75+
3. Trace dependencies on earlier or later upstream commits. Do not recommend a commit alone when it requires a series.
76+
4. Compare touched paths with Pylon's changes since the fork base. Identify semantic conflicts, not only textual conflicts.
77+
5. Evaluate every applicable client, provider, contract, connection mode, migration, generated file, and document.
78+
6. Classify the change using the decision framework and give a concrete Pylon recommendation.
79+
80+
Do not infer value from a commit title alone. Read the implementation and tests.
81+
82+
## Phase 4: Present a decision brief
83+
84+
Lead with a compact summary:
85+
86+
- upstream head and review range;
87+
- number of commits and coherent change sets;
88+
- patch-equivalent or already-adopted work;
89+
- highest-value recommendations;
90+
- areas likely to conflict with Pylon.
91+
92+
For each change set, report:
93+
94+
- stable candidate ID, upstream SHA, and pull request;
95+
- what changed in plain language;
96+
- why Pylon would or would not benefit;
97+
- recommendation: **adopt now**, **consider**, **defer**, or **skip**;
98+
- affected surfaces and providers;
99+
- dependency chain;
100+
- conflict risk and expected integration shape: clean cherry-pick, cherry-pick with adaptation, or manual port;
101+
- validation required.
102+
103+
End with an explicit decision request keyed by candidate ID. Do not integrate while the user's selection is ambiguous.
104+
105+
## Phase 5: Lock completed review decisions
106+
107+
After the user decides every candidate through the reported upstream head, prepare one ledger batch and the new `reviewed-through` value. Do not modify the ledger yet when an approved integration still needs a clean branch setup.
108+
109+
Record each change set as adopted, skipped, or deferred with its upstream SHA or PR, rationale, and eventual Pylon branch or commit when known. Deferred work remains visible in the ledger even though the cursor advances.
110+
111+
Do not advance the cursor when:
112+
113+
- the user has not decided every candidate;
114+
- the report covered only a filtered subset;
115+
- upstream history validation failed;
116+
- the session ended before decisions were confirmed.
117+
118+
If the user selects no integration, update the ledger as the only intended source change and offer a scoped commit and push. If the user selects work to integrate, create the integration branch first, then update the ledger on that branch after the integration outcome is known.
119+
120+
## Phase 6: Integrate only approved change sets
121+
122+
Before modifying the ledger or source, require a clean worktree, then refresh the private product branch without rewriting history:
123+
124+
```bash
125+
git fetch origin pylon
126+
git switch pylon
127+
git pull --ff-only origin pylon
128+
git switch -c upstream/<yyyy-mm-dd>-<topic>
129+
```
130+
131+
Choose the smallest faithful integration method:
132+
133+
- Use `git cherry-pick -x <sha>` in oldest-first order for coherent commits that fit Pylon.
134+
- Cherry-pick a complete dependency series when the selected behavior depends on it.
135+
- Manually port only the approved behavior when upstream structure, branding, migrations, or product direction conflict. Cite the upstream PR and SHA in the commit body.
136+
- Never resolve conflicts by taking all of `theirs`. Read both sides and preserve Pylon's intent.
137+
- If the integration proves materially broader than the approved change set, stop and return to the user with the new scope.
138+
139+
Use `pylon-branding` for asset or visible-name conflicts and `effect-server` for Effect, orchestration, provider, contract, or persistence changes. Treat migration number collisions, generated route trees, lockfiles, mobile native projects, and compatibility identifiers as explicit reconciliation work.
140+
141+
Run the smallest relevant tests, lint, formatting, typechecks, asset checks, and real-client verification required by `AGENTS.md`. Do not claim upstream tests prove the adapted Pylon behavior.
142+
143+
Show the integrated diff, validation results, and remaining risks. Do not merge into `pylon`, push, or open a pull request unless the user explicitly requests that publishing step.
144+
145+
## Finish with traceability
146+
147+
When the integration outcome becomes known, append the prepared batch to `.agents/upstream-review.md` on the integration branch and advance the cursor to the reviewed upstream head. If integration is abandoned, record the decisions separately without claiming an adopted Pylon commit.
148+
149+
Keep the review ledger and final handoff aligned. Report:
150+
151+
- upstream PRs and SHAs reviewed;
152+
- user decisions;
153+
- Pylon branch and commits created;
154+
- adaptations made for Pylon;
155+
- checks run and unresolved risks;
156+
- whether anything remains deferred.

‎.agents/skills/review-t3-upstream/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Review T3 Upstream"
3+
short_description: "Review and selectively adopt T3 changes"
4+
default_prompt: "Use $review-t3-upstream to fetch T3 updates, explain the candidates, and help me choose what Pylon should adopt."

‎.agents/skills/review-t3-upstream/references/decision-framework.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# T3 upstream decision framework
2+
3+
Use this reference to turn upstream commits into product decisions for Pylon.
4+
5+
## Build coherent change sets
6+
7+
Group commits when they belong to one pull request, require one another, share a migration or contract, or split implementation and tests across commits. Keep independent fixes separate so the user can choose them independently.
8+
9+
Use patch equivalence from `git cherry` as a signal, then inspect the Pylon source before declaring a change already adopted. A manual Pylon implementation can be semantically equivalent without producing the same patch ID.
10+
11+
## Classify candidate value
12+
13+
- **Adopt now**: fixes a real Pylon defect, closes a security or data-loss risk, restores provider compatibility, materially improves performance or remote reliability, or supplies infrastructure required by planned Pylon work.
14+
- **Consider**: valuable product or developer-experience work with manageable tradeoffs, but not urgent or clearly aligned enough to adopt automatically.
15+
- **Defer**: potentially useful, but blocked by timing, a dependency, unresolved product direction, or integration cost. Record the condition that should trigger reconsideration.
16+
- **Skip**: T3-specific branding, hosting, monetization, analytics, marketing, or product direction that conflicts with Pylon; superseded work; irrelevant changes; or complexity without a Pylon need.
17+
18+
Recommendations are judgments, not votes. Explain the evidence and tradeoff behind each one.
19+
20+
## Evaluate Pylon impact
21+
22+
For every change set, check the applicable dimensions:
23+
24+
| Dimension | Questions |
25+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
26+
| Product fit | Does it advance Pylon's direction or merely copy T3? Does it conflict with Kanban or another Pylon workflow? |
27+
| Branding | Does it restore T3 logos, names, hosted origins, analytics, or marketing copy? Can behavior be adopted without the branding? |
28+
| Architecture | Does it respect contracts, deciders, projectors, reactors, receipts, and adapter boundaries? |
29+
| Providers | What happens for Codex, Claude, Cursor, Grok, and OpenCode? Is unsupported behavior explicit? |
30+
| Clients | Does it cover web, desktop, mobile, settings, command palette, and keybindings where applicable? |
31+
| Connectivity | Does it work locally, remotely, through relay, and through tunnels? |
32+
| Persistence | Are migrations compatible with Pylon's numbering and existing schema? Is rollback or reverse behavior present? |
33+
| Performance | Does it change websocket volume, rendering cost, list behavior, background work, or continuous animation? |
34+
| Operations | Does it alter build, release, signing, hosting, secrets, telemetry, or infrastructure assumptions? |
35+
| Integration | Is a clean cherry-pick realistic, or should the behavior be manually ported? Which dependent commits are required? |
36+
37+
## Inspect known conflict hotspots
38+
39+
- **Brand assets and visible copy**: retain Pylon sources and regenerate Pylon assets. Do not accept upstream generated icons or T3 product strings blindly.
40+
- **Migrations**: Pylon already diverges from upstream. Detect duplicate migration numbers and reconcile ordering, schema assumptions, and tests deliberately.
41+
- **Generated files**: regenerate route trees, generated schemas, native projects, and lockfiles with Pylon's pinned tools after integrating source changes.
42+
- **Provider protocols**: generated protocol support is not the same as server ingestion or UI support. Trace the full path.
43+
- **Contracts and events**: schema changes can affect server, web, desktop, mobile, persistence, and remote compatibility simultaneously.
44+
- **Hosted services**: upstream T3 Connect, `app.t3.codes`, Clerk, telemetry, or release infrastructure may not match Pylon's deployment model.
45+
- **Git metadata**: retain `origin` as Pylon and T3 remotes as fetch-only. Never import upstream branch tracking configuration.
46+
47+
## Decision brief template
48+
49+
Use a compact table followed by details only where needed:
50+
51+
| ID | Upstream | Change | Recommendation | Pylon impact | Integration |
52+
| --- | ------------------- | ----------------------- | -------------- | ---------------------------------- | ------------------------------------ |
53+
| A1 | `abc1234` / `#1234` | Plain-language behavior | Adopt now | Web + server; low product conflict | Cherry-pick with branding adaptation |
54+
55+
Then state:
56+
57+
1. the exact review range and upstream head;
58+
2. patch-equivalent or already-present work;
59+
3. dependency groups;
60+
4. recommended selections;
61+
5. the candidate IDs the user should choose.
62+
63+
Avoid dumping a raw commit list without interpretation.

‎.agents/upstream-review.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
remote: t3code-upstream
3+
branch: main
4+
reviewed-through: "69dfb7f09a473d270a8b127cb1c39836fa1c6bc4"
5+
reviewed-through-date: "2026-08-02"
6+
---
7+
8+
# T3 upstream review log
9+
10+
This ledger is the durable handoff between upstream-review sessions. The `reviewed-through` commit is the newest upstream commit for which every candidate has received a user decision. Do not advance it for a partial review.
11+
12+
Deferred decisions remain listed after the cursor advances so later sessions can revisit them without rediscovering the entire upstream range.
13+
14+
## Review batches
15+
16+
No upstream review batches have been completed yet.
17+
18+
For each completed batch, append a section in this form:
19+
20+
```markdown
21+
## YYYY-MM-DD — `<previous-cursor>..<reviewed-head>`
22+
23+
| Change set | Upstream | Decision | Pylon reference | Rationale or revisit condition |
24+
| ---------- | ------------- | ----------------------------- | ---------------------- | ------------------------------ |
25+
| A1 | `sha` / `#pr` | adopted, skipped, or deferred | branch, commit, or `—` | concise reason |
26+
```

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Pylon is a long-lived independent product, not a temporary reskin or a patch que
1616
- Base Pylon work on `pylon` or a task branch created from it. Do not treat the inherited `main` branch as Pylon's product branch.
1717
- `t3code-upstream` (`pingdotgg/t3code`) and `t3code-fork` (`rynfar/t3code`) are reference remotes. They are intentionally fetch-only. Never push to them or re-enable their push URLs.
1818
- Upstream changes are opt-in. Fetch and inspect upstream commits, then cherry-pick or selectively merge only changes that benefit Pylon. Do not hard-reset, wholesale rebase, or replace Pylon with an upstream branch.
19+
- Use the `review-t3-upstream` skill whenever the user asks what changed in T3, whether Pylon should update, or wants to evaluate or adopt upstream work. The skill owns the durable review ledger in `.agents/upstream-review.md`; never bypass its human decision gate.
1920
- Resolve upstream conflicts Pylon-first. Preserve Pylon branding, agent guidance, Kanban behavior, and later Pylon-specific product decisions unless the developer explicitly chooses otherwise.
2021
- An inherited compatibility name is not permission to restore visible T3 branding. Keep product identity and runtime compatibility separate.
2122
- Before committing or publishing, verify the current branch and remotes. If the checkout is not rooted in the Pylon repository or a push would target a T3 remote, stop and correct it before proceeding.

0 commit comments

Comments
 (0)