Git Worktree Management

When to Use

At the start of a task, the user will tell you which environment to work in. This skill covers creating and removing worktrees — for starting the dev stack, see the dev-environment skill.

Creating a Worktree

The user gives you a task ID and optionally a branch name (if the branch already exists).

TASK_ID="AYC-123"  # from user
REPO_ROOT="$(git rev-parse --show-toplevel)"
WORKTREE_DIR="$(dirname "$REPO_ROOT")/ayunis-core-wt-${TASK_ID,,}"

# New branch from HEAD:
git worktree add "$WORKTREE_DIR" -b "feat/${TASK_ID,,}/work" HEAD

# OR existing branch:
git worktree add "$WORKTREE_DIR" "$BRANCH"

# Track the new branch in Graphite — REQUIRED before any `gt create`.
# `git worktree add -b` produces a branch Graphite doesn't know about, so the
# first `gt create` fails with "Cannot perform this operation on untracked
# branch". Track it as a child of main:
cd "$WORKTREE_DIR" && gt track --parent main

# Symlink secret .env files (gitignored, not in the new worktree)
ln -sf "$REPO_ROOT/ayunis-core-backend/.env" "$WORKTREE_DIR/ayunis-core-backend/.env"
ln -sf "$REPO_ROOT/ayunis-core-frontend/.env" "$WORKTREE_DIR/ayunis-core-frontend/.env"

# Install dependencies — ayunis-core is a pnpm workspace
# (pnpm-workspace.yaml + pnpm-lock.yaml at repo root, packageManager pinned to pnpm).
# Never `npm install` inside a sub-project — that creates a stray package-lock.json
# and resolves the wrong tree.
cd "$WORKTREE_DIR" && pnpm install

# Build the workspace packages so @ayunis/* types resolve (see below).
cd "$WORKTREE_DIR" && pnpm run build:deps

Build @ayunis/* deps before trusting a full typecheck

A fresh worktree has node_modules (after pnpm install) but not the built dist/index.d.ts for the @ayunis/* workspace packages — those only exist after the tsup build. Until you run pnpm run build:deps, a full pnpm exec tsc --noEmit emits ~60 TS2307 "Cannot find module '@ayunis/…'" errors on your branch AND on clean HEAD.

Never wave those TS2307 errors off as "pre-existing on clean HEAD." They are a missing-build artifact, not a real baseline — and treating them that way hides genuine type errors in your own new code behind the noise. In one session this masked a real bug (a raw 'mistral' string passed where an EmbeddingsProvider enum was required).

The pre-commit hook (tsc-files, staged-only) and ts-jest (transpile-only) both have blind spots that only a full post-build typecheck covers. So, in any worktree, before running or trusting tsc --noEmit:

cd "$WORKTREE_DIR" && pnpm run build:deps   # builds @ayunis/* dist/*.d.ts
pnpm exec tsc --noEmit                       # now TS2307 noise is gone; real errors surface

Empty Base Branch Gotcha

The worktree branch feat/<task>/work is the base — Graphite stacks are built on top of it (see the git-workflow skill). Following git-workflow, the first commit goes on a gt create child branch, leaving the worktree base intentionally empty.

That's fine until you push. gt submit --stack refuses to submit an empty base branch:

WARNING: This branch does not introduce any changes: ▸ feat/<task>/work
Nothing to submit!

Fix: re-parent the child directly onto main so the empty base drops out of the stack:

gt track --parent main --force   # run on the CHILD branch, not the base
gt submit --stack --force --no-interactive

Alternative (single-PR tasks): skip the gt create and commit on the worktree base branch directly with gt modify --commit so the base isn't empty in the first place. Prefer this when the task is a single self-contained change, not a stack.

Scenario C — Use an existing worktree

The user points you to a worktree that already exists. Just cd into it and start working.

WORKTREE_DIR="/path/to/existing/worktree"  # from user
cd "$WORKTREE_DIR"

Cleanup

Only tear down when the user asks you to, or when they explicitly say the task is complete. Worktrees persist across agent sessions.

# First stop the dev stack if running (see dev-environment skill)
cd "$WORKTREE_DIR" && ./dev down

# Remove the worktree (from the main repo)
cd "$REPO_ROOT"
git worktree remove "$WORKTREE_DIR"

Branch Naming

Worktree branches follow the pattern feat/${TASK_ID,,}/work (e.g., feat/ayc-123/work). This is the base branch that Graphite stacks are built on top of — see the git-workflow skill.