Multi-person projects - shared state, todo claiming, handoffs
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.
┌─────────────────────────────────────────────────────────────────┐
│ 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. │
└─────────────────────────────────────────────────────────────────┘
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
_project_specs/team/state.md:
# 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
_project_specs/team/contributors.md:
# 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)
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘
In active.md, add claim annotation:
## [TODO-042] Add email validation
**Status:** in-progress
**Claimed:** @alice (2024-01-15 10:30 EST)
**ETA:** Today
...
state.md if you touch new filesdecisions.md before making architectural choicesdecisions.md immediately┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘
When passing work to another team member, create:
_project_specs/team/handoffs/auth-feature-handoff.md:
# 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
Before modifying a file, check state.md for who's touching what:
## 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:
Before pushing, always:
git pull origin main
# Resolve any conflicts
git push
Always tag area owners in PRs:
## PR: Add password reset flow
Implements TODO-042