multi-agent-collab

A reusable skill for bootstrapping consistent multi-agent collaboration in any Git repository. Supports Claude Code, OpenAI Codex, and Google Antigravity / Gemini CLI out of the box, and is elastically extensible to additional agents (OpenCode, Cline, Aider, Cursor, Copilot CLI, custom) via the --join flow.

Status

v0.4.4 — small correctness patch. Fixes a same-day archive clobber in collab-rotate-log.sh (data loss bug), kills the rotation-advisory loop in collab-check.sh when the log is already at keep-minimum, and aligns the --stats entry-count regex with the v0.4.2-corrected pattern. See CHANGELOG.md for the full release notes.

What's new in v0.4.4

• Same-day archive append (no clobber) — collab-rotate-log.sh now appends to an existing same-day archive instead of overwriting it. Pre-fix, rotating twice in one day (e.g., after tweaking rotate_keep_recent) silently destroyed the prior archive's entry bodies. Append uses an H3 ### Continued — rotated <ISO> separator so the archive stays one human-readable file per agent-day.
• Content-aware rotation advisory — collab-check.sh no longer advises rotation when rotation would be a no-op. When the live log exceeds rotate_at_lines but the entry count is already at-or-below rotate_keep_recent, the advisory text now points at config tuning (raise rotate_at_lines or accept the verbose Receipt size) instead of looping the user through useless rotate invocations.
• --stats regex aligned — --stats mode now counts date-only entry headers (## 2026-04-28 title) correctly. Projects using date-only headers will see higher (correct) entry counts in --stats output than under v0.4.3.
• 2 new test cases on the rotate side, 16 new test cases on the check side — including a three-way regex-alignment guard across collab-rotate-log.sh, the advisory site, and the --stats site.

Upgrading to v0.4.4

# Standard one-command upgrade (no state migration required):
npx @gpgaoplane/multi-agent-collab update

# Auto-confirm for CI:
npx @gpgaoplane/multi-agent-collab update --yes

What's new in v0.4.3

• update subcommand — npx @gpgaoplane/multi-agent-collab update wraps the upgrade flow in a single command: pre-flight version check, interactive confirmation prompt, auto-backup, migration chain, post-flight ack reminder. Modes: update, update --check, update --ack, update --rollback. Modifier flags: --yes / -y (skip prompt), --diff-first (preview before apply), --no-backup, --force-dirty. Replaces the pre-v0.4.3 multi-step init → read notes → --ack-upgrade flow with a single command. The old flow still works on installs that haven't upgraded yet.
• update --rollback cleans up stale migration sentinels — fixes a latent bug where post-rollback re-upgrades would silently skip migration bodies. Critical for any future migration that does real file work; for v0.4.x's no-op summary migrations the practical impact was just "no upgrade banner appeared."
• Tightened vocabulary — PROTOCOL.md "Framework upgrade vocabulary" section points at the new update subcommand. New phrases recognized: "preview the upgrade" → update --diff-first; "roll back the upgrade" → update --rollback; "ack the upgrade" → update --ack. Forward-only: existing installs keep their old PROTOCOL.md text (re_init_shared treats it as create-once); functional contract preserved (old 3-command path == new 1-command path). Manual fix below for users who want the new vocab on existing installs.
• scripts/lib/semver.sh, scripts/lib/migrations.sh — helper functions extracted from collab-init.sh so collab-update.sh can source them without re-executing init's body. Pure refactor.
• 41 new tests.

Upgrading to v0.4.3

# From v0.4.2+:
npx @gpgaoplane/multi-agent-collab update

# From v0.4.1 (cli.js flag-drop bug — call bash directly):
bash node_modules/@gpgaoplane/multi-agent-collab/scripts/collab-init.sh

# Then once v0.4.2+ is installed, prefer the new 'update' command for all
# future upgrades:
npx @gpgaoplane/multi-agent-collab update

Manual PROTOCOL.md vocabulary refresh (optional)

Existing v0.4.x installs upgrading to v0.4.3 keep their old .collab/PROTOCOL.md text — re_init_shared treats PROTOCOL.md as create-once. The old 3-step upgrade vocabulary still works (functionally equivalent to the new 1-command vocab), so this is OPTIONAL. If you want the new "update", "preview the upgrade", "roll back the upgrade" phrases recognized in your installed copy:

# Inside your project root (after upgrading to v0.4.3):
cp node_modules/@gpgaoplane/multi-agent-collab/templates/collab/PROTOCOL.md .collab/PROTOCOL.md
# OR for skill-clone users:
cp ~/.claude/skills/multi-agent-collab/templates/collab/PROTOCOL.md .collab/PROTOCOL.md

Warning: this overwrites your .collab/PROTOCOL.md. Any local customizations to that file are lost. The vocabulary content is the only meaningful difference between v0.4.2 and v0.4.3 PROTOCOL.md, so this is usually safe — but inspect the diff first if you've customized.

What's new in v0.4.2

• Rotation accepts date-only entry headers — ## 2026-04-28 first task now matches the rotation regex. Previously required full ISO datetime with T, so logs with date-only headers silently never rotated regardless of size. The work-log seed template gains a worked example so future agents follow a consistent format.
• rotate_keep_recent default lowered 8 → 3 in shipped templates/config.yml. Existing .collab/config.yml files are NOT auto-rewritten — opt in by editing your config line.
• bin/cli.js forwards all flags for init/join/archive/register. Previously these silently dropped --agent, --diff, --restore, --prune-backups, --ack-upgrade, --install-hooks, --force-dirty, --no-backup, --dry-run, and register --type/--owner — every documented npm-channel example using these flags was broken. v0.4.1 users should call bash directly to upgrade (see below).
• Pre-commit hook is self-contained — receipt-verify logic is inlined from scripts/lib/receipt.sh at install time. Works identically in npm-installed repos (no scripts/ dir needed) and direct-clone repos. The installed hook has zero external script dependency.
• --restore prunes migration-created files — --diff (apply-then-restore) and --restore latest no longer leak migration side effects. Strict allowlist scoped to collect_backup_paths(); never recursive on directories; .collab/backup/ itself is never touched.
• UPGRADE_NOTES.md auto-archived on chained upgrades — a second upgrade run before --ack-upgrade no longer overwrites the prior transient notes. Schema unified across both --ack-upgrade and the auto-archive path: UPGRADE_NOTES-<from>-to-<to>-<YYYYMMDDHHMMSS>.md.
• .collab/VERSION format validated — garbage content (typo, partial corruption, latest) hard-fails with guidance. The validation runs AFTER the --restore short-circuit so corrupted VERSION never locks users out of recovery.
• Doubled marker blocks emit a loud warning — merge_replace_section previously silently corrupted files with duplicate <!-- collab:NAME:start --> markers. Now: stderr WARNING + return 1; refresh paths tolerate so init still completes on already-corrupted files.
• Migrations are idempotent via sentinels — per-migration sentinel files at .collab/.migrations/<from>-to-<to>.applied make the chain runner safe to re-enter. SHA-256 of the migration script body detects future patches that should re-trigger application. Legacy migrations on existing v0.4.x installs are auto-back-filled (NOT re-run). Portable SHA shim picks sha256sum/shasum/openssl.
• inject_agents_md_section no-ops on orphan markers — defensive against the partial-restore path that previously produced doubled-start corruption.
• ~80 new tests.

Upgrading from v0.4.1 (cli.js flag-drop bug)

If you're on v0.4.1, the cli.js shim silently drops every flag for init. Call bash directly so --diff/--restore/--ack-upgrade reach the bootstrap script:

# Preview the migration without applying:
bash node_modules/@gpgaoplane/multi-agent-collab/scripts/collab-init.sh --diff

# Apply the upgrade:
bash node_modules/@gpgaoplane/multi-agent-collab/scripts/collab-init.sh

# After reading .collab/UPGRADE_NOTES.md, ack:
bash node_modules/@gpgaoplane/multi-agent-collab/scripts/collab-init.sh --ack-upgrade

# Roll back if anything looks wrong:
bash node_modules/@gpgaoplane/multi-agent-collab/scripts/collab-init.sh --restore latest

Once v0.4.2 is installed the standard npx @gpgaoplane/multi-agent-collab init -- --diff (etc.) flow works because the shim now forwards flags correctly.

What's new in v0.4.1

• default_agent in .collab/config.yml — opt-in per-repo persistent setting that fits between $COLLAB_AGENT and the env-var probe. Zero false positives. Set once, never re-export.
• collab-init --prune-backups [--keep N] — clean up old .collab/backup/ directories. Default keep = 5 (configurable via keep_recent_backups in .collab/config.yml).
• Auto-prune on --ack-upgrade — .collab/backup/ self-cleans after each upgrade ack.
• Hard-fail message clarified — names the default_agent option and warns that Codex/Gemini env-var probes are best-effort (only CLAUDECODE is a strong session signal).

What's new in v0.4.0

• Calling-agent-only bootstrap — init materializes only the agent that ran it. Detection probes env vars; falls back to --agent <name> or $COLLAB_AGENT; hard-fails with guidance when nothing matches. Other agents arrive via join.
• Dynamic adapter table — Current Adapters section in AI_AGENTS.md is rendered from .collab/agents.d/ and re-rendered on every init/join/migration.
• Work-log rotation — collab-rotate-log.sh <agent> archives older entries (default: 300-line threshold, keep 8 entries) preserving Receipts as one-line summaries and open handoff blocks verbatim. CRLF + ## subsection aware.
• Handoff pickup verb + vocabulary — collab-handoff pickup <id> --from <self> prints summary + stamps picked-up:. Sender phrases ("wrap up for handoff") and receiver phrases ("take the baton") documented in PROTOCOL.md. Group to: any handoffs supported.
• Upgrade communication — migrations emit >>> Upgrade summary: blocks; the upgrade chain writes .collab/UPGRADE_NOTES.md for the next agent to read. collab-init --ack-upgrade archives it. collab-check surfaces it at top of output.
• Migration safety — auto-backup on upgrade (.collab/backup/...), --restore <id>, --diff (preview migrations without applying), --force-dirty override for the new pre-migration cleanliness check. Loud BEFORE/AFTER per-file logging.
• Marker warnings — every framework-managed <!-- collab:NAME:start --> block now has an inline warning comment; AI_AGENTS.md ships a collab:customization-guide section explaining the edit-outside-markers convention.
• Post-compact ritual — explicit guidance in AI_AGENTS.md for what to re-read after auto-compaction. Optional Claude PreCompact hook template.
• Commit cadence rule — Cadence bullet under AI_AGENTS.md Commits formalizes the "commit only on user request or task boundaries" convention.
• Critical rules inlined into AGENTS.md — Receipt requirement, read-before-modify, commit cadence, post-compact pointer surfaced in the auto-discovered front-door file.
• AI_AGENTS.md trimmed to ≤100 lines — verbose explanations relocated to docs/design.md (already reference-only); load-bearing rules retained inline.
• User vocabulary — natural-language phrases for rotation ("rotate the log") and upgrade ("update the framework") map to commands.
• collab-register --type/--owner/--status flags — register files that lack frontmatter, or override frontmatter values.
• collab-check --stats — per-agent diagnostic table with entries, log lines, open handoffs, archive counts.
• 0.3.0 → 0.4.0 migration — interactive prune of agents with seed-only work logs. Calling agent is never flagged.
• ~196 new tests.

What v0.3.0 shipped

• Cross-agent handoff — collab-handoff <to-agent> writes a structured handoff block with chain support (A→B→C→A).
• Delta-read on demand — collab-catchup previews files newer than your watermark; ack commits it (two-phase keeps it honest).
• Presence board — collab-presence start|end manages .collab/ACTIVE.md rows.
• Receipt enforcement — opt-in portable pre-commit hook via collab-init --install-hooks. .collab/config.yml: strict: true blocks instead of warning.
• Update advisory — collab-check reports when a newer npm version exists.
• Session-start snippets (optional) — surface remote drift automatically.
• Auto-publish — tag v* → GitHub Actions publishes to npm.

What this skill does

• Bootstraps a canonical directory structure for multi-agent work: shared contract (AI_AGENTS.md), cross-agent front door (AGENTS.md), per-agent adapters (.claude/, .codex/, .gemini/, …), per-agent memory, outward-facing work logs.
• Ships a shared behavioral ruleset every agent inherits — verification, commit hygiene, read-before-modify, cross-agent courtesy, memory routing, timestamp conventions, delta-read.
• Defines a fan-out routing matrix and End-of-Task Protocol with required Receipts, so substantive tasks never leave relevant files un-updated.
• Uses YAML frontmatter + a central .collab/INDEX.md + per-agent read-watermarks so agents skip irrelevant files and read only what changed since their last session.
• Is idempotent on re-run and merge-safe for existing repos via marker-guided sections (<!-- collab:SECTION:start/end -->).

Design summary

Five central mechanisms:

1. Shared contract + per-agent adapters, elastic via YAML descriptors in .collab/agents.d/.
2. Core-five memory model per agent (work log, state, context, decisions, pitfalls), plus free custom files with frontmatter + INDEX obligations.
3. Fan-out routing matrix mapping task dimensions to required file updates.
4. End-of-Task Protocol + Receipt making update completeness visible and non-negotiable.
5. Two-tier session/task model — automatic session boundaries for presence, explicit task boundaries for documentation.

Installation

Three channels — pick whichever fits your setup. All three run the same bootstrap and produce the same result.

Via npm (recommended)

npx @gpgaoplane/multi-agent-collab init

Runs without permanent install. For a permanent install:

npm install -g @gpgaoplane/multi-agent-collab
multi-agent-collab init

Calling-agent-only install (v0.4.0+). init bootstraps only the agent that runs it. Detection ladder:

1. --agent <name> flag wins.
2. $COLLAB_AGENT env var if no flag.
3. Probe of CLAUDECODE, CLAUDE_CODE_SSE_PORT, CLAUDE_CODE_OAUTH_TOKEN, CODEX_HOME, CODEX_CLI, GEMINI_CLI, GEMINI_API_KEY, GOOGLE_AI_API_KEY.
4. Hard-fail with re-run guidance if nothing matches.

To install with a specific agent regardless of detection:

npx @gpgaoplane/multi-agent-collab init -- --agent codex
# or:
COLLAB_AGENT=codex npx @gpgaoplane/multi-agent-collab init

Via skill drop-in (for SKILL.md-aware agents)

Claude Code, OpenCode, Cursor, and several other agents auto-discover skills in ~/.claude/skills/ and ~/.agents/skills/. Clone this repo there:

git clone https://github.com/gpgaoplane/multi-agent-collab.git ~/.claude/skills/multi-agent-collab

When the user asks the agent to "set up multi-agent collaboration," the agent loads SKILL.md, checks whether the target repo is already bootstrapped, and runs the installer if not. Updates: git pull inside that clone.

Via direct clone (no npm, no agent)

git clone https://github.com/gpgaoplane/multi-agent-collab.git /tmp/multi-agent-collab
cd /path/to/your/repo
/tmp/multi-agent-collab/scripts/collab-init.sh

Adding a new agent

# In a repo already bootstrapped with multi-agent-collab:
npx @gpgaoplane/multi-agent-collab join <agent-name>

<agent-name> can be any agent:

• Known (shipped descriptor): claude, codex, gemini.
• Unknown (generic descriptor auto-generated): opencode, cline, aider, cursor, windsurf, or anything else.

For agents with non-standard conventions (e.g., adapter file at repo root instead of .{name}/), edit the auto-generated descriptor at .collab/agents.d/<name>.yml then re-run join.

Upgrading

npx @gpgaoplane/multi-agent-collab init

The bootstrap detects the previous version and runs the full migration chain (e.g. v0.1.0 → v0.4.0 runs 0.1.0-to-0.2.0.sh, 0.2.0-to-0.3.0.sh, 0.3.0-to-0.4.0.sh in order). User content outside marker sections is preserved.

Upgrading from v0.3.0 to v0.4.0 — step by step

In each repo bootstrapped at v0.3.0:

1. Commit or stash any in-flight work. v0.4.0 runs a cleanliness check at the start of upgrades and refuses to proceed on a dirty working tree (override with --force-dirty if you really want to mix the diffs).
2. (Optional) Preview the migration without applying it:

   npx @gpgaoplane/multi-agent-collab init -- --diff

   Prints unified-diff hunks per changed file, then restores the repo to its pre-migration state. Doesn't keep any UPGRADE_NOTES.md or backup directory behind.
3. Run the upgrade:

   npx @gpgaoplane/multi-agent-collab init

   • Auto-backup runs first: snapshots all framework-managed files into .collab/backup/0.3.0-to-0.4.0-<timestamp>/. Disable with --no-backup if you don't want it.
   • Migration prompts appear if the 0.3.0→0.4.0 migration detects agents with seed-only work logs (no real entries). Per-agent yes/no, default keep. The calling agent is never flagged. Non-interactive contexts (CI, no tty, COLLAB_MIGRATE_NONINTERACTIVE=1) skip the prompts and keep everything. To prune all flagged seed-only agents non-interactively (destructive, intentional), set COLLAB_MIGRATE_REMOVE_ALL_SEED=1.
   • >>> Upgrade summary: blocks print to stdout listing what each migration changed.
   • .collab/UPGRADE_NOTES.md is written. Status transient — the next agent to start a session reads it, follows the post-upgrade ritual, then runs collab-init --ack-upgrade to archive it.
4. Rollback if anything looks wrong:

   bash scripts/collab-init.sh --restore latest

   Or --restore <specific-backup-id> to pick a particular backup directory.

Natural-language phrases agents understand (v0.4.0+)

You can speak any of these to a Claude/Codex/Gemini session in a bootstrapped repo and the agent runs the right command:

• Upgrade: "update the framework", "get the latest version", "is there a new version" (check-only), "update multi-agent-collab".
• Rotation: "rotate the log", "trim my work log", "compact the work log", "archive old entries", "the log is getting long".
• Handoff (sender): "wrap up for handoff", "prepare handoff to ", "tag out to ".
• Handoff (receiver): "take the baton", "pick up handoff", "take over from ", "you're up".

Full vocabulary contract in templates/collab/PROTOCOL.md.

Flags (all channels)

• init — bootstrap the current repo (fresh, re-init, or upgrade; auto-detected)
• join <name> — add an agent with three-tier descriptor lookup
• check — audit INDEX vs filesystem
• archive <path> — move a file to .collab/archive/ and flip its status
• register <path> — register a file in INDEX (used internally, exposed for custom flows)

Underlying bash script accepts also:

• --agent <name> (repeatable) — bootstrap a specific agent only
• --add-agent <name> — add an agent whose descriptor already exists (v0.1.0-compatible)
• --dry-run — preview without writing
• --force — overwrite non-marker content (destructive)

Cross-agent workflow commands

• handoff <to-agent> --from <name> [--message ...] [--files ...] — sender writes a handoff block
• handoff close <id> --from <name> — receiver marks block done
• catchup preview --agent <name> [--handoff] — see what changed, or surface open handoffs
• catchup ack --agent <name> — commit current time as INDEX watermark
• presence start|end --agent <name> — manage ACTIVE.md presence rows

Requirements

• git, bash
• For npm channel: Node.js ≥18
• On Windows: Git for Windows (includes Git Bash)

Testing

./tests/run-all.sh

All tests must pass before merge. TDD is required for new scripts.

License

MIT. See LICENSE.