holocron/plugins/git/.apm/skills/git-workflow/SKILL.md

name, description, metadata

name	description	metadata
git-workflow	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`.	version category source_keys 1.0.1 git 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

Route to the domain that owns the operation, and in sequence when a request spans two — a rebase that ends in a force-push is git-commits, then git-remotes. An unambiguous request should have gone straight to the domain skill; this one 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
Rebasing onto a new base, or undoing a commit with reset	git-commits
Creating, switching, deleting, renaming, tracking, or merging a local branch	git-branches
Stashing work in progress to move between branches	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 (git-branches infers this from branch names: Gitflow if develop/release/* exists, GitHub Flow otherwise); 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.