| 1 | ## Working on g1t |
| 2 | |
| 3 | This repository is on g1t. Other agents and people may be working in it at |
| 4 | the same time; the `g1t` CLI is how you see them and how they see you. |
| 5 | |
| 6 | - When you start, record a session titled with what you were asked to do: |
| 7 | `g1t session start --harness codex --title "Fix the preview builds"` |
| 8 | (or `cursor`, `copilot`, `other`: the harness you are). The CLI remembers |
| 9 | it for this working copy. Run `g1t session heartbeat` every few minutes |
| 10 | while you work, and `g1t session end` when you stop. |
| 11 | - With no issue, just work: the session shows to the team. When the work |
| 12 | becomes a change others should know about (a branch to push, a pull |
| 13 | request), look for its issue (`g1t work list`, `g1t issue list`) and |
| 14 | claim it; if there is none, open and claim one with |
| 15 | `g1t work claim --title "TITLE"`. Never open issues for questions, |
| 16 | exploration or trivial fixes. |
| 17 | - Before working on an issue, load it with `g1t work context N`: its |
| 18 | definition of done, who has claimed it, its pull requests, checks and |
| 19 | overlaps, and what blocks it. Then claim it with |
| 20 | `g1t work claim N --note "what you are about to do"`. If someone else |
| 21 | holds a claim, say so before going on. |
| 22 | - Work on a branch whose name starts with the issue number |
| 23 | (`42-short-description`), and open a draft pull request early: |
| 24 | `g1t pr create --issue N --draft --fill`. |
| 25 | - Log decisions worth keeping with `g1t session log --kind note "TEXT"`. |
| 26 | Never log secrets or command output. |
| 27 | - Run the repository's tests before each push, and watch the checks with |
| 28 | `g1t pr checks --watch --fail-fast` (and `g1t run logs --failed` for why |
| 29 | one failed). When the merge queue reports an integration failure, read |
| 30 | it with `g1t work events --type integration.failed --issue N`, diff the |
| 31 | other pull requests in the combination (`g1t pr diff OTHER`), fix, push |
| 32 | and merge again. |
| 33 | - If you stop before the issue is done, hand it off: |
| 34 | `g1t work handoff N --note "what is done, what is left"`. |