Quick Ref / Command

Engineer Kit

/ak:worktree

Git worktree isolation

Create, inspect, and clean isolated git worktrees for parallel feature work, worktree audits, stale metadata cleanup, monorepos, and submodule workflows.

01

Read repo info

02

Detect exact names

03

Infer branch type

04

Build the slug

Rule 01

Start by reading repo metadata with scripts/worktree.cjs info --json.

Rule 02

Use --no-prefix when the user supplied an exact branch name or convention.

Rule 03

Let configured worktree roots resolve by priority; use --worktree-root only for true overrides.

Rule 04

In monorepos, ask for or supply the project before creating the worktree.

Rule 05

Rely on env-template copying and background dependency installation inside the new worktree.

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

01

Start

Input, scope, route

  1. 1 Read repo info Run node scripts/worktree.cjs info --json, then parse repo type, base branch, projects, root location/source, dirty state, and dirty details.
  2. 2 Detect exact names If the caller provides uppercase, issue keys, slashes, or an explicit exact branch name, choose --no-prefix and preserve it as the slug.
02

Work

Agent / skill execution

  1. 3 Infer branch type Otherwise infer fix, refactor, docs, test, chore, or perf from the description, with feat as the default prefix.
  2. 4 Build the slug Convert the feature description to kebab-case up to 50 characters, skipping this step only when --no-prefix was selected.
03

Verify

Gate, review, validation

  1. 5 Resolve monorepo project For monorepos without a supplied project, ask the user which project path should receive the worktree.
  2. 6 Execute create Run scripts/worktree.cjs create with standalone or monorepo arguments plus --prefix, --base, --checkout-submodules, --json, --dry-run, or root overrides as needed.
04

Close

Report, handoff, artifact

  1. 7 Install dependencies In the new worktree, install dependencies in the background from the detected lockfile or manifest: bun, pnpm, yarn, npm, poetry, pip, cargo, or go.
  2. 8 Operate worktrees Use info, list, status, remove, and prune for health checks, normalized paths, base-branch divergence, removals, and stale metadata cleanup.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:worktree [feature-description]

or

/ak:worktree [project] [feature]

or

/ak:worktree <create|info|list|status|remove|prune> ...

Arguments

[feature-description] Required

Feature description

Natural-language feature or fix to isolate in a new worktree. May be an exact branch name; omit when running an explicit maintenance command.

/ak:worktree fix checkout retry handling
[project]

Monorepo project

Optional project name or path for monorepos. It selects which project receives the new isolated checkout.

/ak:worktree web fix checkout redirect
[feature]

Project feature

Feature description used with a monorepo project. The skill still derives or preserves the branch name from this value.

/ak:worktree web fix checkout redirect

Shared options

--prefix <type>

Branch prefix

Override the inferred branch type. Allowed values are feat, fix, refactor, docs, test, chore, and perf.

/ak:worktree create login hardening --prefix fix
--base <branch>

Base branch

Use an existing branch instead of the automatic dev, develop, main, then master detection order.

/ak:worktree create analytics export --base release/next
--no-prefix

Preserve exact name

Skip prefixing and preserve a validated supplied branch name, including case and safe slash segments.

/ak:worktree create ND-1377-cleanup-docs --no-prefix
--worktree-root <path>

Worktree root

Override where this skill places new worktrees after path validation. It does not affect host-created worktrees.

/ak:worktree create billing dashboard --worktree-root ../app-worktrees
--checkout-submodules

Checkout submodules

Run recursive submodule initialization in the new worktree after creation.

/ak:worktree create sdk update --checkout-submodules
--dry-run

Preview only

Preview create, remove, or prune without applying that filesystem or Git operation.

/ak:worktree prune --dry-run
--json

Structured output

Return structured result and error fields for automation and audits.

/ak:worktree status --json

Subcommands

create Create
/ak:worktree create [project] <feature> [--prefix <type>|--no-prefix] [--base <branch>] [--worktree-root <path>] [--checkout-submodules] [--dry-run] [--json]

Create or attach a branch in a new isolated worktree. Monorepos can pass the project first.

[project]
Optional monorepo project name or path.
<feature>
Feature description, slug, or exact branch name to isolate.

Outcome: New worktree path, branch, base branch, root source, copied env templates, warnings, and optional dependency setup evidence.

/ak:worktree create web fix checkout redirect
info Info
/ak:worktree info [--json]

Read repository type, detected base, projects, worktree root, env file names, and dirty-state counts.

Outcome: Repository metadata for deciding project, branch, base, and placement before a create operation.

/ak:worktree info --json
list List
/ak:worktree list [--json]

List normalized worktree records without removing or changing them.

Outcome: Normalized worktree paths, branches, and records for audit or selection.

/ak:worktree list --json
status Status
/ak:worktree status [--json]

Inspect worktree health, normalized paths, current/main flags, dirty state, branch existence, detected base, and ahead/behind counts.

Outcome: Current checkout health plus normalized worktree records and base-branch divergence details.

/ak:worktree status --json
remove Remove
/ak:worktree remove <name-or-path> [--dry-run] [--json]

Force-remove one matched worktree by exact name or path, then attempt a safe branch delete.

<name-or-path>
Exact worktree name or absolute path. Use status and dry-run first because removal can delete uncommitted checkout files.

Outcome: Matched worktree removed when not dry-run; merged branches may be deleted safely, while unmerged branches are kept and reported.

/ak:worktree remove /Users/me/app-worktrees/feat-demo --dry-run
prune Prune
/ak:worktree prune [--dry-run] [--json]

Clean stale Git worktree metadata. Use dry-run first for an audit pass.

Outcome: Stale metadata entries are listed in preview or removed during the confirmed prune operation.

/ak:worktree prune --dry-run

Special Operations

Exact branch mode

Select --no-prefix for Jira-style keys, uppercase branch names, multi-segment branches, or explicit exact-name requests.

Root resolution

Location priority is CLI --worktree-root, project config, user config, WORKTREE_ROOT, superproject, monorepo, then sibling directory.

Safe prune

Use prune --dry-run as the first pass when auditing stale worktree metadata.

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Create feature worktree Recommended
/ak:worktree create billing dashboard
Use when:
You need an isolated worktree for parallel feature development.
Expected:
Reads repo info, infers feat plus billing-dashboard, creates the checkout, copies env templates, and installs detected dependencies.
Preserve exact branch
/ak:worktree create ND-1377-cleanup-docs
Use when:
An issue tracker or team convention already supplied the branch name.
Expected:
Chooses --no-prefix, preserves uppercase and issue-key characters exactly, and creates the worktree without adding a feat/fix prefix.
Monorepo project
/ak:worktree create web fix checkout redirect
Use when:
A specific monorepo project should receive the new isolated checkout.
Expected:
Uses web as the project, infers a fix branch type, slugs checkout-redirect, then creates and initializes that project worktree.
Inspect worktree health
/ak:worktree status --json
Use when:
You need a worktree audit with normalized paths or base-branch divergence.
Expected:
Runs the status command, returns normalized worktree records, and includes the current checkout health and divergence details.
Preview stale cleanup
/ak:worktree prune --dry-run
Use when:
Worktree metadata may be stale after manual branch or directory cleanup.
Expected:
Audits stale metadata safely first, reports prune entries without removing them, and leaves the final cleanup decision explicit.
Repo info
/ak:worktree info --json
Use when:
You need parseable repo and worktree location facts before creating a checkout.
Expected:
Returns repoType, baseBranch, worktreeRoot, and dirtyState without creating or deleting a worktree.
List worktrees
/ak:worktree list --json
Use when:
You need every registered worktree path and branch in one listing.
Expected:
Lists registered worktrees with normalized paths and branch names and does not mutate checkouts.
Remove worktree
/ak:worktree remove billing-dashboard
Use when:
A named feature worktree should be removed after the branch is finished.
Expected:
Removes that named worktree checkout after confirmation and leaves other worktrees untouched.

Handled Scope

  • Read repo info
  • Detect exact names
  • Infer branch type
  • Build the slug
  • Resolve monorepo project
  • Execute create

Next