docs/protocol.md

Use the Clankie Protocol Without Clankie

The first adoption tier is the protocol: Clankie's way of coordinating agents as visible, named Herdr panes with a lead/worker split and harvestable completion sentinels. It does not require the Clankie brain, relay, iOS app, or bundled stage.

flowchart LR
  repo["your repo<br/>AGENTS.md block"] --> lead["lead pane<br/>clankie-lead skill"]
  lead --> stage["Herdr<br/>your terminal stage"]
  stage --> w1["clankie:docs<br/>worker pane"]
  stage --> w2["clankie:tests<br/>worker pane"]
  w1 --> result1["result.md<br/>DONE/BLOCKED"]
  w2 --> result2["result.md<br/>DONE/BLOCKED"]
  result1 --> lead
  result2 --> lead

Install

Run the protocol-only installer:

npx create-clankie --protocol

It renders these five skills into the Claude, Agents, and Codex skill roots:

herdr
clankie-lead
clankie-worker
clankie-consultant
clankie-work-tracker

It also writes the canonical paste block to ~/.clankie/protocol/AGENTS.md and prints it. Paste that block into a repository AGENTS.md when you want agents in that repo to follow the protocol.

Re-run the same command when policy environment variables change. The installer only overwrites skill directories it generated; it refuses to replace an existing real or symlinked skill directory unless the directory carries the protocol-generated marker.

Remove generated protocol skills with:

npx create-clankie --protocol-uninstall

Preferences

The renderer reads the same flat behavior-policy namespace used by full Clankie:

Variable	Values	Effect
`CLANKIE_POLICY_PR_ONLY`	`on` / `off`	Adds or removes PR-only delivery instructions.
`CLANKIE_POLICY_MERGE_AUTHORITY`	`auto` / `human`	Controls whether rendered guidance allows autonomous merge.
`CLANKIE_POLICY_DESIGN_GATE`	`on` / `off`	Adds design-work routing guidance.
`CLANKIE_POLICY_PR_GRANULARITY`	`per_issue`, `per_batch`, `per_epic`, `unset`	Adds PR grouping preference text.

Equivalent flags are available for one-off renders:

npx create-clankie --protocol --policy approval
npx create-clankie --protocol --policy-pr-only off
npx create-clankie --protocol --policy-merge-authority human

The default preset is autonomous: PR-only on, merge authority auto, design gate off.

Capability Renders

Protocol-only renders assume there is no clankie CLI. The generated skills use raw Herdr commands for reading, messaging, spawning, waiting, and harvesting. They also state what is missing: no Clankie transcript helper, no clankie msg sender stamping, and no Clankie watcher wake.

When the full product is present, render Tier 3 helper text with:

npx create-clankie --protocol --protocol-with-clankie-cli

That render includes the clankie transcript, clankie msg, and clankie watch helpers and omits the Tier 1 fallbacks.

Operating Shape

The lead opens one Herdr tab per run and spawns one named pane per worker:

# Use the root for the harness you are running:
#   $HOME/.codex/skills/clankie-lead/scripts
#   $HOME/.claude/skills/clankie-lead/scripts
#   $HOME/.agents/skills/clankie-lead/scripts
OP="$HOME/.codex/skills/clankie-lead/scripts"
RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
"$OP/spawn.sh" --run "$RUN_ID" --slug docs-audit --task "Audit docs" \
  --harness codex --cwd "$PWD" --prompt "Audit the docs and report stale pages."

Each worker prompt gets a completion protocol appended. A worker finishes by writing result.md and creating either DONE or BLOCKED. The lead harvests:

"$OP/harvest.sh" "$RUN_ID" --results

Then the lead reviews the work, verifies evidence, updates the tracker, and cleans up the run tab:

"$OP/cleanup.sh" "$RUN_ID"

Stage Compatibility

Tier 1 uses public Herdr commands: pane list/read/run/send-*, tab create/list, agent start/get/list/read, and wait output/agent-status. That is the intended stock-Herdr surface.

Clankie's bundled clankie-herdr carries read-correctness fixes for heavy pane read patterns and product features such as native attach, retained rendering, and relay-facing session exposure. On stock Herdr, keep protocol reads modest and prefer explicit sentinels over scrollback polling. When you need the full receipt, wake-on-done, iOS window, or terminal mirror behavior, move up to the Clankie tier.

Upgrade Path

Protocol: rendered skills plus a repository AGENTS.md block.
Stage: use clankie-herdr as the terminal stage for Clankie's carried read and product patches.
Clankie: install the always-on lead, CLI, receipts, watcher, tracker, and relay.
Windows: add the Clankies iOS app, Discord, and other control surfaces.