title: Team Collaboration Playbook README form: index updated: 2026-06-22 status: active tags:

• team-collab
• entrypoint aliases:
• Team Collab
• Team Collaboration Playbook

Team Collaboration Playbook

Team Collab is the file-backed collaboration playbook and CLI for OPC-style teams that coordinate humans and coding agents across code repositories, Obsidian project docs, GitHub/GitLab PRs/MRs, and Feishu automation.

What This Is

• A shared docs workflow for project memory, handoffs, TODO ownership, and review gates.
• A CLI package, @embodot/collab, exposed as team-collab / embodot-collab.
• A runtime protocol installer for Claude Code and Codex skills.
• A multi-agent file protocol where multi-agent/<wave>/ artifacts are canonical truth.
• A thin live-session accelerator for local tmux panes; tmux is never source of truth.

Quick Start

npm install -g @embodot/collab@latest
team-collab install-skills --agent all --force
team-collab register <project> --code <code-dir> --docs <docs-dir>
team-collab doctor --project <project>

For a new project:

team-collab init --leader <project> --docs <docs-dir> --code <code-dir> --dry-run
team-collab init --join <project> --dry-run

Core Commands

| Area | Commands | Purpose | |---|---|---| | Setup | install-skills, install-adapters, register, register-docs, init | Install local agent protocol and register code/docs layouts. | | Health | doctor, health, lint, lint-state, lint-multi-agent | Check wiring, sync risks, and docs/protocol shape. | | Sync | sync, $team-progress, $docs-refresh, $handoff, $checkpoint | Keep local project memory and handoff artifacts current. | | Multi-agent wave | multi-agent enable, multi-agent init, multi-agent digest, multi-agent gate, multi-agent plan --check, multi-agent monitor | Create and verify a file-backed multi-agent workstream. | | Agent lifecycle | agent start, agent checkpoint, agent finish, agent close, agent status | Maintain per-agent status, claims, review state, and merge closeout. | | Live session | agent bind-session, agent watch, agent send | Bind local tmux panes, observe redacted output, and deliver persisted messages. |

Multi-Agent Workflow

Enable a project once:

team-collab multi-agent enable --project <project> --language en

Create a wave:

team-collab multi-agent init --project <project> --slug <wave-slug>

Start workers:

team-collab agent start --project <project> --wave <wave-slug> --task T1 --name codex-mac-a --role implementer --owned-files 'src/**'

Coordinate and verify:

team-collab agent checkpoint --project <project> --wave <wave-slug> --name codex-mac-a --summary "..."
team-collab multi-agent digest --project <project> --wave <wave-slug>
team-collab multi-agent gate --project <project> --wave <wave-slug> --pr 123
team-collab multi-agent plan --check --project <project> --wave <wave-slug> --strict

Optional live-session accelerator:

team-collab agent bind-session --project <project> --wave <wave-slug> --agent codex-mac-a --tmux session:0.0
team-collab agent watch --project <project> --wave <wave-slug> --agent codex-mac-a
team-collab agent send --project <project> --wave <wave-slug> --agent codex-mac-a --message "Please checkpoint before changing shared files."

agent send writes and commits a messages/ artifact before tmux delivery. agent watch redacts secret-like pane output by default and does not write shared docs unless --update-last-seen is explicit.

Language Policy

The packaged playbook and templates are English-only. Project-level language, agent_language, and human_brief_language keys remain available for generated multi-agent prose, but this repository no longer ships a parallel translated README or bilingual runtime documents.

Repository Map

| Path | Purpose | |---|---| | bin/team-collab.js | Main CLI implementation. | | scripts/ | Installers, lints, sync helpers, Feishu/GitLab automation. | | templates/ | Bootstrap files for docs/code repos and agent adapters. | | tests/ | Python unittest coverage for CLI behavior and scripts. | | 00-*.md ... 10-*.md | English playbook reference docs. |

Status

• npm package: @embodot/collab v0.2.1.
• Multi-agent Phase 0-5 are implemented on main: enable/init, agent lifecycle, digest/status, gate/plan/lint, live-session adapter, and i18n foundation.
• Runtime CLI message catalog localization is intentionally separate from this docs/template English-only cleanup.

Evolution

This playbook evolves through GitLab MRs. Code and formal code docs use the code platform PR/MR flow; high-level shared docs use GitLab docs MRs. Protected/shared branches must not be force-pushed.