🐙 Git — Autonomous End-to-End Release & GitHub Lifecycle Engine

Aliases: git-flow | git-lifecycle | github-workflow | git-workflow | github-release

Autonomous, vendor-neutral Git and GitHub release orchestrator. Enforces the strict 4-Phase Branch Model (master production, dev staging, release/vX.Y.Z cuts, feature/* lanes), 9-tier anti-slop issue triage, automated documentation synchronization, GitHub SEO/metadata tuning, semantic release tagging, and post-release cleanup.

When to Use

Execute this skill when:

• Triage and classify incoming GitHub issues or bug reports before writing code.
• Starting feature or bugfix development that requires a clean branch from dev.
• Preparing a pull request with verified test evidence, secret scanning, and automated doc updates.
• Optimizing GitHub repository SEO, topics, tags, descriptions, and README visual hierarchy.
• Cutting a production release: staging on release/vX.Y.Z, merging into protected master, tagging with SemVer (vX.Y.Z), back-merging to dev, and publishing GitHub release notes.
• Cleaning up merged local and remote branches safely after a sprint or milestone.

Do NOT use this skill for:

• One-line scratch edits in untracked local exploration workspaces.
• Committing directly to master (commits to master are strictly prohibited).

Quick Reference

The 11-Phase Lifecycle Protocol

┌─────────────────────────────────────────────────────────────────────────────┐
│                       11-PHASE LIFECYCLE PIPELINE                           │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. Issue Intake & 9-Tier Anti-Slop Triage                                   │
│ 2. Feature Branch Creation from dev (feat/*, fix/*)                         │
│ 3. Surgical Code Edits & Local Gate (bun test, tsc, secret scan)             │
│ 4. Documentation & Changelog Sync (updatedocs)                              │
│ 5. GitHub SEO, Open Graph & README Copywriting Pass                         │
│ 6. PR Creation Against dev with Evidence Receipt                            │
│ 7. Staging Integration & Merge into dev                                     │
│ 8. Cut release/vX.Y.Z from dev & Bump package.json                          │
│ 9. Production Merge into master (no-ff) + Tag vX.Y.Z + GitHub Release       │
│ 10. Back-Merge master into dev                                              │
│ 11. Branch Cleanup & Linked Issue Closure                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Modes

Token rule: in a mode, load only the references in its row — never the full set.

Support references (load on topic)

Loadable by topic; also routable as /git-<file> commands (not separate routed modes):

• report-template.md

Verification

Run before reporting completion:

• Pre-flight context and documentation freshness verified (CACHE_HIT or synchronized)
• Target branch exists (or was created) from dev
• Current branch ≠ master (commits to master forbidden)
• bun test passes with ≥1 updated test file
• No secrets in staged files (scan sk-*, ghp_*)
• Commit message follows Conventional Commits <type>(<scope>): <subject>
• .gitignore passes wildcard trap and index cache audit (gitignore-audit.ts --audit && --check-tracked)
• PR description includes test-evidence refs and deploy notes
• Changelog entry added (not under ### Unreleased alone)
• .agents/artifacts/WORKTREE-LEASE.md released (if held)

For shared-worktree safety: audit-lease checks WORKTREE-LEASE.md before git mutations.

Full audit-mode spec: skills/references/audit-mode-guidance.md.

Review-mode substeps (invoked from pr after the PR is open)

• code-review-comments — review comments arrived on the PR: fetch → number + summarize each → apply selected fixes. Delegates to code-review (receive mode) for the actual feedback triage. Use when a review round lands and you need to triage, acknowledge, and clear comments before merging.
• pr-check — CI checks failed on the open PR: inspect → pull failure logs → extract the failure snippet → --json machine-readable output + human-readable fix plan. Use before merging when CI is red; does not implement fixes, only diagnoses.

9-Tier Anti-Slop Classification Matrix

Branching Rules & Permissions

Procedure

Phase 0: Pre-Flight Context & Doc Sync Gate, Dynamic .gitignore & Workspace Security

Before executing any Git operations or staging commits, verify context synchronization and repository hygiene:

1. Pre-Flight Context & Doc Freshness Gate (Zero Token Waste):
   • Check if updateagents and updatedocs are already fresh from the current turn or last message (bun skills/core-engine/git/scripts/git-preflight.ts --preflight-check).
   • If fresh (CACHE_HIT), skip execution immediately to avoid burning 10,000–30,000 tokens on redundant passes.
   • If drift is detected, run bun skills/core-engine/git/scripts/git-preflight.ts --preflight-run to synchronize context (updateagents) first, then documentation (updatedocs), and record cache receipts before staging commits.
2. Dynamic .gitignore Seeding:

   if [ ! -f ".gitignore" ]; then
     echo "🛡️ .gitignore missing. Seeding hardened Zero-Leakage template from updateagents..."
     TEMPLATE_PATH="$(git rev-parse --show-toplevel 2>/dev/null)/updateagents/templates/gitignore.template"
     if [ -f "$TEMPLATE_PATH" ]; then
       cp "$TEMPLATE_PATH" .gitignore
     else
       cat > .gitignore << 'EOF'

.e[n]v .e[n]v.* !.e[n]v.example node_modules/ dist/ build/ .worktrees/ worktrees/ .agents/ .gemini/ .claude/ .cursor/ .DS_Store *.log EOF fi git add .gitignore git commit -m "chore(git): seed hardened zero-leakage .gitignore" else # Ensure worktrees directory is ignored if ! git check-ignore -q .worktrees 2>/dev/null; then echo -e "\n# Git Worktrees\n.worktrees/\nworktrees/" >> .gitignore fi fi

3. **`.gitignore` Wildcard Trap & Tracked Index Cache Audit**:
Audit `.gitignore` rules for negative parent directory exclusion traps (`dir/` pruning `!dir/file`) and index cache leaks:
```bash
bun skills/core-engine/git/scripts/gitignore-audit.ts --audit
bun skills/core-engine/git/scripts/gitignore-audit.ts --check-tracked

If parent traps exist, automatically fix them with bun skills/core-engine/git/scripts/gitignore-audit.ts --fix.

Phase 1: Issue Intake & Anti-Slop Triage

1. View issue details using GitHub CLI:

   gh issue view <issue-id>

2. Classify against the 9-tier taxonomy.
3. If non-actionable, comment with clear evidence and close or defer.
4. If actionable, note the exact minimal scope and proceed to Phase 2.

Phase 2: Feature Branch Creation & Worktree Parallel Lanes

Choose the execution lane appropriate for your environment:

Option A: Worktree Parallel Lane (Recommended for Multi-Agent Workflows & Active Watchers)

Protects running dev servers (bun dev), file watchers, and parallel subagents from branch-switching churn:

1. Detect Existing Isolation & Submodule Guard:

   GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
   GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
   SUBMODULE=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
   # If GIT_DIR != GIT_COMMON and no SUBMODULE, already in a worktree—work in place!

2. Create Worktree Lane:

   git checkout dev && git pull origin dev
   git worktree add .worktrees/feat-<slug> -b feat/<issue-id>-<slug> dev
   cd .worktrees/feat-<slug>

3. Bootstrap & Verify Clean Baseline:

   bun install || npm install || cargo check || true
   bun test || npm test || cargo test

(For detailed worktree mechanics, see Worktree Parallel Lanes).

Option B: In-Place Working Tree Lane (Standard Single-Agent Fallback)

Used when sandboxing restricts worktrees or for simple isolated edits:

1. Ensure working tree is clean and dev is up to date:

   git checkout dev && git pull origin dev
   git checkout -b feat/<issue-id>-<slug> dev

Phase 3: Surgical Implementation, Interactive Rebase & Local Verification Gate

1. Implement the requested changes following the Surgical Changes Doctrine (touch only what is necessary; no unrequested refactors of adjacent code).
2. Interactive Rebase & Atomic Commits:
   • Keep commits atomic and self-contained.
   • Clean up intermediate checkpoint commits before pushing:

     git rebase -i dev  # Squash fixups, clean up commit messages

   • When updating a remote feature branch, always use --force-with-lease (never bare --force and never on shared branches).
3. Execute the verification suite:

   # Run tests
   bun test
   # Run type checks
   tsc --noEmit
   # Run pre-ship secret scan
   bun run secret-scan . 2>/dev/null || rg -i "ghp_|sk-[a-zA-Z0-9]{20,}|PRIVATE KEY" . || grep -riE "ghp_|sk-[a-zA-Z0-9]{20,}|PRIVATE KEY" . --exclude-dir={.git,node_modules,dist}

4. Commit using Conventional Commits format:

   git status --short          # review every line before staging
   git add <explicit paths>    # never `git add -A` / `git add .`
   git commit -m "feat(<scope>): <imperative summary> (Closes #<issue-id>)"

   The commit message must match git show --stat HEAD.

Phase 4: Documentation Synchronization (updatedocs)

1. Invoke updatedocs to synchronize project context with new code behavior:

   # Update CHANGELOG.md under [Unreleased] following the High-Signal Feature Craft Standard
   # (Section 4 in updatedocs/references/CHANGELOG-POLICY.md: thematic naming, multi-category, PR links)
   # Synchronize .agents/context/current.md

2. If docs were updated, commit:

   git add CHANGELOG.md .agents/context/
   git commit -m "docs(<scope>): update documentation and changelog"

Phase 5: GitHub SEO, Open Graph & Presentation Polish

1. Audit and sync repository topics, description, and homepage:

   gh repo edit --add-topic "ai-agents,developer-tools,agent-skills,devops,release-automation"
   gh repo edit --description "Autonomous end-to-end Git release engine with anti-slop issue triage and automated doc sync."

2. Verify social preview card exists in assets/banner.svg or assets/banner.png.
3. Check README visual layout against Refactoring UI standards (clean badges, scannable tables, crisp typography, copy-paste quickstart).

Phase 6: Pull Request Creation & Review Gate

1. Push the branch to remote:

   git push -u origin feat/<issue-id>-<slug>

2. Open PR against dev:

   gh pr create --base dev --title "feat(<scope>): <summary>" --body "$(cat << 'EOF'
   ### Summary
   - Concise summary of changes.
   
   ### Verification Evidence
   - [x] All automated tests pass (`bun test`).
   - [x] Static type check passes (`tsc --noEmit`).
   - [x] Pre-ship secret scan passed.
   - [x] Documentation synchronized.
   
   Closes #<issue-id>
   EOF
   )"

2b. Clean-PR branch (GSD scaffolding filter, micro). When the branch carries GSD planning commits (.planning/ artifacts: PLAN.md, SUMMARY.md, STATE.md), mint a reviewer-facing branch with only code commits so the PR diff stays clean.

Source: tomascortereal/claude-code-setup gsd-pr-branch (same shape in open-gsd/gsd-core), raw SKILL.md fetched per lane-a-skillshub-remainder.md #11; enrich-only, no new skill or mode.

git checkout -b feat/<issue-id>-<slug>-pr <base>
git log --reverse --format=%H <base>..feat/<issue-id>-<slug> | while read c; do
  git cherry-pick -n "$c"                                   # stage each commit
  git reset -q HEAD -- '.planning/*' 2>/dev/null || true   # drop scaffolding
  git checkout -q -- '.planning' 2>/dev/null || true
  git commit -C "$c" --allow-empty --allow-empty-message 2>/dev/null || git cherry-pick --skip
done

Open (or retarget) the PR from the -pr branch; keep the full branch as the build record. Skip entirely when no .planning/ commits exist.

3. After the PR is open and CI runs, use review-mode substeps as needed: - pr-check — if CI is red: inspect failing checks, pull the failure logs, extract the failure snippet, produce --json machine-readable output + a human-readable fix plan. Does not implement fixes; diagnoses so the right mode (or a human) can.
   • code-review-comments — if review comments arrive: fetch → number + summarize each comment → apply selected fixes (delegates to code-review receive mode for the actual triage).

Phase 7: Staging Integration & Conflict Resolution Playbook (dev)

1. Verify CI workflow passes:

   gh pr checks

2. Merge Conflict Resolution (If conflicts occur during staging):
   • Scope Assessment:

     git diff --name-only --diff-filter=U

   • Rebase vs. Merge Decision: Rebase feature branches (git rebase dev); never rebase or force-push shared branches (dev, master). Use --force-with-lease on feature branches.
   • Emergency Abort & Code Extraction: If rebase loops or diverges catastrophically:

     git rebase --abort 2>/dev/null || git merge --abort 2>/dev/null
     git show feat/<slug>:path/to/file > /tmp/recovered-file
     # Reset branch to latest dev, re-apply extracted files, test, and commit cleanly

   • Reflog Safety Net: Recover lost states with git reflog -n 25 and git checkout -b recovery-branch HEAD@{n}. (For full details, see Conflict Resolution & Recovery Playbook).
3. Merge PR into dev using squash or linear rebase:

   gh pr merge --squash --delete-branch=false
   git checkout dev && git pull origin dev

Phase 8: Cut Production Release Branch & Pre-Release Sanitization Gate

1. Pre-Release Sanitization Gate:
   • Sweep and purge uncommitted scratch files (SESSION.md, planning/, screenshots/, test-*.ts, scratch/).
   • Audit repository visibility and licensing:

     VISIBILITY=$(gh repo view --json visibility -q '.visibility' 2>/dev/null || echo "UNKNOWN")
     # Ensure private client repos carry proprietary notices and package.json has "private": true

   • Synthetic ADE/IDE Artifact Sweep: Audit for and unwrap any synthetic ADE/IDE placeholders before release:

     if rg "\[\[ORCA_RICH_MD|<antArtifact|\[cursor:|<<<windsurf" . --exclude-dir={.git,node_modules,dist,.worktrees}; then
       echo "🚨 Synthetic ADE/IDE artifacts detected! Run 'bun updateagents/scripts/updateagents.ts . --sanitize' before release."
       exit 1
     fi

2. Determine SemVer Version & Monorepo Tag Scoping:
   • Auto-detect monorepo (pnpm-workspace.yaml, packages/, lerna.json, turbo.json):
     • Monorepo format: {package-name}-v{semver}
     • Standard single package: v{semver}
   • Tag Pre-Existence Gate:

     if git tag -l "$TAG_NAME" | (rg -q "^${TAG_NAME}$" 2>/dev/null || grep -q "^${TAG_NAME}$"); then
       echo "🚨 Tag $TAG_NAME already exists! Bump version in package.json."
       exit 1
     fi

   (For sanitization & monorepo rules, see Monorepo & Sanitization Protocol).
3. Cut release branch from updated dev:

   git checkout -b release/vX.Y.Z dev

4. Bump version in package.json and stamp CHANGELOG.md with version and release date:
   • Audit CHANGELOG.md against the High-Signal Feature Craft Standard (updatedocs/references/CHANGELOG-POLICY.md).
   • Append the comparison diff URL before the release divider: **Full Changelog**: https://github.com/<owner>/<repo>/compare/v<PREV>...v<NEW>
5. Commit release preparation:

   git add package.json CHANGELOG.md
   git commit -m "chore(release): vX.Y.Z"

Phase 9: Production Merge & Semantic Tagging

1. Switch to master and merge the release branch with --no-ff:

   git checkout master
   git pull origin master
   git merge --no-ff release/vX.Y.Z -m "Release: vX.Y.Z"
   git push origin master

2. Create annotated tag and push:

   git tag -a vX.Y.Z -m "release: vX.Y.Z"
   git push origin vX.Y.Z

3. Create GitHub release with release notes:

   gh release create vX.Y.Z --title "vX.Y.Z" --notes-file RELEASE_NOTES.md || gh release create vX.Y.Z --generate-notes

Phase 10: Back-Merge to dev

1. Merge master back into dev to keep staging strictly synchronized:

   git checkout dev
   git merge master
   git push origin dev

Phase 11: Safe Branch Pruning, Worktree Teardown & Issue Closure

1. Delete local and remote feature/release branches safely:

   git branch -d feat/<issue-id>-<slug>
   git push origin --delete feat/<issue-id>-<slug> 2>/dev/null || true
   git branch -d release/vX.Y.Z
   git push origin --delete release/vX.Y.Z 2>/dev/null || true

2. Safe Bulk Branch Pruning (Sweeps merged branches while protecting dev, master, and main):

   git branch --merged dev | (rg -v '^\*|main|master|dev|develop' 2>/dev/null || grep -vE '^\*|main|master|dev|develop') | xargs -r git branch -d
   git fetch --prune

3. Worktree Teardown (If feature lane was executed in a worktree):

   cd "$MAIN_REPO_ROOT"
   git worktree remove .worktrees/feat-<slug> 2>/dev/null || true
   git worktree prune

4. Close linked issues with release receipts:

   gh issue close <issue-id> --comment "Resolved and released in vX.Y.Z."

(For worktree audit taxonomy before deleting anything, see Worktree Parallel Lanes § Worktree Audit.)

Pitfalls

• Never Commit Directly to master: Direct commits to master violate production protection invariants. All changes must arrive via dev and release/*.
• Never Skip the Verification Gate: Merging unverified PRs introduces regressions and breaks staging pipelines. Always run tests and secret scans before opening or merging PRs.
• Never Leave Stale Branches: Unmerged or orphaned branches create cognitive clutter and trigger spurious merge conflicts. Clean up immediately after release.
• Never Include Unredacted Credentials: Scan diffs for .env files, API keys (sk-*, ghp_*), and private tokens before pushing.
• No Vague Commit Messages: Messages like "fixes bug" or "updates" are strictly forbidden. Always use Conventional Commits with scope and rationale.
• Never Force-Push Shared Branches: --force-with-lease is permissible only on isolated feature branches; force-pushing dev or master is catastrophic.
• Annotated tag pushes carry tagger identity. A git tag -a stores the committer's email in the tag object, so the same email-privacy rule as commits applies: use the noreply address (the repo's configured identity) or the push is rejected. Lightweight tags (git tag vX.Y.Z) do not, but annotated tags do. The same applies to merge commits (e.g. back-merging main into dev) — set the identity or amend with --reset-author.
• Verify the current branch before any write, amend, or push. git checkout <branch> can silently fall through to dev when the target is missing or ambiguous. Run git branch --show-current immediately before committing, amending, tagging, or pushing; a merge/amend/tag created on the wrong branch wastes a release cycle.
• gh pr merge --delete-branch fails when that branch is checked out. Switch off the branch (e.g. git checkout dev) before merging, or delete the branch in a separate step after the merge.
• gh api branch-protection context changes need POST, not PATCH. gh api -X PATCH .../branches/<b>/protection/required_status_checks does not add contexts reliably; POST to .../required_status_checks/contexts with contexts[]=name is the working call. Verify with a GET afterwards.
• Process-spawning tests need explicit timeout headroom. CLI/process tests that spawn subprocesses routinely exceed default 5s caps on CI (e.g. 15015ms vs 15000ms). Give explicit headroom in the test rather than weakening assertions; flaky red on a clean tree is a timeout, not a regression.
• Landing Gate (delivery is not commitment): A commit is not a delivery. Work is LANDED only when reachable from the integration branch on the remote; until then it is LOCAL. The words landed/shipped/merged/released/deployed/"verified on <branch>" may be used only after the gate exits 0 in the same session. Verdicts that cannot be confused: LANDED/LOCAL, REVIEWABLE/NOT REVIEWABLE — never "NOT LANDED" (it contains "LANDED"). Run bun run check:landed (or the repo's equivalent) and include the Remote state block in the close-out. If you cannot push, say LOCAL. Full standard: .agents/standards/landing-gate.md.
• Stuck? See Troubleshooting for symptom → one-command fix → deeper link.

Verification

Before marking this skill complete, verify:

1. git status shows a clean working tree.
2. master and dev branch pointers are properly synchronized.
3. Feature branch is cut strictly from dev (in-place or via .worktrees/).
4. Tests and secret scans pass cleanly.
5. GitHub release is published with valid tag vX.Y.Z (or {package}-vX.Y.Z in monorepos).
6. Obsolete feature branches and worktrees have been deleted locally and remotely.
7. Delivery uses the run report template — fill it at delivery.
8. Landing Gate exits 0 (or the report says LOCAL with the remaining steps).

References

• 🌲 Worktree Parallel Lanes Protocol
• ⚔️ Merge Conflict Resolution & Git Recovery Playbook
• 📦 Monorepo Tagging & Pre-Release Sanitization Protocol
• 🌳 Branching, Commits & Release Matrix
• 🛡️ Anti-Slop Issue Intake Matrix
• 🎨 GitHub SEO & Open Graph Presentation Guide
• 📥 Issue-to-PR Discipline
• 🕘 Session-Linked Commit History
• 🩺 Troubleshooting
• 🧾 Run Report Template
• 📜 Changelog Policy & High-Signal Craft Standard