git-workflow
/git-workflow
Version control for one task card - work in an isolated branch or worktree, write compact Conventional Commits, keep history clean, resolve conflicts, and finish the branch (merge locally, open a pull request, or keep). Pushing to shared repos and deleting branches or work need approval. Use whenever a task changes files in a git repository.
- Author
- Sanit-mann ↗
- Repository
- The-Insectoids ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Version control for one task card - work in an isolated branch or worktree, write compact Conventional Commits, keep history clean, resolve conflicts, and finish the branch (merge locally, open a pull request, or keep). Pushing to shared repos and deleting branches or work need approval. Use whenever a task changes files in a git repository.
Original author description
Version control for one task card - work in an isolated branch or worktree, write compact Conventional Commits, keep history clean, resolve conflicts, and finish the branch (merge locally, open a pull request, or keep). Pushing to shared repos and deleting branches or work need approval. Use whenever a task changes files in a git repository.
How it works
- Approvals (hive rule 02-D7)
- 1. Isolate the work
- 2. Commit
- 3. Keep current and resolve conflicts
- 4. Finish the branch
- Pull requests
- Red flags
- Done when
SKILL.md preview
---
name: git-workflow
description: Version control for one task card - work in an isolated branch or worktree, write compact Conventional Commits, keep history clean, resolve conflicts, and finish the branch (merge locally, open a pull request, or keep). Pushing to shared repos and deleting branches or work need approval. Use whenever a task changes files in a git repository.
metadata:
kind: skill
castes: [coder, tester, documenter]
tags: [git, branching, worktrees, commits, pull-requests]
version: 1
status: vetted
sources:
- repo: affaan-m/ecc
path: skills/git-workflow/SKILL.md
license: MIT
- repo: obra/superpowers
path: skills/using-git-worktrees/SKILL.md
license: MIT
- repo: obra/superpowers
path: skills/finishing-a-development-branch/SKILL.md
license: MIT
- repo: juliusbrussee/caveman
path: skills/caveman-commit/SKILL.md
license: Apache-2.0
---
# Git Workflow
Isolate your work, commit it in small clear steps, and hand it back in a state someone else can integrate or undo.
Commands, a PR template and recovery recipes: [references/commands.md](references/commands.md).
## Approvals (hive rule 02-D7)
Set the card to blocked with an approval request (what, why, exact effect) and wait for the Queen's answer before you:
- **push** to any shared remote, open a pull request, or push tags;
- **merge into a branch others use** (main, develop, release branches); the user choosing "merge locally" when finishing counts as this approval;
- **delete** a branch, a worktree with uncommitted files, or any commits ("discard");
- **rewrite shared history** (force-push, rebase of pushed branches).
Everything else here (branching, committing, rebasing your own unpushed branch, local merges inside your workspace) needs no approval.
## 1. Isolate the work
One task card, one branch, one workspace.
1. **Check for existing isolation first.** The hive may have already given you a workspace (a worktree, a separate checkout, a sandbox). Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`: if they differ (and `git rev-parse --show-superproject-working-tree` prints nothing, so it is not a submodule), you are already in a linked worktree. Don't create another.
2. **Prefer the harness's own workspace tool** if one exists. Creating worktrees behind its back leaves state it cannot see or clean up.
3. **Otherwise create a worktree yourself:**
- Location: a configured worktree directory if one is declared; else an existing `.worktrees/` (preferred) or `worktrees/` in the project; else create `.worktrees/`.
- Verify a project-local directory is git-ignored (`git check-ignore -q .worktrees`). If not, add it to `.gitignore` and commit that first, or the worktree's contents get committed.
- `git worktree add .worktrees/<branch> -b <branch> <base>`
- If creation is refused (sandbox, permissions), work in place on a new branch and say so.
4. **Set up and take a baseline.** Install dependencies with the project's normal command, then run the tests. If the baseline fails, record the failures and ask before proceeding: a dirty baseline makes every later failure ambiguous.
**Branch names:** `<type>/<short-description>`, e.g. `feat/order-export`, `fix/login-redirect-loop`, `refactor/extract-pricing`, `chore/bump-parser`. Include a ticket id if the project does (`fix/456-null-total`). Branch from the base named in the task card; if none is named, ask.
**Branching strategy:** follow the repository's. Most use short-lived branches off `main` merged by pull request; some use `develop` plus release branches. Keep branches short-lived (days, not weeks).
## 2. Commit
Small, focused commits, each leaving the code building. One logical change per commit.
**Stage deliberately.** Add specific files or hunks, not everything. Review `git diff --staged` before committing. Never commit secrets, `.env` files, credentials, build output, dependency folders or editor files.
**Message format (Conventional Commits):**
```
<type>(<scope>)!: <imperative summary>
<body: why, only if needed>
<footer: BREAKING CHANGE: ..., Closes #123>
```
- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`. Scope is optional.
- Imperative mood: "add", "fix", "remove", not "added" or "adds".
- Subject ≤ 50 characters when possible, hard cap 72, no trailing period. Match the project's capitalization.
- Skip the body when the subject says it all. Add one for a non-obvious *why*, breaking changes, migration notes or linked issues. Wrap at 72.
- **Always include a body** for breaking changes, security fixes, data migrations and reverts.
- Mark breaking changes with `!` and a `BREAKING CHANGE:` footer.
- Leave out: "this commit…", "I", "we", "now", restating file names the scope already gives, emoji (unless the project uses them).
- Attribution trailers (co-author, AI assistance): follow the project's or user's rule; don't invent one.
```
fix(api): retry upstream calls on 503
Upstream returns 503 under peak load; retry with backoff,
max 3 attempts.
Closes #123
```
## 3. Keep current and resolve conflicts
- **Your own, unpushed branch:** rebase onto the latest base to keep history linear (`git fetch`, then `git rebase origin/<base>`). Re-run tests after.
- **A branch that is pushed or shared:** merge the base in instead. Never rebase or force-push shared history without approval. If you must update your own pushed branch after an approved rebase, use `--force-with-lease`, never plain `--force`.
- **Never force-push** `main`, `develop` or any protected branch. Undo public commits with `git revert`.
- **Conflicts:** read both sides and understand why each changed before choosing. Keep both intents when both are valid. Remove all conflict markers, run the tests, then continue. If the conflict touches code outside your task's scope and the right answer isn't clear, stop and ask.
- Prevent conflicts: keep branches small and short-lived, sync with the base often.
## 4. Finish the branch
1. **Verify on the exact tree you will hand over.** Run the full test suite (and build/type checks). If anything fails, stop: report the failures; the options below come only after a green run.
2. **Confirm the base branch** this work forked from. If it isn't stated on the card or in the branch's upstream, ask. Merging into the wrong base is expensive to undo.
3. **Tidy local history** if it helps reviewers (squash "wip" and fix-up commits on your unpushed branch). Don't rewrite pushed history.
4. **Report and let the decision be made.** The integration choice belongs to the user (via the Queen) unless the task card already states it. Offer exactly:
1. **Merge locally** into the base branch.
2. **Push and open a pull request** (needs approval).
3. **Keep the branch as-is** for later.
From a detached HEAD, offer only 2 (pushed as a new branch) and 3.
5. **Carry out the chosen option.**
- *Merge locally:* go to the main checkout, update the base, `git merge <branch>`, then run the tests on the merged result. If they fail, stop and leave the branch and worktree in place. If green, clean up (step 6) and delete the merged branch with `git branch -d` (safe delete).
- *Pull request:* push with `-u`, open the PR with the forge's tooling following the repo's template, put the PR link in the task result. Keep the worktree: review fixes happen there.
- *Keep:* report the branch name and worktree path.
6. **Clean up only what you created.** Remove the worktree from outside it (`git worktree remove <path>`, then `git worktree prune`). Only remove worktrees you created under the project's worktree directory; anything else belongs to the harness. If removal is refused because of modified or untracked files, never use `--force`: list the files and ask whether to commit them, move them, or delete them.
**Discarding work** happens only when explicitly requested. Before deleting, show exactly what will be lost (branch, commit list, worktree path) and get explicit confirmation of that list.
## Pull requests
- Title in commit format: `feat(auth): add SSO for enterprise users`.
- Body: what, why, how it was tested, linked issues. Use the repo's template if it has one.
- Keep it to one feature or fix; aim for under ~500 changed lines.
- Self-review the full diff before asking anyone else to.
## Red flags
- Committing directly to `main` or another shared branch.
- `git add .` without looking at what is staged.
- A rejected push "fixed" with force-push. A rejection means the remote moved: fetch and investigate.
- "Tests passed earlier" as proof for a tree that has changed since.
- Commit messages like "update", "fix", "wip" on work being handed over.
- Cleaning up a worktree or branch you did not create.
## Done when
- Work is committed on its own branch with clear messages, tests green on the final tree.
- The chosen finish option is carried out, or the decision is requested on the task card.
- The task result lists branch name, commits, worktree path or PR link, and any pending approvals.
Files in this package (2)
- SKILL.md 9 KB
- references/commands.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Sanit-mann/The-Insectoids | 100 | MIT |
| event4u-app/agent-config | 100 | MIT |
| lee-w/maigo | 100 | MIT |
| hakula139/plugins | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| eliyce/paqad-ai | 100 | MIT |
| langfuse/langfuse | 100 | MIT |
| Muvon/octomind-tap | 100 | Apache-2.0 |
| aws-solutions/konductor | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 704e1c2af07c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90git
Commit, open a pull request, merge, or clean up branches under the git law in ~/.foxrun/config/git.md, and make a worktree only on a direct word. Merge always runs the law check first. Use for /git commit, /git pr, /git merge, /git clean, /git worktree, or when someone says commit this or merge it. - 100worktree-merge
Fold ONE worktree's branch INTO another branch using git merge. Use when combining a worktree branch into a parent, batching small fixes into one branch before opening a single PR, or folding sub-feature branches back together. Triggers on "merge this worktree into X", "fold… - 90worktrees:finish
Use when completing work in a worktree. Handles PR creation or direct merge, worktree removal, and branch cleanup. Invoke with "/worktrees:finish" or when user mentions "finish worktree", "clean up worktree", "merge worktree", "done with worktree", or "complete worktree work". - 100git-worktree-finish
Use when the user asks to finish, land, or merge back a feature worktree created with /git-worktree. - 100branch-commit-pr
Create a professionally named local git branch, commit the current changes in clean Conventional Commits (no Claude/AI signature), push it, and open a GitHub pull request. Use when the user asks to "make a branch and PR", "commit and open a PR", "ship these changes", or invokes /branch-commit-pr. - 100git-commit-and-workflow
Git commit, branch and pull request best practices using Conventional Commits. Use whenever creating commits, naming branches, preparing pull requests, writing commit messages, or when asked to commit, push, merge or release code.