Skip to main content
skill CX Codex

worktree-retry-cleanup — Claude Code skill

worktree-retry-cleanup is a Claude Code skill that cleans up a swarm worktree lane before a task is dispatched again.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-code
Open on GitHub

What worktree-retry-cleanup does

The skill fires before a task that already has a lane goes out a second time. Whatever the earlier run ended with, its worktree and branch are still on disk.

Most retries need nothing manual: the normal dispatch path pre-cleans a stale lane when ownership is clear and the lane is clean. A refusal from provisioning is the answer, not an obstacle. Dirty lanes, lanes checked out in another worktree, and lanes held by an active session get reported to you rather than deleted.

Manual removal comes last and starts with ownership. Read .swarm/session/state.json, confirm no other session's delegationChains point at <session>/<task>, and stop if one does. Only .swarm-worktrees/<session>/<task> is removed, never the session parent, using git worktree remove followed by git worktree prune. For the branch, git branch -d swarm/lane/<session>/<task> is allowed once you know nothing has it checked out and no commit is lost; forcing -D waits for a human to say yes. Finish by confirming git branch --list returns nothing for that lane.

What it helps with

  • clear a stale worktree before re-dispatching a task
  • avoid deleting a lane another active session owns
  • tell a dirty lane apart from one that is safe to remove
  • drop swarm/lane/<session>/<task> without losing commits
  • confirm the lane branch is gone before the retry

Example prompts for the agent

  • Re-dispatch the auth-fix task, but run the worktree cleanup protocol for its lane first
  • Check .swarm/session/state.json for another active session that owns <session>/<task>
  • Remove .swarm-worktrees/<session>/<task>, run git worktree prune, then confirm the lane branch is gone with git branch --list

How to install worktree-retry-cleanup

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-code

2Manually: put the files in place

~/.claude/skills/worktree-retry-cleanup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/worktree-retry-cleanup/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about worktree-retry-cleanup

How do I install worktree-retry-cleanup in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill worktree-retry-cleanup -a claude-code. The skill file lands at ~/.claude/skills/worktree-retry-cleanup/SKILL.md.

What does worktree-retry-cleanup do?

It sets the order of operations for re-dispatching a task that already has a lane: built-in cleanup during dispatch first, then an ownership check and targeted removal of the worktree and branch.

What happens when another session owns the lane?

Deletion is off the table. That lane, like a dirty one or one checked out elsewhere, is surfaced to the user and left alone.

Source text

SKILL.md · MIT
---
name: worktree-retry-cleanup
description: Protocol for cleaning parallel-coder worktree lanes before retry. Triggered before re-dispatching any task that already has a lane (completed, denied, cancelled, or failed).
metadata:
  audience: swarm-plugin
---

# Worktree Retry Cleanup

## Trigger
Before re-dispatching a coder for a task that already has a lane (any prior dispatch status).

## Protocol
1. **Prefer built-in provisioning cleanup.** Re-dispatch normally through the standard coder/worktree path. Provisioning pre-cleans stale same-lane worktrees/branches when ownership is safe and the existing lane is clean.
2. **If provisioning blocks:** Treat the error as signal. Dirty lanes, lanes active in another worktree, and lanes owned by another active session must be surfaced to the user instead of deleted.
3. **If manual cleanup is explicitly required:** Do the ownership check FIRST. Confirm the lane is not owned by another ACTIVE session: read `.swarm/session/state.json` and verify no other session's `delegationChains` reference `<session>/<task>`. If another active session owns it, STOP.
4. **Remove only the specific lane.** Target `.swarm-worktrees/<session>/<task>`, never the session parent. Prefer `git worktree remove .swarm-worktrees/<session>/<task>` and then `git worktree prune`.
5. **Delete only confirmed stale branches.** `git branch -d swarm/lane/<session>/<task>` is allowed after confirming the branch is not checked out and contains no needed commits. Use force deletion only with explicit human approval.
6. **Verify:** `git branch --list "swarm/lane/<session>/<task>"` returns empty before retrying.

## Root cause
Stale same-lane worktrees and branches used to require manual cleanup before retry. Provisioning now handles the safe clean/stale cases automatically and fails closed for dirty, active, or cross-session-owned lanes.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set121

The whole set →
writing-tests writing-tests sets test-authoring rules for the opencode-swarm repository. Use it before changing tests that involve mocks, temporary paths, or regression checks. CX Codex +1 ★ 539repo stars run-affected-test-file-in-isolation-and-in-co-run-with-its-test- run-affected-test-file-in-isolation-and-in-co-run-with-its-test- is a Claude Code skill that makes the agent run tests in isolation and with sibling files after mock cleanup changes. CX Codex +1 ★ 539repo stars update-or-delete-tests-that-assert-intentionally-removed-behavio update-or-delete-tests-that-assert-intentionally-removed-behavio is a Claude Code skill for revising or removing tests of deliberately removed behavior. It applies to code changes that retire a code path. CX Codex +1 ★ 539repo stars use-internals-di-seam-pattern-for-test-injectable-functions use-internals-di-seam-pattern-for-test-injectable-functions is a Claude Code skill that uses _internals as a DI seam and checks mock isolation in combined Bun test runs. CX Codex +1 ★ 539repo stars swarm Enables a rigorous swarm-style posture with parallel searches, visible plan updates, and dual review gates for code changes. CX Codex +1 ★ 539repo stars research-first The research-first skill checks current documentation and discussions before tracing code when an issue depends on an external framework, tool, or platform. For repo-local questions, it searches the repository instead. CX Codex +1 ★ 539repo stars swarm-pr-subscribe swarm-pr-subscribe monitors open pull requests, triages incoming review comments or CI failures, and applies safe fixes until merge. CX Codex +1 ★ 539repo stars swarm-ci-monitor The swarm-ci-monitor skill monitors CI for an approved, reviewed PR, investigates failures, and works through fixes until checks pass. It can then merge the PR after a final review of its state. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open