git-worktree-vibe-flow - SKILL.md Agent Skill

name: git-worktree-vibe-flow slug: git-worktree-vibe-flow version: 1.0.0 description: Mandatory worktree development SOP (GitHub PR). Always follow for branch/worktree/commit/push/PR lifecycle and parallel vibe coding.

Git Worktree Vibe Flow (GitHub PR)

Operate with a stable control worktree (repo root) + one task worktree per task.

Defaults:

Control worktree stays on base and always up to date.
All edits/tests happen in task worktrees.
Auto-commit + auto-push + auto-create PR.
After PR merge: auto-delete remote branch + remove worktree + delete local branch.

Safety rules (non-negotiable)

Never run destructive/history-rewriting commands: git reset --hard, git push --force, interactive rebase.
Never commit or print secrets. Never stage .env*/secret files.
Never remove a worktree unless it is clean.
Do not change global user config (git config, package manager global config) unless the user explicitly asks.

Conventions

Control worktree: the current directory.
Worktree storage (outside repo): <repo_parent>/.worktrees/<repoName>/<branchPath>.
Branch naming (preferred):
- feature/<slug> or fix/<slug>
- vibe/<YYYYMMDD>-<slug>
- slug: lowercase letters/digits/hyphen, keep short.

Control worktree contract (base always latest)

Every session start (from control worktree):

git fetch --prune origin
Determine base from origin/HEAD: git rev-parse --abbrev-ref origin/HEAD (e.g. origin/main)
git switch <base>
git pull --ff-only origin <base>

If control worktree is dirty: do not develop there; create/reuse a task worktree instead.

When to parallelize

Create a new worktree when tasks can progress independently or the current worktree is not clean. Avoid parallel worktrees if tasks touch the same core files.

Create/reuse task worktree

Reuse: git worktree list --porcelain (find branch refs/heads/<branch>)
Create (from control):
- Ensure parent dir exists: <repo_parent>/.worktrees/<repoName>/
- git worktree add -b <branch> <worktreePath> origin/<base>
Verify (in task worktree): git status + git branch --show-current

Bootstrap: symlink local secrets/config (whitelist only)

Goal: keep ONE canonical local secret/config in repo root; each worktree symlinks to it (no copying).

Whitelist (repo-root files only):

.env
.env.local
.env.*.local (e.g. .env.development.local)
.envrc (direnv)
config.local.*, settings.local.*, *.local.json, *.local.yml, *.local.yaml, *.local.toml
.npmrc (treat as sensitive; never print; never commit)

Rules:

Link only if (exists in control repo root) AND (ignored by git) AND (not tracked).
Never overwrite a real file in the task worktree.

Never link build outputs or dependency dirs (do NOT share across branches):

node_modules/, .venv/, dist/, build/, .next/, target/, out/.

Bootstrap: install dependencies (per worktree)

Always install dependencies inside the task worktree.

Prefer existing lockfiles/tools (do not migrate by default):

Node: pnpm-lock.yaml -> pnpm install; package-lock.json -> npm ci; yarn.lock -> yarn install --frozen-lockfile
Python: uv.lock -> uv sync; poetry.lock -> poetry install; else venv + pip per repo docs

Always remind about global-cache acceleration (recommendation, not an automatic migration):

If current setup lacks lockfile or installs are slow/unreproducible, recommend adopting a cached + reproducible flow (e.g. Node: pnpm; Python: uv/poetry). Only migrate if the user explicitly asks.

Work: commit, push, PR (default automatic)

In task worktree:

Make changes + run minimal relevant checks.
Guardrail: staged files must NOT include .env*, .npmrc, *.local.*.
Commit (match repo subject style; inspect git log -10 --pretty=format:%s).
Push: git push -u origin <branch>
PR: gh pr create --base <base> --head <branch> --title <title> --body <body>

If gh is not available:

Still push the branch.
Provide the exact compare URL template and ask the user to create/merge the PR manually.

PR body should include:

What/why, how to test, risks/follow-ups.

Track PR to completion; auto cleanup after merge

After PR is created:

Record PR URL/number.
Check status: gh pr view <pr> --json merged,mergedAt,state,headRefName,baseRefName,url

When PR is merged:

Delete remote branch: git push origin --delete <branch> (note if rejected, continue).
Remove worktree (must be clean): git worktree remove <worktreePath>
Delete local branch: git branch -d <branch>
git worktree prune

If PR is closed/unmerged:

Do not delete remote branch automatically.
Ask the user whether to keep branch/worktree for later or clean up.

Failure modes and what to do

Worktree add fails because branch is checked out elsewhere:
- Find the existing worktree via git worktree list --porcelain and reuse it.
Worktree remove blocked (unclean):
- Stop and ask: commit, stash, or discard (never discard automatically).
Secrets accidentally staged:
- Unstage immediately and add to .gitignore if missing; do not proceed until clean.