Repository Coordination Skill

Smart multi-agent repository coordination. Ensures each Claude session works in an isolated worktree to prevent conflicts.

The Gentleman's Agreement

When multiple Claude sessions work in the same workspace, follow these rules:

1. Always use repos/ directory - All cloned repos live in repos/<repo-name>/
2. Always use worktrees for changes - Never modify the main clone directly
3. Never share worktrees - Each session gets its own worktree at repos/<repo-name>-<branch>/
4. User specifies branch names - Don't auto-generate branch names

Directory Convention

workspace/
├── repos/
│   ├── <repo-name>/              # Main clone (shared, don't modify)
│   ├── <repo-name>-<branch>/     # Worktree for session A
│   └── <repo-name>-<branch2>/    # Worktree for session B

Branch names are normalized for filesystem: feature/auth becomes feature-auth

Actions

Parse $ARGUMENTS to determine which action to run:

/clue-repo work <url-or-name> <branch>

Setup an isolated worktree for this session. Smart behavior:

1. Extract repo name from URL (e.g., https://github.com/org/myapp.git → myapp)
2. Check if main clone exists at repos/<repo-name>/
   • If NO: Clone the repo there first
   • If YES: Fetch latest (git -C repos/<repo-name> fetch --all)
3. Normalize branch name for directory: replace / with -
4. Check if worktree path exists at repos/<repo-name>-<branch>/
   • If YES and is a valid worktree: Inform user it exists, ask if they want a new one with suffix
   • If YES but not a worktree: Error - path conflict
   • If NO: Create the worktree
5. Create worktree:

   cd repos/<repo-name>
   git worktree add -B <branch> ../<repo-name>-<normalized-branch>
   

6. Return the path for the session to use

Examples:

/clue-repo work https://github.com/org/api.git feature/auth
# Creates: repos/api/ (clone) + repos/api-feature-auth/ (worktree)

/clue-repo work api fix/bug-123
# Uses existing repos/api/, creates repos/api-fix-bug-123/

/clue-repo cleanup <repo-name> [branch]

Remove a worktree or the entire repo.

With branch specified:

1. Normalize branch name
2. Check for uncommitted changes in repos/<repo-name>-<branch>/
   • If changes exist: STOP and ask user - don't auto-delete work
3. Remove worktree:

   cd repos/<repo-name>
   git worktree remove ../<repo-name>-<normalized-branch>
   

Without branch (cleanup entire repo):

1. List all worktrees for this repo
2. If any worktrees have uncommitted changes: STOP and ask user
3. Remove all worktrees first
4. Remove main clone: rm -rf repos/<repo-name>

Examples:

/clue-repo cleanup api feature-auth
# Removes repos/api-feature-auth/ worktree

/clue-repo cleanup api
# Removes all api worktrees + repos/api/

/clue-repo status [repo-name]

Show repository and worktree status.

With repo name:

cd repos/<repo-name>
echo "=== Main clone ==="
git -C repos/<repo-name> branch -vv
echo ""
echo "=== Worktrees ==="
git -C repos/<repo-name> worktree list
echo ""
echo "=== Worktree Status ==="
# For each worktree, show: path, branch, uncommitted changes (yes/no)

Without repo name: Show status for all repos in repos/

/clue-repo list

List all repos and their worktrees in tree format:

echo "repos/"
for repo in repos/*/; do
  if [ -d "$repo/.git" ] || [ -f "$repo/.git" ]; then
    name=$(basename "$repo")
    echo "├── $name/"
    git -C "$repo" worktree list --porcelain | grep "^worktree" | while read -r line; do
      wt_path="${line#worktree }"
      wt_name=$(basename "$wt_path")
      if [ "$wt_name" != "$name" ]; then
        echo "│   └── $wt_name (worktree)"
      fi
    done
  fi
done

Edge Case Handling

Auto-Handle (Make Best Judgment)

• Repo doesn't exist: Clone it automatically
• Branch doesn't exist on remote: Create it locally with -B flag
• Network errors during clone: Retry once, then report error
• Stale worktree references: Run git worktree prune before operations

Ask User (Don't Auto-Decide)

• Uncommitted changes in worktree to be deleted: Show changes, ask for confirmation
• Worktree path already exists: Ask if user wants suffix (e.g., -2) or different name
• Merge conflicts: Stop and ask user for guidance
• Delete entire repo with active worktrees: List worktrees, confirm deletion

Error Messages

Provide clear, actionable error messages:

• "Repo 'xyz' not found. Did you mean to clone it? Try: /clue-repo work <url> <branch>"
• "Worktree at repos/api-feature-auth/ has uncommitted changes. Commit or stash before cleanup."
• "Path repos/api-main/ exists but is not a worktree. Remove manually if safe."

Implementation Notes

• Always use absolute paths when running git commands
• The repos/ directory should be created at workspace root if it doesn't exist
• Use git worktree add -B to create-or-reset the branch (handles existing local branches)
• After operations, suggest next steps (e.g., "cd repos/api-feature-auth to start working")