| 1 | --- |
| 2 | name: work-on-item |
| 3 | description: Work on a g1t work item from start to merge. Use when asked to work on, fix, implement or pick up a work item (or an old issue) in a g1t workspace or repository (a number such as #42, or a g1t.sh work item link). |
| 4 | argument-hint: "[work item number]" |
| 5 | allowed-tools: Bash(g1t:*) Bash(git:*) |
| 6 | --- |
| 7 | |
| 8 | # Work on a g1t work item |
| 9 | |
| 10 | The work item is the work: its description says what is wanted, its |
| 11 | "Definition of done" and each repository's required checks say when it is |
| 12 | done, its target repositories say where it has to land, `blocked_by` lists |
| 13 | what must land first, and its pull requests are the attempts. A work item |
| 14 | belongs to the workspace, not to one repository, and its number is unique |
| 15 | in the workspace. Other agents and people may be working on it at the same |
| 16 | time; claims and events are how you stay out of each other's way. Every |
| 17 | `g1t` command takes `--json` when you need fields rather than text. |
| 18 | |
| 19 | Work item: $ARGUMENTS (if empty, ask which work item, or list open ones with `g1t work list`). |
| 20 | |
| 21 | If the work you were asked for has no work item yet and has become a |
| 22 | change others should know about, look for one first (`g1t work list`). If |
| 23 | there is none, `g1t work claim --title "…"` (with `--body "…"` for the |
| 24 | details) opens it in this repository's workspace and claims it for this |
| 25 | session in one step, attaching the session to it: start at step 4 with |
| 26 | its number. Questions, exploration and trivial fixes need no work item; |
| 27 | the session is already recorded on g1t. |
| 28 | |
| 29 | 1. **Load the context.** Run `g1t work view N`. It shows the work item and |
| 30 | its definition of done, the repositories it is linked to (its origin, |
| 31 | its targets and the ones already touched) and which of them have |
| 32 | landed, who has claimed it, the sessions and pull requests already on |
| 33 | it with their checks and overlaps, what blocks it, what it blocks, the |
| 34 | decisions recorded so far and the last integration failure. Read all |
| 35 | of it before you change anything. |
| 36 | 2. **Check it is free to start, and who else is on it.** |
| 37 | - Its sessions include subagents: if you are one of several agents on |
| 38 | this work item (siblings started by the same session, or other |
| 39 | people's), run `g1t session list --item N --subagents` and read what |
| 40 | each is doing and has touched (`g1t session view ID`). Take a part |
| 41 | nobody has, and say which in your claim's note. Before editing a |
| 42 | shared file, `g1t session list --path FILE` says who else touched it. |
| 43 | - If it is blocked by work items that are still open, say so and stop |
| 44 | unless you are asked to go on anyway. |
| 45 | - Another claim does not block complementary work. Compare scopes and |
| 46 | proceed on a separate part (another target repository is a natural |
| 47 | one). If scopes or interfaces overlap, record an agreement about |
| 48 | ownership or order before editing that part. |
| 49 | - If a pull request for it is already open in this repository, prefer |
| 50 | continuing that one (`g1t pr checkout NUMBER`) over starting another. |
| 51 | - If it has no target in this repository yet and the work belongs here, |
| 52 | link it: `g1t work link N --role target`. |
| 53 | 3. **Claim it with a concrete scope.** Use a note containing `Scope:` |
| 54 | (repositories, files, components), `Interfaces:` (contracts you |
| 55 | change), `Depends on:` (work that must land first), and `Checks:` (how |
| 56 | you will verify it): |
| 57 | `g1t work claim N --note "Scope: ...; Interfaces: ...; Depends on: ...; Checks: ..."`. The |
| 58 | claim belongs to this session (a subagent's to its own session) and is |
| 59 | renewed while the session is active. Its answer lists the other claims |
| 60 | on the work item, siblings' included: read them. If g1t later reports |
| 61 | an overlap (`overlap.detected`) with another session, agree who changes |
| 62 | the file before going on; `g1t work events --follow --item N` keeps |
| 63 | you told. |
| 64 | Without the CLI, g1t's MCP server does the same: `work_item` with action |
| 65 | `work`, `claim` and `release`, and `session` with action `list`. |
| 66 | 4. **Branch.** From an up-to-date default branch, make a branch whose name |
| 67 | starts with the work item's number, such as `42-short-description`, so |
| 68 | the session and the next one know which work item it is for. |
| 69 | 5. **Open a draft pull request early**, as soon as there is a first commit: |
| 70 | `g1t pr create --item N --draft --fill`. Others then see your changes, |
| 71 | and g1t tells you when they overlap with someone else's. |
| 72 | 6. **Do the work.** Commit in small steps and push often, with the |
| 73 | trailer `G1t-Session: $G1T_SESSION` on each commit |
| 74 | (`git commit --trailer "G1t-Session: $G1T_SESSION"`) so g1t ties the |
| 75 | commits to this session. Run the same |
| 76 | tests and linters the repository's workflows run before each push. Log |
| 77 | a decision worth keeping with `g1t session log --kind note "TEXT"`. |
| 78 | 7. **Watch the checks.** `g1t pr checks --watch --fail-fast`. When one |
| 79 | fails, `g1t run logs --failed` says why; fix it and push again. |
| 80 | 8. **Finish.** When this repository's part is done and the checks pass, |
| 81 | `g1t pr ready --summary "what changed and why"` (add a screenshot with |
| 82 | `--attach shot.png`, or upload one with `g1t attach FILE` and paste the |
| 83 | Markdown it prints; never commit an image just to link it), then |
| 84 | `g1t pr merge` when you are allowed to merge. With the merge queue on, merging adds the |
| 85 | pull request to the queue; if the queue reports an integration failure, |
| 86 | use the `fix-integration` skill. The merge marks this repository as |
| 87 | landed on the work item, and the work item closes once every target |
| 88 | repository has landed (or at once, when it has no targets). A pull |
| 89 | request that does only part of this repository's share says |
| 90 | `Part of #N` in its description instead, and lands nothing. Where you |
| 91 | commit straight to the default branch instead, the commit that finishes |
| 92 | this repository's part says `Closes #N` in its message (`Fixes` and |
| 93 | `Resolves` work too); a bare `(#N)` only links the work item, and it |
| 94 | stays open. |
| 95 | 9. **Let go.** If you stop before it is done, hand it off rather than |
| 96 | leaving a claim to expire: `g1t work handoff N --note "where it stands, |
| 97 | what is left, what to watch out for"`. Name any target repository it |
| 98 | has not landed in yet. |