bot-collab

name	bot-collab
description	Pattern for multi-agent collaboration sessions in the deep-cuts fam — forge-first coordination over the botfam substrate (Gitea issues/PRs as the coordination plane, the unified `botfam wait` wake loop, bare-actor worktrees), with IRC opt-in for design sprints, plus session-log conventions

Multi-Agent Collaboration Skill

Use this skill as the launcher for structured collaborative sessions between Roberto and multiple agentic coding assistants in the deep-cuts fam.

The canonical protocol lives in the botfam MCP resources (served by botfam serve); read them before acting — they are the single source of truth and this skill only points at them:

• botfam:///docs/start — onboarding, identity resolution, the wake loop.
• botfam:///docs/protocol — coordination rules, PR consensus, Let-It-Crash / Handover Snapshot.
• botfam:///docs/worktrees — worktree ownership & discipline.
• botfam:///docs/ops — IRC runbook (credentials, recovery, FIFO interface).
• botfam:///docs/review — PR review checklist.
• botfam:///docs/bootstrap — same-host coordination primitives.

If this skill and a botfam:///docs/* resource disagree, follow the resource and update this skill later.

Coordination vs. quality. Coordination is the forge plane below. When the goal is to make a specific artifact provably better — reproducible evidence, independent approval, unresolved-risk closure — drive it through a Gitea pull request: open the PR, gather peer reviews per botfam:///docs/review, and merge only when branch protection's approval gate passes (botfam:///docs/protocol §3). They compose: coordinate on the forge, ratchet quality through the PR review gate.

The coordination plane: the forge (first choice)

The Gitea forge is the coordination plane. Agents coordinate with peers and the operator through forge issues and PRs — assignments, reviews, and comments — not through chat. To send another agent a durable, directed message, comment on an issue/PR and @-mention or assign them.

• Identity: your actor name is the basename of your worktree directory (claude, agy, codex). Verify with botfam whoami. The botfam binary is at ~/bin/botfam if not on PATH.
• Wake loop — the unified wake point: run botfam wait as a background task and re-arm it after every wake — an unarmed watcher is the number-one cause of silently unresponsive agents. It reads your per-agent spool ($FAMROOT/spool/<actor>, here /Users/rlupi/src/fams/deep-cuts/spool/<actor>) and prints each surfaced message as a ===== message N/M · <source> ===== banner followed by the verbatim RFC-822 message; surfacing is the ack (moves new/ → cur/). botfam wait --replay re-reads cur/ for gap recovery.
  • Do-not-disturb is the default: forge events wake you only when directed at you (you are an assignee, or @-mentioned in the latest comment). Non-directed activity is still recorded (cur/, via --replay) but does not interrupt; pass --all to surface everything.
  • The single-source watchers botfam irc-wait / botfam forge-wait are deprecated — prefer botfam wait.
• Forge token: minted with botfam mint --harness <harness> --user <forge-user>; stored at ~/.botfam/token-<actor>. A missing token shows up as a forge_token health warning in botfam:///index.json.
• Health: read botfam:/// (or run botfam orient) first — it indexes the resources and lists environment health warnings (missing token, IRC client offline, wrong directory).

IRC (opt-in, design sprints only)

IRC is not required to coordinate or to be woken — that is the forge's job. Join the channel only when participating in a design sprint:

botfam irc-client claude

• The nick is the fam-scoped <actor>-dc (e.g. claude-dc); the pass file resolves on its own (no --pass-file flag needed). Channels derive from slug = "dc": #dc (discussion) and #session-<slug> working channels. Cross-fam channels (e.g. #party) are joined on request.
• While joined, botfam wait always relays IRC lines (DND never filters IRC — you control exposure by joining/parting).
• The client does not auto-reconnect — restart it after any server downtime. Server ops, credentials, recovery, and the FIFO line protocol live in botfam:///docs/ops.
• Replay-on-join: before acting after a (re)connect, read the durable channel history via the irc_replay MCP tool (or botfam wait --replay) so you never reply to a stale conversation.

Worktree Topology

The fam uses the unified multi-fam layout: /Users/rlupi/src/fams/deep-cuts/main is the shared merge target; each agent works in its own bare-actor worktree (claude, agy, codex, …) on an agent/<actor> branch.

• Worktree branches are for deliverables; other actors' worktrees are read-only (botfam:///docs/worktrees) — to update one, request it on the forge or #dc and let the owner act.
• main is merge-only: never rebase or force-push it; claim ref-changing operations first, and merge with explicit identity (git -c user.name=claude -c user.email= merge --no-ff <branch>).
• Process state (assignments, review approval, merge-readiness) lives on the forge; the repository tip is mutated only by merges. Use git commits/PRs for concrete deliverables.

Repository Family Boundaries

Multiple fams run on this host (e.g. deep-cuts and botfam). An agent operates only within its own fam:

• Read across fams is permitted — read files, status, and logs in another fam's checkout for reference and cross-checking.
• Never write, execute, or manage processes across fams — do not edit files, run modifying commands, or spawn/manage/kill background processes (botfam wait, irc-client, serve) in another fam's worktree or environment.
• No identity impersonation — speak and act only as your own fam nick (e.g. claude-dc, never botfam's claude); never use another fam agent's credentials or workspace config.
• Coordinate over the forge / IRC — any action needed in another fam's checkout is requested on that fam's plane, and that fam's own agent executes it.

Let It Crash & Warm Handover

Agents degrade as their context fills, so we design for failure recovery, not in-place recovery (botfam:///docs/protocol §4.1):

• Let it crash: if context-fullness approaches the crash threshold or the agent stalls/loops, exit immediately rather than writing defensive recovery code.
• Handover Snapshot: before crashing (or at progress milestones), write a compact snapshot to the control plane (the forge issue/PR comment): the task goal, decisions taken so far and why, a pointer to the branch/PR (reference the product state, don't copy it), the current blocker, and the next step.
• Warm restart: the supervising harness spins up a fresh agent and injects the snapshot; the new agent checks out the branch and resumes from the next step — no replay from genesis.

Startup Checklist

When the user mentions a multi-agent collaboration session or asks you to join the fam:

1. Read botfam:/// for health, then verify botfam whoami.
2. Launch botfam wait as a background task (re-arm after every wake). Join IRC only for a design sprint.
3. If resuming, load the latest Handover Snapshot from the relevant forge issue/PR and check out its branch — do not replay history from genesis.
4. Find or create the session directory under doc/collab/sessions/YYYY-MM-DD-topic-slug/ when the work needs a durable session log; read the full session.md, not only the tail.
5. After every wake: read the new spool lines, act, re-arm botfam wait.

Session Files

New sessions use this path shape:

doc/collab/sessions/YYYY-MM-DD-topic-slug/session.md

Session logs are working records. Durable decisions must be promoted into normal doc/ files, skills/ files, or code comments. The forge (issues/PRs) is the live record; the session log is the curated one.

---

Handoff Format

End collaborative turns with the structured handoff required by botfam:///docs/protocol:

**→ Handoff:**
**Task:** [what to do]
**Context:** [files, data, or prior decisions needed]
**Deliverable:** [expected artifact]

Post the same Task/Context/Deliverable triple as a forge issue/PR comment (@-mention or assign the next owner so it surfaces through their botfam wait). On IRC during a design sprint, post the same triple to #dc.

Documenting Roberto's Contributions

When Roberto makes a direct contribution (e.g., providing design direction, running commands, writing code, or giving explicit feedback that is not just relaying an agent's handoff), the active agent must document it in the session log:

• Insert a ## [Roberto, HH:MM] block outlining his feedback, code changes, or decisions, OR
• Explicitly credit and outline his steering decisions within the agent's own turn. This keeps the session log as the single source of truth for the collaborative path.

Recording Acknowledgements (ACKs)

Agreement is signal worth keeping, not just handoffs and disagreements. When you endorse, confirm, verify, or accept another participant's work, record it in the session log — not only on the forge:

• A short ACK line inside your turn ("ACK: verified Gemini's mir_eval numbers, consistent on re-run"), OR
• A one-line ## [X, HH:MM] block when relaying someone else's ACK.

This makes consensus — and who reached it — part of the durable record.