From ywc-agent-toolkit
Manages git worktree lifecycle: path resolution, creation, auditing, and pruning. Designed for coordinated use with parallel-executor and finish-branch, but usable standalone.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ywc-agent-toolkit:ywc-worktreesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Announce at start:** "I'm using the ywc-worktrees skill to manage the git worktree lifecycle for an isolated workspace."
Announce at start: "I'm using the ywc-worktrees skill to manage the git worktree lifecycle for an isolated workspace."
Single source of truth for git worktree priority resolution, creation,
audit, and pruning. Extracted from ywc-parallel-executor so the same
discipline is callable from any skill that needs worktree isolation
(parallel-executor's per-task worktrees, finish-branch's post-merge
cleanup, ad-hoc developer use). Pattern inspiration: superpowers
using-git-worktrees skill, adapted to this project's self-contained
runtime policy — referenced for design intent only, never dispatched at
runtime.
When tempted to skip a step, check this table first:
| Excuse | Reality |
|---|---|
| "Worktree location does not matter — drop it next to the repo" | Worktree path is a contract. Callers and audit tooling expect .worktrees/<task-name> or the project's documented worktree_root. Inventing a sibling path breaks every downstream cleanup that scans the documented location. |
"git worktree prune is enough — skip the audit step" | prune removes only stale metadata for worktrees whose directories are gone. It does not report worktrees whose directories still exist but were never claimed by any task. Audit catches both classes; prune alone hides drift. |
| "If a worktree path already exists, just reuse it" | A pre-existing path means either a prior run did not clean up (drift) or another task is currently using it (collision). Reuse silently corrupts whichever party is touching the path. Always treat existing paths as an error, not a hint. |
"The caller passed --mode create so the resolution step is decided — skip the audit" | Pre-flight audit is mandatory before any new worktree creation. Stale metadata from a previous run causes the new git worktree add to fail with a confusing "already registered" error; the audit + prune catches this before the user-visible failure. |
| "Worktree priority is overhead — the caller knows where it wants to go" | The priority chain (.worktrees/ > CLAUDE.md worktree_root > --root fallback) exists so that a project can pin a worktree location once (in its CLAUDE.md) and have every skill respect it. Callers that bypass the chain silently fragment worktree locations across the project. |
Violating the letter of these rules is violating the spirit. A stale worktree from yesterday's run is the most common cause of "the new run is broken for no reason" in parallel-executor.
| Parameter | Format | Example | Description |
|---|---|---|---|
--mode | <mode> | --mode create | One of create, audit, prune, resolve. See Modes. |
--task-name | <task-name> | --task-name 000001-010-db-create-users | The task this worktree belongs to. Required for create and prune; optional for audit. |
--branch | <branch-name> | --branch feature/000001-010-db-create-users | The branch to associate with the worktree. Required for create; optional for prune (defaults to feature/<task-name>). |
--base-branch | <branch-name> | --base-branch develop | The starting point for the new branch. Required for create (no default). |
--root | <path> | --root .worktrees | Fallback worktree root when the project has neither .worktrees/ nor CLAUDE.md worktree_root. Project-level configuration wins over this value. |
--expect | <task1,task2,...> | --expect 000001-010,000001-020 | (Audit only) Comma-separated list of task names that should currently have a worktree. Any extra or missing worktree fails the audit. |
--force | flag | (Prune only) Pass --force to git worktree remove even if the worktree is dirty. Use only when the caller has confirmed the worktree's contents are disposable. | |
--keep-branch | flag | (Prune only) Remove the worktree and prune stale metadata, but skip the local branch deletion (git branch -d) and its verification. Same semantics as ywc-finish-branch --keep-branch: use when the branch must survive the worktree teardown (e.g. an integration branch a caller will later raise a trunk PR from). |
| Mode | Reads | Writes | Use case |
|---|---|---|---|
resolve | .worktrees/ presence, CLAUDE.md worktree_root, --root | nothing | Caller wants to know where a worktree would land before committing to create. Returns the resolved path on stdout. |
create | resolved root + --task-name + --branch + --base-branch | git worktree add | Per-task worktree creation. Called by ywc-parallel-executor Step 4 for each in-wave task. |
audit | resolved root contents + --expect (optional) | nothing (read-only) | Pre-flight or wave-end audit. Reports stale, leaked, or unexpected worktrees. |
prune | resolved root + --task-name + optional --branch + optional --keep-branch | git worktree remove + local branch delete (skipped when --keep-branch) + git worktree prune | Post-merge cleanup. Called by ywc-finish-branch Step 5/8 and ywc-parallel-executor Step 4g. --keep-branch preserves the branch (e.g. ywc-sequential-executor --worktree non-aggregate teardown). |
Modes are mutually exclusive — --mode takes exactly one value. The caller chooses the mode based on the lifecycle stage; this skill does not infer.
The worktree root is resolved by walking the following chain in order; the first match wins:
.worktrees/ directory present in repo root — if the directory exists (even empty), it is the worktree root. This is the recommended pattern: a project commits an empty .worktrees/.gitkeep to make the location explicit and discoverable.worktree_root directive — if CLAUDE.md contains a line matching worktree_root: <path>, that path is the root. Allows projects to pin a location outside the repo (e.g., a sibling ../<repo>-worktrees/) without requiring an in-repo directory.--root <path> fallback — used only when neither .worktrees/ nor CLAUDE.md declares a project-level root. This lets callers pass an explicit location without overriding project policy.../ fallback — if none of the above match, fall back to ../worktree-<task-name> (the legacy parallel-executor convention). A warning is logged: the project should adopt .worktrees/ or the CLAUDE.md directive to make this explicit.The resolved path is recorded in the caller's payload and re-derived (not stored) on every invocation, so a mid-run change to CLAUDE.md or .worktrees/ presence takes effect on the next call.
--mode resolve--root was provided but is not a writable directory.No side effects. Safe to call from --dry-run paths in upstream skills.
--mode create--mode resolve internally to get the worktree root.<root>/<task-name> does not already exist. If it does, exit 1 with a descriptive error — never overwrite.git worktree add <resolved-path> -b <branch> <base-branch>.git worktree list --porcelain | grep <resolved-path> returns a row.Error handling: if git worktree add fails (locked, branch already exists elsewhere, etc.), surface the exact git error and exit 1. Never retry; the caller decides whether the failure is recoverable.
--mode audit--mode resolve to get the worktree root.scripts/audit-worktrees.sh against the resolved root. The script reports:
--expect task has a worktree.git worktree list rows whose directories no longer exist (stale metadata) OR directories under the root whose paths are not in git worktree list. Both cases fail the audit.--expect is provided, tasks in the expect list that do not have a worktree. Fails the audit.--expect is provided, worktrees that exist but are not in the expect list. Fails the audit (a previous task was not cleaned up).--mode prune--mode resolve to get the worktree root.scripts/cleanup-worktree.sh against the resolved task worktree path. The script:
git worktree remove <path> (or --force if --force was passed).git branch -d <branch> (default feature/<task-name>) after the worktree is released — unless --keep-branch is set, in which case the branch deletion and its verification are skipped. The branch name is treated as a git ref (it may legitimately contain /, e.g. integration/run-<slug> or work/<name>); only --task-name, which forms a path component, is allowlisted to ^[A-Za-z0-9_-]+$.--aggregate-pr integration branch already merged and deleted by its final PR), the deletion step is idempotent — it logs and continues rather than failing.git worktree prune to clear any stale metadata.--keep-branch is not set) the local branch no longer exists.The script refuses to operate on dirty worktrees unless --force is set — this is the discipline that catches accidental deletion of work in progress.
ywc-parallel-executor (Pre-flight --mode audit, Step 4 per-task --mode create, Step 4g --mode prune); ywc-finish-branch (Step 5/8 cleanup --mode prune when called from a parallel-executor context).scripts/audit-worktrees.sh (audit), scripts/cleanup-worktree.sh (prune + local branch deletion). Both moved here from ywc-parallel-executor/scripts/ via git mv, preserving history.Adapted from the superpowers using-git-worktrees skill. The priority resolution chain (.worktrees/ > CLAUDE.md > --root > fallback) and the four-mode interface (create / audit / prune / resolve) follow that pattern. This project's self-contained runtime policy means the superpowers skill is not dispatched at runtime — it is a design reference for the pattern shape only, and this file is the project-owned implementation.
This skill is the single source for worktree lifecycle. Callers must not re-implement worktree creation or pruning inline; doing so fragments the priority resolution chain and the audit / prune discipline. If a caller needs a worktree operation not covered by the four modes, extend this skill rather than work around it.
npx claudepluginhub yongwoon/ywc-agent-toolkitGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.