Stats
Actions
Tags
From harness-claude
Creates isolated git worktrees for branch work, auto-installs dependencies, verifies baselines, and handles branch finishing with clean isolation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-claude:harness-git-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Worktree setup, dependency installation, baseline verification, and branch finishing. Clean isolation for every workstream.
Worktree setup, dependency installation, baseline verification, and branch finishing. Clean isolation for every workstream.
on_pr or on_commit triggers fire and worktree management is neededPrompt the human in plain text — every choice and destructive confirmation in this skill (worktree location, discard-experiment, etc.) is plain text only. Do not elevate to AskUserQuestion: option labels like the A/B/C worktree-location choices and natural headers like "Discard commits" routinely exceed its 4-option / 12-char caps and render as ERR.
Check for .worktrees/ directory in the project root. If it exists, use it — this is the preferred location.
Check CLAUDE.md or AGENTS.md for worktree preferences. Some projects specify a custom worktree directory or naming convention. Follow those instructions.
If neither exists, ask the user: "Where should I create the worktree? Options: (A) .worktrees/<branch-name> in the project root, (B) a sibling directory alongside the project, (C) a custom path."
If placing worktrees in the project directory, verify that the worktree directory is gitignored. Check .gitignore for .worktrees/ or the chosen directory name. If not gitignored, add it before creating the worktree.
Run git worktree list to see active worktrees.
If a worktree already exists for the target branch, do not create a duplicate. Ask: "A worktree for branch <name> already exists at <path>. Should I use it, or create a new branch?"
If the target directory already exists (but is not a worktree), do not overwrite. Ask the user how to proceed.
Create the branch from the current HEAD (or from the specified base):
git branch <branch-name> <base>
Create the worktree:
git worktree add <path> <branch-name>
Verify the worktree was created. Check that the directory exists and contains a .git file (not a .git directory — worktrees use a file pointing to the main repo).
Inspect the worktree for project files and run the appropriate setup:
| File Found | Action |
|---|---|
package.json | npm install (or yarn install / pnpm install if lockfile indicates) |
Cargo.toml | cargo build |
go.mod | go mod download |
requirements.txt | pip install -r requirements.txt |
pyproject.toml | pip install -e . or poetry install |
Gemfile | bundle install |
Makefile (with install target) | make install |
If multiple project files exist (monorepo), install at the root level. Do not guess which subpackages to install — follow the project's documented setup or ask.
Before any work begins, verify the worktree is in a clean, working state:
Run the test suite. All tests must pass on the fresh branch before any changes.
Run harness validate. Project health must be green before starting work.
If tests fail or validation fails on the fresh branch, stop. The base branch has issues. Report: "Baseline verification failed on fresh branch: [failure details]. The base branch needs to be fixed first."
Record the baseline. Note the test count and validation result. This is the comparison point for the branch finishing phase.
When work on the branch is complete, follow this protocol to land the changes.
Run the full test suite. All tests must pass.
Run harness validate. Project health must be green.
Check for uncommitted changes. Run git status. All changes must be committed. If there are uncommitted changes, commit or stash them before finishing.
Check the branch is up to date. If the base branch has advanced since the worktree was created:
git fetch origin
git log HEAD..origin/main --oneline
If there are new commits on the base, rebase or merge before finishing:
git rebase origin/main
Re-run tests after rebasing.
Present 4 options to the user:
Merge locally. Merge the branch into the base branch on the local machine.
git checkout main && git merge <branch>Push and create PR. Push the branch to the remote and open a pull request.
git push -u origin <branch> then create PR via gh pr createKeep as-is. Leave the branch and worktree in place for continued work later.
Discard. Delete the branch and worktree. All changes are lost.
If merge locally:
cd <main-repo-path>
git merge <branch-name>
# Run tests on main after merge
# Run harness validate after merge
git worktree remove <worktree-path>
git branch -d <branch-name>
If push and create PR:
cd <worktree-path>
git push -u origin <branch-name>
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<PR body with real newlines — never use \n escape sequences>
## Test plan
<checklist>
EOF
)"
# Report the PR URL to the user
# Leave worktree in place until PR is merged
If keep as-is:
No action needed. Report the worktree path and branch name for future reference.
If discard:
# Confirm with user first — list commits that will be lost
git worktree remove <worktree-path>
git branch -D <branch-name>
GitHub auto-links any #N token in commit messages, PR titles, and PR bodies to the issue or PR with that number. Treat #N as a reserved sigil — never use it for non-issue references.
#N for proposal success criteria, list ordinals, footnote refs, table rows, or any other in-document numbering. Write "criterion 9", "item 9", "step 3" instead. Using #9 to mean "criterion 9" will silently cross-reference issue #9 — which is almost certainly an unrelated issue — and add a misleading back-reference to that issue's timeline.Refs #<issue> for context-only links and Closes #<issue> / Fixes #<issue> only when the merge should auto-close that issue.#N tokens. For each one, confirm it points to the intended issue/PR — or rewrite it as plain text.Remove the worktree (unless keeping as-is or waiting for PR merge):
git worktree remove <worktree-path>
Prune stale worktree references:
git worktree prune
Verify cleanup. Run git worktree list and confirm the removed worktree is no longer listed.
harness validate — Run during baseline verification (Step 5 of Part A) and pre-finish verification (Step 1 of Part B). Ensures project health is green at both boundaries..gitignore — Verify worktree directory is gitignored if it lives inside the project tree..worktrees/ preferred, or per project convention)| Rationalization | Reality |
|---|---|
| "The tests are probably fine on the fresh branch — they were passing on main when I last checked. I'll skip baseline verification and start working." | Baseline verification is the condition that makes branch work trustworthy. A test failure discovered at finish time is ambiguous — it could be pre-existing or introduced by the work. Skipping baseline removes the only clean comparison point. |
| "The user said 'just merge it' — I'll merge without checking if the base branch has advanced since the worktree was created." | The pre-finish check for base branch divergence is mandatory before any finishing strategy. Merging without rebasing first can produce a merge that silently breaks tests that were passing on the branch but conflict with new commits on main. |
| "The worktree directory isn't gitignored, but it's inside a nested folder that's unlikely to be committed accidentally." | The .gitignore check is not about likelihood — it is about preventing accidental commits of worktree state that would corrupt the repository. If the worktree directory is not gitignored, add it before creating the worktree. No exceptions. |
| "The user chose to discard — I'll delete the branch and worktree immediately without showing the commits that will be lost." | The discard path requires showing the commit list from git log main..HEAD --oneline and receiving explicit confirmation before running git worktree remove and git branch -D. Work is being permanently deleted; the user must see what they are losing. |
| "There's already a worktree for this branch at a different path — I'll create a second one since the user asked for a fresh setup." | Git does not allow two worktrees checked out to the same branch. Attempting to create a duplicate will fail. Instead, ask the user whether to use the existing worktree or create a new branch. Never assume a second worktree is the right answer. |
"I'll use #9 in the commit message to refer to 'success criterion 9' in the proposal — it's obviously an in-document reference." | #N is GitHub's reserved syntax for issue/PR links in commits and PR bodies. It will auto-link to issue/PR #9 regardless of intent and post a misleading back-reference on that unrelated issue. Write "criterion 9" (no #) and cite the real roadmap issue separately with Refs #<n>. |
# Check for preferred location
ls .worktrees/ # exists — use it
# Check gitignore
grep '.worktrees' .gitignore # found — good, already gitignored
# Check existing worktrees
git worktree list
# /Users/dev/project abc1234 [main]
# No existing worktree for this feature
# Create branch and worktree
git branch feat/notifications main
git worktree add .worktrees/notifications feat/notifications
# Auto-detect setup (found package.json)
cd .worktrees/notifications && npm install
# Verify baseline
npm test # 142 tests, all pass
harness validate # passes
# Ready to work. Report:
# "Worktree created at .worktrees/notifications on branch feat/notifications.
# 142 tests passing. harness validate green. Ready to start."
# Pre-finish verification
cd .worktrees/notifications
npm test # 158 tests, all pass (16 new)
harness validate # passes
git status # clean — all committed
# Check if base has advanced
git fetch origin
git log HEAD..origin/main --oneline
# 3 new commits on main — rebase
git rebase origin/main
npm test # still passes after rebase
# User chooses: Push and create PR
git push -u origin feat/notifications
gh pr create --title "feat(notifications): email and in-app notifications" --body "$(cat <<'EOF'
## Summary
Implements notification service with create, list, and expiry.
## Test plan
- [x] 16 new tests, all passing
EOF
)"
# Report: "PR created: https://github.com/org/repo/pull/42
# Worktree at .worktrees/notifications kept until PR merges."
# User says: "That approach didn't work, let's scrap it."
# Show what will be lost
git log main..HEAD --oneline
# a1b2c3d try websocket approach
# d4e5f6g add socket.io dependency
# "These 2 commits will be lost. Discard? (yes/no)"
# Human: "yes"
git worktree remove .worktrees/ws-experiment
git branch -D feat/ws-experiment
git worktree prune
git worktree list # ws-experiment no longer listed
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeAutomates git workflow: creates isolated worktrees for features with .gitignore safety checks, enables atomic commits, completes branches via merge, PR, preserve, or discard.
Creates isolated git worktrees for parallel development without disrupting the main workspace. Includes safety verification to prevent accidental commits of worktree contents.
Creates isolated git worktrees with smart directory selection and safety verification. Use when starting feature work needing branch isolation.