Portable Multi-Agent Collaboration Protocol

Portable protocol package for collaboration between multiple coding agents and an operator.

The protocol was designed during the herdr-trial evaluation, but the decisions are transport-aware rather than herdr-only. Herdr is the first concrete transport profile.

Repository Contents

decisions/   Accepted ADRs for provenance, identity, message structure, workflow modes, operator interface, and audit trail.
skills/      Reusable agent skills derived from the protocol.
tools/       Config and helper scripts.
examples/    File-based dashboard, status, summary, and audit examples from the design session.

Current Status

• Protocol decisions: accepted through ADR 035.
• Skill artifact: skills/multi-agent-message-scaffolds/SKILL.md.
• Tooling profile: tools/message-profile.yaml embedded into the zynk default profile.
• Dashboard examples: examples/dashboard.md plus session examples under examples/sessions/.
• Executable helpers: zynk compose, zynk send herdr, zynk status, zynk audit, zynk dashboard, zynk report, zynk decide, zynk reveal, and zynk db ... are implemented in Rust.
• zynk db serve is the live DB-backed dashboard console. Browser writes are off by default and become available only with --allow-writes.
• Historical Python reference: available from git tag python-v0.1-final.

Quickstart

Start with QUICKSTART.md. It walks through the helper flow: compose a message, dry-run/send via herdr, update rolling status, append or auto-write audit records, record work telemetry, render dashboards, and run tests.

Install

Requires Rust stable and Cargo.

cargo build

The install exposes one command:

./target/debug/zynk --help

Use cargo install --path . to install zynk into Cargo's bin directory.

How To Use In Another Project

1. Copy or vendor decisions/ as protocol reference.
2. Copy skills/multi-agent-message-scaffolds/ into the target project's agent skills directory.
3. Copy tools/message-profile.yaml into the target project's outputs/tools/ or equivalent tool config location.
4. For active sessions, create outputs/sessions/<session_id>/status.md, summary.md, and audit.md following ADR 022 and ADR 023.
5. Use examples/ as sample output, not as canonical state.

Implemented Tooling

Implemented helpers:

zynk compose reads the embedded message profile and generates:

• human prefix,
• structured header,
• required type-specific fields,
• short body templates.

zynk send herdr wraps message composition and sends the composed message through herdr pane run. Use --dry-run to print without sending. As of v0.5 (ADR 029), passing --session-id audits the send by default: on a successful transport send zynk writes the sender audit (delivery_status=sent, verified_by=helper-tool) and persists the message into the corpus automatically — no separate zynk audit. --no-audit opts out; --no-db keeps the audit file-only.

zynk status writes ADR 022 rolling status files at outputs/sessions/<session_id>/status.md.

zynk audit appends ADR 023 audit records with SHA-256 payload hashes and previous_audit_id chain links.

zynk report records typed work telemetry events for the v1 dashboard feed (think, system, tool, plan, usage, diff, artifact, gate, and conflict).

zynk decide records typed operator decisions (gate, conflict, mode, interrupt, and redirect) with audited provenance.

zynk reveal reveals a retained payload only after writing an operator-verified reveal proof. Use --retain-custody on audited writes when a redacted payload must be revealable later.

zynk db serve serves the live DB-backed dashboard console. It is loopback by default; browser writes require --allow-writes.

zynk dashboard renders a point-in-time snapshot at outputs/dashboard.md. It uses .zynk/zynk.db when present and falls back to session status files.

Delivery proof matters: text printed by zynk compose or zynk send herdr --dry-run is only a draft. Record delivery_status=sent only after a real transport send or operator relay, and use delivery_status=drafted for message-shaped text that remained in the sender pane.

The current implementation uses Rust. The previous Python helper set is preserved at git tag python-v0.1-final; it is intentionally absent from main.

Run tests with:

cargo test

Transport Scope

The current profile targets herdr first because that is the observed transport. The protocol leaves room for tmux, chat, Slack, or other transports through stable agent_id, transport address fields, and transport_thread_id.