git-workflow · diff
v1.0.1 to v1.1.1
81 added, 1 removed. Audit A to A.
---
name: git-workflow
description: >-
Git workflow skill: branching strategies, Conventional Commits, creating or reviewing
PRs, resolving PR review comments, merging PRs (CI verification, auto-merge queues,
post-merge cleanup), PR review threads, signed commits, merge conflicts, Git+CI/CD
integration, git hooks (lefthook, captainhook, husky, pre-commit), debugging
hook-install failures in git worktrees, and GitHub release creation rules. Use when
merging stalls on failing checks or unresolved review threads, when a hook fails to
install in a worktree, when writing commit/branch/tag conventions, or when creating
a GitHub release. NOT for: diagnosing BLOCKED project-workflow PR states; no skill
name implied.
slug: git-workflow
- version: 1.0.1
+ version: 1.1.1
displayName: git-workflow
---
# Git Workflow Skill
+ ## When to Use / How to Invoke
+
+ Invoke explicitly by name when any of these is true (do not self-trigger on ordinary git chatter):
+
+ - "merge is blocked on failing checks / unresolved review threads" → load `references/pull-request-workflow.md`.
+ - "hook won't install / fails in a worktree" → load `references/git-hooks-setup.md`.
+ - writing commit / branch / tag conventions → `references/commit-conventions.md`.
+ - creating a GitHub release → `references/release-rules.md`.
+
+ Invocation form: `use git-workflow: <what you need, e.g. "merge PR #42 after CI passes">`. If invoked without arguments, ask which of the trigger scenarios above applies before loading references.
+
+ **NOT for (observable boundaries):**
+
+ - Not a git repository (no `.git/` where `pwd` points) → stop; this skill has nothing to act on.
+ - Diagnosing BLOCKED project-workflow PR states → that is a workflow-state issue, not a git operation; no skill name implied.
+ - No network / GitHub unreachable: all local operations (branches, commits, rebase, hooks, `verify-git-workflow.sh`) still work; defer PR/release steps and say which command failed on connectivity.
+ - Wrong repo (the repo you are in is not the one the user named) → verify with `git remote -v` before any write operation; abort on mismatch.
+
+ ## Quick-Start Example
+
+ Precondition: you are in a feature-branch repo with a PR waiting on CI.
+
+ Invocation:
+
+ ```text
+ use git-workflow: PR #42 is green, merge it per the merge gate
+ ```
+
+ What happens / typical output excerpt:
+
+ ```text
+ Loaded references/pull-request-workflow.md.
+ Merge gate: threads resolved ✓ · CI green ✓ · rebased onto main ✓ · signed ✓
+ → git fetch origin && git rebase origin/main
+ → git push --force-with-lease origin feature/TICKET-42
+ → git merge --ff-only main (or via platform merge button)
+ ```
+
+ Local-only check (no PR needed):
+
+ ```bash
+ ./scripts/verify-git-workflow.sh /path/to/repository
+ ```
+
+ Output excerpt: `✅ All branch names follow conventions` / `⚠️ Non-standard branch names found: ...`. Exit code 0 when the checks ran (warnings are counted and reported, not fatal); exit 1 when the path is not a git repository (`❌ Not a git repository`).
+
## Critical Rules (Non-Negotiable)
1. **No direct push to main** — always open a PR.
2. **No merge before all threads resolved** — see `references/pull-request-workflow.md`.
3. **No squash unless asked** — preserves atomic commits, signatures, bisection.
4. **No "tested/verified/working" without pasted command output** — else say so.
5. **No edits to installed skill/plugin cache paths** (`~/.claude/skills/`, `~/.claude/plugins/cache/`, `**/.bare/**`) — always the repo worktree, verified by `pwd`.
6. **Force-push only with `--force-with-lease`** — never plain `--force`.
7. **Commit before rebase** — `add → commit → fetch → rebase → push`. Dirty tree aborts rebase.
8. **No editorializing** — state what changed, not how good it is; no narrating expected results or self-praise. See `references/no-editorializing.md`.
See `references/pull-request-workflow.md` for merge-gate and atomic-commit patterns.
## Reference Files
Load on demand:
| Reference | Content Triggers |
|-----------|-----------------|
| `references/commit-conventions.md` | Conventional commits, DCO sign-off |
| `references/pull-request-workflow.md` | Default-branch check, PR merge, merge gate, signed rebase |
| `references/ci-cd-integration.md` | Watching CI from the CLI, git mirror repositories |
| `references/advanced-git.md` | Rebase, cherry-pick, bisect, stash, worktrees, reflog, recovery |
| `references/release-rules.md` | GitHub releases: immutable tags and tag reuse, Latest badge, pre-create checks |
| `references/git-hooks-setup.md` | Hook frameworks, detection, hooks per stage |
| `references/claude-code-hooks.md` | Claude Code `settings.json` hooks — merge gate, cache-path rejection, auto-lint |
| `references/code-quality-tools.md` | shellcheck, shfmt, git-absorb, difftastic |
| `references/merge-gate-watcher.md` | Merge-driver loop, check taxonomy, stale-SHA rerun, review-bot rounds |
| `references/spec-cleanup.md` | Keep planning artifacts off the base branch; guard + capture-to-ADR |
| `references/no-editorializing.md` | Writing without self-praise or narrating the expected |
## Conventional Commits
```
<type>[scope]: <description>
```
**Types**: `feat` (MINOR), `fix` (PATCH), `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
**Breaking change**: Add `!` after type or `BREAKING CHANGE:` in footer.
## Branch Naming
```
feature/TICKET-123-description
fix/TICKET-456-bug-name
release/1.2.0
hotfix/1.2.1-security-patch
```
## Hook Detection
Detect hooks first:
```bash
ls lefthook.yml .lefthook.yml captainhook.json .pre-commit-config.yaml .husky/pre-commit 2>/dev/null || echo "No hooks"
```
Install: `lefthook install` | `composer install` | `npm install` | `pre-commit install`
## Critical Release Rules
1. **Immutable releases**: deleted releases block tag reuse; bump version.
2. **Multi-branch releases**: Use `--latest=false` from non-default branches.
3. **Pre-release**: Version bumped, CI green, CHANGELOG updated, `git pull` BEFORE `gh release create`.
## PR Merge Requirements
Before merging: threads resolved, CI green (incl. annotations), rebased, signed. Rebase-only + signed: `git merge --ff-only`.
## Verification
```bash
./scripts/verify-git-workflow.sh /path/to/repository
```
+
+ - Argument: repository path (default `.`). No flags.
+ - Exit 0: checks ran (fix reported ⚠️ warnings before opening/merging a PR).
+ - Exit 1: target is not a git repository — check `pwd` and the path argument.
+
+ ## Failure Exits
+
+ | Symptom (observable) | Way out |
+ |----------------------|---------|
+ | `❌ Not a git repository` from the verify script (exit 1) | Wrong path or wrong directory; run `pwd` + `git remote -v`, rerun with the correct repo path |
+ | `fatal: not a git repository` from any git command | Same as above — never `git init` to make the error go away |
+ | Hook install prints nothing / `echo "No hooks"` fired (see Hook Detection) | No hook framework configured; pick one from `references/git-hooks-setup.md` first, then install |
+ | Push rejected (non-fast-forward) | Do **not** plain `--force`; commit local work, `git fetch`, `git rebase`, then `git push --force-with-lease` |
+ | Rebase aborts with dirty tree | Rule 7: `git add → git commit` (or `git stash`) first, then rebase |
+ | `gh release create` fails on existing tag | Releases are immutable — bump the version, never reuse the tag (see Critical Release Rules) |
+ | Network timeout on `git fetch` / `gh` | Finish all local steps, then retry the remote step once connectivity is back; state which step is pending |
+
+ ## 中文速览（Quick Guide）
+
+ - **做什么**：覆盖分支策略、Conventional Commits、PR 创建/评审/合并、git hooks 安装排障与 GitHub 发布规则的实操指引，按触发场景加载对应 references。
+ - **何时用**：合并被失败检查或未解评审线程卡住、hook 在 worktree 装不上、写提交/分支/标签规范，或建 GitHub release 时。
+ - **核心步骤**：①`git remote -v` 确认在正确仓库 ②按触发场景选参考文件 ③本地操作（分支/提交/rebase/钩子） ④PR 合并走 CI 验证 ⑤发布遵循不可变 tag 规则。
+ - **国内可达性**：本地 git 操作全部离线可用；`gh`/GitHub PR/release 步骤依赖 GitHub，网络不通时先完成本地步骤并注明待远端的一步（正文 Failure Exits 已给此出口）。
+
+ ## FAQ / Wrong Way → Fix
+
+ | Wrong way | Fix |
+ |-----------|-----|
+ | `git push --force` because "it's my branch" | `--force-with-lease` only; plain force can eat teammates' commits |
+ | Squashing by default for a "clean history" | Don't squash unless asked — it destroys atomic commits, signatures, bisectability (Rule 3) |
+ | Saying "tested and working" without pasting output | Paste the command output or say it's unverified (Rule 4) |
+ | Editing skills under `~/.claude/skills/` or `**/.bare/**` | Always edit the repo worktree; verify with `pwd` (Rule 5) |
+ | Self-triggering this skill for any git question | Only for the named trigger scenarios; otherwise answer inline without loading references |
+ | Merging with unresolved review threads because CI is green | Threads-resolved is a hard gate — resolve or get explicit waiver first (Rule 2) |
---
> **Contributing:** <https://github.com/netdelegated-research/git-workflow-skill>