From ae98179243ed668a5d4853fe7b2c9457e3de9b74 Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Sun, 25 Oct 2026 16:03:12 -0700 Subject: [PATCH 1/3] docs: open and track PRs through GitCafe when origin is git.cafe Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- docs/operations/development.md | 41 +++++++++++++--------------------- 2 files changed, 16 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a0a1f949faa51..e0af56a8ade66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,7 +139,7 @@ For authorized mobile verification, a missing or outdated native client is an in ## Pull requests - Never make a PR unless the developer explicitly asks you to do so. -- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): use `cafe` for existing PRs, issues, comments and labels, but push and open PRs on GitHub, where CI runs. +- If `origin` is git.cafe, follow [GitCafe mirror](docs/operations/development.md#gitcafe-mirror-optional): push to `origin`, open and track PRs with `cafe` and their git.cafe URLs, and keep `gh` for CI logs and merging. - Conventional commit titles, plain language: `fix(web): new threads no longer spike CPU`. - Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work. - UI changes need before/after images. Motion or timing needs a short video. diff --git a/docs/operations/development.md b/docs/operations/development.md index c34dc108890b6..e44c0caf6e849 100644 --- a/docs/operations/development.md +++ b/docs/operations/development.md @@ -18,43 +18,32 @@ Prefer a container? See [Dev container](../internals/devcontainer.md) for VS Cod ## GitCafe mirror (optional) GitHub is the source of truth. [git.cafe/pingdotgg/t3code](https://git.cafe/pingdotgg/t3code) is a -two-way synced mirror with much higher API rate limits, which helps when many agents read PRs and -issues at once. You never need it to contribute. +two-way synced mirror with much higher API rate limits, which helps when many agents work at once. +You never need it to contribute. -Comments, reviews, labels, and issue edits made on GitCafe sync back to GitHub. The exception is -code: push branches and open PRs on GitHub, where CI runs. GitCafe mirrors a new PR within about a -minute, and from then on you can work with it through either forge. +Pushes, PRs, comments, reviews, labels, and issue edits made on GitCafe sync to GitHub within +about a minute, and PR and issue numbers match. CI runs on GitHub, and its checks show up on +GitCafe. ```sh git remote set-url origin https://git.cafe/pingdotgg/t3code.git git remote add github https://github.com/pingdotgg/t3code.git -# The GitHub remote you push to: `github`, or your fork's remote. -git config remote.pushDefault github -gh repo set-default pingdotgg/t3code bun install -g @gitcafe/cli # `cafe` needs Bun 1.2 or newer cafe auth login && cafe auth http setup cafe skills install --global # optional: cafe-* skills for coding agents ``` -With `origin` on git.cafe: - -- Use `cafe` for existing PRs, issues, comments, reviews, and labels, both reading and writing. Check status - comes from `cafe pr status --json`. -- Create PRs on GitHub: `git push` (to the `pushDefault` remote), then `gh pr create` or `gh stack`. - A PR opened with `cafe pr create` or `cafe stack submit` can get a different number on each forge, - a sync marker appended to its body, and rewritten references, and it cannot come from a fork. -- Write or edit text with closing keywords using `gh`. Any text GitCafe writes to GitHub has its - `#` references turned into GitCafe links, so a `Fixes #` edited through `cafe` silently stops - closing the issue. -- Merge with `gh pr merge --match-head-commit `. `cafe pr merge` only pins the head - GitCafe last saw, not the commit you reviewed. -- Use `gh` where the mirror falls short: CI logs and reruns, a fork PR's head repository, and - anything `cafe` returns empty or 403/404 for. -- PR and issue numbers can differ between the forges. Name PRs by branch - (`cafe pr list --head `, `gh pr view `), and write `Fixes #`. +With `origin` on git.cafe, work through GitCafe and leave GitHub's API alone: + +- Push to `origin`, open PRs with `cafe pr create` (`--head owner/repo:branch` from a fork) or + `cafe stack submit`, and use `cafe` for everything after that. Link the git.cafe PR URL, not the + github.com one, wherever a tool tracks the PR, so polling stays on GitCafe. +- Read checks with `cafe pr status `. +- Two things still need `gh`: CI logs and reruns (`gh run view`), and merging, with + `gh pr merge --match-head-commit `, because `cafe pr merge` cannot pin the commit you + reviewed. - `cafe` flags differ from `gh`: `--repo` not `-R`, `cafe issue comments ` not `--comments`, - `cafe pr status` not `pr checks`. This repository's CI is GitHub Actions on GitHub, so `cafe ci` - has no runs for it; read logs with `gh run view`. `cafe api` paths omit `/api` (`cafe api /repos/...`). + `cafe pr status` not `pr checks`. `cafe api` paths omit `/api` (`cafe api /repos/...`). ## Choosing a dev process From fa146e8df0f75d5f2eeb6ee4d8ec24094223b6c1 Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Sun, 25 Oct 2026 16:06:23 -0700 Subject: [PATCH 2/3] docs: write GitCafe-safe closing references Co-Authored-By: Claude Opus 5.5 --- docs/operations/development.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/operations/development.md b/docs/operations/development.md index e44c0caf6e849..8be4493505936 100644 --- a/docs/operations/development.md +++ b/docs/operations/development.md @@ -28,6 +28,7 @@ GitCafe. ```sh git remote set-url origin https://git.cafe/pingdotgg/t3code.git git remote add github https://github.com/pingdotgg/t3code.git +gh repo set-default pingdotgg/t3code # for the few `gh` commands below bun install -g @gitcafe/cli # `cafe` needs Bun 1.2 or newer cafe auth login && cafe auth http setup cafe skills install --global # optional: cafe-* skills for coding agents @@ -39,6 +40,8 @@ With `origin` on git.cafe, work through GitCafe and leave GitHub's API alone: `cafe stack submit`, and use `cafe` for everything after that. Link the git.cafe PR URL, not the github.com one, wherever a tool tracks the PR, so polling stays on GitCafe. - Read checks with `cafe pr status `. +- Write closing references as `Fixes pingdotgg/t3code#`. GitCafe turns a bare `#` in text it + syncs to GitHub into a git.cafe link, and GitHub does not close issues from those. - Two things still need `gh`: CI logs and reruns (`gh run view`), and merging, with `gh pr merge --match-head-commit `, because `cafe pr merge` cannot pin the commit you reviewed. From 5222f40887040b54b8ab8a6e8a5b05dff959b37b Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Sun, 25 Oct 2026 16:19:59 -0700 Subject: [PATCH 3/3] docs: name the gh commands for CI logs and reruns Co-Authored-By: Claude Opus 5.5 --- docs/operations/development.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/operations/development.md b/docs/operations/development.md index 8be4493505936..3222b86d17a40 100644 --- a/docs/operations/development.md +++ b/docs/operations/development.md @@ -42,9 +42,9 @@ With `origin` on git.cafe, work through GitCafe and leave GitHub's API alone: - Read checks with `cafe pr status `. - Write closing references as `Fixes pingdotgg/t3code#`. GitCafe turns a bare `#` in text it syncs to GitHub into a git.cafe link, and GitHub does not close issues from those. -- Two things still need `gh`: CI logs and reruns (`gh run view`), and merging, with - `gh pr merge --match-head-commit `, because `cafe pr merge` cannot pin the commit you - reviewed. +- Two things still need `gh`: CI logs and reruns (`gh run view --log`, `gh run rerun`), and + merging, with `gh pr merge --match-head-commit `, because `cafe pr merge` cannot pin + the commit you reviewed. - `cafe` flags differ from `gh`: `--repo` not `-R`, `cafe issue comments ` not `--comments`, `cafe pr status` not `pr checks`. `cafe api` paths omit `/api` (`cafe api /repos/...`).