using-git-worktrees

Files (4)

• SKILL.md
• openai.yaml · agents/
• resolve-worktree · scripts/
• test-resolve-worktree · scripts/

SKILL.md (first lines)

# Using Git Worktrees

Use this before changing files in a Git repo. The goal is to keep each task in
its own working tree, branch, dependencies, and verification state.

Chad's repositories use the bare container layout owned by the
`cloning-repositories` skill: a bare repository at `<repo>/.git` with worktrees
directly under `<repo>/`, and the default branch worktree at `<repo>/main`. Read
that skill for clone commands and layout details. Do not use a normal checkout
at the repository root and do not put task worktrees under `.worktrees/`.

## When to use this

Use the workflow for file-changing work inside a Git repository. Skip it for
read-only tasks, discussion, research, or commands that do not modify repo
files.

## Start with the current state

Resolve an existing worktree before running status, diff, build, test, or
file-changing commands. Run the bundled read-only resolver from this skill's
directory:

```bash
scripts/resolve-worktree --cwd "$PWD" --mode write
```

When the task names a repository, branch, or pull request, pass it directly:

```bash
scripts/resolve-worktree \
  --repo ~/src/convergint/ee-monorepo \
  --branch agent/fix-sftp-tenant-validation \
  --mode write

scripts/resolve-worktree \
  --pr convergint/ee-monorepo#5678 \
  --mode write
```

The resolver never creates a branch or worktree. It reports the repository
container, selected worktree, branch, head SHA, dirty state, default-branch
status, mise trust state, and whether a pull request worktree matches the
current PR head. Use its absolute `worktree` value as the working directory for
every later command.

The resolver requires Bash and Git. JSON output requires `jq`, and pull request
resolution also requires `gh`.

Write mode refuses the default-branch worktree unless `--allow-main` is
explicitly provided. If no matching worktree exists, continue through the
topology decision below and create one only after choosing a single branch or
Stack. Re-run the resolver after creation to verify the selected checkout.

Treat unrelated dirty work as user-owned. Do not move, stage, revert, clean, or
overwrite another checkout's changes unless the user explicitly asks.

## Keep the default worktree current

Fetch the remote default branch before using it as the base for a new task
worktree. Also fetch whenever status, branch comparisons, or another command
shows that the default-branch worktree may be behind:

```bash
git -C <repo-container> fetch origin <default-branch>
git -C <main-worktree> status --short --branch
git -C <main-worktree> rev-list --left-right --count \
  <default-branch>...origin/<default-branch>
```

The counts are local-ahead and local-behind, in that order. When the default
worktree is clean and the counts are `0 N`, where `N` is greater than zero,
update it immediately without waiting for another request:

```bash
scripts/resolve-worktree \
  --repo <repo-container> \
  --main \
  --mode write \
  --allow-main

git -C <main-worktree> merge --ff-only origin/<default-branch>
```

`--allow-main` applies only to this synchronization. Do not make task changes in
the default worktree.

If the default worktree is dirty, ahead, or diverged, do not stash, reset,
rebase, merge, or overwrite it. Treat its state as user-owned and report why a
safe fast-forward was not possible. Base new work on the fetched remote default
branch when that lets the task continue without modifying the blocked worktree.

## Choose the necessary scope

Before choosing branches, state the observed failure and the behavior the user
needs after the fix. Find the boundary responsible for that failure and check
its existing configuration and supported interfaces first.

Choose the smallest safe change that delivers that behavior. For each proposed
migration, abstraction, helper script, release change, test harness, or
operating procedure, ask whether the requested fix would still work without it.
Leave out work that isn't needed for the outcome. Keep prerequisites required
for correctness, safety, or compatibility in scope and explain why they're
needed.

A dependency bot that can't look up a private Terraform provider may only need a
registry URL override and scoped credentials. Changing the application's
provider source, installation workflow, state, and release pipeline requires a
separate reason; sharing the same provider doesn't make those changes necessary.

If a narrow fix starts requiring a migration guide, a new wrapper, or several
layers of validation scaffolding, reconsider the boundary before adding more.
Prefer existing validation commands and a focused check of the failed behavior.
Complete the requested fix and surface useful broader improvements separately;
don't make them prerequisites or create follow-up work without a request.

## Choose the review topology

Decide how reviewers should receive the work before creating the first task

From chadxz/prompts, MIT.

More from chadxz/prompts