Bearing Lite (@alphazede/bearing-lite) is a skills-first Agent
Plugins package
that gives AI-assisted repository work a structured delivery lifecycle from
an owner-approved plan to an independently assessed result. It improves
repeatability and reduces hallucination risk through bounded
implementation, deterministic checks, verification, validation, independent
assurance, and traceable evidence. Planning artifacts and the Definition of
Done Manifest compare what AI was authorized to touch with actual changes,
supporting evidence, and unresolved gaps. It ships portable skills,
references, templates, and optional client adapters. An agent cannot certify
its own work. Owner Authority remains human-only. Bearing Lite was created
by William Rumph.
Teams now ask coding agents to change real repositories. The work needs a visible plan, exact write sets, deterministic checks, and independent assessment before anyone treats the result as done.
Unbounded agent sessions invent architecture, skip owner decisions, mix implementation with self-review, and leave no comparable record of what was authorized versus what changed.
How can AI-assisted repository work follow one input-to-evidence path that stays reviewable, portable, and bounded without pinning a provider?
Use the Bearing Delivery Lifecycle: Intake → Architectural Alignment and Scope →
parallel MBSE and Integration and Test planning → Orchestrator final Planning
and Design and assembly →
requested planning review → owner confirmation → written handoff → bounded
implementation (Test Implementer before Product Implementer under tdd, or one
Implementer for code and tests), then any requested Test Engineer assurance,
Reviewer defect review, and Integration Engineer execution assessment. Only
profile-enabled roles the task needs run; the arrows are data dependencies, so
independent ready work runs in parallel. Persistent configuration is
~/.agents/bearing-lite/profiles.json only. The Definition of Done Manifest
is the human-readable projection of planned versus actual work; it never
grants execution, acceptance, release, or deployment authority.
Focused pages:
- Explanation: lifecycle guide
- Reference: roles and sessions, lifecycle specification
- Troubleshooting: wait, resume, and configuration
- Process diagrams: lifecycle context, planning and implementation
If Bearing Lite helps keep a long agent task scoped and reviewable, star the repository.
- Install the plugin or copy
skills/into a host skills directory. - Run onboard-bearing for guided setup or a targeted edit. It classifies the catalog first and asks one setting at a time. You supply all harness, model, and reasoning choices. The skill previews the approved edits and preserves unaddressed settings and host-extension keys.
- Configure named role and session routes (including both
test_implementerandimplementerindependently fortdd), optional catalog-levelfellow, fallbacks, development strategy (single_implementerortdd), assurance cadence, concurrency booleans, the planning-to-implementation clean-session boolean, holds, optional OpenCodeReview (review.coverage_assist),assurance_repair, and optional Reverify / additional testing tools. Coordinator is retired for new waves (the Implementation Orchestrator owns new-wave coordination; existingroles.coordinatorentries are ignored on load and preserved only for frozen legacy journeys). Planning review is requested per Lifecycle, not stored inprofiles.json. Validate before and after saving withskills/onboard-bearing/scripts/validate-profiles.mjs(andhooks/profiles.cjswhen hooks are installed). No value is preselected. - If you decline Reverify or decline its download, onboard-bearing persists
reverify.enabled: falsefor that named profile and does not ask again during ordinary Lifecycles. Reverify is an optional third-party backend. Bearing Lite does not bundle, download, or install it, and never invokes it; the adapter only judges receipts a caller produces. - A leftover
~/.agents/bearing-lite/lineups.jsonis not live configuration. Runtime returnsMIGRATION_REQUIREDuntil onboard-bearing migrates it.
The only persistent Bearing user configuration is
~/.agents/bearing-lite/profiles.json. Runtime never searches, merges,
prefers, or falls back to lineups.json.
Some agent harnesses may stall after delegated work completes. Before restarting the task, check whether the assigned agent is still active and avoid duplicate dispatch. Wait/status reliability varies by host and route; use a host-native status check when one exists.
Install the published skills package:
pi install npm:@alphazede/bearing-liteThen give your agent a real task:
Use Bearing Lite to add rate limiting to this API without changing its public responses. Require independent assurance at the configured cadence.
Bearing Lite runs Intake and combined Architectural Alignment and Scope,
dispatches the enabled specialists the task needs, then the Planning
Orchestrator itself performs final Planning and Design and assembles the
complete five-artifact package (<lifecycle-topic>-technical-plan.md,
design.md, seit.json, implementation.json, and
<plan-name>-dod-manifest.html) with proposed route, profile, role states,
reasoning, and cadence. A planning review runs only when requested; one
integrated owner confirmation approves or changes that package. The
Orchestrator writes handoff.md with the visible task state. The approved
clean-session setting determines whether implementation continues here or
in a fresh Implementation Orchestrator session.
Install as a host plugin. The portable identity is always bearing-lite /
@alphazede/bearing-lite. No postinstall script, global hook copy, or
host-config mutation is required. Host-specific plugin manifests and
discovery remain host contracts; this README does not replace them.
Qwen Code, Kimi Code, and Grok Build are no longer supported. Their retained metadata describes legacy integrations only; they are excluded from release qualification.
Claude Code and Codex install from a local checkout and load session-start activation and stop closeout hooks. Installation does not activate Bearing: an explicit owner request is bound to the current task/native session in the existing visible project plan (binding format).
# Claude Code
claude plugin marketplace add /path/to/bearing-lite
claude plugin install bearing-lite@bearing-lite
# Codex (prepared local marketplace; see below)
node /path/to/bearing-lite/tools/prepare-codex-plugin.mjs --out /path/to/bearing-lite-codex
codex plugin marketplace add /path/to/bearing-lite-codex
codex plugin add bearing-lite@bearing-lite
Codex needs the prepared marketplace. Codex 0.162.1 registers zero plugin
hooks when the root plugin.json carries the Agent Plugins $schema key, and
reports no warning or error. Adding the repository root as a marketplace
(including the root .agents/plugins/marketplace.json, which points at the
GitHub repository) installs the skills but no hooks. tools/prepare-codex-plugin.mjs
writes a new local marketplace whose bearing-lite/ payload is the npm package
file set plus .codex-plugin/, byte for byte, except that root plugin.json
omits $schema. The portable source is not changed.
- Run it from a git checkout. The npm package omits
.codex-plugin/, and the tool stops if that metadata is missing. It also needs Node 22 andnpmonPATH(it reads the file set fromnpm pack --dry-run; no network). --outmust be a new directory with an existing parent, outside the checkout. The tool refuses an existing path, the checkout, a path inside it, an ancestor of it, or a symlink alias that resolves into it.- Rerun it into a fresh directory after updating the checkout, then reinstall.
node --test test/native/codex-hook-discovery.test.mjs is the native proof: it
installs the prepared artifact into a disposable Codex home and checks that
Codex lists all eight hooks/hooks.json registrations and every packaged skill
when enabled, and no Bearing hook when disabled. It proves registration only,
not that a hook runs or denies anything. Release smoke must still show a
positive hook invocation and an allowed and a denied write-lock case; the
absence of errors is not evidence.
These hosts install through their own UI or TUI. They are still plugin clients, not a skills-only copy.
Cursor. Open Customize in the sidebar, find the plugin, and select
Install for a project or user scope. The shipped layout is
.cursor-plugin/. For a local checkout, link the repository into Cursor's
documented local-plugin directory, then restart Cursor or run Developer:
Reload Window:
mkdir -p ~/.cursor/plugins/local
ln -s /path/to/bearing-lite ~/.cursor/plugins/local/bearing-liteGitHub Copilot in VS Code. Run Chat: Install Plugin From Source from
the Command Palette and enter a Git repository URL such as
https://github.com/alphazede/bearing-lite. See Agent plugins in VS
Code.
The package is Agent Plugins 1.0 plugin.json plus
com.github.copilot/hooks/hooks.json. VS Code also discovers plugins installed
by GitHub Copilot CLI after a new window or reload.
GitHub Copilot CLI requires Node.js 22 or later.
# GitHub Copilot CLI
npm install -g @github/copilot
copilot plugin marketplace add alphazede/bearing-lite
copilot plugin install bearing-lite@bearing-lite
Stage the npm payload with the Antigravity manifest to install the skills and seven hook registrations. Follow the Antigravity installation instructions.
Pi, DeepCode, and Muse Code load skills without command hooks.
# Pi — published skills package
pi install npm:@alphazede/bearing-lite
# Muse Code — no plugin subsystem; install each skill
for skill in /path/to/bearing-lite/skills/*/SKILL.md; do
muse skills install "$(dirname "$skill")" --scope user
doneDeepCode has no plugin-install or command-hook surface. Copy skills/
into ~/.deepcode/skills or ~/.agents/skills.
Claude Code, Codex, Cursor, Antigravity CLI, and GitHub Copilot clients
are partial hook clients: only an explicitly bound current Bearing task runs
the activation/closeout advice, ownership lock, and git-sync. Ordinary or stale
sessions stay quiet and never fetch or fast-forward. Active git-sync fast-forwards
the session checkout from origin and names anything still unpushed. GitHub Copilot also has the implemented Test
Engineering channels PreToolUse, Stop, and SubagentStop. Antigravity
maps SessionStart, PreToolUse, and Stop. Pi, DeepCode, and Muse Code
are skills-only.
General transition-order, protected-action and planning-review checks stay
procedural. The assurance budget has a mandatory bound pretool dispatch barrier
on the common, Cursor, Antigravity and Copilot mappings. See the host test status
in the mapping
and the binding contract. Node.js must be on PATH for the hook
adapters.
Planning-review constraints live only in
skills/bearing-lite/references/review-policy.md;
the shared evaluator is hooks/planning-review.cjs. Lifecycle-specific
abstract slot IDs and owner-selected primary/ordered fallback route
references belong only in the approved profile snapshot. Existing host
mappings cannot safely derive the nested record from session events, so they
preserve partial or skills-only coverage and apply this gate procedurally.
Planning review is an owner-requested pre-dispatch plan gate; implementation
max_assurance_rounds remains separate.
Skills-only copy of skills/ into a host skills directory does not
register hooks. That path remains first-class. See
hooks/com.anthropic.claude-code/mapping.md.
- Fill only missing planning stages: Intake → Architectural Alignment and Scope.
- Dispatch enabled specialists in data-dependency order once material intent
is settled. MBSE and Integration and Test start in parallel from the frozen
requirement IDs and titles. The Planning Orchestrator then authors the final
technical plan and
design.mdand assemblesimplementation.jsonand the Definition of Done Manifest; specialists keep requirements andseit.json. Design fixes owners, structures, and bounds per slice lens; programs add milestones, dependencies, estimates, notices, and replanning. - Confirm once: after any requested planning review, approve or change the
proposed route, user-owned primary/fallback profile, role states, reasoning,
cadence, and plan; the Orchestrator then writes
handoff.md. - Dispatch bounded sessions with compact receipts. Implementer may continue in-wave. The Implementation Orchestrator owns new waves (Coordinator is retired for new work; frozen legacy Coordinator waves keep their pinned runtime until explicit handover). Declared assurance starts fresh at the configured cadence boundary.
- Record state visibly. The project's human-readable Markdown plan is the
only task-state record: task blocks, task states, and their transitions. The
Lifecycle, execution, V&V, and authority records are machine-readable JSON
validated against
schemas/:journey.json(Lifecycle identity, checkout lease, decisions, planning receipts, profile selection),seit.json(V&V proof rows),implementation.json(nested execution authority, waves, slices, dispatch), andauthority.json(authority envelope). The Definition of Done Manifest and diagrams present state; like diagrams, they never authorize a transition, create state, or grant authority.
Bearing Lite never selects models, providers, credentials, or launchers. The
owner provides each role's primary/fallback agent or harness, model, and
reasoning level in ~/.agents/bearing-lite/profiles.json, then confirms
the applicable Lifecycle snapshot before implementation.
Owner questions follow the owner-stop policy. The integrated approval records bounded continuation with exclusions and expiry.
Current routing diagram source: skills/bearing-lite/references/role-routing.mmd.
The text below remains authoritative for clients that do not render Mermaid.
Authoritative text (vision optional): Owner Authority remains human-only.
The Bearing Lite Orchestrator is the stateful controller, not a work role, in
an explicitly requested Planning or Implementation mode. It invokes only
missing planning stages and the enabled specialists the task needs, performs
final Planning and Design itself to complete all five artifacts with proposed
profile and cadence, runs a planning review only when requested, obtains one
integrated owner confirmation, and writes the handoff that a new
Implementation Orchestrator session consumes before bounded implementation.
Direct packets never dispatch Coordinator; the Implementation Orchestrator owns
new waves as parent controller and bookkeeper. Coordinator is retired for new
work (roles.coordinator entries are ignored on load); only frozen legacy
Coordinator waves retain their pinned runtime until explicit handover. Assurance
Test Engineer, Reviewer, and Integration Engineer execution appear when declared
at the configured cadence boundary. Diagrams explain orientation; they never
authorize a transition.
| Role | Sessions | Primary work |
|---|---|---|
| Orchestrator | planning or implementation control | Planning mode: context, specialist dispatch, final plan/design, assembly, handoff. Implementation mode: consumes the handoff; wave sequencing; direct-packet parent controller and bookkeeper. Observed, not selected. |
| Intake | planning | Confirms repository and plan directory |
| Architectural Alignment and Scope | controller | Architectural fit, workspace map, and owner-confirmed scope |
| Scope Definition | compatibility | Forwards to the combined skill; no separate stage or agent |
| Planning and Design | controller procedure | The Orchestrator's own final plan/design and assembly; not a dispatched or configured role |
| MBSE | planning | Authors and checks requirements, chooses modeling mode, and returns view metadata and a placement receipt |
| Integration and Test | planning | Authors the boundary contract, assembly sequence, and SEIT proof cases |
| Coordinator | retired (legacy only) | Retired for new waves (roles.coordinator ignored); frozen legacy waves keep their pinned runtime until handover |
| Test Implementer | implementation | TDD test-first author (roles.test_implementer); tests and approved fixtures only |
| Product Implementer | implementation | Product write set under tdd (roles.implementer); combined author under single_implementer. Neither self-certifies |
| Light Implementer | implementation | work_class: light slices only |
| Scribe | planning and implementation | Transcribes; cannot activate authority |
| Test Engineer | assurance | The Assurance Test Engineer independently verifies and validates the candidate. Default cadence is phase |
| Reviewer | implementation review | Independent defect review. Default cadence: phase |
| Integration Engineer | execution | Independently assesses the integrated candidate. Default cadence is lifecycle |
| Owner Authority | human decision | Never an agent role |
| onboard-bearing | configuration | One-setting-at-a-time profile writes; no credentials |
Cadence values are slice, phase, or lifecycle. Defaults are phase for
Test Engineer assurance, phase for Reviewer, and lifecycle for Integration
Engineer execution. A declared boundary runs each enabled session once, allows
one aggregated repair, then uses deterministic closure without automatic
rereview.
single_implementer is the speed default: one Implementer writes product
changes plus tests. tdd orders Test Implementer before Product Implementer
for a behavior-changing slice. Independent dependency-ready slices may run
concurrently when write sets and mutable resources do not overlap.
Independent review: a candidate author never provides their own Assurance Test Engineer, Reviewer, or Integration Engineer execution verdict.
Public Bearing Lite remains usable without AlphaZede-specific skills
(requirements-engineering, sysml-modeling, test-engineering,
integration-engineering). Specialized capabilities activate when selected
or required. Unavailability of a selected-or-required capability is a typed capability gap, not success and not invented behavior. Selected-only missing and required-only missing are each typed gaps. Only unselected and unrequired absence remains inactive / not a global failure.
Failure escalates to the nearest role whose scope can see it:
| Failure scope | Escalates to |
|---|---|
| Within one slice or packet | Parent controller: Implementation Orchestrator on new waves (Coordinator only on a frozen legacy wave) |
| Across slices in a wave | Implementation Orchestrator (Coordinator only on a frozen legacy wave) |
| Across waves or phases | Orchestrator |
| Contract, security, or authority change | Owner Authority |
Current task-state diagram source: skills/bearing-lite/references/task-state.mmd.
The text below remains authoritative for clients that do not render Mermaid.
Authoritative transition rules: skills/bearing-lite/references/task-state.md.
Authoritative summary: The project's plan is the only task-state record.
Normal progress is PROPOSED → READY → IN_PROGRESS → EVIDENCE_READY, then
optional VALIDATING / REVIEWING when required, then ACCEPTANCE →
COMPLETE. WAITING_ON holds for missing prerequisites, checkout-lease
conflict, or assurance dispatch.
Ordinary execution corrections remain bounded. The assurance gate allows one
review-directed repair, followed by deterministic parent-controller
verification (Implementation Orchestrator on new waves; Coordinator only on a
frozen legacy wave) and no second review. Diagrams never create state or
authorize transitions.
hooks/reconcile.cjs deterministically applies evidence events to Lifecycle
state. It is a short-lived Orchestrator-run invocation, not a daemon or host
event adapter; hosts emit no events today, so invocation remains a procedural
limitation. It observes merge and issue closure but never grants acceptance,
merges, or closes issues.
Default packet completion is author self-check plus parent-controller
confirmation: Implementation Orchestrator on new waves (Coordinator only on a
frozen legacy wave). Implementer must not self-certify. Declared independent
assurance runs at the configured cadence boundary. A repairable verdict permits
one repair; deterministic parent-controller verification then closes the gate
without another review. Once the Lifecycle is COMPLETE,
an already authorized deployment proceeds with operational checks and rollback
readiness, not a new assurance round. Source-changing deployment work is
separate work.
flowchart LR
W[Bounded work] --> C[Deterministic checks]
C --> R[Single independent review]
R -->|Pass| X[COMPLETE]
R -->|Repairable| F[One repair]
F --> V[Parent-controller verification]
V --> X
X --> D[Authorized deploy and operational verification]
| Path | Purpose |
|---|---|
plugin.json |
Agent Plugins 1.0 manifest (schema) |
skills/ |
Orchestrator, planning stages, and role skills |
hooks/ |
Portable class adapters plus verified host mappings |
profiles.json |
Empty shipped catalog; no packaged providers, models, or defaults |
schemas/ |
JSON Schema for seit.json, implementation.json, authority.json, journey.json, and profiles.json |
README.md and governance docs |
Public product and conduct surfaces |
There is no mcp.json, bin entrypoint, postinstall, or runtime dependency on
another product's state.
Skills declare capabilities (reasoning depth, repository access, mutation tools, independence, optional vision). They never pin a model, provider API key, default route, or launcher. Owners and clients choose how to satisfy each role.
Issues and carefully scoped pull requests help. See CONTRIBUTING.md. Everyone is covered by the Code of Conduct. Release notes and acknowledgements are in docs/releases/.
Report suspected vulnerabilities privately—not in a public issue. See SECURITY.md.
Licensed under the Apache License 2.0.