zynk 1.1.0

Portable protocol and helper CLI for multi-agent collaboration.
zynk-1.1.0 is not a library.

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/audit examples + workflow-profile reference artifacts (examples/workflow-profiles/).

Current Status

  • Protocol decisions: accepted through ADR 037 (ADR 036 actor/role/trait + ADR 037 workflow-profiles are merged to main and publish in v1.1.0; v1.0.1 is the latest crates.io release).
  • 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, zynk assign, 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 assign (ADR 036) records a participant overlay so the dashboard roster is actor/role/trait aware in a 3+-agent workflow. Three orthogonal concepts ride one audited write (record_type=participant-overlay, a non-transport operator proof, never delivery_status=sent):

  • zynk assign actor-kind --subject <actor> --kind human|agent|external — the human operator is human, NOT an agent, and the roster renders it distinctly.
  • zynk assign role --subject <actor> --role-id <slug> --role-label "<free>" — roles are FULLY free-form and profile-defined; the machine never reasons over the role name (it is for human display only).
  • zynk assign trait --subject <actor> --trait <name> [--unset] — a small KNOWN integrity-trait vocabulary the machine DOES reason over: independent, can_edit_source, non_iterating, can_verify_gate, can_merge_approve.

The roster shows kind + role + trait badges, each carrying its asserter and asserted-at provenance. The honesty bound is STRUCTURAL, not authenticated identity: a trait is only honored when the proof-bound asserter is not the subject (no self-grant) and the proof is operator-grade (verified_by=operator, command_origin=operator, transport=none). zynk has no identity authentication, so the badge cites provenance and never implies an authenticated identity.

Workflow profiles (ADR 037) are a distribution-artifact layer — "out of core, not out of zynk". A workflow profile expresses a reusable, gated-verification multi-agent workflow (its roles, the role→integrity-trait mapping, and its gate sequence) by composing the existing verbs; it requires no core change and is a separate concept from the message/audit --profile. The repo ships a generic template and a sanitized reference instance under examples/workflow-profiles/, a deterministic reference script scripts/workflow-profile-smscode.sh, and the zynk-workflow-profiles skill. Every overlay a profile enacts stays operator-asserted; a profile declares roles freely but never invents a machine-reasoned trait (the trait vocabulary stays core and closed).

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.