Skip to content

Commit 7c8db8b

Browse files
donjor-agent[bot]donjor
authored andcommitted
docs(agents): tighten fork development priorities (#1683)
## Problem Fork direction repeated procedures without making the cost of carrying and retiring changes prominent. ## Change Emphasize sync conflict cost, easy retirement, and long-term maintainability, with correctness and client compatibility as the baseline. Keep essential branch, trailer, and safety rules; link existing fork procedures and preserve upstream sections byte-for-byte. ## Scope and approval Maintainer-requested documentation cleanup, limited to the fork section of `AGENTS.md`. ## Verification | Check | Result | | --- | --- | | `vp run fork:ci` | Exit 0; all gates passed, 63 scripts test files and 761 tests passed | | Upstream text comparison | Byte-for-byte identical to the upstream base | | Markdown lint | No fork-section findings; 123 existing upstream findings left untouched | | `git diff --check` | Exit 0 | Model: GPT-6.1-sol; harness: Codex in T3 Code. ## Fork trailers Fork-Domain: fork-meta Fork-Tier: qol Co-authored-by: donjor <[email protected]>
1 parent 6257c11 commit 7c8db8b

1 file changed

Lines changed: 27 additions & 29 deletions

File tree

‎AGENTS.md‎

Lines changed: 27 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -2,37 +2,35 @@
22

33
## Fork direction
44

5-
This checkout is the `RSI-Software/t3code-hyprws` fork.
6-
Read [Fork development](docs/fork/internals/fork-development.md) before changing fork behavior or Git topology.
7-
Read [Fork delta](docs/fork/internals/fork-delta.md) before adding to the fork, and walk its rebase scan on every upstream rebase.
8-
9-
Upstream guidance below remains the default unless this section or the fork guide overrides it.
10-
11-
- Treat any desktop window as the user's T3 instance.
12-
- Keep the all-projects view available and share the Electron process, backend pool, auth, providers, and persisted state.
13-
- Let Hyprland place windows across workspaces and monitors; do not encode compositor policy in T3 Code.
14-
- Keep local `main` identical to `upstream/main`; never add fork commits to it.
15-
- Maintain the fork delta on `hyprws`, the single fork trunk, and create focused worktrees from it with Worktrunk.
16-
- Rebase `hyprws` onto any upstream release tag, stable or nightly; never merge upstream into the fork branch.
17-
- Never target an untagged upstream commit; use the `fork-sync` skill for the rebase.
18-
- Tag every fork commit with `Fork-Domain` and `Fork-Tier` trailers; `vp run fork:delta --check` must pass.
19-
- Run `vp run fork:ci` before every pull request.
20-
It derives the CI scan flags and runs the delta check, the stale-delete check, the rebase scan, `vp check`, plus the whole scripts workspace, so scripts tests are never hand-picked.
21-
That is a subset of the pull-request jobs, not all of them.
22-
- Cite an upstream item in fork prose only inside a code span or a fenced block, and write a fork item in full as `RSI-Software/t3code-hyprws#108`, because a live reference posts a backlink on the upstream thread and a bare number the fork never issued resolves there; `vp run fork:upstream-refs <file>` refuses a body that carries one.
23-
- Publish rebased history only with the explicit expected-old lease documented in the fork guide.
24-
- Fold the ahead commits to one intent each with the [`fork-fold`](.agents/skills/fork-fold/SKILL.md) skill.
25-
- Never delete an upstream line a fork commit later restores; `fork:ci` refuses it. Add beside an upstream block instead of rewriting it.
26-
- Keep patches small, upstream-native, and checked across every affected client and connection mode.
27-
- Triage a bug felt in the fork build with the [`upstream-triage`](.agents/skills/upstream-triage/SKILL.md) skill before filing or fixing it.
5+
This checkout is `RSI-Software/t3code-hyprws`.
6+
Fork rules override upstream guidance below; keep those upstream sections unchanged.
7+
[Fork development](docs/fork/internals/fork-development.md) and [Fork delta](docs/fork/internals/fork-delta.md) own the detailed procedures and domain boundaries.
8+
9+
**Every change must satisfy all three priorities.**
10+
11+
| Priority | Required approach |
12+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
13+
| **Limit sync conflicts** | Design every fork feature and change for frequent `fork-sync` rebases: isolate fork code and keep upstream edits to narrow extension hooks |
14+
| **Easy retirement** | Keep each implementation separable so it can be removed cleanly when upstream supersedes it |
15+
| **Long-term maintainability** | For lasting features, favor designs that remain simple to maintain across many upstream syncs |
16+
17+
Judge each design by: **How hard is the next sync? How cleanly can we remove this? What must we keep maintaining?**
18+
Correctness and client compatibility remain the baseline.
19+
20+
| Concern | Rule |
21+
| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
22+
| `main` | Keep local `main` identical to `upstream/main`; never add fork commits |
23+
| Base branch | `hyprws` is the fork trunk; base fork worktrees on freshly fetched `origin/hyprws`, not potentially stale local `hyprws` |
24+
| Topology | Rebase onto upstream release tags, stable or nightly; never merge upstream or target an untagged commit |
25+
| Trailers | Every fork commit needs `Fork-Domain` and `Fork-Tier`; bugfixes also need `Fork-Upstreamable: yes` or `no` |
26+
| PR gate | Run `vp run fork:ci` before every PR; it overrides the upstream restriction on repo-wide checks |
27+
| Windows | Keep all-projects available; share Electron, backend, auth, providers, and state; leave placement to Hyprland |
28+
| Citations | Upstream items stay in code spans or fences; fork references use the full `RSI-Software/t3code-hyprws#108` form |
2829

2930
**Nothing is posted upstream.**
30-
The fork posts nothing to `pingdotgg/t3code`: no pull request, issue, comment, review, or reaction.
31-
Reading upstream is fine; writing to it is not.
32-
This is a baseline rule, not a preference: it holds until at least 2026-11-27, may hold permanently, and only the human may lift it.
33-
`Fork-Upstreamable: yes` is a tracking tag only.
34-
It marks a commit upstream is likely to supersede so the rebase feasibility walk can flag it as a retire candidate, and it never authorizes contributing that commit.
35-
The fork tracks upstream and retires superseded commits; it does not contribute to upstream.
31+
Reads of `pingdotgg/t3code` are allowed; no PR, issue, comment, review, or reaction.
32+
Only the human may lift this rule; it holds until at least 2026-11-27 and may be permanent.
33+
`Fork-Upstreamable` tracks retirement only; it never authorizes contributing.
3634

3735
T3 Code is a minimal GUI for coding agents. A Node WebSocket server wraps provider CLIs and agents (Codex, Claude Code, Cursor, Grok, OpenCode, Antigravity) and serves web, desktop, and mobile clients.
3836

0 commit comments

Comments
 (0)