Etiquette

Govern agent-assisted engineering work with seats, evidence, and promotion gates. Local-first: your repo is the ledger, receipts are the proof, and no server ever sees your code.

When several coding agents (and humans) work the same repository, the hard part isn't running them — it's knowing who did what, on whose authority, and what proved it worked. Etiquette gives each participant a seat, each unit of work a task envelope, each completion a receipt, and each merge a promotion gate — all recorded as plain files and git history you can audit with tools you already trust.

The same records give your agents perfect recall: every decision, receipt, and state change is a citable, append-only entry — weeks later, any seat can read exactly what happened and why, instead of re-deriving it from a stale chat log.

Install & verify

npm install -g @etiquekit/etq
# etq, etiquette and etiquette-core land on PATH
etq doctor --project .

curl -fsSL https://etiquekit.com/install.sh | sh

Both channels verify integrity automatically — the installer checks every artifact against a pinned public key before anything executes, and npm checks the registry's integrity hash on install.

# fetch the manifest, signature, and key
curl -fsSLO https://etiquekit.com/releases/SHA256SUMS
curl -fsSLO https://etiquekit.com/releases/SHA256SUMS.sig
curl -fsSLO https://etiquekit.com/releases/etiquette-release-signing.pub.pem

# display the key's fingerprint
shasum -a 256 etiquette-release-signing.pub.pem

openssl dgst -sha256 -verify etiquette-release-signing.pub.pem \
  -signature SHA256SUMS.sig SHA256SUMS
shasum -a 256 -c SHA256SUMS

Quickstart — a governed workspace in five minutes

1. Provision the workspace. From your project repo:

   etq init --project .          # folders, journal, roster
   etq doctor --project .        # everything green before work

2. Bootstrap seats and tasks. One command creates repo-local state, seats, task envelopes, pickup docs, events, and runbooks:

   etq bootstrap local --project . --profile codex-cc-gemini --task-prefix APP

3. Register your agent CLI (explicit, never automatic — Etiquette refuses to silently modify agent configs):

   etq setup --target auto --project .   # or codex | claude-code | gemini

4. Take a seat and claim a task.

   etq join --seat dev-a --project .
   etq pickup --seat dev-a --task APP-001 --expect-project-id <id> --text

5. Work, then gate on evidence. The return check refuses "done" without proof:

   etq return check --task APP-001 --seat dev-a
   etq console board --project . --text     # the live task board

Concepts

Who did what? — the four identities

Authority model

Authority flows through leases: narrow, expiring permissions to spend an existing grant. Spend can nest, bounded — mint never nests. A child lease is a strict subset of its parent (shorter TTL, narrower scope, subset writes, inherited prohibitions). Children return evidence to their parent; the parent synthesizes one upstream receipt and stays accountable.

Receipts prove work.
Grants authorize consequential action.
Sessions bound execution noise.
Portals display and coordinate.
Execution returns evidence; it never mints authority.

CLI reference

etq and etiquette are the same binary; a bare-bones governance profile lives in etiquette-core. Every command takes --project <path>; most support --json.

Start here

Daily work

Views & readiness

Full surface: etq help · advanced: etq help advanced · minimal profile: etiquette-core help.

Field manuals new in 1.0.11

Shipped in the package under docs/ and templates/ — written from live multi-seat runs, including a cold external consumer's first-run reports.

Agents bootstrapped in 1.0.11+ also carry the Propulsion doctrine in their rendered AGENTS.md: never stop silently — state WORKING, GATED (present the decision card), or BLOCKED, and end every return with Next:.

Runbooks

etq init --project .
etq bootstrap local \
    --project . \
    --profile codex-cc-gemini \
    --task-prefix APP
etq doctor --project .

etq whereami --seat dev-a --task APP-001
etq pickup \
    --seat dev-a \
    --task APP-001 \
    --expect-project-id <id> --text

etq return check --task APP-001 --seat dev-a

# red? read the named missing evidence,
# produce it, re-run. Never hand-wave.

etq doctor --project .
etq diagnostics runner-glitch \
    --symptom "<text>"
etq diagnostics no-return \
    --task APP-001 --seat dev-a

For agents

Agent-facing quickstart lives at etiquekit.com/llms.txt — fetch it first. The short version:

Seat packs provision per-runtime integration explicitly: provision-seat claude-code · codex · gemini · ollama · openrouter. Note: agent harnesses may (correctly) block etq setup as self-modification — the operator runs setup, once, reviewably.