agentleFS
alinaqialinaqi/claude-bootstrap/skills/team-coordination/SKILL.md

team-coordination

Skill708 starsChanged 5 months agoMITView on GitHub

Multi-person projects - shared state, todo claiming, handoffs

  • Commits and pushes

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. 0 are common, 23 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 23

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 36
  2. Very specific:

    Update state.md if you touch new files

    line 179
  3. Very specific:

    Check decisions.md before making architectural choices

    line 180
  4. Very specific:

    If you make a decision, add it to decisions.md immediately

    line 181
  5. Distinctive:

    When passing work to another team member, create:

    line 201
  6. Distinctive:

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

    line 257
  7. Very specific:

    If you need to touch src/auth/* and Alice is working there:

    line 267
  8. Distinctive:

    Check if it's truly conflicting (same file?

    line 268
  9. Distinctive:

    Add a note to "Conflicts to Watch" section

    line 270
  10. Distinctive:

    Always tag area owners in PRs:

    line 284
  11. Distinctive:

    Check if decision already exists

    line 309
  12. Distinctive:

    If similar decision exists, follow it (consistency > preference)

    line 310
  13. Distinctive:

    If new decision needed, add it and push immediately

    line 311
  14. Distinctive:

    Add claim annotation to todo

    line 346
  15. Distinctive:

    Remove claim annotation from todo

    line 352
  16. Distinctive:

    Update state.md (remove from Claimed Todos)

    line 353
  17. Distinctive:

    Add team state sync check to pre-push:

    line 362
  18. Distinctive:

    When user starts a session in a team project:

    line 388
  19. Distinctive:

    If exists, read it and report:

    line 391
  20. Distinctive:

    Ask what they want to work on

    line 397
  21. Distinctive:

    Check if it's already claimed

    line 398
  22. Distinctive:

    Before touching files, check if someone else is working there

    line 403
  23. Distinctive:

    Before making decisions, check decisions.md

    line 404
  24. Distinctive:

    Ask if they need to create a handoff

    line 410
  25. Distinctive:

    When a project needs team coordination:

    line 417
  26. Distinctive:

    Add claim annotations to active todos

    line 422
  27. Distinctive:

    Update CLAUDE.md to reference team-coordination.md skill

    line 423

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

# 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:

# 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:

## [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:

# 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:

## 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:

git pull origin main
# Resolve any conflicts
git push

PR Tagging

Always tag area owners in PRs:

## 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)
  4. If new decision needed, add it and push immediately

Decision Format

## [2024-01-15] JWT vs Sessions for Auth (@alice)

**Decision:** Use JWT tokens
**Context:** Need auth for API and mobile app
**Options:**
1. Sessions - simpler, server-side state
2. JWT - stateless, works for mobile
**Choice:** JWT
**Reasoning:** Mobile app needs stateless auth, JWT works across platforms
**Trade-offs:** Token revocation is harder, need refresh token strategy
**Approved by:** @bob, @carol

Commands

Check Team State

# See who's working on what
cat _project_specs/team/state.md

# Quick active sessions check
grep "🟢 Active" _project_specs/team/state.md

Claim a Todo

  1. Edit _project_specs/todos/active.md
  2. Add claim annotation to todo
  3. Update _project_specs/team/state.md
  4. Commit and push

Release a Claim

  1. Remove claim annotation from todo
  2. Update state.md (remove from Claimed Todos)
  3. Commit and push

Git Hooks for Teams

Pre-Push Hook Addition

Add team state sync check to pre-push:

# In .git/hooks/pre-push (add to existing)

# Check if team state is current
echo "🔄 Checking team state..."
git fetch origin main --quiet

LOCAL_STATE=$(git show HEAD:_project_specs/team/state.md 2>/dev/null | md5)
REMOTE_STATE=$(git show origin/main:_project_specs/team/state.md 2>/dev/null | md5)

if [ "$LOCAL_STATE" != "$REMOTE_STATE" ]; then
    echo "⚠️  Team state has changed on remote!"
    echo "   Run: git pull origin main"
    echo "   Then check _project_specs/team/state.md for updates"
    # Warning only, don't block
fi

Claude Instructions

At Session Start

When user starts a session in a team project:

  1. Check for _project_specs/team/state.md
  2. If exists, read it and report:
    • Who's currently active
    • What todos are claimed
    • Any conflicts to watch
    • Recent announcements
  3. Ask what they want to work on
  4. Check if it's already claimed
  5. Help them claim and update state

During Session

  • Before touching files, check if someone else is working there
  • Before making decisions, check decisions.md
  • Remind user to update state periodically

At Session End

  • Prompt user to update state.md
  • Ask if they need to create a handoff
  • Remind them to push state changes

Single → Multi-Person Conversion

When a project needs team coordination:

  1. Run /check-contributors
  2. Create _project_specs/team/ structure
  3. Initialize state.md and contributors.md
  4. Add claim annotations to active todos
  5. Update CLAUDE.md to reference team-coordination.md skill

Quick Reference

Status Icons

🟢 Active - Currently working
🟡 Paused - Stepped away, will return
🔴 Blocked - Needs help/waiting on something
⚪ Offline - Not working today

Claim Format

**Claimed:** @handle (YYYY-MM-DD HH:MM TZ)

Daily Standup Template

## Standup [DATE]

### @alice
- Yesterday: Finished TODO-042 auth flow
- Today: Starting TODO-045 password reset
- Blockers: None

### @bob
- Yesterday: Fixed checkout bug
- Today: Payment webhook integration
- Blockers: Need STRIPE_WEBHOOK_SECRET from @carol

Checklist

Starting Work

  • git pull origin main
  • Read team/state.md
  • Check todo not claimed
  • Claim todo in active.md
  • Update state.md
  • Push state changes

Ending Work

  • Commit all changes
  • Update current-state.md
  • Update team/state.md
  • Create handoff if needed
  • Push everything

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.