skills: add agent_worktree.py for isolated PR/branch checkouts

[doomedraven]

What

Adds agent_worktree.py to the capemon-developer skill and documents it in SKILL.md: a wrapper around git worktree for reviewing PRs and testing branches without touching your working clone.

Why

Checking out someone else's branch means either polluting your clone — unsafe when it carries uncommitted work, which most do — or doing the git worktree plumbing by hand.

This repository makes the manual version more error-prone than usual: it uses the fork convention, so origin is your own fork and upstream is kevoreilly/capemon, and the default branch is capemon rather than master. Getting a PR branch checked out means working out which of the two remotes (or which third-party fork) actually holds the head ref.

Usage

S=.gemini/skills/capemon-developer/scripts/agent_worktree.py

python $S new --pr 123                      # resolve head fork via gh, fetch, branch, check out
python $S new --branch some-topic-branch
python $S new --from upstream/capemon --name scratch

python $S list                              # flags: main / managed / dirty / pr#N
python $S path pr123                        # for use in $(...)
python $S update pr123                      # re-fetch after the author pushes
python $S remove pr123                      # also drops the branch it created
python $S cleanup
python $S info                              # repo, remotes, dirty state

--json on any command for scripted use. gh is needed only for --pr.

Fork-layout handling

• The canonical repository is read from upstream when configured, so new --pr <id> queries kevoreilly/capemon instead of your fork.
• new --pr asks gh which fork the head branch lives in and fetches from the matching remote; if no remote matches it fetches straight from the fork URL into a private ref namespace and warns that no upstream was set.
• new --branch tries origin, then upstream, then any other remote, and reports which one supplied the branch. --remote forces one.

Safety

• Nothing is written to the main working tree. No checkout, reset, stash or clean; remove refuses the main worktree outright.
• Only its own worktrees are removed. Each is tagged with an agent-meta.json inside .git/worktrees/<id>/, i.e. the git admin directory, so git status in the worktree stays empty and a hand-made git worktree add is never touched by cleanup.
• Refuses to destroy work. remove and cleanup bail on uncommitted changes or unpushed commits; cleanup skips them and prints the reason. --force overrides.
• Worktrees default to ~/.cache/agent-worktrees/capemon/<name>, overridable with --base-dir, --path or $AGENT_WORKTREE_DIR.

Notes

Python standard library only — no dependencies, nothing to build, and no interaction with the MSBuild toolchain. A worktree is a full checkout, so the existing build commands work inside one unchanged.

The same script is maintained in CAPEv2 as utils/agent_worktree.py (kevoreilly/CAPEv2#3228), where it ships with a test suite covering the CLI against throwaway local repositories. SKILL.md notes that the two copies should be kept in sync.