@ssheleg/agent-sync 1.2.2

package/README.md

@@ -0,0 +1,389 @@
+# agent-sync
+
+[![CI](https://github.com/appvillis-com/agent-sync/actions/workflows/validate.yml/badge.svg)](https://github.com/appvillis-com/agent-sync/actions/workflows/validate.yml)
+[![npm](https://img.shields.io/npm/v/%40ssheleg%2Fagent-sync)](https://www.npmjs.com/package/@ssheleg/agent-sync)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Several coding agents, one repository, no collisions — and each one can see what the
+others are doing.**
+
+`agent-sync` is an agent skill (plus a Claude Code plugin) that gives concurrent
+coding agents a coordination plane: leases with a TTL, race-free id reservation, a run
+journal, a cross-repo signal feed and a generated board.
+
+- [The problem](#the-problem)
+- [What you get](#what-you-get)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Update](#update)
+- [Set up a project](#set-up-a-project)
+- [Everyday use](#everyday-use)
+- [Configuration](#configuration)
+- [Backends](#backends)
+- [Enforcement hooks](#enforcement-hooks)
+- [Where it plugs into task-pipeline](#where-it-plugs-into-task-pipeline)
+- [Limits, stated plainly](#limits-stated-plainly)
+- [Troubleshooting](#troubleshooting)
+- [Uninstall](#uninstall)
+- [Develop and verify](#develop-and-verify)
+
+## The problem
+
+When more than one agent works a project at the same time, the coordination substrate
+most teams already have — a decisions log, a roadmap, a board, per-repo task files —
+stops being enough. Every one of those is a file edited by hand. That works for people
+taking turns and fails for agents working at once:
+
+| What goes wrong | Why |
+|---|---|
+| Two agents mint the same decision id | "Next free id" is a line in a file; reading it is not reserving it |
+| A claim blocks a task forever | A role name is not a holder, and it has no expiry |
+| Two agents start the same task | Git shows what was committed, never what is in flight |
+| An agent is blocked but not informed | Knowing a task is taken is not knowing who has it or what they touch |
+| Merge conflicts on every shared register | Everyone writes the same three files |
+| A cross-repo dependency is never noticed | Filing one notifies nobody |
+
+`agent-sync` closes exactly those, and nothing else.
+
+## The idea
+
+> **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, so your single-source-of-truth rules stay intact.
+
+**The knowledge base never decides a lease.** It cannot: measured against a real
+instance, twelve concurrent appends to one document returned twelve successes and left
+three lines. Exclusion comes from something that genuinely has compare-and-swap — an
+atomic file create on one machine (`leaseBackend: "local"`), or a pushed git ref across
+machines (`leaseBackend: "git"`), where the remote's non-fast-forward rejection *is* the
+CAS. Id reservation still replays the log, which is safe because allocation is positional
+and every reader computes the same answer.
+
+## What you get
+
+- **Leases with a TTL** — claim a task, renew automatically, steal an expired one.
+  Exclusive across machines with `leaseBackend: "git"`; the tool always states which
+  guarantee you have rather than implying the stronger one.
+- **The claim written through to the roadmap** — one row, one cell, refused on ambiguity,
+  and restored verbatim on release. Closing a task stays yours.
+- **Awareness, not just exclusion** — `status` lists every *other* run's live holdings,
+  so an agent learns who holds a task and what they are touching, instead of only that
+  it is taken.
+- **Race-free id reservation** — positional allocation over the log, so two agents
+  cannot be handed one number.
+- **A run journal** — what each run did, with commits, gate results and evidence.
+- **A cross-repo signal feed** — `filed → accepted → delivered → closed`. `status`
+  surfaces what landed since this run last looked, watermarked per run so it stays quiet
+  until something actually changes.
+- **A generated board** — machine-written, commit-stamped, and it refuses to overwrite a
+  page a human took over.
+- **Enforcement hooks** for Claude Code that deny an edit to a guarded register file, or
+  a commit staging one, without a live lease.
+
+## Requirements
+
+| Requirement | Why | Check |
+|---|---|---|
+| **python3 ≥ 3.9** | the coordinator is one stdlib-only script — HTTP included, nothing to `pip install` | `python3 --version` |
+| **git** | the record plane, and the cross-machine lease store | `git --version` |
+| **bash** | the four Claude Code hook scripts | `bash --version` |
+| **Node ≥ 18** | only for the `npx @ssheleg/agent-sync` installer | `node --version` |
+| **[task-pipeline](https://github.com/ssheleg/task-pipeline)** | `agent-sync` supplies stages, it does not define them — without it `status` prints one line and stops | `npx sshlg-skills install` |
+| A knowledge-base instance *(optional)* | the shared record, awareness and board; without one the `fs` backend keeps leases but loses cross-agent visibility | — |
+
+## Install
+
+```bash
+npx @ssheleg/agent-sync install
+```
+
+Claude Code gets the plugin; every other agent gets the skill through the
+[skills CLI](https://github.com/vercel-labs/skills). The duplicate plain copy in
+`~/.claude/skills/` is pruned afterwards, because that shadow silently serves a stale
+skill over the installed plugin — **one channel per agent** is the rule.
+
+Restart Claude Code after installing, so it picks the plugin up.
+
+<details>
+<summary>Other install routes</summary>
+
+Track `main` from GitHub instead of the npm release:
+
+```bash
+npx github:appvillis-com/agent-sync install
+```
+
+Claude Code only, no skills CLI:
+
+```bash
+npx @ssheleg/agent-sync install --claude-only
+```
+
+Pick which agents the skills CLI installs for:
+
+```bash
+npx @ssheleg/agent-sync install --agent cursor,codex
+```
+
+Or add the plugin by hand — the full `<name>@<name>` form is required:
+
+```bash
+claude plugin marketplace add appvillis-com/agent-sync && claude plugin install agent-sync@agent-sync
+```
+
+</details>
+
+## Update
+
+**agent-sync itself** — update every channel you installed, then restart Claude Code:
+
+```bash
+claude plugin marketplace update agent-sync && claude plugin update agent-sync@agent-sync && npx --yes skills update agent-sync --global --yes
+```
+
+Re-running the installer works too, but pin `@latest` or npx may serve you its cache:
+
+```bash
+npx @ssheleg/agent-sync@latest install
+```
+
+Check what you are actually running — the plugin and the skill must report the same
+version, and a mismatch means one channel is stale:
+
+```bash
+claude plugin list | grep agent-sync
+python3 ~/.claude/plugins/cache/*/agent-sync/*/skills/agent-sync/scripts/agent_sync.py --version
+```
+
+**Its dependencies** — `task-pipeline` (and the rest of the same family) come from one
+installer, which also prunes the shadow copies:
+
+```bash
+npx sshlg-skills install
+```
+
+Nothing else to update: the coordinator is stdlib-only python, and the npm package has
+zero runtime dependencies.
+
+## Set up a project
+
+**Initialisation is the first command, and it asks a question rather than guessing.**
+
+```
+/agent-sync init
+```
+
+The agent asks where coordination state should live — a knowledge cloud, or local files
+— and, for the cloud, the instance URL. Then it writes two files:
+
+| File | Holds | Committed? |
+|---|---|---|
+| `.claude/agent-sync.json` | **shape** — backend, TTLs, guarded files, registers, gates | yes |
+| `.env.agent-sync` | **identity** — instance URL, token, collection id | **no** — mode 600, added to `.gitignore` |
+
+The token line is written **empty**. Creating the API token in your own instance and
+pasting it into that line is your step, and it stays yours: the tool never asks for a
+token in chat, never echoes one, and never passes one as a command-line argument.
+
+Load the environment before running agents:
+
+```bash
+set -a && . ./.env.agent-sync && set +a
+```
+
+Then create the container the coordination log lives in, once per project, and paste the
+id it prints into `AGENT_SYNC_OUTLINE_COLLECTION`:
+
+```bash
+/agent-sync bootstrap
+```
+
+Verify the setup — idempotent, repairs what is missing, and names exactly one next
+action:
+
+```bash
+/agent-sync status
+```
+
+## Everyday use
+
+In an agent session you use the slash command (`/agent-sync claim ASC-072`); the same
+commands run directly against the coordinator script, which is what the hooks and CI do:
+
+```bash
+python3 "$SKILL_DIR/scripts/agent_sync.py" <command>
+```
+
+| Command | Does |
+|---|---|
+| `init` | **Run first.** Ask where state lives, write config + gitignored env file, print your step |
+| `status` | Inspect, repair, report — including other runs' leases and signals new since you last looked |
+| `bootstrap` | Create the cloud container and print the id to paste into the env file |
+| `acquire <KEY>` | Take the lease on a task id. Prints `won`, or `lost <holder>` |
+| `renew <KEY>` | Extend the lease. In Claude Code the `PostToolUse` hook does this for you |
+| `release <KEY>` | Give the lease back. Always, including on failure |
+| `reserve <REG>` | Reserve the next id in a register (`DEC`, `OQ`, `DEP`, …). Prints the id |
+| `release-id <REG> <ID>` | Return an id you did not end up writing to git |
+| `journal <text>` | Append one line to this run's journal |
+| `signal <DEP-ID> <state>` | Move a cross-repo dependency: `filed`/`accepted`/`delivered`/`closed`/`refused` |
+| `guard <path>` | May this run write that path? Exit 0 = yes, 2 = no |
+| `board` | Regenerate the read-only board and the mirror from git |
+| `whoami` | Print this run's id and its held leases |
+
+The shape that matters:
+
+```
+acquire → do the work → release
+```
+
+Never skip `release`, including when the work failed. An abandoned lease blocks the task
+until its TTL expires, and the next agent cannot tell "in progress" from "crashed an hour
+ago". A lease is a promise to come back.
+
+**The lease is not the claim.** The lease says who holds the task *now* and expires; the
+durable claim is the tag in git (`[name]`, `todo (claimed: <role>)`). `acquire` writes
+that tag through and `release` clears it, so one fact keeps one home.
+
+## Configuration
+
+`.claude/agent-sync.json` — committed, validated against
+[`agent-sync.schema.json`](agent-sync.schema.json), starting point in
+[`agent-sync.example.json`](agent-sync.example.json):
+
+| Key | Meaning |
+|---|---|
+| `backend` | `outline` or `fs` (required) |
+| `leaseTtlSeconds` | how long a lease survives without a renew (default 2700) |
+| `renewIntervalSeconds` | how often a live run renews (default 300) |
+| `gated` | whether runs may be recorded as enforced at all |
+| `idRegisters` | register → the git file that owns it, and its "next free id" pattern |
+| `guardedFiles` | registry files no run may edit without a live lease |
+| `claimTags` | file → the durable claim tag `acquire`/`release` writes through |
+| `gates` | commands the pipeline stages run as gates |
+| `mirror` | which git files are rendered into the read-only mirror |
+
+`.env.agent-sync` — gitignored, mode 600:
+
+```
+AGENT_SYNC_BACKEND=outline
+AGENT_SYNC_OUTLINE_URL=https://<your-instance>
+AGENT_SYNC_OUTLINE_TOKEN=          # you fill this line, nobody else
+AGENT_SYNC_OUTLINE_COLLECTION=     # printed by `bootstrap`
+```
+
+Never write a host name or a token into the config, a test, an example or a commit. If
+an agent offers to handle a token for you, that is the wrong answer.
+
+**A submodule's config declares only its own registers.** Cross-repository facts belong
+to the parent repository; a service repo listing the parent's decision register is a
+configuration defect.
+
+## Backends
+
+The knowledge store is a **pluggable adapter** — six primitives, three declared
+capabilities. Nothing about a specific vendor is baked in, and no instance address ships
+in this repository.
+
+| Backend | Lease authority | Notes |
+|---|---|---|
+| `outline` | yes | [Outline](https://www.getoutline.com), hosted or self-hosted. Server-side append gives a total order without compare-and-swap |
+| `fs` | no — **degraded** | Local files. Real mutual exclusion between agents on one machine, none across machines. Every run is recorded `ungated` |
+
+**A backend that cannot arbitrate says so.** When the adapter is not the lease authority,
+`agent-sync` announces it, falls back to git-file leases, and marks runs `ungated` —
+because a lease that is not actually exclusive is worse than none, and the other agent
+has stopped checking.
+
+Adding one: read
+[`references/adapter-contract.md`](plugins/agent-sync/skills/agent-sync/references/adapter-contract.md).
+
+## Enforcement hooks
+
+Installed with the Claude Code plugin. Every hook exits immediately in projects without
+`.claude/agent-sync.json`, so installing globally changes nothing elsewhere.
+
+| Hook | Runs | Effect |
+|---|---|---|
+| `SessionStart` | startup, resume | `status` — the board summary, other runs, one next action |
+| `PreToolUse` | `Edit`/`Write`/`MultiEdit`/`NotebookEdit`, and `git commit` | Denies the edit (exit 2) when the path is guarded and this run holds no lease; a `git commit` is checked against every staged path |
+| `PostToolUse` | every tool call | Throttled `renew` — touches the network at most once per `renewIntervalSeconds` |
+| `SessionEnd` | session end | Releases every lease this run holds |
+
+Details and removal:
+[`references/hooks.md`](plugins/agent-sync/skills/agent-sync/references/hooks.md).
+
+## Where it plugs into task-pipeline
+
+`agent-sync` supplies stages; it does not define them. It binds to task-pipeline's
+stages 0, 3, 4, 5, 9 and 10 — lease before the brief is committed, reserve ids before
+they reach git, register file ownership for parallel groups, signal and regenerate the
+board at docs, release everything at acceptance. Wiring:
+[`references/pipeline-binding.md`](plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md).
+
+## Limits, stated plainly
+
+- **Hooks are Claude Code only.** On Cursor, Codex and the rest there is no `PreToolUse`,
+  so nothing blocks a guarded edit; the same checks run as a self-check and the run is
+  recorded `ungated`. Read the board's column rather than assuming.
+- **Ordering, not clocks.** Document order decides who holds a lease; timestamps only
+  expire one. Agents' clocks differ and the protocol does not depend on them.
+- **A reserved id that never reaches git is reported, not reclaimed.** A half-written
+  decision on a branch is not an unused number.
+- **`fs` is not cross-machine.** It is a real mutex between agents on one host and
+  nothing more, which is why it never claims lease authority.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `task-pipeline is not installed` and `status` stops | Intentional — there are no stages to bind to. `npx sshlg-skills install` |
+| `⚠ ungated backend — this lease is advisory` | The `fs` backend, or missing credentials. Expected; configure `outline` for enforced leases |
+| Every `acquire` reports `lost` | Check the holder in `status`. If the log itself is unreadable, `acquire` raises instead — that is a parse failure, not a race |
+| Guarded edit blocked in Claude Code | Working as designed: `acquire` the key first, or unstage the file |
+| Guarded edit *not* blocked | You are not on Claude Code. Run `guard <path>` yourself; the run is `ungated` |
+| `AGENT_SYNC_OUTLINE_COLLECTION is not set` | Run `bootstrap` and paste the printed id into `.env.agent-sync` |
+| An HTTP `400`/`403` from the backend | The response body is surfaced verbatim — read it; a bad collection id and a bad token look nothing alike |
+| A stale skill after updating | Two channels serving one skill. Delete `~/.claude/skills/agent-sync` and keep the plugin |
+| The board refuses to write | A human took the page over (no generated marker on line 1). Reported, never overwritten |
+
+## Uninstall
+
+```bash
+claude plugin uninstall agent-sync@agent-sync
+npx --yes skills remove agent-sync --global --yes
+```
+
+Project files stay where they are; delete `.claude/agent-sync.json`, `.env.agent-sync`
+and `.agent-sync/` if you want the project clean too.
+
+## Develop and verify
+
+```bash
+python3 test/validate.py             # manifests, version sync, no host/credential leaks
+python3 test/validate.py --self-test # the validator must still be able to fail
+npm test                             # both of the above
+```
+
+What ships: one skill (`agent-sync`), `scripts/agent_sync.py` (stdlib only), four hook
+scripts, the slash command, `agent-sync.schema.json`, and eight reference contracts the
+agent loads on their own trigger rather than by default:
+
+| Reference | Read it when |
+|---|---|
+| [`adapter-contract.md`](plugins/agent-sync/skills/agent-sync/references/adapter-contract.md) | adding or auditing a knowledge backend |
+| [`lease-protocol.md`](plugins/agent-sync/skills/agent-sync/references/lease-protocol.md) | changing acquisition, expiry, stealing or id allocation |
+| [`backend-outline.md`](plugins/agent-sync/skills/agent-sync/references/backend-outline.md) | making any Outline API call, or debugging one |
+| [`backend-fs.md`](plugins/agent-sync/skills/agent-sync/references/backend-fs.md) | running without a cloud backend, or explaining degraded mode |
+| [`pipeline-binding.md`](plugins/agent-sync/skills/agent-sync/references/pipeline-binding.md) | wiring `pipeline.json`, or adding a stage hook |
+| [`hooks.md`](plugins/agent-sync/skills/agent-sync/references/hooks.md) | installing, debugging or removing the Claude Code hooks |
+| [`two-sources.md`](plugins/agent-sync/skills/agent-sync/references/two-sources.md) | before the first reconcile, or when deciding where a document belongs |
+| [`roadmap.md`](plugins/agent-sync/skills/agent-sync/references/roadmap.md) | configuring `claimTags`, taking or closing a task, or re-planning a board |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Security
+reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT © Appvillis

package/agent-sync.example.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://raw.githubusercontent.com/appvillis-com/agent-sync/main/agent-sync.schema.json",
+  "backend": "outline",
+  "leaseTtlSeconds": 2700,
+  "renewIntervalSeconds": 300,
+  "gated": true,
+  "idRegisters": {
+    "DEC": {
+      "file": "docs/DECISIONS.md",
+      "nextFreeIdPattern": "\\*\\*Next free ID:\\*\\* `DEC-(\\d{4})`"
+    },
+    "OQ": {
+      "file": "docs/OPEN_QUESTIONS.md",
+      "nextFreeIdPattern": "\\*\\*Next free ID:\\*\\* `OQ-(\\d{4})`"
+    }
+  },
+  "guardedFiles": [
+    "docs/DECISIONS.md",
+    "docs/OPEN_QUESTIONS.md",
+    "docs/ROADMAP.md"
+  ],
+  "claimTags": {
+    "docs/ROADMAP.md": {
+      "mode": "cell",
+      "cell": -1,
+      "held": "{prev} (claimed: {holder})"
+    }
+  },
+  "gates": [
+    "bash scripts/check-docs.sh"
+  ],
+  "mirror": {
+    "enabled": true,
+    "sources": [
+      "docs/DECISIONS.md",
+      "docs/ROADMAP.md"
+    ]
+  },
+  "leaseBackend": "git"
+}

package/agent-sync.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/appvillis-com/agent-sync/main/agent-sync.schema.json",
+  "title": "agent-sync project configuration",
+  "description": "Shape only. Identity (instance URL, token, container id) lives in .env.agent-sync and is never committed.",
+  "type": "object",
+  "required": [
+    "backend"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "backend": {
+      "type": "string",
+      "enum": [
+        "outline",
+        "fs"
+      ],
+      "description": "Which adapter holds coordination state. 'fs' is degraded: not the lease authority across machines."
+    },
+    "leaseTtlSeconds": {
+      "type": "integer",
+      "minimum": 60,
+      "default": 2700
+    },
+    "renewIntervalSeconds": {
+      "type": "integer",
+      "minimum": 30,
+      "default": 300
+    },
+    "gated": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether runs may be reported as enforced. Effective only when the backend is the lease authority."
+    },
+    "idRegisters": {
+      "type": "object",
+      "description": "Registers whose next free id must be reserved before it is written to git.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "file",
+          "nextFreeIdPattern"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Repo-relative path to the register file."
+          },
+          "nextFreeIdPattern": {
+            "type": "string",
+            "description": "Regex with one capture group holding the next free number."
+          }
+        }
+      }
+    },
+    "guardedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Glob patterns that require a live lease before being written. A submodule lists only its own registers; cross-repository files belong to the parent repository."
+    },
+    "claimTags": {
+      "type": "object",
+      "description": "How a lease is written through to the roadmap. See references/roadmap.md.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "mode"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "cell"
+            ],
+            "description": "'cell' edits one cell of the single table row containing the task id."
+          },
+          "cell": {
+            "type": "integer",
+            "description": "0-based cell index in that row; negative counts from the end."
+          },
+          "held": {
+            "type": "string",
+            "description": "Template for the held value. {prev} is the current cell text, {holder} the run id."
+          }
+        }
+      }
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Shell commands run at the pipeline's lint stage; each result is journaled."
+    },
+    "mirror": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Files or directories rendered one-way into the knowledge store, stamped with the source commit."
+        }
+      }
+    },
+    "setupFile": {
+      "type": "string",
+      "description": "Where the generated setup snapshot is written. Defaults to docs/AGENT_SYNC.md when docs/ exists, else AGENT_SYNC.md."
+    },
+    "leaseBackend": {
+      "type": "string",
+      "enum": [
+        "local",
+        "git"
+      ],
+      "default": "local",
+      "description": "Where a contended lease is decided. 'local' is an atomic file create \u2014 exclusive between processes on one filesystem. 'git' pushes a ref, and the remote's non-fast-forward rule is a real compare-and-swap, exclusive across machines."
+    },
+    "leaseRemote": {
+      "type": "string",
+      "default": "origin",
+      "description": "Git remote holding the lease refs when leaseBackend is 'git'."
+    },
+    "settleSeconds": {
+      "type": "number",
+      "minimum": 0,
+      "default": 3.0,
+      "description": "Unused by the git and local backends; retained for adapters that must wait for writes to become visible."
+    }
+  }
+}