x-manage-worktrees

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Triggers

/x-manage-worktrees create --branch feat/task-0049-0001-001-domain [--base develop] [--id task-0049-0001-001]
/x-manage-worktrees list
/x-manage-worktrees remove --id task-0049-0001-001
/x-manage-worktrees cleanup [--dry-run]
/x-manage-worktrees detect-context

Parameters

Operation	Parameter	Type	Required	Default	Description
create	--branch	string	Yes	—	Branch name for the worktree
create	--base	string	No	develop	Base branch to create the new branch from
create	--id	string	No	derived from branch (strips feat/, fix/, hotfix/, refactor/ prefixes)	Worktree directory identifier
remove	--id	string	Yes	—	Worktree identifier to remove
cleanup	--dry-run	boolean	No	false	Preview candidates without removing
detect-context	(none)	—	—	—	Returns JSON: {inWorktree, worktreePath, mainRepoPath}

All worktrees are placed under .claude/worktrees/{identifier}/. Protected branches (main, develop) cannot host worktrees. Creator-owns-removal invariant enforced per Rule 14 §5 — only the skill that called create may call remove for the same worktree.

Output Contract

Operation	Output
create	Prints absolute worktree path on success; exits 1 on protected branch or conflict
list	Markdown table: ID, Branch, Status (ACTIVE/STALE/MERGED/ORPHAN), Last Commit, Age
remove	Confirmation message on success; exits 1 if --id not found
cleanup	Summary table of removed worktrees; --dry-run prints candidates only
detect-context	Single-line JSON: `{"inWorktree":bool,"worktreePath":string

detect-context is read-only and safe to call from any context — used by orchestrators to decide REUSE | CREATE | LEGACY branching (Rule 14 §3 Non-Nesting Invariant).

Error Envelope

Code	Condition	Message
PROTECTED_BRANCH	create on main or develop	Cannot create worktree on protected branch (<name>)
BRANCH_CONFLICT	Branch already checked out in another worktree	Branch '<name>' is already an active worktree
WORKTREE_EXISTS	Target directory already exists	Worktree directory already exists: .claude/worktrees/<id>
NOT_FOUND	remove --id not found	Worktree '<id>' not found
GIT_ADD_FAILED	git worktree add non-zero	Git error detail; suggest manual cleanup
GIT_REMOVE_FAILED	git worktree remove non-zero (retried with --force)	Git error detail
NOT_A_REPO	detect-context run outside a git repo	{"error":"NOT_A_REPO"} to stderr; exit 1
NO_OBSOLETE	cleanup finds nothing	No obsolete worktrees found (informational, exit 0)

Full Protocol

Complete per-operation Bash implementations (create 7-step workflow, list status classification, cleanup criteria — MERGED/STALE/ORPHAN, detect-context canonical snippet with CWE-116/CWE-209 hardening and JSON-escape), Git Flow integration table (task/story/hotfix base-branch rules), post-merge lifecycle, naming convention derivation, and Integration Notes (x-implement-epic/x-implement-story/x-implement-task callers) in references/full-protocol.md.