# Git Workflow

> Manage git worktrees for parallel development sessions. Create isolated workspaces, check status, finish work with PRs, and clean up merged branches. Use when the user says /git-workflow, needs to create a feature branch worktree, check worktree status, push and create a PR from a worktree, or clean up merged worktrees. Triggers on worktree management and parallel development workflow requests. Use when this capability is needed.

- Skill: `tomevault-io/git-workflow-88` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-88`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-88/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-88

---


# Git Workflow Skill

Manage parallel development sessions using git worktrees. Each session gets its own isolated working directory and branch.

## Subcommands

Parse the user's arguments to determine which subcommand to run. If no argument, run `status`.

---

### `/git-workflow start <type/name>` or `/git-workflow start <name>`

Create an isolated worktree for a new feature branch.

**Steps:**

1. Parse the name. If it contains `/` (e.g., `fix/offset-bug`), use as-is. If not, prefix with `feat/` (e.g., `error-reporting` -> `feat/error-reporting`).
2. Extract the short name (part after `/`) for the worktree directory name.
3. Check if worktree already exists at `.worktrees/<short-name>/`. If yes, just show the path.
4. Check if `--base <branch>` was specified. Default base is `origin/main`.
5. Fetch the base: `git fetch origin`
6. Create worktree:
   ```bash
   git worktree add .worktrees/<short-name> -b <type/name> <base>
   ```
7. Output:
   ```
   Created worktree at .worktrees/<short-name>/
   Branch: <type/name> (based on <base>)

   Next steps:
     cd .worktrees/<short-name> && claude
   ```

**Supported branch types:** feat, fix, docs, chore, refactor, test, release

---

### `/git-workflow status`

Show all worktrees, branches, and recommended cleanup actions.

**Steps:**

1. Run `git worktree list` to get all worktrees
2. For each worktree, check dirty/clean: `git -C <path> status --porcelain`
3. Run `git branch -vv` for branch tracking info
4. Check for merged branches:
   - `git branch --merged main` for fast-forward merges
   - `gh pr list --state merged --json headRefName -q '.[].headRefName'` for squash merges
5. Show summary with recommended actions (which branches can be cleaned up)

---

### `/git-workflow finish`

Push the current branch and create a PR.

**Steps:**

1. Verify current branch is not main: `git branch --show-current`
2. Push with tracking: `git push -u origin <branch>`
3. Create PR: `gh pr create --fill` (or ask user for title/body)
4. Output the PR URL
5. Remind: "When PR is merged, run `/git-workflow cleanup` from the main worktree"

---

### `/git-workflow cleanup`

Remove completed worktrees and merged branches.

**Steps:**

1. Detect merged branches:
   ```bash
   git branch --merged main
   gh pr list --state merged --json headRefName -q '.[].headRefName'
   ```
2. For each merged branch (excluding main):
   - Check no open PRs: `gh pr list --head <branch> --state open`
   - Check worktree is clean: `git -C .worktrees/<name> status --porcelain`
   - If dirty, warn and skip
   - Remove worktree: `git worktree remove .worktrees/<name>`
   - Delete local branch: `git branch -d <branch>`
   - Ask user before deleting remote: `git push origin --delete <branch>`
3. Prune: `git remote prune origin && git worktree prune`
4. Show summary of what was cleaned

**Safety rules:**
- NEVER delete main
- NEVER delete branches with open PRs
- NEVER delete worktrees with uncommitted changes
- ALWAYS ask before deleting remote branches

---

## Rules

- Always use `origin/main` as base (not `git checkout main`) — avoids branch conflict with existing worktrees
- Worktree directory: `.worktrees/<short-name>/` relative to repo root
- One branch per worktree — git enforces this automatically
- Run `melos bootstrap` in new worktrees if the project uses melos

---
> Source: [BottlePumpkin/rfw_gen](https://github.com/BottlePumpkin/rfw_gen) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->