Git Workflows - Git Development Guide
Unified workflow guidance across workspace isolation, commit hygiene, and work completion.
1. WHEN TO USE
When to Use This Guide
Use this guide when starting new git-based work, following a complete git workflow (setup, work,
complete), unsure which git skill to use, or seeking git best practices (branch naming, commits).
When NOT to Use
- Simple
git status/git log queries (use Bash directly)
- Non-git version control systems
Keyword Triggers
Owned: git worktree, worktree, create worktree, numbered worktree, restructure worktrees, worktree prefix, wt/ branch, worktree branch,
branch naming allocator, skilled branch, branch, commit, conventional commits, pull request, pr, pr review, merge, rebase,
finish work, integrate changes, git workflow, github, issue, gitkraken, gitlens, gitlens launchpad, commit composer
Not owned: spec folders / memory / continuity / save context → system-spec-kit. Code implementation / writing tests → sk-code.
2. SMART ROUTING
sk-git is a standalone skill, so the skill advisor scores its owned keywords against the request and selects it here.
A request that names a worktree, a commit, a pull request, a merge, a finish, GitKraken or GitLens lands here,
while spec folders and code implementation belong elsewhere.
references/quick-reference.md loads first on every invocation, then the winning intent loads its phase reference.
references/gitkraken-mcp-integration.md follows for GitKraken and GitLens,
and references/shared-patterns.md carries what every phase shares.
A request whose scores stay near zero loads the shared patterns and asks a disambiguation checklist instead of guessing.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Workspace Choice Enforcement
MANDATORY: The AI must NEVER autonomously choose between a git worktree and the current branch, and must NEVER create a branch directly with git branch, git checkout plus -b, or git switch plus -c.
When a git workspace trigger fires, the AI MUST ask the user to explicitly choose:
| Option |
Description |
Best For |
| A) Create a git worktree |
Isolated workspace in separate directory |
Parallel work, complex features |
| B) Work on current branch |
No new worktree created |
Trivial changes, exploration |
AI Behavior: ASK before proceeding, WAIT for explicit selection (A/B), NEVER assume, RESPECT choice for the session unless the user requests a change. Create any needed branch only through git worktree add -b ....
Launch-Wrapper Worktrees vs the In-Session Ask-First Rule
The ask-first rule above governs in-session decisions: once running, an AI must not autonomously create a worktree.
.skilled/bin/worktree-session.sh is a launch wrapper you opt into at the shell, and it is different. It runs before the AI starts, so it does not violate the ask-first rule. It places each top-level session in its own worktree + branch + isolated MCP databases, and it execs in place for an orchestrated child with AI_SESSION_CHILD=1 or for a session already inside a linked worktree.
Deliberate per-session deps override. The wrapper symlinks the shared node_modules/dist into each worktree and gives each its own MCP DBs (via SPEC_KIT_DB_DIR / SPECKIT_IPC_SOCKET_DIR), rather than paying an install per session.
Known gap. Wholesale-linked dependency trees mean a wrapper session reads the main checkout's first-party code, which is why strict-validate and metadata regeneration run on main. Detail: worktree-workflows.md §10.
Continuous Integration: the always-current live branch
Each launch-wrapper session autosyncs every commit to one shared live branch, the primary checkout's own branch. The IDE fast-forward-follows it, so you see active work seconds behind each commit and never an uncommitted buffer.
Configured by SPECKIT_LIVE_BRANCH, SPECKIT_AUTOSYNC, the post-commit publish through git-sync.sh and its non-force fetch → rebase-or-abort push: continuous-integration.md.
Remote Push Permission Enforcement
MANDATORY: The AI must NEVER push a branch to origin outside the remote allowlist without a fresh, explicit go-ahead for THAT push. Allowlist, what counts as a go-ahead, SPECKIT_ALLOW_REMOTE_PUSH, the pre-push hook backstop and the launch-wrapper autosync exception: remote-branch-policy.md.
Preflight Advisory: the rules reach you at command time
- The rules in
hard-rules.json beside this file are executed, not just documented.
- A preflight advisory hook evaluates every visible
git command against live repository state, and fires on the specific risky state rather than a bare verb.
- It prints the matching rule as typed, advising and never blocking.
- The pre-commit, commit-msg and pre-push hooks enforce.
The seven repository runtimes and the dsh run surface share it. SKGIT_ADVISORY=0, SKGIT_ADVISORY_SKIP=<rule-id> or a
SKGIT_ADVISORY_SKIP=commit-style prefix silences it. Delivery and fail-open:
scripts/hooks/README.md. Rule engine and tests:
scripts/lib/README.md. Operator scenario:
manual-testing-playbook/.
Repository Settings: /doctor:git
A repository adapts sk-git through git config and .sk-git/, never by editing this skill.
/doctor:git (.skilled/commands/doctor/git.md) changes and checks those settings:
hooks switches an optional pre-commit or pre-push gate on or off.
standards copies the commit, PR and branch rule templates into .sk-git/ and edits them.
setup runs eleven read-only checks and names one repair per failure.
When asked whether sk-git is set up or why a rule is not enforced, run /doctor:git setup before reading config by hand.
Git Development Lifecycle Map
Git development flows through 3 phases:
| Phase |
Goal |
Prevents |
Output |
See |
| 1. Workspace Setup |
Isolate work in a short-lived temp branch |
Branch juggling, stash chaos |
Clean, focused workspace |
worktree-workflows.md |
| 2. Work & Commit |
Analyze changes, filter artifacts, write Conventional Commits |
Bad commits, unclear history |
Clean commit history |
commit-workflows.md |
| 3. Complete & Integrate |
Merge, create a PR, or discard work (tests-gated) |
Untested code merged |
Work integrated or discarded |
finish-workflows.md |
Phase Transitions
Setup (worktree created) → Work → Complete (committed, tests passing) → back to Setup (integrated).
Workflow Selection Guide
- New feature/fix → Phase 1. Quick fix → Phase 2.
- Ready to commit → Phase 2. No changes yet → keep coding.
- Tests pass → Phase 3. Failing → return to Phase 2.
Common Workflow Patterns
- Full: all 3 phases.
- Quick fix: skip Phase 1.
- Parallel: repeat Phases 1-2 per feature, then Phase 3 for each.
4. RULES
✅ ALWAYS
- Use deterministic conventional commit format - All authored commits follow
type(scope): summary. Preserve the explicitly exempt Git-generated subjects defined below
- Create worktree for parallel work - Never work on multiple features in the same worktree
- Verify branch is up-to-date - Pull latest changes before creating PR
- Name worktree-created branches with the numbered-worktree grammar -
worktrees/{NNN}-{slug} for a worktree-backed branch, branches/{NNN}-{slug} for a dedicated branch with none.
- Each namespace counts 001..999 independently, sequential, never skipped or reused.
- Never hand-compute
{NNN}. Allocate through .skilled/skills/sk-git/scripts/worktree-naming.sh (create, create-branch or allocate), which locks and seeds each counter from its high-water mark plus every matching ref.
- The script header carries the full grammar, the relocatable
{base} rule and the reserved skilled/v*, main and backup/ lanes.
- This is distinct from the launch wrapper's unnumbered
work/{runtime}/{slug} lane (see above).
- Reference the spec packet in a
Spec: trailer - Put the packet path in a Spec: trailer shaped Spec: <track>/<packet>[/<phase>...]: the packet's path below specs/, with nested phases included and without the specs/ segment itself.
- The packet query is anchored on that line,
git log -E --grep='^Spec: your-track/your-packet', so a leading specs/ makes every commit for that packet unfindable.
- Omit the line when the commit is not packet work.
Refs: is for external links only: issues, pull requests and URLs.
- Clean up after merge - Delete local and remote feature branches after successful merge
- Squash commits for clean history - Use squash merge for feature branches with many WIP commits
- Provision a worktree before you trust anything it reports - Every dependency tree here is gitignored, so a fresh worktree has none of them and fails in ways that read as broken code. A build can exit 0 having compiled nothing, and a hub-conformance check that copies a skill into a temp directory loses that skill's dependencies and reports a correct hub broken.
worktree-naming.sh create installs them, and --no-provision opts out. worktree-naming.sh provision [dir] fixes a worktree made another way. Both are idempotent.
- Both also recreate the operator's private
local-* commands from the primary checkout in the form it holds them, a file as a copy, a relative link as the same link and a folder as one shared link, because git ignores them and a new worktree would otherwise start without them. An existing path is never replaced.
provision rebuilds a listed build output when it is missing or when its tracked sources changed since provisioning last built it, so it also refreshes a checkout whose built plugin went stale after a pull.
- Provisioning installs by default, but what binds is narrower than the technique: no path shared into a worktree may resolve a repository-internal reference back to the source checkout.
- Two mechanisms break that, and each has its own remedy. A package's
node_modules carries relative workspace self-links that re-anchor through wherever the link physically sits, so a wholesale link leaves the worktree reading the source checkout's code however much it edits its own.
- Share such a tree by linking its third-party entries individually and recreating each self-link relative to the worktree's own copy.
- The second mechanism is a compiled entry point reached through a link. It compares the path it was invoked with against the location it derives from its own file, finds them different, and exits 0 having done nothing. Invoke such a script by its canonical path, or give the worktree its own build.
- A dependency tree that does neither may be linked wholesale.
worktree-naming.sh provision installs, which satisfies the invariant the blunt way.
- On a large reorg, still do file/
git mv ops in the worktree and run the spec-kit toolchain and ALL metadata regeneration on main after merge. See large-reorg-playbook.md.
- Scan for gitignored leftovers after a rename wave - After
git mv + merge, detect dirs with disk files but 0 tracked files (git ls-files <dir> empty, git status --porcelain --untracked-files=all clean) and rm -rf them, stale cruft left by git mv.
- Verify rename history is preserved - After a rename wave confirm
R-status (not delete+add) before commit, and after merge confirm the tree has no old+new duplicate folders.
- GitHub release bodies never start with an H1 - The release title field already renders
vX.X.X.X — Title, so a body-leading # vX.X.X.X duplicates it. The H1 belongs ONLY to the repo's changelog md.
- When you publish from a changelog, strip the leading H1 (and blank lines) into a temp notes file before
gh release create/edit --notes-file.
- Full mechanics: finish-workflows.md Step 6.
- Route GitKraken MCP's local-mutation tools back to Bash - GitKraken MCP (
gitkraken.gitkraken_*) exposes git_add_or_commit, git_push, git_pull, git_fetch, git_checkout, git_branch, git_worktree, and git_stash. These duplicate mutations already gated by NEVER #2, ALWAYS #4, and the commit-message logic, so never call them as a Bash substitute.
- Reserve the MCP surface for GitLens AI workflows and cross-platform issue/PR/repository ops with no local equivalent.
- Full detail: gitkraken-mcp-integration.md §2.
- Honor an authorized operator's explicit direct-push directive on a protected branch - Protected-branch rules primarily gate EXTERNAL contributors. When the operator holds bypass rights and explicitly asks for one, do it.
- Do NOT default to a PR detour, re-ask, or frame the bypass as a problem.
- Still apply full commit hygiene: scope to intended files, never blind
git add -A, and use Conventional Commits.
- Report plainly that the push bypassed protection. Bypass authority lives in operator memory, not this codebase-agnostic skill.
- Commit substantial work before an autostash-prone operation -
git merge|pull|rebase --autostash (or pull.rebase=true/rebase.autoStash=true) stashes the tree, runs the operation, then re-applies it. A re-apply CONFLICT strands the changeset behind an easily-missed warning, one git stash drop/clear/gc from permanent loss.
- Before you merge, pull or rebase a large or shared-branch changeset, COMMIT it, or stash and pop it yourself, instead of
--autostash.
- The
post-merge/post-rewrite guard (git-hooks/lib/autostash-orphan-guard.sh) is a safety net, not a substitute: it anchors autostashes under refs/autostash-rescue/<sha> and alerts visibly if not re-applied.
- Recover with
git stash pop and commit immediately, before any git stash drop/clear.
- Reconcile the primary checkout after pushing a detached/worktree HEAD to a shared branch -
git push origin HEAD:<branch> from a detached HEAD or a worktree advances the remote but not the primary checkout's local ref. The work is safe on origin yet invisible there.
- Say so plainly and hand over the safe sync recipe.
- Never stash, rebase or reset a primary tree that is dirty, diverged or concurrently owned.
- See finish-workflows.md Step 5b.
- Let launch-wrapper sessions autosync, and never hand-roll the publish - Under the continuous-integration model, autosync publishes every commit to the live branch through
git-sync.sh.
- Never
git push origin HEAD:<live> or rebase onto the live branch by hand: that risks the invariants the sync protects.
- If autosync prints a conflict, resolve it per its message and never force it.
- The primary checkout follows fast-forward-only and is never worked in. Full contract: continuous-integration.md.
- Reap worktrees before branches, and only reaper-owned lanes - Remove the worktree (
git worktree remove) before its branch. A checked-out branch cannot be deleted.
.skilled/bin/worktree-reaper.sh auto-reaps work/{runtime}/{slug} pairs that are clean, merged and marker-dead.
- With
--numbered it also reaps an unlocked, clean, merged, stash-free worktrees/NNN-slug worktree idle 48 hours, process-free and holding no non-regenerable ignored path (any under specs/ counts), never forced.
- A session-start sweep runs the numbered reaper at most every 6 hours, and
SPECKIT_WORKTREE_AUTOREAP=0 stops it. All else stays report-only.
- Naming is enforced by a migration-tolerant pre-push hook on new remote branches only, never
skilled/v*.
- Ask before every push to a branch outside the remote allowlist - See Remote Push Permission Enforcement above for mechanics. A prior approval never carries forward to the next push. Allowlist: remote-branch-policy.md.
Commit Message Logic (Human-Clear and AI-Deterministic)
Use this logic whenever an AI writes or rewrites a commit message: the subject explains the
outcome in git log --oneline, and the body explains the reason without packet knowledge or
jargon. The hooks enforce structure, not clarity. The structure they enforce is the "Enforced
rules" JSON block in commit-message-template.md §7, read by
validate-message.mjs at commit time, at push time, in the agent
gate and in CI. PR descriptions follow the block in pr-template.md and
new branch names the block in worktree-checklist.md. Each repository
supplies its own copies (.sk-git/ or git config skgit.contractDir). A repository with no rules
block is not checked. There is no bypass: when a rule is wrong, change the template.
1. Classify Special Git Messages
Preserve Git-generated subjects unchanged when they begin with Merge , Revert ", fixup! ,
squash! , or amend! . Intentional checkpoints are not exempt: write them as
chore(wip): checkpoint <specific state>.
2. Authored Subject Contract
Format:
type(scope)[!]: imperative summary
Hard requirements:
- Type and scope are required. Scope is lowercase kebab-case, a stable subsystem name, never a
packet, phase, task, or other numeric-only identifier.
- Summary starts with a lowercase imperative verb, names the changed behavior or artifact (not
the work process), ends without punctuation, has no repeated spaces, and is specific enough to
distinguish this commit from adjacent work.
- Subject has an 80-character target (
subject.length-target, warning) and a 100-character hard limit (subject.max-length).
- A
! requires a BREAKING CHANGE: footer.
Do not use vague summaries like update, changes, cleanup, or work in progress.
Move process metadata (packet numbers, phases, waves, lanes, task counts, model names, review
rounds, remediation labels, verification claims) to the body or Refs: line unless part of the
behavior being changed.
3. Type Selection Order
Use first match:
release: publishing a release.
docs: every substantive path is documentation.
fix: existing behavior was incorrect, unsafe, or failing.
feat: adds new usable behavior or support.
perf: measured performance improves, behavior unchanged.
refactor: structure changes without behavior changes.
test: only tests or fixtures change.
ci: only CI workflow behavior changes.
build: only build or dependency mechanics change.
style: only formatting changes.
revert/merge: authored revert or merge messages.
chore: no more specific type applies.
Tests and documentation shipped with a feature or fix inherit that feature or fix type. Do not
choose chore merely because the commit touches many files.
4. Scope Selection Order
First match, by logical owner:
.skilled/skills/<name>/... -> <name>.
.skilled/scripts/git-hooks/... or installer -> git-hooks.
AGENTS.md or runtime agent definitions -> agents.
.skilled/commands/... -> commands.
opencode.json, .utcp_config.json, or equivalent config -> config.
- Root
README.md only -> readme.
- Spec-doc or generated packet-metadata maintenance only ->
specs.
- Documentation spanning multiple owners ->
docs.
- A dominant top-level component -> its lowercase name.
- Inseparable cross-repository change ->
repo.
Use the full skill folder name as the canonical scope. For example, .skilled/skills/system-spec-kit/... uses system-spec-kit. Files in .skilled/repo-rules/ use repo-rules. The template's subject.scope-alias rule rejects short forms listed in its scopeAliases map.
If two independent owners remain, split the commit instead of inventing a combined scope.
5. Summary Construction
Apply this sequence:
- State the primary outcome of the staged diff.
- Start with a precise imperative action (
add, remove, route, clarify, etc.) naming the
affected behavior or artifact.
- Add the visible effect when the object alone is ambiguous.
- Remove chronology, review claims, and duplicate Conventional Commit prefixes.
- Read only the subject and ask: "Would a maintainer understand what changed without opening
the packet?" If not, rewrite it.
6. Body Contract
Every authored commit carries a body: at least one prose line, separated from the subject by a
blank line, that says why the change exists. The number of staged paths never excuses a missing
body, because a later search reads the body to learn the reason, and a one-path commit is
searched as often as a large one. Trailers such as Spec: and Commit-Id: are machine data and
do not count as a body. Only the Git-generated subjects in §1 are exempt.
Use the full structure below when any condition applies:
- The change fixes a regression, failure, race, security issue, or data risk, or it is breaking or has migration requirements. A breaking commit MUST carry the
Context, Changes and Verification sections below. They are required, not preferred.
- The reason or tradeoff is not obvious from the subject.
- The commit spans code plus generated metadata or multiple repository areas.
Required structure for breaking commits. Recommended for the other cases above:
Context: <plain-language problem or reason>
Changes:
- <observable change>
- <observable change>
Verification:
- `<command>` -> <observed result>
Spec: <track>/<packet>[/<phase>...]
Commit-Id: NNNNNNN
Refs: <issue, PR or URL>
The trailer paragraph is the commit's final paragraph, contiguous and separated from the prose
above it by a blank line. The Commit-Id: ordinal is stamped by the prepare-commit-msg hook
and never typed by hand. An amend keeps its id, unless the message is replaced with -m, which mints a fresh one. A cherry-pick re-mints a fresh one. A rebase re-mints a fresh id on a pick only when the repository asks for ids and git marks the pick with CHERRY_PICK_HEAD. The hook then drops the copied id and stamps a new one. A reworded commit, a commit the rebase leaves in place and git rebase --apply keep the id the message carried. The commit a rebase replaced is recognised as a copy by its author email and author date.
Use only sections that carry useful information, explain internal terms on first use, and state
in verification what actually ran and its result.
7. Deterministic Self-Check
Before committing, verify message format (§1-2), type (§3), scope (§4), summary (§5), body
(§6) and the final trailer paragraph satisfy their rule, and that the same staged diff would
produce the same subject again.
⛔ NEVER
- Force push to main/master - Protected branches must never receive force pushes
- Never create branches directly - Via
git worktree add -b .... Never git branch, git checkout plus -b, or git switch plus -c
- Commit directly to protected branches WITHOUT operator authorization - Default to feature branches + PRs, except when the operator has bypass authority and explicitly directs a direct commit/push (see ALWAYS #13). Don't force a PR detour.
- Leave worktrees uncleaned - Remove worktree directories after merge
- Commit secrets or credentials - Use environment variables or secret management
- Create PRs without description - Always include context, changes, and testing notes
- Merge without CI passing - Wait for all checks to complete
- Rebase public/shared branches - Only rebase local, unpushed commits
- Bypass a git hook with
--no-verify - Never skip commit-msg, pre-commit, or pre-push validation this way. If a message rule is genuinely wrong, change the rules block in the template. --no-verify only defers the block to pre-push and CI
- Amend a commit that has already been pushed or merged - Rewriting published history breaks other clones and any autosynced live branch. Commit a new change (or
git revert) instead once it's left the local repo
- Hand-write or edit a
Commit-Id: value - The prepare-commit-msg hook stamps the ordinal from the allocator. A typed or edited id collides with history, so the commit-msg hook refuses it
⚠️ ESCALATE IF
- Merge conflicts cannot be auto-resolved - Needs a human decision on which changes to keep
- GitHub MCP returns authentication errors - Token may be expired or permissions insufficient
- Worktree directory is locked or corrupted - May require manual cleanup with
git worktree prune
- Force push to protected branch is requested - Requires explicit approval and understanding of consequences
- CI/CD pipeline fails repeatedly - May indicate infrastructure issues beyond code problems
- Branch divergence exceeds 50 commits - Suggests an incremental merging strategy
- Submodule conflicts detected - Updates require careful coordination
- Strict-validate run inside a bare worktree - Its exit code is meaningless (ALWAYS #8: missing gitignored deps). Re-run on
main post-merge before trusting any result. See large-reorg-playbook.md.
5. REFERENCES
Core Workflows
| Document |
Purpose |
Key Insight |
| worktree-workflows.md |
7-step workspace creation |
Directory selection, branch strategies, large-reorg caveats |
| large-reorg-playbook.md |
Step-ordered large rename/reorg runbook |
Worktree-only renames. Toolchain + DB run on main |
| commit-workflows.md |
7-step commit workflow |
Artifact filtering, Conventional Commits, scoped-staging |
| finish-workflows.md |
5-step completion flow |
PR creation, cleanup, merge |
| continuous-integration.md |
Always-current live branch |
Autosync each commit. The IDE follows |
| shared-patterns.md |
Reusable git patterns |
Error recovery, conflict resolution, large-reorg verification |
| quick-reference.md |
Command cheat sheet |
Common operations |
| github-mcp-integration.md |
GitHub MCP remote ops |
PRs, issues, CI/CD via Code Mode |
| gitkraken-mcp-integration.md |
GitKraken MCP cross-platform ops |
GitLens AI, cross-platform PRs/issues |
Assets
| Asset |
Purpose |
| worktree-checklist.md |
Worktree creation checklist |
| commit-message-template.md |
Commit format guide |
| pr-template.md |
PR description template |
6. SUCCESS CRITERIA
Workspace Setup Complete
- Workspace prepared in the selected mode (
git worktree or current branch), user-confirmed
- Any worktree lives in the correct directory (
.worktrees/ or user-specified), branch named per convention (worktrees/{NNN}-{slug} or branches/{NNN}-{slug})
Commit Complete
- All changes reviewed, categorized, and artifact-filtered (build files, coverage, etc.). Only public-value files staged
- Commit message follows Conventional Commits format
Integration Complete
- Tests pass and branch up-to-date before merge/PR
- PR description includes context, changes, and testing notes
- Worktree cleaned up and local/remote feature branches deleted after merge (if used)
Quality Gates
| Gate |
Criteria |
Blocking |
| Pre-commit |
Artifacts excluded and staged-content gates pass |
Yes |
| Commit-msg |
Message structure passes. Clarity warnings reviewed |
Structure only |
| Pre-merge |
Tests pass, branch up-to-date |
Yes |
| Pre-PR |
Description complete, CI passing |
Yes |
| Post-merge |
Worktree removed, branches cleaned |
No |
7. INTEGRATION POINTS
Framework Integration
This skill operates within the framework in AGENTS.md:
- Gate 2: Skill routing via
.skilled/bin/skill-advisor.cjs
- Gate 3: File modifications require the spec folder question (AGENTS.md, HARD BLOCK)
- Tool Routing: AGENTS.md Section 5 decision tree
- Continuity: see Continuity Integration below
Continuity Integration
Recovery sequence (widen with ripgrep only once packet-native sources are exhausted):
// Recover the active packet before planning git work
/speckit:resume
// Recovery order: handover.md -> _memory.continuity -> spec docs
// If packet-native sources are exhausted, widen with the ripgrep recipe in
// system-spec-kit/references/retrieval/retrieval-conventions.md §2.1.
// Exit 1 is a clean no-hit, not an error.
rg --no-config --json --fixed-strings --ignore-case \
--glob '*.md' --glob '!**/z_archive/**' --glob '!**/node_modules/**' \
-- 'branch strategy decisions' specs .skilled
// After major commits or workflow completion
// Save context with: /speckit:save or "save context to [spec-folder]"
8. REFERENCES AND RELATED RESOURCES
The router discovers reference and asset docs dynamically from references/ and assets/. See §5 for the core set.
Manual Testing Playbook
Manual testing scenarios live in manual-testing-playbook/manual-testing-playbook.md, the root index that lists every category and scenario, plus one file per scenario under manual-testing-playbook/<topic>/<scenario>.md.
Validate the structure from the repository root with node .skilled/skills/sk-doc/sk-create-manual-testing-playbook/scripts/validate-playbook-package.cjs --package sk-git, then run the scenarios in an AI runtime for behavioral checks.
Feature Catalog
A companion feature-catalog/feature-catalog.md lists every sk-git capability with its entry point and source files.
Related: system-spec-kit (packet recovery, continuity), sk-doc (PR, release, documentation quality).
1---2name: sk-git3description: "Git: numbered worktrees, conventional commits, PRs, merge/rebase, and finish; single-skill workflow guidance with no spec."4allowed-tools: [Read, Bash, mcp__code_mode__call_tool_chain]5argument-hint: "[worktree|commit|finish]"6version: 1.11.12.07metadata:8 source: https://skillmd.com/skills/michelkerkmeester/sk-git9---1011<!-- Keywords: git-workflow, git-worktree, create-worktree, numbered-worktree, restructure-worktrees, worktree-prefix, wt-branch, worktree-branch, branch-naming-allocator, skilled-branch, branch, commit, conventional-commits, pull-request, PR, merge, rebase, finish-work, integrate-changes, commit-hygiene, workspace-isolation, version-control, github, issues, pr-review, gitkraken, gitlens, gitlens-launchpad, gitlens-commit-composer, cross-platform-pr, multi-provider-issue -->12<!-- Owns: git worktree / create worktree / numbered worktree / restructure worktrees / worktree prefix / wt/ branch / worktree branch / branch naming allocator / skilled branch / branch / commit / conventional commits / pull request / PR / merge / rebase / finish work / integrate changes / git workflow / gitkraken / gitlens / gitlens launchpad / gitlens commit composer / cross-platform pr / multi-provider issue. Does NOT own: spec folders, memory, continuity, save context (system-spec-kit). Code implementation, tests (sk-code). -->1314# Git Workflows - Git Development Guide1516Unified workflow guidance across workspace isolation, commit hygiene, and work completion.1718## 1. WHEN TO USE1920### When to Use This Guide2122Use this guide when starting new git-based work, following a complete git workflow (setup, work,23complete), unsure which git skill to use, or seeking git best practices (branch naming, commits).2425### When NOT to Use2627- Simple `git status`/`git log` queries (use Bash directly)28- Non-git version control systems2930### Keyword Triggers3132**Owned:** `git worktree`, `worktree`, `create worktree`, `numbered worktree`, `restructure worktrees`, `worktree prefix`, `wt/ branch`, `worktree branch`,33`branch naming allocator`, `skilled branch`, `branch`, `commit`, `conventional commits`, `pull request`, `pr`, `pr review`, `merge`, `rebase`,34`finish work`, `integrate changes`, `git workflow`, `github`, `issue`, `gitkraken`, `gitlens`, `gitlens launchpad`, `commit composer`3536**Not owned:** spec folders / memory / continuity / save context → `system-spec-kit`. Code implementation / writing tests → `sk-code`.3738---3940## 2. SMART ROUTING4142sk-git is a standalone skill, so the skill advisor scores its owned keywords against the request and selects it here.43A request that names a worktree, a commit, a pull request, a merge, a finish, GitKraken or GitLens lands here,44while spec folders and code implementation belong elsewhere.4546`references/quick-reference.md` loads first on every invocation, then the winning intent loads its phase reference.47`references/gitkraken-mcp-integration.md` follows for GitKraken and GitLens,48and `references/shared-patterns.md` carries what every phase shares.4950A request whose scores stay near zero loads the shared patterns and asks a disambiguation checklist instead of guessing.5152Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5354---5556## 3. HOW IT WORKS5758### Workspace Choice Enforcement5960**MANDATORY**: The AI must NEVER autonomously choose between a git worktree and the current branch, and must NEVER create a branch directly with `git branch`, `git checkout` plus `-b`, or `git switch` plus `-c`.6162When a git workspace trigger fires, the AI MUST ask the user to explicitly choose:6364| Option | Description | Best For |65| ----------------------------- | ---------------------------------------- | ------------------------------- |66| **A) Create a git worktree** | Isolated workspace in separate directory | Parallel work, complex features |67| **B) Work on current branch** | No new worktree created | Trivial changes, exploration |6869**AI Behavior**: ASK before proceeding, WAIT for explicit selection (A/B), NEVER assume, RESPECT choice for the session unless the user requests a change. Create any needed branch only through `git worktree add -b ...`.7071### Launch-Wrapper Worktrees vs the In-Session Ask-First Rule7273The ask-first rule above governs **in-session** decisions: once running, an AI must not autonomously create a worktree.74`.skilled/bin/worktree-session.sh` is a **launch wrapper** you opt into at the shell, and it is different. It runs *before* the AI starts, so it does not violate the ask-first rule. It places each top-level session in its own worktree + branch + isolated MCP databases, and it execs in place for an orchestrated child with `AI_SESSION_CHILD=1` or for a session already inside a linked worktree.7576**Deliberate per-session deps override.** The wrapper **symlinks** the shared `node_modules`/`dist` into each worktree and gives each its own MCP DBs (via `SPEC_KIT_DB_DIR` / `SPECKIT_IPC_SOCKET_DIR`), rather than paying an install per session.7778> **Known gap.** Wholesale-linked dependency trees mean a wrapper session reads the main checkout's first-party code, which is why strict-validate and metadata regeneration run on `main`. Detail: [worktree-workflows.md](references/worktree-workflows.md) §10.7980### Continuous Integration: the always-current live branch8182Each launch-wrapper session **autosyncs** every commit to one shared **live branch**, the primary checkout's own branch. The IDE fast-forward-follows it, so you see active work seconds behind each commit and never an uncommitted buffer.83Configured by `SPECKIT_LIVE_BRANCH`, `SPECKIT_AUTOSYNC`, the `post-commit` publish through `git-sync.sh` and its non-force fetch → rebase-or-abort push: [continuous-integration.md](references/continuous-integration.md).8485### Remote Push Permission Enforcement8687**MANDATORY**: The AI must NEVER push a branch to `origin` outside the remote allowlist without a fresh, explicit go-ahead for THAT push. Allowlist, what counts as a go-ahead, `SPECKIT_ALLOW_REMOTE_PUSH`, the [pre-push hook](../../scripts/git-hooks/pre-push) backstop and the launch-wrapper autosync exception: [remote-branch-policy.md](references/remote-branch-policy.md).8889### Preflight Advisory: the rules reach you at command time9091- The rules in `hard-rules.json` beside this file are executed, not just documented.92- A preflight advisory hook evaluates every visible `git` command against live repository state, and fires on the specific risky state rather than a bare verb.93- It prints the matching rule as typed, advising and never blocking.94- The pre-commit, commit-msg and pre-push hooks enforce.9596The seven repository runtimes and the dsh run surface share it. `SKGIT_ADVISORY=0`, `SKGIT_ADVISORY_SKIP=<rule-id>` or a97`SKGIT_ADVISORY_SKIP=commit`-style prefix silences it. Delivery and fail-open:98[scripts/hooks/README.md](scripts/hooks/README.md). Rule engine and tests:99[scripts/lib/README.md](scripts/lib/README.md). Operator scenario:100[manual-testing-playbook/](manual-testing-playbook/manual-testing-playbook.md).101102### Repository Settings: /doctor:git103104A repository adapts sk-git through git config and `.sk-git/`, never by editing this skill.105`/doctor:git` (`.skilled/commands/doctor/git.md`) changes and checks those settings:106107- `hooks` switches an optional pre-commit or pre-push gate on or off.108- `standards` copies the commit, PR and branch rule templates into `.sk-git/` and edits them.109- `setup` runs eleven read-only checks and names one repair per failure.110111When asked whether sk-git is set up or why a rule is not enforced, run `/doctor:git setup` before reading config by hand.112113### Git Development Lifecycle Map114115Git development flows through 3 phases:116117| Phase | Goal | Prevents | Output | See |118|-------|------|----------|--------|-----|119| **1. Workspace Setup** | Isolate work in a short-lived temp branch | Branch juggling, stash chaos | Clean, focused workspace | [worktree-workflows.md](./references/worktree-workflows.md) |120| **2. Work & Commit** | Analyze changes, filter artifacts, write Conventional Commits | Bad commits, unclear history | Clean commit history | [commit-workflows.md](./references/commit-workflows.md) |121| **3. Complete & Integrate** | Merge, create a PR, or discard work (tests-gated) | Untested code merged | Work integrated or discarded | [finish-workflows.md](./references/finish-workflows.md) |122123### Phase Transitions124Setup (worktree created) → Work → Complete (committed, tests passing) → back to Setup (integrated).125126### Workflow Selection Guide127- New feature/fix → Phase 1. Quick fix → Phase 2.128- Ready to commit → Phase 2. No changes yet → keep coding.129- Tests pass → Phase 3. Failing → return to Phase 2.130131### Common Workflow Patterns132133- **Full**: all 3 phases.134- **Quick fix**: skip Phase 1.135- **Parallel**: repeat Phases 1-2 per feature, then Phase 3 for each.136137---138139## 4. RULES140141### ✅ ALWAYS1421431. **Use deterministic conventional commit format** - All authored commits follow `type(scope): summary`. Preserve the explicitly exempt Git-generated subjects defined below1442. **Create worktree for parallel work** - Never work on multiple features in the same worktree1453. **Verify branch is up-to-date** - Pull latest changes before creating PR1464. **Name worktree-created branches with the numbered-worktree grammar** - `worktrees/{NNN}-{slug}` for a worktree-backed branch, `branches/{NNN}-{slug}` for a dedicated branch with none.147 - Each namespace counts 001..999 independently, sequential, never skipped or reused.148 - Never hand-compute `{NNN}`. Allocate through `.skilled/skills/sk-git/scripts/worktree-naming.sh` (`create`, `create-branch` or `allocate`), which locks and seeds each counter from its high-water mark plus every matching ref.149 - The script header carries the full grammar, the relocatable `{base}` rule and the reserved `skilled/v*`, `main` and `backup/` lanes.150 - This is distinct from the launch wrapper's unnumbered `work/{runtime}/{slug}` lane (see above).1515. **Reference the spec packet in a `Spec:` trailer** - Put the packet path in a `Spec:` trailer shaped `Spec: <track>/<packet>[/<phase>...]`: the packet's path below `specs/`, with nested phases included and without the `specs/` segment itself.152 - The packet query is anchored on that line, `git log -E --grep='^Spec: your-track/your-packet'`, so a leading `specs/` makes every commit for that packet unfindable.153 - Omit the line when the commit is not packet work.154 - `Refs:` is for external links only: issues, pull requests and URLs.1556. **Clean up after merge** - Delete local and remote feature branches after successful merge1567. **Squash commits for clean history** - Use squash merge for feature branches with many WIP commits1578. **Provision a worktree before you trust anything it reports** - Every dependency tree here is gitignored, so a fresh worktree has none of them and fails in ways that read as broken code. A build can exit 0 having compiled nothing, and a hub-conformance check that copies a skill into a temp directory loses that skill's dependencies and reports a correct hub broken.158 - `worktree-naming.sh create` installs them, and `--no-provision` opts out. `worktree-naming.sh provision [dir]` fixes a worktree made another way. Both are idempotent.159 - Both also recreate the operator's private `local-*` commands from the primary checkout in the form it holds them, a file as a copy, a relative link as the same link and a folder as one shared link, because git ignores them and a new worktree would otherwise start without them. An existing path is never replaced.160 - `provision` rebuilds a listed build output when it is missing or when its tracked sources changed since provisioning last built it, so it also refreshes a checkout whose built plugin went stale after a pull.161 - Provisioning **installs** by default, but what binds is narrower than the technique: **no path shared into a worktree may resolve a repository-internal reference back to the source checkout.**162 - Two mechanisms break that, and each has its own remedy. A package's `node_modules` carries relative workspace self-links that re-anchor through wherever the link physically sits, so a wholesale link leaves the worktree reading the source checkout's code however much it edits its own.163 - Share such a tree by linking its third-party entries individually and recreating each self-link relative to the worktree's own copy.164 - The second mechanism is a compiled entry point reached through a link. It compares the path it was invoked with against the location it derives from its own file, finds them different, and exits 0 having done nothing. Invoke such a script by its canonical path, or give the worktree its own build.165 - A dependency tree that does neither may be linked wholesale. `worktree-naming.sh provision` installs, which satisfies the invariant the blunt way.166 - On a large reorg, still do file/`git mv` ops in the worktree and run the spec-kit toolchain and ALL metadata regeneration on `main` after merge. See [large-reorg-playbook.md](references/large-reorg-playbook.md).1679. **Scan for gitignored leftovers after a rename wave** - After `git mv` + merge, detect dirs with disk files but 0 tracked files (`git ls-files <dir>` empty, `git status --porcelain --untracked-files=all` clean) and `rm -rf` them, stale cruft left by `git mv`.16810. **Verify rename history is preserved** - After a rename wave confirm `R`-status (not delete+add) before commit, and after merge confirm the tree has no old+new duplicate folders.16911. **GitHub release bodies never start with an H1** - The release title field already renders `vX.X.X.X — Title`, so a body-leading `# vX.X.X.X` duplicates it. The H1 belongs ONLY to the repo's changelog md.170 - When you publish from a changelog, strip the leading H1 (and blank lines) into a temp notes file before `gh release create/edit --notes-file`.171 - Full mechanics: [finish-workflows.md](references/finish-workflows.md) Step 6.17212. **Route GitKraken MCP's local-mutation tools back to Bash** - GitKraken MCP (`gitkraken.gitkraken_*`) exposes `git_add_or_commit`, `git_push`, `git_pull`, `git_fetch`, `git_checkout`, `git_branch`, `git_worktree`, and `git_stash`. These duplicate mutations already gated by NEVER #2, ALWAYS #4, and the commit-message logic, so never call them as a Bash substitute.173 - Reserve the MCP surface for GitLens AI workflows and cross-platform issue/PR/repository ops with no local equivalent.174 - Full detail: [gitkraken-mcp-integration.md](references/gitkraken-mcp-integration.md) §2.17513. **Honor an authorized operator's explicit direct-push directive on a protected branch** - Protected-branch rules primarily gate EXTERNAL contributors. When the operator holds bypass rights and explicitly asks for one, do it.176 - Do NOT default to a PR detour, re-ask, or frame the bypass as a problem.177 - Still apply full commit hygiene: scope to intended files, never blind `git add -A`, and use Conventional Commits.178 - Report plainly that the push bypassed protection. Bypass authority lives in operator memory, not this codebase-agnostic skill.17914. **Commit substantial work before an autostash-prone operation** - `git merge|pull|rebase --autostash` (or `pull.rebase=true`/`rebase.autoStash=true`) stashes the tree, runs the operation, then re-applies it. A re-apply CONFLICT strands the changeset behind an easily-missed warning, one `git stash drop`/`clear`/gc from permanent loss.180 - Before you merge, pull or rebase a large or shared-branch changeset, COMMIT it, or stash and pop it yourself, instead of `--autostash`.181 - The `post-merge`/`post-rewrite` guard ([git-hooks/lib/autostash-orphan-guard.sh](../../scripts/git-hooks/lib/autostash-orphan-guard.sh)) is a safety net, not a substitute: it anchors autostashes under `refs/autostash-rescue/<sha>` and alerts visibly if not re-applied.182 - Recover with `git stash pop` and commit immediately, before any `git stash drop/clear`.18315. **Reconcile the primary checkout after pushing a detached/worktree HEAD to a shared branch** - `git push origin HEAD:<branch>` from a detached HEAD or a worktree advances the remote but not the primary checkout's local ref. The work is safe on origin yet invisible there.184 - Say so plainly and hand over the safe sync recipe.185 - Never stash, rebase or reset a primary tree that is dirty, diverged or concurrently owned.186 - See [finish-workflows.md](references/finish-workflows.md) Step 5b.18716. **Let launch-wrapper sessions autosync, and never hand-roll the publish** - Under the continuous-integration model, autosync publishes every commit to the live branch through `git-sync.sh`.188 - Never `git push origin HEAD:<live>` or rebase onto the live branch by hand: that risks the invariants the sync protects.189 - If autosync prints a conflict, resolve it per its message and never force it.190 - The primary checkout follows fast-forward-only and is never worked in. Full contract: [continuous-integration.md](references/continuous-integration.md).19117. **Reap worktrees before branches, and only reaper-owned lanes** - Remove the worktree (`git worktree remove`) before its branch. A checked-out branch cannot be deleted.192 - `.skilled/bin/worktree-reaper.sh` auto-reaps `work/{runtime}/{slug}` pairs that are clean, merged and marker-dead.193 - With `--numbered` it also reaps an unlocked, clean, merged, stash-free `worktrees/NNN-slug` worktree idle 48 hours, process-free and holding no non-regenerable ignored path (any under `specs/` counts), never forced.194 - A session-start sweep runs the numbered reaper at most every 6 hours, and `SPECKIT_WORKTREE_AUTOREAP=0` stops it. All else stays report-only.195 - Naming is enforced by a migration-tolerant pre-push hook on new remote branches only, never `skilled/v*`.19618. **Ask before every push to a branch outside the remote allowlist** - See [Remote Push Permission Enforcement](#remote-push-permission-enforcement) above for mechanics. A prior approval never carries forward to the next push. Allowlist: [remote-branch-policy.md](references/remote-branch-policy.md).197198### Commit Message Logic (Human-Clear and AI-Deterministic)199200Use this logic whenever an AI writes or rewrites a commit message: the subject explains the201outcome in `git log --oneline`, and the body explains the reason without packet knowledge or202jargon. The hooks enforce structure, not clarity. The structure they enforce is the "Enforced203rules" JSON block in [commit-message-template.md](assets/commit-message-template.md) §7, read by204[validate-message.mjs](scripts/validate-message.mjs) at commit time, at push time, in the agent205gate and in CI. PR descriptions follow the block in [pr-template.md](assets/pr-template.md) and206new branch names the block in [worktree-checklist.md](assets/worktree-checklist.md). Each repository207supplies its own copies (`.sk-git/` or git config `skgit.contractDir`). A repository with no rules208block is not checked. There is no bypass: when a rule is wrong, change the template.209210#### 1. Classify Special Git Messages211212Preserve Git-generated subjects unchanged when they begin with `Merge `, `Revert "`, `fixup! `,213`squash! `, or `amend! `. Intentional checkpoints are not exempt: write them as214`chore(wip): checkpoint <specific state>`.215216#### 2. Authored Subject Contract217218Format:219220```text221type(scope)[!]: imperative summary222```223224Hard requirements:225226- Type and scope are required. Scope is lowercase kebab-case, a stable subsystem name, never a227 packet, phase, task, or other numeric-only identifier.228- Summary starts with a lowercase imperative verb, names the changed behavior or artifact (not229 the work process), ends without punctuation, has no repeated spaces, and is specific enough to230 distinguish this commit from adjacent work.231- Subject has an 80-character target (`subject.length-target`, warning) and a 100-character hard limit (`subject.max-length`).232- A `!` requires a `BREAKING CHANGE:` footer.233234Do not use vague summaries like `update`, `changes`, `cleanup`, or `work in progress`.235236Move process metadata (packet numbers, phases, waves, lanes, task counts, model names, review237rounds, remediation labels, verification claims) to the body or `Refs:` line unless part of the238behavior being changed.239240#### 3. Type Selection Order241242Use first match:2432441. `release`: publishing a release.2452. `docs`: every substantive path is documentation.2463. `fix`: existing behavior was incorrect, unsafe, or failing.2474. `feat`: adds new usable behavior or support.2485. `perf`: measured performance improves, behavior unchanged.2496. `refactor`: structure changes without behavior changes.2507. `test`: only tests or fixtures change.2518. `ci`: only CI workflow behavior changes.2529. `build`: only build or dependency mechanics change.25310. `style`: only formatting changes.25411. `revert`/`merge`: authored revert or merge messages.25512. `chore`: no more specific type applies.256257Tests and documentation shipped with a feature or fix inherit that feature or fix type. Do not258choose `chore` merely because the commit touches many files.259260#### 4. Scope Selection Order261262First match, by logical owner:2632641. `.skilled/skills/<name>/...` -> `<name>`.2652. `.skilled/scripts/git-hooks/...` or installer -> `git-hooks`.2663. `AGENTS.md` or runtime agent definitions -> `agents`.2674. `.skilled/commands/...` -> `commands`.2685. `opencode.json`, `.utcp_config.json`, or equivalent config -> `config`.2696. Root `README.md` only -> `readme`.2707. Spec-doc or generated packet-metadata maintenance only -> `specs`.2718. Documentation spanning multiple owners -> `docs`.2729. A dominant top-level component -> its lowercase name.27310. Inseparable cross-repository change -> `repo`.274275Use the full skill folder name as the canonical scope. For example, `.skilled/skills/system-spec-kit/...` uses `system-spec-kit`. Files in `.skilled/repo-rules/` use `repo-rules`. The template's `subject.scope-alias` rule rejects short forms listed in its `scopeAliases` map.276277If two independent owners remain, split the commit instead of inventing a combined scope.278279#### 5. Summary Construction280281Apply this sequence:2822831. State the primary outcome of the staged diff.2842. Start with a precise imperative action (`add`, `remove`, `route`, `clarify`, etc.) naming the285 affected behavior or artifact.2863. Add the visible effect when the object alone is ambiguous.2874. Remove chronology, review claims, and duplicate Conventional Commit prefixes.2885. Read only the subject and ask: "Would a maintainer understand what changed without opening289 the packet?" If not, rewrite it.290291#### 6. Body Contract292293Every authored commit carries a body: at least one prose line, separated from the subject by a294blank line, that says why the change exists. The number of staged paths never excuses a missing295body, because a later search reads the body to learn the reason, and a one-path commit is296searched as often as a large one. Trailers such as `Spec:` and `Commit-Id:` are machine data and297do not count as a body. Only the Git-generated subjects in §1 are exempt.298299Use the full structure below when any condition applies:300301- The change fixes a regression, failure, race, security issue, or data risk, or it is breaking or has migration requirements. A breaking commit MUST carry the `Context`, `Changes` and `Verification` sections below. They are required, not preferred.302- The reason or tradeoff is not obvious from the subject.303- The commit spans code plus generated metadata or multiple repository areas.304305Required structure for breaking commits. Recommended for the other cases above:306307```text308Context: <plain-language problem or reason>309310Changes:311- <observable change>312- <observable change>313314Verification:315- `<command>` -> <observed result>316317Spec: <track>/<packet>[/<phase>...]318Commit-Id: NNNNNNN319Refs: <issue, PR or URL>320```321322The trailer paragraph is the commit's final paragraph, contiguous and separated from the prose323above it by a blank line. The `Commit-Id:` ordinal is stamped by the `prepare-commit-msg` hook324and never typed by hand. An amend keeps its id, unless the message is replaced with `-m`, which mints a fresh one. A cherry-pick re-mints a fresh one. A rebase re-mints a fresh id on a pick only when the repository asks for ids and git marks the pick with `CHERRY_PICK_HEAD`. The hook then drops the copied id and stamps a new one. A reworded commit, a commit the rebase leaves in place and `git rebase --apply` keep the id the message carried. The commit a rebase replaced is recognised as a copy by its author email and author date.325326Use only sections that carry useful information, explain internal terms on first use, and state327in verification what actually ran and its result.328329#### 7. Deterministic Self-Check330331Before committing, verify message format (§1-2), type (§3), scope (§4), summary (§5), body332(§6) and the final trailer paragraph satisfy their rule, and that the same staged diff would333produce the same subject again.334335### ⛔ NEVER3363371. **Force push to main/master** - Protected branches must never receive force pushes3382. **Never create branches directly** - Via `git worktree add -b ...`. Never `git branch`, `git checkout` plus `-b`, or `git switch` plus `-c`3393. **Commit directly to protected branches WITHOUT operator authorization** - Default to feature branches + PRs, except when the operator has bypass authority and explicitly directs a direct commit/push (see ALWAYS #13). Don't force a PR detour.3404. **Leave worktrees uncleaned** - Remove worktree directories after merge3415. **Commit secrets or credentials** - Use environment variables or secret management3426. **Create PRs without description** - Always include context, changes, and testing notes3437. **Merge without CI passing** - Wait for all checks to complete3448. **Rebase public/shared branches** - Only rebase local, unpushed commits3459. **Bypass a git hook with `--no-verify`** - Never skip commit-msg, pre-commit, or pre-push validation this way. If a message rule is genuinely wrong, change the rules block in the template. `--no-verify` only defers the block to pre-push and CI34610. **Amend a commit that has already been pushed or merged** - Rewriting published history breaks other clones and any autosynced live branch. Commit a new change (or `git revert`) instead once it's left the local repo34711. **Hand-write or edit a `Commit-Id:` value** - The `prepare-commit-msg` hook stamps the ordinal from the allocator. A typed or edited id collides with history, so the commit-msg hook refuses it348349### ⚠️ ESCALATE IF3503511. **Merge conflicts cannot be auto-resolved** - Needs a human decision on which changes to keep3522. **GitHub MCP returns authentication errors** - Token may be expired or permissions insufficient3533. **Worktree directory is locked or corrupted** - May require manual cleanup with `git worktree prune`3544. **Force push to protected branch is requested** - Requires explicit approval and understanding of consequences3555. **CI/CD pipeline fails repeatedly** - May indicate infrastructure issues beyond code problems3566. **Branch divergence exceeds 50 commits** - Suggests an incremental merging strategy3577. **Submodule conflicts detected** - Updates require careful coordination3588. **Strict-validate run inside a bare worktree** - Its exit code is meaningless (ALWAYS #8: missing gitignored deps). Re-run on `main` post-merge before trusting any result. See [large-reorg-playbook.md](references/large-reorg-playbook.md).359360---361362## 5. REFERENCES363364### Core Workflows365| Document | Purpose | Key Insight |366|----------|---------|-------------|367| [worktree-workflows.md](references/worktree-workflows.md) | 7-step workspace creation | Directory selection, branch strategies, large-reorg caveats |368| [large-reorg-playbook.md](references/large-reorg-playbook.md) | Step-ordered large rename/reorg runbook | Worktree-only renames. Toolchain + DB run on main |369| [commit-workflows.md](references/commit-workflows.md) | 7-step commit workflow | Artifact filtering, Conventional Commits, scoped-staging |370| [finish-workflows.md](references/finish-workflows.md) | 5-step completion flow | PR creation, cleanup, merge |371| [continuous-integration.md](references/continuous-integration.md) | Always-current live branch | Autosync each commit. The IDE follows |372| [shared-patterns.md](references/shared-patterns.md) | Reusable git patterns | Error recovery, conflict resolution, large-reorg verification |373| [quick-reference.md](references/quick-reference.md) | Command cheat sheet | Common operations |374| [github-mcp-integration.md](references/github-mcp-integration.md) | GitHub MCP remote ops | PRs, issues, CI/CD via Code Mode |375| [gitkraken-mcp-integration.md](references/gitkraken-mcp-integration.md) | GitKraken MCP cross-platform ops | GitLens AI, cross-platform PRs/issues |376377### Assets378| Asset | Purpose |379|-------|---------|380| [worktree-checklist.md](assets/worktree-checklist.md) | Worktree creation checklist |381| [commit-message-template.md](assets/commit-message-template.md) | Commit format guide |382| [pr-template.md](assets/pr-template.md) | PR description template |383384---385386## 6. SUCCESS CRITERIA387388### Workspace Setup Complete389- Workspace prepared in the selected mode (`git worktree` or current branch), user-confirmed390- Any worktree lives in the correct directory (`.worktrees/` or user-specified), branch named per convention (`worktrees/{NNN}-{slug}` or `branches/{NNN}-{slug}`)391392### Commit Complete393- All changes reviewed, categorized, and artifact-filtered (build files, coverage, etc.). Only public-value files staged394- Commit message follows Conventional Commits format395396### Integration Complete397- Tests pass and branch up-to-date before merge/PR398- PR description includes context, changes, and testing notes399- Worktree cleaned up and local/remote feature branches deleted after merge (if used)400401### Quality Gates402403| Gate | Criteria | Blocking |404|------|----------|----------|405| **Pre-commit** | Artifacts excluded and staged-content gates pass | Yes |406| **Commit-msg** | Message structure passes. Clarity warnings reviewed | Structure only |407| **Pre-merge** | Tests pass, branch up-to-date | Yes |408| **Pre-PR** | Description complete, CI passing | Yes |409| **Post-merge** | Worktree removed, branches cleaned | No |410411---412413## 7. INTEGRATION POINTS414415### Framework Integration416417This skill operates within the framework in [AGENTS.md](../../../AGENTS.md):418- **Gate 2**: Skill routing via `.skilled/bin/skill-advisor.cjs`419- **Gate 3**: File modifications require the spec folder question (AGENTS.md, HARD BLOCK)420- **Tool Routing**: AGENTS.md Section 5 decision tree421- **Continuity**: see Continuity Integration below422423### Continuity Integration424425Recovery sequence (widen with ripgrep only once packet-native sources are exhausted):426427```text428// Recover the active packet before planning git work429/speckit:resume430// Recovery order: handover.md -> _memory.continuity -> spec docs431432// If packet-native sources are exhausted, widen with the ripgrep recipe in433// system-spec-kit/references/retrieval/retrieval-conventions.md §2.1.434// Exit 1 is a clean no-hit, not an error.435rg --no-config --json --fixed-strings --ignore-case \436 --glob '*.md' --glob '!**/z_archive/**' --glob '!**/node_modules/**' \437 -- 'branch strategy decisions' specs .skilled438439// After major commits or workflow completion440// Save context with: /speckit:save or "save context to [spec-folder]"441```442443---444445## 8. REFERENCES AND RELATED RESOURCES446447The router discovers reference and asset docs dynamically from `references/` and `assets/`. See §5 for the core set.448449### Manual Testing Playbook450451Manual testing scenarios live in `manual-testing-playbook/manual-testing-playbook.md`, the root index that lists every category and scenario, plus one file per scenario under `manual-testing-playbook/<topic>/<scenario>.md`.452453Validate the structure from the repository root with `node .skilled/skills/sk-doc/sk-create-manual-testing-playbook/scripts/validate-playbook-package.cjs --package sk-git`, then run the scenarios in an AI runtime for behavioral checks.454455### Feature Catalog456457A companion `feature-catalog/feature-catalog.md` lists every sk-git capability with its entry point and source files.458459Related: `system-spec-kit` (packet recovery, continuity), `sk-doc` (PR, release, documentation quality).