git-workflow

---
name: git-workflow
description: >-
  Prepare commits, draft or create and update pull requests or merge requests, push branches, merge
  approved requests, resolve merge or rebase conflicts, update existing issues, and clean up
  finished work. Use when completing a logical implementation chunk, resolving conflicts, updating
  an existing issue, cleaning up after merged or abandoned work, or performing Git ref creation and
  publication tasks, including PR titles and descriptions. Skip read-only Git inspection and code
  review.
compatibility: Requires Workmux for worktrees
---

# Git Workflow

Read the repository's contribution instructions before starting, and create worktrees with Workmux while the repository owns rebases and merges.

## Authorization

- **Publish completed changes by default.** For requested work and incidental environment repairs, commit the verified changes on a task branch, push them, and create or update a PR / MR before reporting completion, reusing the task's existing branch and request when appropriate.
- **Clean up finished work by default.** You may remove a merged branch, or an abandoned branch whose commits all exist on a remote, together with its worktree once that worktree is verified clean. You may also delete plans and notes when a closed issue or merged PR / MR confirms the work is complete. Ask before deleting abandoned work with commits missing from every remote, or notes whose completion you cannot confirm.
- **Honor narrower authorization.** Review-only and draft-text-only requests do not authorize publication. Follow instructions to keep work local, avoid pushing, or omit a PR / MR. Create tags and backup refs only when explicitly requested.
- **Get explicit approval before merging each PR / MR.** Blanket approval given earlier does not cover requests opened later in the session. Share the URL and wait for `lgtm` or `merge` referring to that specific PR / MR. The approval covers the request's final head once its pending work is pushed and CI passes, so a head that moves within the approved scope, as [Merging](#merging) defines it, needs no new approval. A request to review and merge authorizes merging each PR / MR covered by the review, including requests opened for its fixes, once every finding is fixed and the fixes are verified.
- **Approve a PR / MR on the user's behalf only when the user explicitly allows it.** Authorization to review or merge a request does not extend to approving it.

## Worktrees

If Workmux or tmux is missing, enter a Nix shell:

```bash
nix shell github:raine/workmux nixpkgs#tmux
```

tmux supplies Workmux's terminal backend.

- Keep the main checkout on the default branch, because several agents may work in the repository at once and editing it or switching its branch can collide with their work.
- Create every task branch, including the coordinator's own, with `workmux add <branch> --name <handle> --headless --json`, and open or hand the session the receipt's `worktree_path`, where Workmux's `worktree_dir` setting puts it. Always pass `--name`, since an `add` without one applies Workmux's configured `worktree_prefix`, which a host may use to mark unattended workers.
- Never run `git worktree add`, since Workmux records the handle, branch, and base in git config.
- To discard an unwanted worktree, use `workmux remove --force <handle>`.

## Ignore rules

- Keep portable generated outputs and project-local private state in repository ignores. Put personal OS, editor, and optional assistant state in the global ignore. Check the configured producer before treating an artifact as optional. Contributor privacy must hold without the maintainer's global excludes.
- Match generated directories wherever their producer can create them. Anchor paths only when the producer fixes their location. A trailing `/` matches directories, leaving same-named files and symlinks visible. Preserve source directories and workflow aliases when ignoring output links.
- Before changing a rule, verify root and nested paths, files, directories, symlinks, and relevant source exceptions with isolated `git check-ignore` cases that disable global excludes.

## Commits

- Commit each logical chunk before moving on, once its fast checks such as pre-commit hooks pass. Push it to the task's PR / MR right away so the user can review and steer early, and run slow checks such as Nix host builds in parallel, fixing any failure in a follow-up commit before asking for merge approval.
- Verify the current branch and inspect the diff, then stage only the intended files or hunks.
- Before discarding a lockfile that a tool regenerated, check whether it corrects a stale lock, as `uv lock --check` reports. Keep a correction, publishing it separately when it falls outside the task.
- Use `type(scope): description` in the imperative mood, with one logical change per commit. Types are `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`, `style`, and `perf`. Infer the scope and granularity from comparable commits.
- For substantial changes, include a body explaining the problem, rationale, and relevant tradeoffs or validation without repeating the subject. Keep the body proportional to the change.
- Name branches `<type>/<short-name>` using the same types, and keep an appropriate existing branch.

## Pull / merge requests

### Repository conventions

- Before drafting, learn the conventions for titles, body structure, assignees, and labels from the PR / MR template and recent comparable, human-authored requests. Prefer those closest in scope and size, broaden the sample when they do not cover the change, and follow explicit repository rules where examples differ.
- Record the chosen examples and the conventions they show, including heading names, hierarchy and order, prose or list structure, and validation format, and include these notes in any brief.
- Infer assignees from comparable requests, checking the authenticated identity when the convention is self-assignment.
- Match labels to established usage and the available labels' descriptions. Commit types can inform the choice but do not imply a fixed label mapping.
- If metadata remains ambiguous, choose the closest established match, record the choice, and ask the user to confirm it in the next report. Never invent a rule or silently omit metadata.
- Keep each request focused on one purpose. Put unrelated changes, including dependency or lockfile churn, in separate requests, and fix every occurrence of the same problem within a repository in one request.

### Description

Write within the recorded structure for reviewers who have not seen the conversation, without repeating a point across its sections.

- Open with the concrete problem or goal and the resulting behavior.
- Give reviewers what they need to assess the change, such as rationale, tradeoffs, measurements, or migration steps.
- Report each check you ran on the final head with its result, distinguishing verified behavior from untested limits. Give only the output a reviewer needs to trust it, without commit SHAs or incidental store paths and hashes.
- Update the description without asking whenever later pushes, including review fixes, change what it should say, without widening the scope of a merge approval already given. Omit implementation history, such as commit inventories, rebase proofs, and abandoned approaches, unless it explains a current tradeoff, and omit boilerplate sections, generated-by attributions, and emojis unless requested.
- Keep local-only paths and internal information, including internal URLs and plain-text references, out of commits and descriptions.

### Publication

- Rebase task branches onto the current target branch whenever integrating upstream changes. Never merge the target branch into a task branch or use an Update branch action.
- Coordinate exclusive ownership before rewriting a shared or bot-managed branch. Until ownership is established, publish fixes as new commits and use `git revert` for pushed changes. Before rebasing a published branch, verify that the observed remote head is an ancestor of the local tip. Push rebased history with `--force-with-lease=refs/heads/<branch>:<observed-remote-head>`. If the lease fails, inspect and integrate remote changes before retrying. Never use a blind force push.
- Before pushing, verify the base branch, diff, and commit count. Before creating or updating a request, compare its complete title and body with the recorded conventions and fix any difference.
- After pushing `HEAD:refs/heads/<branch>` from a detached worktree, synchronize the owned local branch to the published head. Fast-forward when possible. After a rebase, verify that no other worktree or agent owns the branch, then use `git update-ref refs/heads/<branch> <published-head> <pre-rebase-local-head>`. If the expected old tip changed or another worktree owns the branch, coordinate with its owner before updating it.
- If asked only to draft a title and body, return the text without publishing. A request for a draft PR / MR authorizes publishing it as a draft.
- Set assignees and labels when creating a request. If no existing label fits, create one that follows the repository's label scheme.
- Pass multiline bodies through a file or structured argument, such as `gh pr create --body-file <file>`.
- Use `#N` for issues and GitHub PRs in the same repository, and `!N` for GitLab MRs.
- Read back each created or updated request, verifying its title, body, base, diff, assignees, and labels, and fix anything lost before reporting completion.
- Request review once per PR / MR. Fix every finding, including suggestions, and verify the fixes without re-requesting review after later pushes. Merge with the approval required by [Authorization](#authorization).
- Finalize the title and body before merging, since a squash merge can copy them into the commit message, as GitHub's PR_BODY default and a GitLab `%{description}` template do, and an edit afterwards cannot change it.
- For an approved merge, delegate to the `operator` agent when one is available, once the branch owner reports its pending work pushed. Its spawn prompt quotes the user's approval verbatim and gives the approved head SHA, the final head SHA, the title and description at approval, the review findings or fix list, and the user's follow-ups on the request. Have it follow [Merging](#merging).
- Stack a request that depends on or overlaps another open request on that request's branch, and name the base request in the description. Keep dependent requests in one stack of at most three unmerged requests, and once three are open, land the bottom one before opening another. After the base squash-merges, run `git rebase --onto <default-branch> <old-base-head> <branch>` to drop its pre-squash commits, then retarget the request to the default branch if the forge has not.

### Merging

1. Confirm that the remote head equals the final head SHA, which is the approved head when no work was pending, and that the forge reports the branch as mergeable there. If the two heads differ, run `git range-diff <target>..<approved-head> <target>..<final-head>` and check each new or changed commit against the approved scope. A commit is out of scope if it touches paths outside `git diff --name-only <target>...<approved-head>` or adds behavior that none of the quoted title, description, findings, fixes, or follow-ups covers, and a commit presented as a review fix must match a quoted finding. Stop and report on a head mismatch or an out-of-scope commit.
2. Wait for CI to pass on that head. On GitHub, first wait (bounded) until `gh pr view <n> --json headRefOid,statusCheckRollup` shows that head with at least one check, because right after a push or branch update `gh pr checks` fails with `no checks reported` until GitHub registers the new head's checks.
3. On GitHub, next wait for `gh pr checks <n> --watch --fail-fast`, then (bounded) for `gh pr view <n> --json mergeStateStatus` to read `CLEAN`, because some required checks, such as Codecov, are created only after the others finish.
4. If `mergeStateStatus` reads `BEHIND`, refresh the target branch and rebase the request branch onto it, following the ownership and push safeguards in [Publication](#publication). Repeat steps 2 and 3 on the new head.
5. Merge with the repository's merge method at that head, such as `gh pr merge <n> --squash --match-head-commit <sha>`. Never pass `--auto`, and pass `--admin` only where the repository documents it.
6. After the merge, verify the remote state and confirm CI passes on the target branch. For GitHub squash merges, keep GitHub's default commit message. Report a merge queued by GitLab's default auto-merge as pending until it lands.

## Conflict resolution

Read the upstream PR / MR or commit message and the surrounding code to learn each side's intent, integrate both so each purpose survives without duplication or contradiction, keep local ordering conventions such as sorted lists and section order, then rerun the checks covering the conflicting files.

## Issues

- **Description**: The current specification, covering the goal, acceptance criteria, decisions and scope, dependencies, and findings that shape the work. Edit it in place, marking criteria as they are met, so it shows the current state on its own.
- **Comments**: Only events watchers need, such as why an issue closes without a linked PR / MR or reopens, questions or discussion that need a reply, and brief pointers to material scope changes in the description. Skip progress updates and anything a linked PR / MR already shows.
- **Working notes**: Execution details, such as agent assignments, worktrees, in-flight branches, and private context, stay in the session or a gitignored plans directory.
- **Existing comments**: Fold a decision or finding that belongs in the spec into the description, and delete the comment only once the description covers everything it says.

Pass an edited body through a file or structured argument, then read the issue back.

## Cleanup

When work finishes, clean up within the authorization above, and include the cleanup in the operator's spawn prompt after an approved merge when an `operator` agent is available.

- Use the `clean-gone` skill to remove finished local branches and worktrees.
- Delete a remote branch only when explicitly requested.
- Delete completed plans and working notes from the plans directory, such as a gitignored `.agents/plans/`. Rewrite stale notes to show only the current state and remaining work.
- Each agent removes the scratch copies and build directories it created, such as `git archive` exports and their `CARGO_TARGET_DIR`s under `/tmp`, and names in its report anything it leaves for someone else.

• SKILL.md 14 KB
• agents/openai.yaml 1 KB