Agent Config Adapter

---
name: Agent Scaling
description: Spawn and manage parallel Claude Code sessions using full git checkouts (Boris Cherny method) with optional cloud handoff support. Use when user says "scale agents", "spawn sessions", "parallel sessions", or needs to manage multiple Claude instances.
allowed-tools: Bash, Read, Write, Grep, Glob, Bash(git:*), Bash(tmux:*)
---

# Agent-Scaling Skill

Spawn and manage parallel Claude Code sessions using full git checkouts (Boris
Cherny method) with optional cloud handoff support.

## Trigger Phrases

- "Scale agents for [features]"
- "Spawn parallel sessions"
- "agent-scaling [task list]"
- "Run [N] agents in parallel"

---

## Quick Start

### Single Agent Session

```bash
# 1. Create full checkout
git clone . agent-feature1/

# 2. Spawn tmux session
tmux new-session -d -s agent-1 -c agent-feature1/

# 3. Start Claude Code
tmux send-keys -t agent-1 'claude' C-m

# 4. Attach and work
tmux attach -t agent-1
```

### Multiple Parallel Sessions

```bash
# Create checkouts
git clone . agent-1/
git clone . agent-2/
git clone . agent-3/

# Spawn tmux sessions
tmux new-session -d -s agent-1 -c agent-1/
tmux new-session -d -s agent-2 -c agent-2/
tmux new-session -d -s agent-3 -c agent-3/

# Start Claude in each
tmux send-keys -t agent-1 'claude' C-m
tmux send-keys -t agent-2 'claude' C-m
tmux send-keys -t agent-3 'claude' C-m
```

---

## Why Full Checkouts Over Worktrees

| Aspect                 | Full Checkouts                | Git Worktrees                                  |
| ---------------------- | ----------------------------- | ---------------------------------------------- |
| **Shared state**       | None - completely independent | Shared `.git` directory                        |
| **Concurrent git ops** | Safe - no interference        | Can conflict                                   |
| **Merge complexity**   | Standard branch merge         | Same, but worktree management adds complexity  |
| **Disk space**         | More (duplicated `.git`)      | Less                                           |
| **Risk**               | Zero state bugs               | "worktree already checked out" errors possible |

**Key insight (Boris Cherny)**: Full checkouts have a "simpler merge story"
because there's no shared state to worry about during parallel development.

---

## Session Management

### Naming Convention

- `agent-1`, `agent-2`, `agent-3` for numbered sessions
- `agent-{feature}` for feature-specific sessions (e.g., `agent-auth`,
  `agent-api`)
- `agent-{ticket}` for ticket-based sessions (e.g., `agent-42`, `agent-GH-123`)

### Monitoring Sessions

```bash
# List all agent sessions
tmux list-sessions | grep agent

# Check session status
tmux has-session -t agent-1 && echo "Running" || echo "Stopped"

# View recent output (last 100 lines)
tmux capture-pane -t agent-1 -p -S -100

# View with line numbers
tmux capture-pane -t agent-1 -p -S -100 | nl
```

### Switching Between Sessions

```bash
# Attach to specific session
tmux attach -t agent-1

# Detach from current session
# Press: Ctrl+b d

# Switch directly between sessions (when attached)
# Press: Ctrl+b s (session list)
# Press: Ctrl+b ( (previous session)
# Press: Ctrl+b ) (next session)
```

### Cleanup

```bash
# Kill specific session
tmux kill-session -t agent-1

# Kill all agent sessions
tmux list-sessions | grep agent | cut -d: -f1 | xargs -I {} tmux kill-session -t {}

# Remove checkout after merge
rm -rf agent-1/
```

---

## Cloud Handoff (`&` and `--teleport`)

### Prerequisites

**CRITICAL REQUIREMENTS** for handoff to work:

1. Repository must be in **CLEAN state** - all changes committed
2. Changes must be **PUSHED to GitHub** - cloud session pulls from remote
3. Verify before handoff:
   ```bash
   git status  # Should show "nothing to commit, working tree clean"
   git push    # Ensure remote is up to date
   ```

### Limitations

**IMPORTANT**: Custom slash commands (like `/startWork`, `/completeWork`,
`/codePlanner`) are **NOT available** on claude.ai/code sessions.

| Use Cloud For                   | Stay Local For                         |
| ------------------------------- | -------------------------------------- |
| Long-running implementation     | Workflows requiring slash commands     |
| Exploration and research        | Quick iterations with `/startWork`     |
| Overnight autonomous work       | MCP server integrations (memory, etc.) |
| When laptop capacity is limited | Structured dev-work workflows          |

### Hand Off to Cloud

1. **Commit all changes**:
   ```bash
   git add . && git commit -m "WIP: handoff to cloud"
   ```

2. **Push to remote**:
   ```bash
   git push
   ```

3. **In running Claude session**, type:
   ```
   &
   ```

4. Session transfers to claude.ai/code - continue from browser

### Bring Back to Local

1. Start Claude with teleport flag:
   ```bash
   claude --teleport
   ```

2. Session context pulls back from cloud

---

## Parallel Development Workflow

### Phase 1: Setup Checkouts

```bash
# For each feature/task
git clone . agent-{feature}/
cd agent-{feature}
git checkout -b feat/{feature}
cd ..
```

### Phase 2: Spawn Sessions

```bash
# Create tmux session for each
tmux new-session -d -s agent-{feature} -c agent-{feature}/
tmux send-keys -t agent-{feature} 'claude' C-m
```

### Phase 3: Work in Each Session

```bash
# Attach and provide task
tmux attach -t agent-{feature}
# In session: /startWork taskNotes/{feature}/taskFindings.md
```

### Phase 4: Monitor Progress

```bash
# Quick status check
for s in agent-1 agent-2 agent-3; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p -S -20 2>/dev/null || echo "Session not found"
done
```

### Phase 5: Merge Results

```bash
# For each completed feature
cd agent-{feature}
git push origin feat/{feature}
cd ..

# Create PR or merge locally
git fetch origin feat/{feature}
git merge origin/feat/{feature}
```

### Phase 6: Cleanup

```bash
# Remove checkouts
rm -rf agent-{feature}/

# Kill sessions
tmux kill-session -t agent-{feature}
```

---

## Session Abandonment

**Expect 10-20% of sessions to fail** (Boris Cherny observation). Signs of
abandonment:

- Session stuck in error loop
- Unexpected scenario Claude can't handle
- Scope creep beyond original task

### When to Abandon

- No meaningful progress after multiple attempts
- Session diverged significantly from plan
- Easier to restart than continue

### How to Abandon

```bash
# Kill the session
tmux kill-session -t agent-{feature}

# Keep or remove checkout depending on salvageable work
# If salvageable: cherry-pick commits
git log --oneline agent-{feature}/

# If not: remove entirely
rm -rf agent-{feature}/
```

---

## Best Practices

### DO

- Use full checkouts for parallel work (not worktrees)
- Number sessions sequentially: agent-1, agent-2, agent-3
- Commit and push before cloud handoff
- Monitor sessions periodically
- Accept ~10-20% abandonment rate as normal
- Use local sessions for slash command workflows

### DON'T

- Mix worktrees and full checkouts in same workflow
- Hand off to cloud without pushing first
- Expect slash commands to work on cloud sessions
- Keep failed sessions running indefinitely
- Forget to cleanup checkouts after merge

---

## Integration with parallel-dev-work

This skill is typically called by the `parallel-dev-work` skill which:

1. Plans all features with `/codePlanner`
2. Calls `agent-scaling` to spawn parallel sessions
3. Monitors and collects results
4. Merges completed work

For full orchestrated workflow, use `/parallel-dev-work` instead of calling this
skill directly.

No companion files

Add companion files to enhance this skill