Isolate Git work with ak:worktree

Use ak:worktree to create a separate Git checkout for a feature, inspect existing worktrees, audit branch health, or clean stale metadata. The Skill handles standalone repositories, monorepos backed by submodules, and work inside a superproject.

Choose ak:worktree for Git isolation

Use ak:worktree when

• You want a feature or fix isolated from the current checkout.
• Parallel workers need separate branches and directories.
• You need to inspect worktree paths, branches, dirty state, or divergence.
• Stale Git worktree metadata needs a preview and cleanup.
• A monorepo or submodule setup makes the correct worktree root unclear.

Choose another workflow when

• You only need a new branch in the current checkout.
• You need operating-system, container, credential, or network isolation.
• You want to stash or preserve uncommitted changes from the current checkout.
• You are ready to implement inside an existing worktree. Use ak:cook or the owning implementation workflow there.

Prepare Git and the runtime

Before you start:

• Complete Onboarding, and confirm the Kit containing ak:worktree is installed for the runtime and scope you use.
• Run from inside a Git repository.
• Use Node.js 18 or later and Git 2.5 or later.
• Inspect current changes. A new worktree starts from a branch or commit; it does not copy uncommitted changes from another checkout.
• Know the exact worktree or branch before any removal.

Run the Skill

/ak:worktree "fix checkout retry handling; base on main; preview before creating"

/ak:worktree "fix checkout retry handling; base on main; preview before creating"

$ak:worktree "fix checkout retry handling; base on main; preview before creating"

The Skill translates a normal description into the bundled worktree script. It detects fix, refactor, docs, test, chore, and perf; other normal descriptions default to a feat/ branch.

Understand naming and placement

When you provide a normal feature description, the Skill creates a lowercase kebab-case slug of at most 50 characters and adds the derived prefix. When you provide an exact branch name with uppercase letters, an issue key, or slash segments, it uses --no-prefix and preserves a validated version of that name.

Base detection checks dev, develop, main, then master, using a matching local or origin branch. If none exists, the script falls back to main; use --base when that fallback is not correct.

The worktree root is selected in this order:

1. An explicit path wins. --worktree-root is validated first.
2. An environment override comes next. WORKTREE_ROOT is honored when set and valid.
3. A superproject owns submodule worktrees. The root is placed under the topmost discovered superproject.
4. A monorepo keeps worktrees internally. It uses a worktrees directory under the monorepo root.
5. A standalone repository uses a sibling directory. This avoids placing worktrees inside the repository being checked out.

Understand what changes

1. The Skill inspects the repository. It reports repository type, project choices, base branch, root selection, and dirty state.
2. The Skill resolves project and branch naming. Ambiguous monorepo matches require a selection; invalid feature, base, or path input stops the run.
3. The Skill previews when requested. Dry-run returns the branch, base, path, project, and warnings without creating files or refs.
4. The Skill creates the worktree. It creates a worktree directory and a new branch from the base, or attaches an existing local or remote branch.
5. The Skill copies environment templates. Files named like .env*.example are copied into the new worktree with .example removed. The copied files are templates; their contents still need review.
6. The Skill handles optional submodules and dependencies. Submodules are checked out only with the explicit option. After creation, the workflow can run the package-manager or language setup inferred from the project files.
7. The Skill reports evidence. The structured result includes the path, branch, base and source, project, copied templates, and warnings.

Keep approval and safety with you

After removing a worktree, the script deletes its branch only with the safe -d check. An unmerged branch is kept and reported. prune cleans stale Git metadata; preview it first when auditing an unfamiliar repository.

Creation can write a branch, directory, copied environment templates, submodule checkouts, and dependency artifacts. Dependency installation may use the network and execute package lifecycle behavior. Request a preview and state whether installation is allowed when those effects matter.

Verify the result

A successful create should provide:

• The absolute worktree path and how its root was chosen.
• The exact branch and base branch, including whether the base was explicit or auto-detected.
• The selected monorepo project, when applicable.
• Whether submodules were checked out.
• Environment templates copied and any warnings.
• A clean status record or a clear explanation of expected dirty artifacts after setup.

Before implementation, enter the reported directory and confirm the branch, base, project files, copied templates, and dependency state. A successful Git command does not prove the new checkout contains local edits from another worktree.

Troubleshoot or continue

Continue with ak:cook inside the new checkout, or review Projects, artifacts, and checkpoints and Runtime adapters.

Know the current limits

• The script detects monorepos from Git submodules; other workspace layouts may be treated as standalone repositories.
• Worktrees isolate Git checkouts, not processes, secrets, ports, caches, databases, or external services.
• Automatic dependency setup depends on recognizable project files and the package manager available in the session.
• The test suite covers command output, naming, validation, dry-run, status, prune, and many path and monorepo cases, but some monorepo tests skip when their fixture is unavailable.
• Stable and beta contain identical ak:worktree Skill and script behavior.