Agent Sync

agent-sync — one project, many agents, no collisions

Two planes, and one rule between them:

Git is the record plane. The cloud is the coordination plane. A fact that must survive is written to git first and referenced from the cloud. A fact about who is doing what right now lives in the cloud and expires.

No cloud object is ever the only home of a durable fact. Everything below exists to keep that true while several agents write at once.

Four traps — read these before anything else

1. The knowledge base never decides a lease. It cannot: twelve concurrent appends to one Outline document returned twelve successes and left three lines. Exclusion comes from something with real compare-and-swap. The plane carries the record and nothing else.

2. Know which lease you have, and say so. leaseBackend: "local" is an atomic file create — exclusive between processes on one filesystem, advisory across machines. leaseBackend: "git" pushes a ref, and the remote's non-fast-forward rejection is a compare-and-swap — exclusive across machines. acquire prints which. A pretended lease is worse than no lease: the other agent stops checking.

acquire also writes the claim through to the roadmap, and release restores exactly what was there — one row, one cell, refused on ambiguity, git diff empty after a round-trip. Read references/roadmap.md before configuring claimTags or closing a task; closing is a statement about the work and stays yours.

Work on a branch; the integration branch is somebody else's stable base. acquire writes the claim through only there — on any other branch the holder stays in the coordination plane, where status shows it to every agent. Committed to a branch, a claim is invisible until the merge and turns the shared roadmap into a file two branches both edit. Land work with merge: conflicts computed before anything is touched, the merge recorded in docs/MERGES.md, the --key lease released; merges says what landed while you were away. Read references/branching.md before merging.

3. Hooks exist only in Claude Code. Elsewhere nothing blocks a guarded edit: run guard yourself and record the run as ungated. A mode's five capability fields live in ONE place — references/adapter-contract.md → The status capability contract, never restated here. Do not describe a project as protected when it is not.

4. Parse liberally, and never call an unreadable log a lost race. The store rewrites what you wrote — Outline turns a - bullet into * . Emit - , accept -/*/+, count anything entry-shaped that fails, and fail loudly past 2% unparseable. Reporting lost when the truth is unreadable names a holder who does not exist. Watch for a silent pre-filter: a continue before the regex hides bad lines from the counter.

Bringing this into ANY project — the whole chain

scaffold  → create the documentation architecture, only where it is absent
adopt     → read the repository, propose a config, write nothing
init      → write the approved config + the gitignored env file
            (operator pastes the token — never you)
reconcile --set-baseline    → make history a counted backlog, once
setup     → generate the snapshot that describes this project's wiring
check     → validate the whole thing; non-zero if it is not healthy

check is what makes the skill self-sufficient. It refuses to call a setup healthy on a rule that protects nothing (a register, guard glob, claim pattern, gate or mirror source pointing at what is not there), on missing credentials, on an env file tracked by git — the one unrecoverable mistake here — on a stale snapshot, or on a register with no baseline. It names each one; every one failed for real during this tool's own adoption. Run it after adopting, after changing the config, and in CI.

scaffold never overwrites. It seeds a decision register and an AGENTS.md pointing at the snapshot, and leaves every existing file untouched.

Existing project: start with adopt

Run adopt before init. It reads the repository and prints what it found — id registers, registry files, gates — plus the decisions it refuses to make for you — then proposes a config.

python3 "$SKILL_DIR/scripts/agent_sync.py" adopt

Confirm the registers and guarded files with the operator first: a register pointed at the wrong file makes every later check confidently wrong, and a guarded list that misses a shared file leaves the one place collisions happen unprotected. In a submodule it declares no registers — decisions belong to the parent. Then take the chain above from init.

First command in a project: init

Never run anything else against an uninitialised project. init asks and answers the storage question once, and writes it down.

Ask the operator these two things in chat — do not guess, do not pick a default:

1. Where should coordination state live?

   • a knowledge cloud — outline, hosted or self-hosted, or notion — the shared record, awareness and board across machines — neither decides leases (trap 1);
   • or local files (fs) — no credentials, and no visibility to an agent on another machine — no shared awareness, cross-repo signal or board.

   The lease is decided separately by leaseBackend (trap 2), and gated follows that choice, never the record plane — report the guarantee you actually have.

2. If cloud: where. Outline needs its instance URL; Notion needs the id of the page the container goes under. Both are configuration, not secrets, so you may write them. The token is not — you never ask for it in chat, never read it back, and never place it yourself.

Then run it with their answers:

python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend outline --url https://<their-instance>
python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend notion
python3 "$SKILL_DIR/scripts/agent_sync.py" init --backend fs

init writes .claude/agent-sync.json (shape, committed) and .env.agent-sync with an empty token line (identity, mode 600), gitignores both, and prints the one step that is the operator's — creating the token and pasting it into that line. Never overwrites either file without --force. Relay those closing instructions verbatim; the design depends on the token staying theirs.

Then, before every session

python3 "$SKILL_DIR/scripts/agent_sync.py" status

Idempotent. Inspects, repairs, reports, names exactly ONE next action — and carries check's verdict, so the command every session runs and the one that validates the setup cannot give two answers about one project.

Read the two awareness sections it prints — they are the point, not decoration.

• Other runs working this project right now. Who holds what, this minute. Do not take those on, and do not "just look at" the files they cover.
• New since you last looked. Cross-repo dependency moves that landed while you were away — watermarked per run, so it stays quiet until something changes. A dependency that moved may unblock what you planned, or invalidate it.

status also decides: no credentials → degraded mode; task-pipeline absent → it prints the install line and stops. Absence is checked across every host layout or an explicit pipelinePath — no host's copy masks or is missed. The lease core (acquire/renew/release) needs a backend + lease, not the binding.

npx sshlg-skills install

The commands

$SKILL_DIR is this skill's own directory: ${CLAUDE_PLUGIN_ROOT}/skills/agent-sync under the Claude Code plugin, ~/.agents/skills/agent-sync elsewhere. Resolve it once per session and reuse it. Every command reads .claude/agent-sync.json from the project root and needs no arguments beyond those listed.

One identity per session, and how it is decided

A lease is only a lease if two agents get two identities, and both ends have bitten: CLAUDE_SESSION_ID alone gave one session two identities — it acquired as one and was denied by its own guard as the other — and one id per checkout gave two sessions one identity, silently, so release took a lease the caller never had.

The order is: AGENT_SYNC_RUN_ID · CLAUDE_SESSION_ID · the session that started this shell · shared. The third exists because a plain shell command has no session id and a hook does, so SessionStart stamps .agent-sync/sessions/<CLI pid> and a later command walks its own process ancestry to it. Why that and not command-line parsing: references/earned-rules.md.

When none of the four can be established the run says so — "this identity is shared with any other session in this checkout" — rather than presenting a shared entry as separation.

Claiming — the shape that matters

acquire → do the work → release

Never skip release, including on failure: an abandoned lease blocks the task until its TTL expires, and the next agent cannot tell "in progress" from "crashed an hour ago".

The lease is not the claim. The lease says who holds it now and expires; the durable claim is the tag in git, written through by acquire and cleared by release. One fact, one home — do not invent a third place that records ownership.

One notion of held, consulted by both planes. The TTL ends the lease, so a tag naming a run whose lease has ended is residue: reported by status, residue and reconcile, and cleared by release <KEY>, which says whose it was. A tag whose lease is still live is never touched by another run.

Read references/lease-protocol.md before changing acquisition, expiry, stealing or id allocation.

Guarded files

The config lists registry files several agents write. Before editing one:

python3 "$SKILL_DIR/scripts/agent_sync.py" guard docs/DECISIONS.md

Exit 2 is about this run: it holds no lease — not that somebody else holds that file. A denial names the other run and its key, because "r-x holds a lease" beside a path gets repeated as "r-x holds this file". Do not edit anyway, and do not "just fix one line" — a clobbered decision looks exactly like a decision.

Two write modes, and the tool does not promise the wrong one. A task lease authorizes the TASK, never the file — so a guarded write also takes the FILE's own resource claim (res--<repo>--<canonical path>, SY-04). That is the short transaction lock: two agents on one shared registry serialize on it, independent files never serialize, honest cross-machine only under leaseBackend: "git" (advisory otherwise). The other mode is isolated worktree + merge — each agent a private checkout, a merge policy reconciling them — for when writes overlap so heavily a lock would just queue everyone. What the guard does NOT promise is enforcement from a single task owner: holding a lease was never holding this file.

Claude Code's PreToolUse hook runs this for you. Elsewhere nothing does.

Reserving an id

Reading a "Next free ID" line is not reserving it — two agents read the same number and both use it.

python3 "$SKILL_DIR/scripts/agent_sync.py" reserve DEC   # → DEC-0216

Allocation is positional over the merged log — every shard, never just this run's — so every agent computes the same answer. Reserved and not written to git? release-id it, or the number is a hole the board reports as a leak.

Nothing in a log is ever edited or deleted

Logs are replayed in order, so an edit silently rewrites a conclusion other agents already acted on. Correct by appending: release a lease, release-id an unused id, supersede a wrong as-built entry with a later one. Generated pages are the only exception. Lifetimes and the generated-object contract: references/two-sources.md.

Two documentation sources, and the duty to reconcile them

Git docs answer how it should be; the as-built record answers how it actually is. Neither outranks the other, and the gap between them is the finding, not a defect. The duty runs at both ends of a task: reconcile before starting, record and reconcile after finishing — and reconcile is mechanical, so treating its green as agreement is how a divergence survives both ends.

Read references/two-sources.md before the first reconcile: it holds the full duty, what reconcile refuses to judge, the generated setup snapshot, where a document belongs, and why nothing is deleted.

Binding to task-pipeline

This skill supplies stages; the names are task-pipeline's own. Five of the eleven stages carry an ordering rule: 0 acquire before the brief commits; 1 reconcile before code; 3 reserve ids before git; 9 the main write; 10 merge/release every lease.

Read references/pipeline-binding.md when wiring pipeline.json — per-stage reasoning, skills[] entries, what to guard, and the gate expressions.

Configuration

Two files, and the split between them is the whole security model.

.claude/agent-sync.json — shape, committed: which backend, TTLs, which files are guarded, which registers exist, which gates to run.

.env.agent-sync — identity, written by init with the keys already in it, mode 600, gitignored. The operator fills the token line and nobody else; bootstrap prints the collection id to paste beside it. Found here, or in a superproject, or wherever AGENT_SYNC_ENV points — check prints which. Load it before running agents:

set -a && . ./.env.agent-sync && set +a

Never write a host name or token into the config, a test, an example or a commit; never handle, echo or argv-pass a token value. Offered one in chat, point at that file instead.

A submodule's config declares only its own registers. Cross-repository facts belong to the parent; a service repo listing the parent's decision register is a config defect.

Non-negotiables

• Append, read back, then act. Never rewrite a coordination document.
• A generated object without its agent-sync:generated marker is refused, not overwritten — a human took it over. Contract: references/two-sources.md.
• release what you acquire, on every path including failure.
• A run reports what it leaves behind: expiry ends a lease, not the file — residue.
• Credentials never reach argv, a log line, or the repository.
• Degrade out loud. ungated is an acceptable state; a false claim of enforcement is not.
• Two agents in one checkout are two identities, or the lease is decoration.
• A submodule commit is unfinished until the parent points at it — run finish.
• Everything the cloud holds about a durable fact is a link to git, never a substitute.
• Boundary: .claude/agent-sync.json. None, or one agent alone — route past. The operator's waiver: "no coordination" / «без координации».

References

Each file is loaded on its own trigger, not by default.

Missing references/? Fetch from https://raw.githubusercontent.com/ssheleg/agent-sync/main/plugins/agent-sync/skills/agent-sync/references/<file>.