teams-collaboration

What this skill does

# Claude Code Teams & Collaboration

Complete guide to team features, multi-user workflows, and organizational settings.

## Team Plans

### Overview
Claude Code supports team/organizational plans that provide:
- Shared billing and usage tracking
- Managed settings and policies
- Centralized API key management
- Team member management
- Usage analytics and reporting

### Organization Setup
```bash
# Login with organization credentials
claude auth login

# Check organization status
claude config
```

## Enterprise Managed Settings

### Managed Policies
Enterprise admins can enforce settings that individual users cannot override:

```json
{
  "managedSettings": {
    "permissions": {
      "deny": [
        "Bash(curl *)",
        "Bash(wget *)",
        "WebFetch",
        "WebSearch"
      ]
    },
    "model": "claude-sonnet-4-6",
    "allowedModels": ["claude-sonnet-4-6", "claude-haiku-4-5-20251001"],
    "hooks": {
      "PostToolUse": [
        {
          "matcher": "*",
          "hooks": [{
            "type": "command",
            "command": "bash /opt/company/audit-log.sh"
          }]
        }
      ]
    },
    "autoMemory": false,
    "maxTokensPerSession": 500000
  }
}
```

### Settings Hierarchy with Teams
```
Enterprise managed (cannot override)
  └── Organization defaults
      └── Team settings
          └── User settings (~/.claude/settings.json)
              └── Project settings (.claude/settings.json)
                  └── Local overrides (.claude/settings.local.json)
```

## Multi-User Project Conventions

### Shared Configuration (Git-Tracked)
These files should be in version control:
```
.claude/
├── CLAUDE.md              # Project instructions (everyone sees)
├── settings.json          # Shared permission rules
├── rules/                 # Shared rules
│   ├── code-style.md
│   ├── git-workflow.md
│   └── architecture.md
├── skills/                # Shared skills
│   └── deploy/SKILL.md
└── hooks/                 # Shared hooks
    └── pre-commit.sh
```

### Personal Configuration (Git-Ignored)
These stay local per user:
```
.claude/settings.local.json   # Personal overrides
~/.claude/CLAUDE.md            # Personal global instructions
~/.claude/settings.json        # Personal global settings
```

### .gitignore Entries
```gitignore
# Claude Code local files
.claude/settings.local.json
.claude/cache/
.claude/memory/

# Never commit
.env
.env.local
*.pem
*.key
```

## Collaborative Workflows

### Shared CLAUDE.md Best Practices
```markdown
# Project Instructions

## For All Team Members
- Use pnpm (not npm or yarn)
- Follow conventional commits
- Run `pnpm test` before committing
- All PRs require review

## Architecture Decisions
- ADR records in docs/adr/
- Major changes require RFC

## Contacts
- Frontend: @alice
- Backend: @bob
- Infrastructure: @carol
```

### Team Skills
Share skills across the team via git:
```markdown
# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy to staging/production
---

# Deployment Skill

## Steps
1. Run tests: `pnpm test`
2. Build: `pnpm build`
3. Deploy to staging: `kubectl apply -f k8s/staging/`
4. Run smoke tests: `pnpm test:e2e:staging`
5. If passing, deploy to production: `kubectl apply -f k8s/production/`
```

### Team Hooks
Enforce team standards via shared hooks:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/team-bash-guard.sh"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/ensure-tests-pass.sh"
        }]
      }
    ]
  }
}
```

## API Key Management

### Per-User Keys
Each team member uses their own API key:
```bash
export ANTHROPIC_API_KEY="sk-ant-user-specific-key"
```

### Shared Organization Key
Use organization-level auth:
```bash
export ANTHROPIC_AUTH_TOKEN="org-oauth-token"
```

### Key Rotation
```bash
# Generate new key via Anthropic Console
# Update environment variable
# Old key automatically expires based on org policy
```

## Usage Tracking & Analytics

### Per-Session Costs
```
/cost
```

### Organization Dashboard
- View at console.anthropic.com
- Per-user usage breakdown
- Model usage distribution
- Cost trends over time

### Audit Logging Hook
```bash
#!/bin/bash
# .claude/hooks/audit-log.sh
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
USER=$(whoami)
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

echo "$TIMESTAMP|$USER|$TOOL" >> .claude/audit.log
```

## Claude Code Agent Teams (Experimental)

Agent Teams coordinate multiple Claude Code instances working in parallel with direct
teammate-to-teammate communication. Unlike subagents (hub-and-spoke), teams are a
mesh network where any teammate can message any other.

### Enable Agent Teams

```bash
# Environment variable (required, v2.1.32+)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Or in settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

### Team Architecture

```
┌─────────────────────────────────────┐
│           Lead Session              │
│  - Creates team & task list         │
│  - Spawns teammates                 │
│  - Monitors progress               │
│  - Synthesizes results              │
├─────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐        │
│  │Teammate A│←→│Teammate B│        │
│  │(frontend)│  │(backend) │        │
│  └──────────┘  └──────────┘        │
│       ↕              ↕              │
│  ┌──────────┐  ┌──────────┐        │
│  │Teammate C│←→│Teammate D│        │
│  │ (infra)  │  │ (tests)  │        │
│  └──────────┘  └──────────┘        │
└─────────────────────────────────────┘
```

### Team Primitives

| Primitive | Purpose |
|-----------|---------|
| `TeamCreate` | Create a new team with name and roles |
| `TaskCreate` | Add work items with assignee and dependencies |
| `TaskUpdate` | Mark tasks complete, blocked, or add notes |
| `TaskList` | List all tasks (teammates self-claim) |
| `SendMessage` | Direct teammate-to-teammate messaging |
| `TeamDelete` | Dissolve team and clean up |

### Display Modes

- **In-process** (default): `Shift+Down` to cycle between teammate views
- **Split-panes**: Use tmux/iTerm2 for side-by-side teammate views

### Team Best Practices

```yaml
team_guidelines:
  size: 3-5 teammates (optimal)
  tasks_per_teammate: 5-6 (avoid overload)
  token_cost: 4-7x single session
  lead_is_fixed: true  # cannot change mid-session
  nesting: false        # no teams within teams
  session_resume: false # in-process only
```

### Team Lifecycle Management

The lead session is responsible for monitoring teammate health:

```
Every 2 minutes:
  1. Check TaskList for stale assignments (>5 min, no progress)
  2. SendMessage to idle teammates: "Status check?"
  3. For stalled teammates:
     - Try redirecting with clearer instructions
     - If unresponsive >3 min: reassign task to another teammate
  4. For completed teammates with no remaining tasks:
     - Collect final outputs
     - Release teammate
  5. Before finishing:
     - TeamDelete to dissolve
     - Verify all tasks completed or explicitly abandoned
```

### TeammateIdle Hook

Configure automatic idle detection:

```json
{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/teammate-idle-handler.sh"
        }]
      }
    ]
  }
}
```

```bash
#!/bin/bash
# teammate-idle-handler.sh
INPUT=$(cat)
TEAMMATE=$(echo "$INPUT" | jq -r '.teammate_name // "unknown"')
IDLE_SECONDS=$(echo "$INPUT" | jq -r '.idle_seconds // 0')

if [ "$IDLE_SECONDS" -gt 180 ]; then
  echo "WARNING: Teammate $TEAMMATE idle for ${IDLE_SECONDS}s" >&2
fi
```

## Multi-Agent Orchestration Patterns

### Orchestration-First Principle

Claude should **prefer to orchestrate** rather than do work directly:
- Break complex tasks into w