Skip to content

cleverb/bearing

v0.2.0MIT

BEARING: an EOCR-based decision system — recover, elicit, anchor, and enforce the decisions governing a codebase, so architectural intent is discoverable at generation time rather than only enforceable at commit time.

GitHubOpen Website

bearing-system (Python distribution) / bearing (plugin and CLI)

The installable BEARING plugin: three Skills, their canonical subagent definitions, the projection renderers, and the bearing CLI. The standalone Python distribution is named bearing-system; its import package and command remain bearing.

Layout

plugin/
├── plugin.json              # canonical manifest (Agent Plugins v1.0.0)
├── .cursor-plugin/          # generated — Cursor manifest
├── .claude-plugin/          # generated — Claude Code manifest
├── .codex-plugin/           # generated — Codex manifest
├── hooks/hooks.json         # generated — Claude PreToolUse injection
├── hooks/cursor.json        # generated — Cursor workspaceOpen projection
├── hooks/context_injection.py
├── hooks/render_ephemeral.py
├── skills/
│   ├── decision-recovery/   # retrospective acquisition (operator-invoked)
│   ├── decision-interview/  # live acquisition (structured elicitation)
│   └── decision-onboarding/ # optional adoption facilitation
└── src/bearing/             # the CLI

plugin.json is the only hand-maintained manifest. Everything in .cursor-plugin/, .claude-plugin/, .codex-plugin/, the per-Skill Codex metadata, and the two hook manifests is generated by bearing package. Cursor's workspaceOpen hook runs python3 hooks/render_ephemeral.py; Claude's PreToolUse hook runs the scoped context adapter. Both wrappers resolve the bundled Python source without requiring bearing on PATH.

bearing package            # rewrite every generated manifest and adapter
bearing package --check    # fail if anything drifted (this runs in CI)
bearing package --release-check  # additionally require current Tier 4 evidence

The purity rule

Nothing under this directory is written to at runtime. The plugin is read-only after install.

This is not a stylistic preference. Both Cursor and Claude Code copy the plugin directory into a versioned cache on install and replace it wholesale on update, so anything BEARING wrote inside itself would be silently destroyed on the next upgrade. It is also normative under Agent Plugins v1.0.0 §4.1.3, which requires clients to reject package paths resolving outside the plugin root — which is why no file here may reference ../ to reach a sibling.

All runtime writes go to one of two places in the workspace:

  • .bearing/ — run state: config, price book, ledgers, evaluation sets, caches, the projection lock.
  • <decisions.path>/ — decision content: authored ADRs, the index, and the shadow graph including interview transcripts.

tests/test_packaging.py enforces both halves of this: it copies the plugin to a temp directory, asserts no path escapes the root, and runs the pipeline with the plugin tree read-only.

Skills

Each skill is self-contained — no skill reaches into a sibling's directory, because a ../ reference does not survive installation. decision-interview shares decision-recovery's candidate schema by resolving it through the CLI (bearing schema candidate), which locates it relative to the installed plugin root rather than by a relative path from one skill to another.

CLI

Bundled here and installable standalone:

pipx install .        # or: uv tool install .  (optional — CI/contributors)

Marketplace users do not need pipx. After installing the plugin:

python3 plugin/enable.py --discover   # from a bearing-system clone
export PATH="$HOME/.bearing/bin:$PATH"

Or bearing enable --discover once bearing is on PATH. Opening a workspace also writes the same shims automatically.

Python 3.9+, standard library only. Deliberately dependency-free: the CLI runs inside whatever environment a target repository already has, and a decision system that cannot bootstrap without a package install is a decision system that does not get adopted.

Candidate disposition (human judgment, then mechanical execution):

bearing review --json          # list surfaced candidates
bearing dispose --id CAND-… --action Promote \
  --still-valid 1 --eocr Contract --scope 'src/**' --status Accepted
bearing-mcp                    # stdio MCP server (also shipped as plugin/mcp.json)

Principle: one-click execution of a human promotion decision is allowed; one-click substitution for that decision (confidence → Approve) is not.