team-coordination

What this skill does

# Team Coordination Skill


**Purpose:** Enable multiple Claude Code sessions across a team to coordinate and work together without conflicts. Manages shared state, todo claiming, decision syncing, and session awareness.

---

## Core Philosophy

```
┌─────────────────────────────────────────────────────────────────┐
│  TEAM CLAUDE CODE                                               │
│  ─────────────────────────────────────────────────────────────  │
│  Multiple devs, multiple Claude sessions, one codebase.         │
│  Coordination > Speed. Communication > Assumptions.             │
│                                                                 │
│  Before you start: Check who's working on what.                 │
│  Before you claim: Make sure nobody else has it.                │
│  Before you decide: Check if it's already decided.              │
│  Before you push: Pull and sync state.                          │
└─────────────────────────────────────────────────────────────────┘
```

---

## Team State Structure

When a project becomes multi-person, create this structure:

```
_project_specs/
├── team/
│   ├── state.md              # Who's working on what right now
│   ├── contributors.md       # Team members and their focus areas
│   └── handoffs/             # Notes when passing work to others
│       └── [feature]-handoff.md
├── session/
│   ├── current-state.md      # YOUR session state (personal)
│   ├── decisions.md          # SHARED - architectural decisions
│   └── code-landmarks.md     # SHARED - important code locations
└── todos/
    ├── active.md             # SHARED - with claim annotations
    ├── backlog.md            # SHARED
    └── completed.md          # SHARED
```

---

## Team State File

**`_project_specs/team/state.md`:**

```markdown
# Team State

*Last synced: [timestamp]*

## Active Sessions

| Contributor | Working On | Started | Files Touched | Status |
|-------------|------------|---------|---------------|--------|
| @alice | TODO-042: Add auth | 2024-01-15 10:30 | src/auth/* | 🟢 Active |
| @bob | TODO-038: Fix checkout | 2024-01-15 09:00 | src/cart/* | 🟡 Paused |
| - | - | - | - | - |

## Claimed Todos

| Todo | Claimed By | Since | ETA |
|------|------------|-------|-----|
| TODO-042 | @alice | 2024-01-15 | Today |
| TODO-038 | @bob | 2024-01-14 | Tomorrow |

## Recently Completed (Last 48h)

| Todo | Completed By | When | PR |
|------|--------------|------|-----|
| TODO-037 | @alice | 2024-01-14 | #123 |

## Conflicts to Watch

| Area | Contributors | Notes |
|------|--------------|-------|
| src/auth/* | @alice, @carol | Carol needs auth for TODO-045, coordinate |

## Announcements

- [2024-01-15] @alice: Refactoring auth module, avoid touching until EOD
- [2024-01-14] @bob: New env var required: STRIPE_WEBHOOK_SECRET
```

---

## Contributors File

**`_project_specs/team/contributors.md`:**

```markdown
# Contributors

## Team Members

| Handle | Name | Focus Areas | Timezone | Status |
|--------|------|-------------|----------|--------|
| @alice | Alice Smith | Backend, Auth | EST | Active |
| @bob | Bob Jones | Frontend, Payments | PST | Active |
| @carol | Carol White | DevOps, Infra | GMT | Part-time |

## Ownership

| Area | Primary | Backup | Notes |
|------|---------|--------|-------|
| Authentication | @alice | @bob | All auth changes need @alice review |
| Payments | @bob | @alice | Stripe integration |
| Infrastructure | @carol | @alice | Deploy scripts, CI/CD |
| Database | @alice | @carol | Migrations need sign-off |

## Communication

- Slack: #project-name
- PRs: Always tag area owner for review
- Urgent: DM on Slack

## Working Hours Overlap

```
EST:  |████████████████████|
PST:  |   ████████████████████|
GMT:  |████████████|
      6am        12pm       6pm       12am EST

Best overlap: 9am-12pm EST (all three)
```
```

---

## Workflow

### Starting a Session

```
┌─────────────────────────────────────────────────────────────────┐
│  START SESSION CHECKLIST                                        │
│  ─────────────────────────────────────────────────────────────  │
│  1. git pull origin main                                        │
│  2. Read _project_specs/team/state.md                           │
│  3. Check claimed todos - don't take what's claimed             │
│  4. Claim your todo in active.md                                │
│  5. Update state.md with your session                           │
│  6. Push state changes before starting work                     │
│  7. Start working                                               │
└─────────────────────────────────────────────────────────────────┘
```

### Claiming a Todo

In `active.md`, add claim annotation:

```markdown
## [TODO-042] Add email validation

**Status:** in-progress
**Claimed:** @alice (2024-01-15 10:30 EST)
**ETA:** Today

...
```

### During Work

- Update `state.md` if you touch new files
- Check `decisions.md` before making architectural choices
- If you make a decision, add it to `decisions.md` immediately
- Push state updates every 1-2 hours (keeps team in sync)

### Ending a Session

```
┌─────────────────────────────────────────────────────────────────┐
│  END SESSION CHECKLIST                                          │
│  ─────────────────────────────────────────────────────────────  │
│  1. Commit your work (even if WIP)                              │
│  2. Update your current-state.md                                │
│  3. Update team state.md (status → Paused or Done)              │
│  4. If passing to someone: create handoff note                  │
│  5. Unclaim todo if abandoning                                  │
│  6. Push everything                                             │
└─────────────────────────────────────────────────────────────────┘
```

### Creating a Handoff

When passing work to another team member, create:

**`_project_specs/team/handoffs/auth-feature-handoff.md`:**

```markdown
# Handoff: Auth Feature (TODO-042)

**From:** @alice
**To:** @bob
**Date:** 2024-01-15

## Status

70% complete. Core auth flow works, need to add:
- [ ] Password reset flow
- [ ] Email verification

## What's Done

- Login/logout working
- JWT tokens implemented
- Session management done

## What's Left

1. Password reset - see src/auth/reset.ts (skeleton exists)
2. Email verification - need to integrate SendGrid

## Key Decisions Made

- Using JWT not sessions (see decisions.md)
- Tokens expire in 7 days
- Refresh tokens stored in httpOnly cookies

## Watch Out For

- The `validateToken` function has a weird edge case with expired tokens
- Don't touch `authMiddleware.ts` - it's fragile rn

## Files to Start With

1. src/auth/reset.ts - password reset
2. src/email/verification.ts - email flow
3. tests/auth.test.ts - add tests here

## Questions?

Slack me @alice if stuck
```

---

## Conflict Prevention

### File-Level Awareness

Before modifying a file, check state.md for who's touching what:

```markdown
## Active Sessions

| Contributor | Working On | Started | Files Touched | Status |
|-------------|------------|---------|---------------|--------|
| @alice | TODO-042 | ... | src/auth/*, src/middleware/* | 🟢 Active |
```

If you need to touch `src/auth/*` and Alice is working there:
1. Check if it's truly conflicting (same file? same functions?)
2. Coordinate via Slack before proceeding
3. Add a note to "Conflicts to Watch" section

### Pre-Push Check

Before pushing, always:

```bash
git pull origin main
# Resolve any conflicts
git push
```

### PR Tagging

Always tag area owners in PRs:

```markdown
## PR: Add password reset flow

Implements TODO-042

cc: @alice (auth owner), @bob (reviewer)

### Changes
- Added password reset endpoint
- Added email templates

### Testing
- [ ] Unit tests pass
- [ ] Manual testing done
```

---

## Decision Syncing

### Before Making a Decision

1. Pull latest `decisions.md`
2. Check if decision already exists
3. If similar decision exists, follow it (consistency > preference)