# Git Workflow > This skill should be used when the user asks to "init a repo", "set up git", "manage branches", "switch branch", "create a worktree", "list worktrees", "clean merged branches", "sync with remote", "git activity", "git recap", "protect main", "apply branch protection", "bypass protection", "undo a commit", "fix a git mistake", or mentions git lifecycle, worktrees, branch protection, GitHub-side baseline protection, safety rails, or learning git workflows. Covers craft's full git lifecycle — repo init, branch and worktree management, remote sync, status/recap, local and GitHub-side branch protection, and the learning/safety reference docs. Use when this capability is needed. - Skill: `tomevault-io/git-workflow-22` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-22` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-22/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/git-workflow-22 --- # Git Workflow End-to-end git lifecycle for craft users: initialize a repo, manage branches and worktrees, sync with remotes, protect (or temporarily bypass) main/dev, and surface the learning/safety reference material when users ask "how do I undo X?". Consolidates the 10 `commands/git/*.md` commands and 4 `commands/git/docs/*.md` reference docs into one coherent skill. ## When to Use Activate when the user's prompt matches any of these concerns: | User intent | Operation | |-------------|-----------| | "init repo", "set up git", "bootstrap repository" | Repo init | | "show branches", "new branch", "switch branch", "delete branch" | Branch management | | "git status", "what's the state of this repo" | Enhanced status | | "clean merged branches", "delete merged" | Branch cleanup | | "create a worktree", "list worktrees", "remove worktree", "finish worktree" | Worktree management | | "sync with remote", "pull and push", "update from upstream" | Sync | | "git activity", "git recap", "what did I commit today" | Activity summary | | "protect main", "enable branch protection", "configure protection level" | Local protection | | "apply baseline protection", "github-side protection", "PR-required setup" | GitHub-side protection | | "bypass protection", "unprotect", "let me commit to main once" | Session bypass | | "how do I undo X?", "fix a git mistake", "I messed up git" | Undo reference | | "teach me git", "learn git workflow", "git refcard" | Learning material | | "what are the safety rails?", "is this safe?" | Safety reference | If the prompt is ambiguous, default to **enhanced status** (cheapest) and offer follow-ups. ## Prerequisites - Git installed (`git --version`) - For protection / GitHub-side operations: `gh` CLI authenticated - For worktrees: shared `~/.git-worktrees/` directory convention (created on first use) - For learning material: no prerequisites — pure reference ## Operations ### 1. Repo Init Bootstrap a new git repo with craft's workflow conventions. **Inputs:** optional remote (`OWNER/REPO` or URL), workflow pattern (`main-dev` | `simple` | `gitflow`), `--dry-run`, `--yes` for non-interactive. **Steps:** 1. `git init` (idempotent — detect existing `.git/`). 2. Scaffold initial commit if working tree is empty. 3. If `main-dev` workflow (the craft default for multi-branch repos): create `dev` branch off `main`, set `dev` as the integration branch. 4. If `remote` provided: `gh repo create ` (private by default), set origin, push both branches. 5. Apply local branch-guard rules (see Operation 8) and optionally GitHub-side baseline (Operation 9). 6. Write a starter `.gitignore`, `README.md` skeleton, and `CLAUDE.md` template if absent. **Default workflow:** `main-dev` (craft's recommended pattern). Switch to `simple` only when the user explicitly opts out of the dev integration branch. ### 2. Branch Management Create, switch, and delete branches safely. **Sub-actions:** `new `, `switch `, `delete `, `sync` (alias to Operation 6), and a default no-arg overview. **Safety rules (enforced before any destructive action):** - Never delete the current branch. - Never delete protected branches (`main`, `master`, `dev`, `develop`). - Refuse to switch if working tree has uncommitted changes — suggest `git stash` or commit first. - For `new`, default base is `dev` if it exists, else `main`. ### 3. Enhanced Status `git status` with extra context: current branch, ahead/behind, worktree-aware path, teaching-mode hints if a `_teaching/` directory exists. **Modes:** `--verbose` (full `git status` after the summary), `--compact` (one-line summary only). Use this as the cheap default when the user's prompt is ambiguous. ### 4. Branch Cleanup Remove merged feature branches that no longer have work in progress. **Steps:** 1. List branches merged into the integration branch (`dev` or `main`). 2. Skip protected branches and the current branch. 3. Skip branches with uncommitted changes or unpushed commits. 4. **ORCHESTRATE check:** warn if any `ORCHESTRATE-*.md` files remain on `dev` — they're working artifacts and should have been deleted by the `worktree finish` step. 5. Preview deletions in `--dry-run`; confirm interactively before executing. **Never** run `git branch -D` without explicit confirmation. ### 5. Worktree Management Parallel development via `git worktree` — each branch in its own folder, no stash juggling. **Sub-actions:** | Action | Behavior | |--------|----------| | `setup` | One-time: create `~/.git-worktrees//`, configure conventions | | `create ` | Add a worktree for a new or existing branch | | `move ` | Relocate an existing worktree (e.g., into the shared root) | | `list` | Show all worktrees with branch + path | | `clean` | Remove stale/merged worktrees safely | | `finish` | Post-merge cleanup: delete worktree, delete branch, remove `ORCHESTRATE-*.md` | | `validate` | Check worktree health (orphaned dirs, locked refs, branch drift) | | `install` | Install the worktree helpers into a new project | **Convention:** `~/.git-worktrees//feature-/`, branch named `feature/`, base typically `dev`. **Critical safety rule:** before any git operation in a worktree, verify CWD and branch with `git worktree list` + `git branch --show-current` — sessions are CWD-pinned and absolute paths may diverge. ### 6. Remote Sync Pull and push with conflict-handling guidance. **Steps:** 1. Detect divergence: ahead/behind counts against upstream. 2. Fast-forward pull if behind only. 3. If both ahead and behind: prompt for `rebase` vs `merge` (default rebase for feature branches, merge for `dev`/`main`). 4. Push after pull; report any non-fast-forward rejections instead of force-pushing. **Never** force-push to protected branches (`main`, `dev`). For feature branches, prefer `--force-with-lease` over `--force`. ### 7. Git Activity Recap Lightweight summary: today's commits, this week's commits, branch ahead/behind, unpushed work, open PRs (`gh pr list --author @me`). **Modes:** `default` | `detailed` | `summary`. Complements (does not replace) the broader `recap` operation in `adhd-workflow` — that one reads `.STATUS`; this one reads git history. ### 8. Local Branch Protection Re-enable or configure craft's local `branch-guard.sh` hook (the layer that blocks commits to `main` / new code on `dev` / etc.). **Sub-actions:** `--show` (display current config), `--level `, `--reset` (revert to auto-detect), `--no-hard-deny` (skip the hard_deny installation prompt). **Three protection levels:** - `smart` — matches the craft default table (main blocked, dev allows existing-file edits, feature/* allows all). - `block-all` — paranoid; nothing flows through `main` or `dev` without explicit unprotect. - `block-new-code` — allows .md and config edits, blocks new code files on `dev`. This operation manages the **local hook only**. For GitHub-side protection, see Operation 9. ### 9. GitHub-Side Baseline Protection Apply craft's GitHub-side baseline (PR required with `required_approving_review_count: 0`, no force-push, no deletions) to any repo via `gh api -X PUT repos/OWNER/REPO/branches//protection`. **Arguments:** `--repo OWNER/REPO`, `--branch`, `--check ` (repeatable, for required status checks), `--strict` (require up-to-date with base), `--dry-run`, `--remove`, `--show`. **API quirks to handle:** - `required_status_checks` and `restrictions` must be explicit `null` when absent — omitting them rejects the PUT. - Status check names with embedded commas (`test (ubuntu-latest, 3.12)`) need `--check` as a repeatable flag, never comma-separated parsing. - Route check names through `json.dumps()` / `jq -R -s`; never hand-build the JSON. - Human-readable headers go to stderr; JSON payload to stdout — preserves pipeability (`... | jq`). GitHub-side protection is **independent** of the local hook — `unprotect` (Operation 10) does NOT remove it. ### 10. Session Bypass (Unprotect) Session-scoped bypass of the local branch-guard hook. Persists until `protect` (Operation 8) re-enables, or the session ends. **Required input:** reason — one of `merge-conflict`, `ci-fix`, `maintenance`, or a freeform string for the audit log. Reason is logged to `.claude/branch-guard.log`. **Does NOT bypass:** GitHub-side protection, pre-commit hooks, or any other layer. Only the craft local hook. ### 11. Reference Docs (Learning, Refcard, Safety, Undo) When the user wants to **read** rather than **act**, surface the reference docs instead of running operations: | User intent | Doc to surface | |-------------|----------------| | "teach me git", "how does this workflow work", "learning path" | `commands/git/docs/learning-guide.md` | | "quick reference", "git refcard", "cheat sheet" | `commands/git/docs/refcard.md` | | "is this safe?", "what are the safety rails?", "won't this break things?" | `commands/git/docs/safety-rails.md` | | "I messed up", "how do I undo X", "git emergency" | `commands/git/docs/undo-guide.md` | For undo specifically, prefer the doc over speculating — it has scripted recovery flows for the common "oh no" scenarios (wrong commit message, wrong branch, accidental push, deleted work, merge conflicts). ## Cross-Operation Patterns ### Always verify CWD and branch before destructive ops Worktrees and CWD-pinned sessions mean a single `git push` can land somewhere unexpected. Before any push, branch delete, or worktree remove: ```bash git worktree list git branch --show-current pwd ``` ### Branch architecture per repo Two patterns coexist in the craft ecosystem: - **Multi-branch:** `main` (PR only) ← `dev` (integration) ← `feature/*`. Used by **craft only**. - **Single-integration:** `main` (PR only) ← `feature/*`. All other repos. Detect with `git branch -a | grep -E 'remotes/origin/(main|dev)$'` before assuming which integration branch applies. ### Defense in depth Branch protection layers, weakest to strongest: 1. Convention (CLAUDE.md says "don't commit to main"). 2. Local pre-commit / branch-guard hook (Operation 8). 3. GitHub-side protection (Operation 9). Operation 8 is the everyday enforcer; Operation 9 is the backstop. Apply both for solo-dev repos — the GitHub side catches local bypasses or work pushed from another machine. ## Overlap with Other Skills - **`guard-audit`** — analyzes branch-guard rules to find false positives and proposes JSON config changes. **This skill** toggles the guard on/off and applies the baseline. Trigger phrases are distinct: guard-audit fires on "audit guard" / "guard friction" / "false positives"; this skill fires on "protect main" / "apply baseline" / "bypass protection". If the user reports the guard is blocking legitimate work, prefer `guard-audit` to tune config; if they want to toggle the layer, use this skill. - **`release`** — runs the release pipeline (version bump, PR, tag, GitHub release). It uses git heavily but doesn't manage the git lifecycle itself. Hand off to `release` when the user says "ship it" or "cut a release"; stay here for branch/worktree/protection concerns. - **`adhd-workflow`** — its `recap` reads `.STATUS` for session-level context. This skill's Operation 7 (git activity) reads git history. Both can be useful; run this skill's recap when the user explicitly says "git recap" or "git activity", and the other one for general "where did I leave off". ## Integration This skill replaces the 10 commands and 4 reference docs under `commands/git/` during the v2.34.0 → v3.0.0 migration: | Command | Operation | |---------|-----------| | `/craft:git:init` | 1 (Repo Init) | | `/craft:git:branch` | 2 (Branch Management) | | `/craft:git:status` | 3 (Enhanced Status) | | `/craft:git:clean` | 4 (Branch Cleanup) | | `/craft:git:worktree` | 5 (Worktree Management) | | `/craft:git:sync` | 6 (Remote Sync) | | `/craft:git:git-recap` | 7 (Git Activity Recap) | | `/craft:git:protect` | 8 (Local Protection) | | `/craft:git:protect-baseline` | 9 (GitHub-Side Protection) | | `/craft:git:unprotect` | 10 (Session Bypass) | | `commands/git/docs/learning-guide.md` | 11 (Reference: learning) | | `commands/git/docs/refcard.md` | 11 (Reference: refcard) | | `commands/git/docs/safety-rails.md` | 11 (Reference: safety rails) | | `commands/git/docs/undo-guide.md` | 11 (Reference: undo) | Both invocation paths work during the deprecation cycle. The skill auto-fires on natural-language match; explicit `/craft:git:*` paths continue to function until v3.0.0. ## Related Skills - `release` — when the next action is "ship it" or "cut a release". - `guard-audit` — when the user wants to tune guard config (false positives), not toggle protection. - `adhd-workflow` — session-scope recap and next-task; this skill is git-scope. - `project-planner` — multi-week project breakdowns; this skill handles the git lifecycle that planning eventually flows into. --- > Source: [Data-Wise/craft](https://github.com/Data-Wise/craft) — distributed by [TomeVault](https://tomevault.io).