zynk 0.3.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

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

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