---
name: git-workflow

description: >
  Use when a human's local git request is general or ambiguous — it routes to the owning
  domain skill: `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules`
  or `git-worktrees`. An unambiguous request goes straight to its domain skill instead. Not an
  agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.

metadata:
  category: git
  source_keys:
    - nvie-gitflow-post
    - atlassian-gitflow-tutorial
    - gitflow-cheatsheet
    - context7-git-htmldocs
    - org-git-conventions
---

## Gotchas

- Session context built during one multi-step request — branch names, the chosen base, the commit
  strategy — persists for that request and then clears. Do not re-ask the user for a decision they
  already gave you earlier in the same workflow.
- Run parent-repo commands through `rtk git <command>`, never bare `git <command>`. This is a
  mandated org wrapper, not a style preference. Submodule-specific commands run from inside the
  submodule's own directory instead.

## Domains

Every request resolves to exactly one of these six. An unambiguous one should have gone straight
to the domain skill; this skill exists for the ones that did not.

| The request is about | Domain |
|---|---|
| Writing, amending, squashing, or cherry-picking a commit, and its message | `git-commits` |
| Creating, switching, deleting, renaming, tracking, or merging a local branch | `git-branches` |
| When a change landed, which commit broke something, what to revert or backport | `git-history` |
| Anything touching a remote — remote config, fetch, push, pull — even unnamed | `git-remotes` |
| A nested repository pinned inside this one by a recorded commit | `git-submodules` |
| Several branches checked out at once, in separate directories, without stashing | `git-worktrees` |

`git-orchestrate` executes whatever this resolves to (step 5); the table only decides which domain
owns the request.

## Workflow

1. **Parse intent** — extract the operation and, from the table above, the domain that owns it,
   plus any options the user named.
2. **Check the hard rules** — if the request creates, amends, or rewrites a commit, pushes, or
   touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule
   before acting, not after.
3. **Read the repo** — current branch, working-tree state, and which branching model the repo
   follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names
   if absent); the last of those decides which tips are worth offering.
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
   force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
   declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
   confirmations: never offer "Proceed?" for a force-push of `main` or `master`.
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
   inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
   destructive op the user approved in step 4.
6. **Clarify when the orchestrator asks for more** — put its question to the user in plain
   language ("Which branch should this be based on?") and loop back to step 5 with the answer.
7. **Report the outcome** — on success, the result and what changed, in plain language; on
   failure, the error reason and a recovery action.

## Interaction style

The caller is a human, so the interaction is the point. Explain each step and why it happens ("I'm
squashing your last 3 commits into one clean commit" beats "Squashing commits"), show progress as
you go, and prefer natural language to raw command lines.

Match tips to the repo's branching model rather than offering generic advice: on a Gitflow repo,
feature branches come off `develop` and `main` tracks only released code; on a trunk-based or
GitHub Flow repo, short-lived branches off `main` keep merges small and reviewable.