A serializable, provenance-carrying handoff protocol for multi-agent / multi-worktree development. Compact one high-entropy session into a dense, durable seed; let many concurrent workers reconcile through git without lost updates; and make the gap between serialized (git-tracked) and advisory (everything else) state visible and enforceable.
License: MIT · Status: v0.1.0 (draft) · Runtimes: Node · Python · Rust · POSIX shell — all four verified against one shared conformance suite.
The belief-log's real output is not the decision — it's the trace elements of conviction: the faint markers of how a decision's conviction formed and moved.
In one line: durable, mergeable state across every boundary an agentic workflow crosses — cross-time, cross-session, cross-branch/worktree, cross-context, cross-environment, cross-agent. Git already solves order for tracked files; the belief-log solves it for understanding; the manifest solves it for the surfaces git can't lock.
An agentic dev session is high-entropy and ephemeral: a conversation, scratch files, several open worktrees, half-formed understanding. Almost none of it survives to the next session — and what's most portable is never the per-task deliverable, but the machinery that makes ephemeral sessions durable and mergeable. Two orthogonal axes:
Compact a session into a dense, durable seed a later session (or a different agent, or a human) can pick up cold. Three parts:
- manifest — what surfaces exist and whether they agree;
- belief-log — the append-only history of understanding (not of files);
- handoff — the compaction, with a head (forward pickup pointers: "next session starts here") and a tail (provenance/lineage: how we got here).
"The diamond reaching the cloud" is git push.
Many workers write at once and must reconcile to one agreed total order without lost updates. Git is the serializer — its non-fast-forward rejection is the write-lock. But that guarantee holds only for tracked files. Cloud docs, hosted artifacts, snapshots, dashboards have no such lock; a concurrent editor silently clobbers them. That gap — serialized (git-tracked) vs. advisory (everything else) — is the central hazard this toolkit surfaces.
| Primitive | What it is | Command |
|---|---|---|
| belief-log | append-only, OpenTelemetry-shaped JSONL that version-tracks understanding (trace/span/kind/confidence/risk/evidence/status) | belief validate · belief append |
| manifest | registry of every surface (canonical git SSOT + advisory projections), each stamped with a docset version | drift-check |
| handoff | coal→diamond compaction: head (pickup) + tail (lineage) | compact · pickup |
| serializability check | git is the serializer for tracked files; warn where advisory state escapes the lock | serializability · install-hooks |
A projection whose stamped docset is less than the manifest header is STALE
by definition — no content diff required. drift-check exits non-zero on any
drift, so it is a CI gate. See SPEC.md for the normative model.
# npm (Node CLI — bins: germinate, hl)
npm install -g germinate
# Homebrew (signed single binary — the Rust build)
brew install flashesofbrilliance/tap/germinate
# or vendor the zero-dep shell CLI directly
cp packages/shell/hl.sh /usr/local/bin/hl && chmod +x /usr/local/bin/hlNothing is hosted. There is no server, no Vercel config, no database — it's a CLI + file-format + library. The least-invasive, highest-leverage install is a local git hook; the team gate is a GitHub Action. See
docs/INTEGRATION.md.
# 1. Record understanding as it forms (append-only, OTel-shaped)
germinate belief append notes.jsonl --kind trace.open --trace myproj --span _meta --note "belief log"
germinate belief append notes.jsonl --kind belief.open --trace myproj --span 1.path \
--belief "Path A is fastest" --confidence 0.6 --risk 0.4 --status OPEN
germinate belief append notes.jsonl --kind belief.update --trace myproj --span 1.path \
--from "Path A is fastest" --to "Path B, given the new constraint" \
--trigger "benchmark" --confidence 0.85 --risk 0.15 --status ALIGNED
# 2. Track every surface + catch drift (CI gate)
germinate drift-check --manifest manifest.json # exit 1 if any projection is STALE
# 3. Compact the session into a durable seed + a cold-start pickup prompt
germinate compact --docset 2026-08-13-build.1 --belieflog notes.jsonl \
--starts-at "wire delivery to the sandbox" --out SESSION-HANDOFF.md
germinate compact --belieflog notes.jsonl --starts-at "…" --prompt # emit pickup prompt
# 4. Guard the serialized surface (force-push risk / untracked shared state)
germinate serializability --strict
germinate install-hooks # installs a pre-push breakerFull worked example: examples/quickstart/.
Storing the diamond was never the bottleneck (git + memory files already persist it).
The recurring failure is context-blind recall: the same insight re-derived every
session because nothing surfaces it at the moment it applies. A seed fixes that —
it's content plus germination conditions (soil, antipatterns, provenance), so
it re-expresses when the context is right and stays dormant otherwise.
germinate seed --soil "marketplace,payments" --antipatterns "b2c" \
--title "Split-payment shape" --out _SEEDS/split-payment.md # mint
germinate sprout --context "building a marketplace with payments" # surface what's ripe nowSURFACED (1):
✔ split-payment-shape [score 2] ← marketplace, payments
sprout is deterministic by design: literal soil/tags match, a visible
antipattern veto (it prints which antipattern suppressed a seed — "receipts for
silence"), and a STALE demotion when a seed's soil path has vanished from git. No
NLP, no embeddings, no LLM — so every result is explainable and fixture-tested, and it
cannot hallucinate a match. An empty result is a healthy "winter", not an error, and
dormant seeds are never garbage-collected — dormancy is the feature (a seed carries
potential energy until its soil returns).
The germinate ↔ ARCS boundary is the moat, stated honestly. germinate ships the deterministic socket — mechanical, transparent, open. Semantic ripeness (judging relevance beyond literal match, at the opportune moment) is a distinct, private activation layer — the "vox animus". The open tool is honest and mechanical; the intelligence is the layer above it. See
docs/adjacencies.mdand the seven-stage grammar indocs/grammar.md.
The real deliverable is language-neutral: the SPEC.md, the JSON
Schemas in spec/, and the conformance/ fixtures. Every
implementation — Node, Python, Rust, shell — is tested against the same fixtures,
so they cannot silently diverge. That is the toolkit's own anti-drift principle,
applied to its own codebase.
| Runtime | Role | Path |
|---|---|---|
| Node/TS | reference CLI, npm bin, provenance signing | packages/node |
| POSIX shell | zero-dep CLI + git hooks (home of the serializability checks) | packages/shell |
| Python | stdlib-only port | packages/python |
| Rust | signed single binary for the Homebrew bottle | packages/rust |
The spec + conformance suite is the deliverable; the runtimes are proofs of it. Node is the reference implementation. The substrate primitives (belief-log, manifest, handoff, serializability) are conformant in all four runtimes; the seed layer ships conformant in Node + Python today (shell + Rust are tracked conformance targets — the fixtures already exist, the ports are welcome contributions).
The core operates on files + git only. A harness adapter maps a specific agent
environment (Claude Code, Cursor, Aider, …) onto compact at session end and
pickup at session start. Adapters are thin and optional — see
adapters/. The same wrap-the-core pattern hosts an infra-agnostic
microservice (Lambda / serverless / worker / LangChain tool) when you want one.
Where else these primitives apply (ML/RL experiment tracking, model provenance,
forensic traces, governance circuit-breakers, and the designated follow-on public
goods kairos and observatory): docs/adjacencies.md.
npm (provenance/sigstore), a Homebrew tap, and a GitHub Actions release workflow
are scaffolded in docs/RELEASING.md and
.github/workflows/. The maintainer performs the actual
signed publish and holds all secrets — this repo prepares the workflow, never the
keys.
Six principles govern every stage (plan → build → accept), each bound to a concrete
mechanism: traceable · transparent · explainable · composable · anti-hallucination
· anti-sycophancy. See docs/PRINCIPLES.md.
New behavior lands as a conformance fixture first, then in each implementation.
Run make test (or per-package: npm test, python -m unittest, cargo test,
sh packages/shell/test.sh).