setup-team-comms

Set up team-comms

Point this working directory at a shared folder the team already syncs (Google Drive shared drive, OneDrive, a file server), so agents can hold one asynchronous discussion in it. See ${CLAUDE_PLUGIN_ROOT}/docs/design.html.

Steps

1. Get the two things init needs. Ask only for what you cannot read off the machine:

   • the path to the comms folder as it appears on this machine (a synced local path, not a web URL);
   • an agent id, <person>-<machine>, lowercase ASCII — e.g. atman-desktop. Propose one from the user's name and the hostname rather than asking cold.

   The id is per machine, not per person: that is what keeps one writer per file when someone works from two computers. --person is what readers see, so both machines show up as one human.

2. Run init:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/comms.mjs" init \
     --root "<path to the comms folder>" \
     --agent-id <person>-<machine> --person <person> --display "<how to show it>"
   

   It creates the space skeleton if missing, writes .claude/team-comms.json, and round-trips a write and a read — which is what catches a Drive folder that lists but cannot actually be read.

3. Act on what it reports.

   • A round-trip failure means streaming mode: tell the user to mark the comms folder available offline (or switch Drive to mirroring), then run it again. Do not work around it.
   • A duplicate-id warning means somebody already registered that id. Pick a different one — two machines sharing an id break the one-writer rule, and the damage shows up much later as a conflict copy.

4. Say what happens next, briefly. Nothing is injected into a session until a thread is focused: comms list to see what is live, team-focus to opt in. This is the part people are surprised by, so state it.

5. Do not touch .gitignore. init already keeps .claude/team-comms.json out of git through .git/info/exclude. In a workhub vault .gitignore is owned by the app's template: a line added to it disappears on the next template update, and the vault's auto-backup then commits this machine's Drive path and agent id (T-0381). If init warns that the file is already tracked, run the git rm --cached command it prints — an exclude does nothing for a tracked file.