agentleFS
Sign inStart free
ulises-jeremiasulises-jeremias/agent-toolkit/skills/forge/worktree/SKILL.md

worktree

Skill19 starsChanged 2 months agoMITView on GitHub

Manage Git worktrees per writer for Agent Toolkit swarms — isolated branches, handoff promotion,

  • Commits and pushes

We split this skill into the rules it gives an agent

8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 45 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create and maintain worktree-per-writer isolation for agent-toolkit swarm so each role works on its own branch without stepping on others.

    line 19
  2. Very specific:

    Before swarm promote — ensure the handoff's worktree is clean and pushable.

    line 25
  3. Very specific:

    Do not create worktrees by hand for swarm roles — let handoff create do it so state.json stays authoritative.

    line 54
  4. Distinctive:

    If a worktree is orphaned or locked:

    line 66
  5. Distinctive:

    After reviewer/integrator approves the handoff's artifact:

    line 77
  6. Very specific:

    Never edit .agent-toolkit/swarm/runs/<run-id>/state.json worktree entries by hand — use swarm CLI.

    line 101
  7. Distinctive:

    Never use git checkout in the main worktree to switch swarm branches.

    line 102
  8. Very specific:

    Never delete a worktree that has an active handoff — complete or handoff first.

    line 103

“Common” is measured: kept by at least 6 in 10 of the 45 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Worktree

Create and maintain worktree-per-writer isolation for agent-toolkit swarm so each role works on its own branch without stepping on others. Integrates with swarm-handoff promotion and github-cli-workflow for PRs.

When to use

  • Swarm needs isolated writes: implementer, reviewer, integrator each own a worktree/branch.
  • worktree_failed trace or find_repo_root error on .git file worktrees.
  • Before swarm promote — ensure the handoff's worktree is clean and pushable.
  • Cleanup after a run is promoted or abandoned.

Prerequisites

  • Repo is Git with git worktree available (git worktree --help).
  • Swarm run exists: .agent-toolkit/swarm/runs/<run-id>/state.json; worktrees live under .agent-toolkit/swarm/runs/<run-id>/worktrees/<role>-<short>/.
  • find_repo_root uses git rev-parse --git-common-dir to handle worktree .git files (not directories).

Workflow

1. Inspect current worktrees

git worktree list
agent-toolkit swarm status --run-id <run-id> --json | jq '.worktrees'
# Expected: {implementer: {path, branch, commit}, reviewer: {path, branch}, ...}
cat .agent-toolkit/swarm/runs/<run-id>/state.json | jq '.trace | map(select(.event | contains("worktree")))'

2. How swarm creates them (automatic)

On handoff create --from X --to Y for a writer role Y, swarm:

  1. Resolves repo root via find_repo_root (git rev-parse --git-common-dir fallback).
  2. Creates branch swarm/<run-id>/<role> if missing.
  3. Runs git worktree add <run-dir>/worktrees/<role>-<short> <branch>.
  4. Exports AGENT_TOOLKIT_SWARM_RUN_ID/RUN_DIR/REPO SWARMFORGE_ROLE and cd <worktree> && exec <runner> "$(cat prompt)" via _user_shell() (/usr/bin/zsh -lc on this host).

Do not create worktrees by hand for swarm roles — let handoff create do it so state.json stays authoritative.

3. Manual recovery

If worktree_failed:

git rev-parse --git-common-dir  # from worktree dir — should succeed
AGENT_TOOLKIT_SWARM_RUN_ID=<run-id> agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/retry.md --run-id <run-id>
# Re-triggers provisioning with fixed repo-root logic

If a worktree is orphaned or locked:

git worktree list | grep <run-id>
git worktree remove <path> --force
git worktree prune
git branch -D swarm/<run-id>/<role>  # only if run is abandoned and branch is merged/abandoned

4. Promotion and PR

After reviewer/integrator approves the handoff's artifact:

agent-toolkit swarm promote --run-id <run-id> --handoff-id <handoff-id>
git -C <worktree-path> log --oneline -n 5
git -C <worktree-path> push -u origin <branch>
# Delegate to github-cli-workflow for draft PR
gh pr create --title "swarm/<run-id>: <summary>" --body-file artifacts/<handoff-artifact> --base main

For reuse: same run-id reuses worktrees; no prune between sequential handoffs. New run only for isolated feature branches.

5. Cleanup after merge

gh pr merge <number> --squash --delete-branch
git worktree remove <path> --force
git worktree prune
agent-toolkit swarm list --json | jq '.[] | select(.run_id=="<run-id>") | .status'
# Optionally archive state: tar -czf /tmp/swarm-<run-id>.tgz .agent-toolkit/swarm/runs/<run-id>

Boundaries

  • Never edit .agent-toolkit/swarm/runs/<run-id>/state.json worktree entries by hand — use swarm CLI.
  • Never use git checkout in the main worktree to switch swarm branches; always git worktree.
  • Never delete a worktree that has an active handoff — complete or handoff first.

Delegates to

NeedSkill
Create the handoff that provisions the worktreeswarm-handoff
Launch or observe the swarmswarm, swarm-observer
Herdr/tmux pane for the worktreeherdr
Push and create PR after promotiongithub-cli-workflow
Review before promotioncode-reviewer, security-reviewer

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free