zynk 1.0.1

Portable protocol and helper CLI for multi-agent collaboration.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# 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 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](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.

```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.

## 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:

```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`.