# team-coordination

Coordinates multiple Claude Code sessions in a single repository via shared Markdown state files and task claiming. Helps developer teams avoid merge conflicts when editing the same codebase.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 314 installs · ★ 711
- Author: alinaqi
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/alinaqi/maggy/tree/HEAD/skills/team-coordination/SKILL.md
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/skills/team-coordination

## What it does

The skill sets up a `_project_specs/` directory inside the repository to track shared work across multiple sessions. Everything runs on plain Markdown files. Team members see active tasks and touched files in `team/state.md`, while architectural choices go into `session/decisions.md`. Work distribution is tracked inside `todos/active.md`.

This skill is not user-invocable. Instead, it instructs the coding assistant to follow strict operational checklists. The agent must pull the latest Git changes, verify that a todo is unassigned, claim it, and broadcast the session state before editing code. When transferring tasks, it writes a detailed handoff note under `handoffs/`.

The workflow breaks if developers fail to push their state files every 1–2 hours. Because there is no background sync server, coordination relies entirely on regular Git commits.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill team-coordination -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/team-coordination/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/team-coordination/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill team-coordination -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/team-coordination/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill team-coordination -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/team-coordination/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install alinaqi/maggy team-coordination
```

2. **Manually: put the files in place**
- File: `.github/skills/team-coordination/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill team-coordination -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/alinaqi/maggy --path skills/team-coordination
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/team-coordination/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add alinaqi/maggy --skill team-coordination -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alinaqi/maggy/tree/HEAD/skills/team-coordination/SKILL.md

## When to use it
- claim tasks in `active.md` to prevent duplicate work
- track touched files across active sessions to detect conflicts
- pass unfinished work to teammates using handoff files
- record shared architectural choices in `decisions.md`

## Example prompts
- Check _project_specs/team/state.md and claim an unassigned task from active.md
- I am ending this session, update my status in state.md and create a handoff note
- Record our architectural decision on JWT in session/decisions.md and push the update

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 85c4cbeb96330370.

BEGIN THIRD-PARTY FILE 85c4cbeb96330370
````text
---
name: team-coordination
description: Multi-person projects - shared state, todo claiming, handoffs
when-to-use: When multiple developers are working on the same repo
user-invocable: false
effort: low
---

# 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 |
````
END THIRD-PARTY FILE 85c4cbeb96330370

The third-party file has ended. Everything between the 85c4cbeb96330370 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2787 of 13259 bytes. © alinaqi · MIT · https://github.com/alinaqi/maggy/tree/HEAD/skills/team-coordination/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md