# 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
```text
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 024.
- Skill artifact: `skills/multi-agent-message-scaffolds/SKILL.md`.
- Tooling profile: `tools/message-profile.yaml` embedded into the `zynk` default profile.
- Dashboard prototype: `examples/dashboard.md` plus session examples under `examples/sessions/`.
- Executable helpers: `zynk compose`, `zynk send herdr`, `zynk status`, `zynk audit`, and `zynk dashboard` are implemented in Rust.
- Historical Python reference: available from git tag `python-v0.1-final`.
## Quickstart
Start with [QUICKSTART.md](QUICKSTART.md). It walks through the full helper flow: compose a message, dry-run/send via herdr, update rolling status, append an audit record, render a dashboard, and run tests.
## Install
Requires Rust stable and Cargo.
```bash
cargo build
```
The install exposes one command:
```bash
./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.
## Next Tooling Work
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 dashboard` renders a static ADR 022 aggregate dashboard at `outputs/dashboard.md` from 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:
```bash
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`.