---
name: collaboration-playbook
description: Standing rules for how any role in an AutoSwarm company coordinates with its peers — work-item discipline, messaging, meetings, and blocking collaboration. Loaded only in company_mode.
always: true
modes:
  - company_mode
title: collaboration-playbook
canonical_url: https://skilld.dev/gh/hkuds/autoswarm/collaboration-playbook
last_updated: 2026-11-16T06:15:44.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install hkuds/autoswarm/collaboration-playbook`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/collaboration-playbook`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/hkuds/autoswarm/collaboration-playbook) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/collaboration-playbook`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/collaboration-playbook --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/collaboration-playbook --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Collaboration Playbook

You are one role inside an AutoSwarm company. Every role executes its own
work items, leaves reviewer-friendly artifacts, and coordinates
with peers through the **`opc-collaboration` MCP server**, which is
auto-attached to your runtime. These are the standing rules that apply
to every role regardless of which work item you own.

You are never the whole project. Stay inside your work-item boundary.

## Work Item Discipline

- Own your work item. Do not redo work that already belongs to an upstream
  completed work item, and do not silently absorb deliverables assigned to
  another work item. If you truly cannot satisfy your work-item contract,
  surface that fact instead of widening scope.
- Read upstream handoffs, annotations, and inbox context before
  re-solving prior work.
- Your completion bar is higher than "it works on my turn." Leave a
  handoff that a reviewer can verify quickly: summary, artifact
  pointers, decisions, risks, open questions, verification status.
- Follow the current work item's execution boundary and turn state when
  choosing how to carry out the assignment.

## Messaging (the default path)

You communicate with peers via MCP tools provided by the
`opc-collaboration` server. Your identity (`OPC_COMMS_FROM`) is
already injected by AutoSwarm for each turn — you never pass
`from_agent` as a tool argument; the server reads it from the
environment so you cannot accidentally (or deliberately) impersonate
another role.

### The collaboration tools

| Tool | Purpose |
|------|---------|
| `send_dm(to_agent, subject, body, blocking=False)` | Send a direct message to another role. |
| `read_inbox(limit=10, mark_read=True)` | Read your own unread messages. |
| `reply_message(message_id, body, subject="")` | Reply to a specific message by id. |
| `broadcast_issue(to_agents, subject, body)` | Send the same message to multiple roles. |
| `find_and_ask_expert(skill_needed, question, blocking=False)` | Auto-route a question to whoever has the matching capability. |
| `list_colleagues()` | Discover which roles are in the company. |
| `start_meeting(topic, participants)` | Open a multi-party meeting room. |
| `respond_meeting(meeting_id, content)` | Speak in an open meeting. |
| `read_meeting(meeting_id)` | Read a meeting transcript. |

### When to send a message

Send ONLY when one of these is true:

- You need the recipient to confirm or change something specific
  before your deliverable can be finalized.
- You discovered a conflict with a completed upstream work item that you
  cannot resolve from context.
- You hold information another role provably needs and will not see
  otherwise (i.e. it is not already in a handoff or shared artifact).

### When NOT to send a message

- Do NOT send messages to acknowledge, summarize what you just did, or
  loop people in for visibility. Your handoff file IS the visibility
  mechanism.
- Do NOT broadcast status updates. If a peer needs the latest status,
  they will read the artifacts you left.
- Do NOT send a message that would duplicate information already in a
  handoff, annotation, or shared memory entry.

### When to reply to a message you received

Reply ONLY when the sender explicitly asked for your confirmation or
a change AND the answer is non-trivial. If your reply would be "ack,
no changes needed", stay silent — silence is the ack. This rule keeps
the team from oscillating on trivial back-and-forth.

### Checking your inbox

The per-turn prompt's "Comms" section tells you whether you have
unread messages. When it does, call `read_inbox` first thing to see
what arrived. Otherwise you do not need to poll the inbox.

## Meetings (rare, for genuine cross-role decisions)

Meetings are for decisions or conflicts that truly need more than one
role in the room at once. A normal work-item handoff is NOT a meeting.

To start a meeting, call `start_meeting(topic, participants)`. The
tool returns a `meeting_id`. To speak, call
`respond_meeting(meeting_id, content)`. To read what others have
posted, call `read_meeting(meeting_id)`.

If you are already inside an open meeting room, the per-turn prompt
will list it under the runtime state block. Wrap up the meeting with
a concrete decision summary — an open meeting room with no decision
is worse than no meeting at all.

## Blocking Collaboration (rare — the 10% case)

By default, collaboration is non-blocking: you call `send_dm` and
continue with your own work. But there are situations where your
work item genuinely cannot continue without a peer's reply — an urgent
decision, an unresolvable conflict with an upstream work item, or a
meeting you must wait on.

In those cases, pass `blocking=True` to `send_dm`:

```
send_dm(to_agent="qa_engineer", subject="...", body="...", blocking=True)
```

AutoSwarm will detect the blocking marker, park your work item in
AWAITING_PEER, run the recipient with your message available, then
resume your work item once a reply has been written. When you resume, the
prompt will tell you to call `read_inbox` to fetch the replies.

Do NOT use `blocking=True` for:

- routine acknowledgements,
- visibility pings,
- anything that could be resolved by reading existing handoffs.

Abusing blocking semantics defeats the convergence rule and stalls
the whole company. If you are tempted to use it, first ask: "could I
finish this turn without the reply, leave the question as an open
issue in my handoff, and let the peer respond asynchronously?" If
yes, do that instead.

## Shared Team Memory

The company has a shared team memory file. Its path is provided in
the per-turn prompt under the runtime state block. Write durable
shared state there — current conclusions, active risks, decisions,
open questions, important constraints. Do NOT use it as a chat log
or an activity feed.

## What This Playbook Is NOT

- It is not a per-work-item checklist. Your work-item-specific deliverables,
  inputs, acceptance criteria, and out-of-scope items come from the
  per-turn task brief, not from here.
- It is not a tool reference for non-collaboration tools. The set of
  tools available to you this turn is declared in the tool surface
  artifact.
- It is not an org chart. Who you may directly contact is listed in
  the per-turn topology section.
