From bfbb619cd1e67b70b60d2dd28abb7d3157fe7569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A0=D0=BE=D0=B1=D0=BE=D1=82?= Date: Sun, 27 Sep 2026 23:56:11 +0200 Subject: [PATCH] =?UTF-8?q?0.1.1=20=E2=80=94=20coordination=20on,=20as=20t?= =?UTF-8?q?he=20family=20requires?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .claude/agent-sync.json guards the release surfaces and the three.js export snapshot; docs/AGENT_SYNC.md is generated from it (agent_sync.py setup → check: healthy) and linked from CLAUDE.md. The umbrella refused the member without a committed config. Gate: npm test OK; negatives 13/13; installer 11; evals; strict validate ×2. Co-Authored-By: Claude Opus 5.5 (1M context) --- .claude-plugin/marketplace.json | 2 +- .claude/agent-sync.json | 27 ++++++ CHANGELOG.md | 7 ++ CLAUDE.md | 6 ++ SKILL-CARD.md | 2 +- docs/AGENT_SYNC.md | 97 +++++++++++++++++++ package.json | 2 +- plugins/web3d-dev/.claude-plugin/plugin.json | 2 +- .../web3d-dev/skills/web3d-animation/SKILL.md | 2 +- .../web3d-dev/skills/web3d-assets/SKILL.md | 2 +- .../web3d-dev/skills/web3d-runtime/SKILL.md | 4 +- 11 files changed, 145 insertions(+), 8 deletions(-) create mode 100644 .claude/agent-sync.json create mode 100644 docs/AGENT_SYNC.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cd102f6..eb59e54 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "name": "web3d-dev", "displayName": "Web3D Dev", "description": "Three skills for realtime 3D on the web: the three.js WebGPU runtime with TSL, compute, post-processing and a WebGL2 fallback; the glTF asset pipeline from source to frame, with compression, budgets, sourcing and optional Asset Foundry ordering; and a 3D animation protocol covering rigs, clip conventions, blending, GPU and instanced animation, and reduced motion. Every API fact is pinned to a verified three.js release.", - "version": "0.1.0", + "version": "0.1.1", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93" diff --git a/.claude/agent-sync.json b/.claude/agent-sync.json new file mode 100644 index 0000000..c69effb --- /dev/null +++ b/.claude/agent-sync.json @@ -0,0 +1,27 @@ +{ + "backend": "fs", + "leaseTtlSeconds": 2700, + "renewIntervalSeconds": 300, + "gated": true, + "idRegisters": {}, + "guardedFiles": [ + "CHANGELOG.md", + "package.json", + ".claude-plugin/marketplace.json", + "plugins/*/.claude-plugin/plugin.json", + ".github/workflows/*.yml", + "test/validate.py", + "README.md", + "test/fixtures/three-exports.json" + ], + "claimTags": {}, + "gates": [], + "mirror": { + "enabled": false, + "sources": [] + }, + "mergeLog": { + "file": "docs/MERGES.md", + "retentionDays": 7 + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 77992d4..29b2d11 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## 0.1.1 — 2026-09-27 + +- Coordination on: `.claude/agent-sync.json` guards the release surfaces and the three.js + export snapshot, and `docs/AGENT_SYNC.md` is generated from it and linked from `CLAUDE.md`. + The family umbrella refuses a member whose coordination config is not committed — found + when this pack joined it. + ## 0.1.0 — 2026-09-27 First release. Three skills for realtime 3D on the web, split by the question each answers: diff --git a/CLAUDE.md b/CLAUDE.md index 774d556..ddbcc58 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,3 +36,9 @@ All green or the change does not land. - **Prose is English.** Russian survives only inside trigger phrases. - **Asset Foundry is described, never advertised.** It is an optional private service: detect, delegate, or work by its principles — never tell a user to install it. + +## Coordination + +`docs/AGENT_SYNC.md` — generated from `.claude/agent-sync.json`, describing how coordination +is wired here and which files are guarded. Regenerate with `agent_sync.py setup`; never +hand-edit it. diff --git a/SKILL-CARD.md b/SKILL-CARD.md index 4be8d8a..7557e16 100644 --- a/SKILL-CARD.md +++ b/SKILL-CARD.md @@ -5,7 +5,7 @@ | Field | Value | |---|---| | Pack | `web3d-dev` | -| Version | `0.1.0` | +| Version | `0.1.1` | | Skills | `web3d-runtime`, `web3d-assets`, `web3d-animation` | | License | MIT | | Source | https://github.com/ssheleg/web3d-dev | diff --git a/docs/AGENT_SYNC.md b/docs/AGENT_SYNC.md new file mode 100644 index 0000000..1314662 --- /dev/null +++ b/docs/AGENT_SYNC.md @@ -0,0 +1,97 @@ + + +# How documentation and coordination work in web3d-dev + +This file is **generated** from the live configuration. If it disagrees with +what the tool does, the tool is right and this file is stale — regenerate it. + +## Two documentation sources + +| Source | Answers | Where | +|---|---|---| +| Git documents | *how it should be* — intent, decisions, contracts | this repository | +| As-built record | *how it actually is* — what agents wrote, with commits | the coordination plane | + +Neither outranks the other; they answer different questions. **The gap between +them is the finding.** Reconcile before starting a task and after finishing it. + +## This project's wiring + +- record plane: **fs** · lease: **local** — exclusive on this machine, advisory across machines · runs recorded **ungated** +- lease TTL 2700s, renewed every 300s +- credentials read from `(none found)` — gitignored, never committed + +### Id registers — reserve before you write + +None declared here. Ids live in the parent repository; reserve them there. + +### Guarded files — a live lease is required to write these + +- `CHANGELOG.md` +- `package.json` +- `.claude-plugin/marketplace.json` +- `plugins/*/.claude-plugin/plugin.json` +- `.github/workflows/*.yml` +- `test/validate.py` +- `README.md` +- `test/fixtures/three-exports.json` + +### Gates run before a change is considered done + +- none configured + +### Mirrored into the plane (read-only rendering of git) + +- disabled + +## What is written where, and what is never deleted + +| Information | Home | Lifetime | +|---|---|---| +| Decisions, specs, contracts, user-facing behaviour | git | permanent, append-only register | +| What was actually built, with its commit | as-built log | permanent, append-only | +| Cross-repo dependency state | signal log | permanent, append-only | +| Who holds a task right now | claims log | expires by TTL | +| A lock left by a run that stopped | the lease directory | until it is reported and reaped | +| Per-run narrative | that run's journal | permanent | +| The board and these pages | generated | replaced on every regeneration | + +**Nothing in a log is edited or deleted.** A mistake is corrected by appending +the correcting entry, because the logs are replayed in order and a deletion +would silently rewrite a decision every other agent already read. A lease is +released, never removed. A reserved id that is not used is returned with +`release-id`, which appends — it does not erase. + +Generated pages are the exception: they are rewritten wholesale, and a page +whose first line lost its generated marker is **refused**, not overwritten. + +## The cycle, per task + +``` +merges → what landed while you were away +status → who else is working, and what changed since you last looked +reconcile → resolve every divergence BEFORE writing code +branch → work happens on one; the integration branch is somebody + else's stable base +acquire ID → take the lease. On the integration branch the claim tag is + written through to git; on any other branch the holder stays + in the coordination plane, where `status` shows it to everyone + … work … +record → what you ACTUALLY built, with the decision id and files + … update the git documents in the same change … +reconcile → check both sides again +board → regenerate the shared view +merge --key → land the branch: conflicts checked first, the merge recorded, + that lease released. Without a branch, `release ID` by hand + — on every path, including failure +residue → what this run leaves on disk. Expiry ends a lease and leaves + the file, so `status` and `finish` enumerate them; `reap` + clears only what THIS run can prove it owns and has spent, + and reports foreign or ambiguously owned locks untouched +``` + +This project's integration branch is `main`. + +Full doctrine ships with the skill: `references/two-sources.md`, +`references/lease-protocol.md`, `references/branching.md`, +`references/roadmap.md`, `references/pipeline-binding.md`. diff --git a/package.json b/package.json index 2ab7b80..a6c8d49 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@ssheleg/web3d-dev", - "version": "0.1.0", + "version": "0.1.1", "description": "Three skills for realtime 3D on the web: the three.js WebGPU runtime with TSL, compute, post-processing and a WebGL2 fallback; the glTF asset pipeline from source to frame, with compression, budgets, sourcing and optional Asset Foundry ordering; and a 3D animation protocol covering rigs, clip conventions, blending, GPU and instanced animation, and reduced motion. Every API fact is pinned to a verified three.js release.", "bin": { "web3d-dev": "bin/web3d-dev.js" diff --git a/plugins/web3d-dev/.claude-plugin/plugin.json b/plugins/web3d-dev/.claude-plugin/plugin.json index 8c53a40..ad83fb2 100644 --- a/plugins/web3d-dev/.claude-plugin/plugin.json +++ b/plugins/web3d-dev/.claude-plugin/plugin.json @@ -3,7 +3,7 @@ "name": "web3d-dev", "displayName": "Web3D Dev", "description": "Three skills for realtime 3D on the web: the three.js WebGPU runtime with TSL, compute, post-processing and a WebGL2 fallback; the glTF asset pipeline from source to frame, with compression, budgets, sourcing and optional Asset Foundry ordering; and a 3D animation protocol covering rigs, clip conventions, blending, GPU and instanced animation, and reduced motion. Every API fact is pinned to a verified three.js release.", - "version": "0.1.0", + "version": "0.1.1", "author": { "name": "ssheleg", "url": "https://x.com/sshlg93" diff --git a/plugins/web3d-dev/skills/web3d-animation/SKILL.md b/plugins/web3d-dev/skills/web3d-animation/SKILL.md index 43a9512..4eb48fa 100644 --- a/plugins/web3d-dev/skills/web3d-animation/SKILL.md +++ b/plugins/web3d-dev/skills/web3d-animation/SKILL.md @@ -18,7 +18,7 @@ compatibility: >- needed to call motion verified — without one the verdict is NOT_RUN, never PASS. metadata: author: ssheleg - version: "0.1.0" + version: "0.1.1" --- # web3d-animation — decide how it moves, then make both halves agree diff --git a/plugins/web3d-dev/skills/web3d-assets/SKILL.md b/plugins/web3d-dev/skills/web3d-assets/SKILL.md index 19ef6f9..baefe06 100644 --- a/plugins/web3d-dev/skills/web3d-assets/SKILL.md +++ b/plugins/web3d-dev/skills/web3d-assets/SKILL.md @@ -18,7 +18,7 @@ compatibility: >- Asset Foundry is optional: detected through its foundry_* MCP tools or its skill, never assumed. metadata: author: ssheleg - version: "0.1.0" + version: "0.1.1" --- # web3d-assets — from a source to the frame, within a budget someone wrote down diff --git a/plugins/web3d-dev/skills/web3d-runtime/SKILL.md b/plugins/web3d-dev/skills/web3d-runtime/SKILL.md index cdb8d57..6825c2c 100644 --- a/plugins/web3d-dev/skills/web3d-runtime/SKILL.md +++ b/plugins/web3d-dev/skills/web3d-runtime/SKILL.md @@ -18,7 +18,7 @@ compatibility: >- visual result verified; without one the verdict is NOT_RUN. metadata: author: ssheleg - version: "0.1.0" + version: "0.1.1" --- # web3d-runtime — the scene runs, on every GPU it meets, and you can prove how fast @@ -122,4 +122,4 @@ Choose the rung per scene, top down; every rung must still be a working page. Asset files and budgets are `web3d-assets`; making things move is `web3d-animation`. The public `webgpu-threejs-tsl` skill (dgreenheck) informed the gotcha-first shape of this one; -several of its examples are exactly the silent failures listed above. +the errata found when re-verifying its examples against r186 are among the gotchas above.