Skip to content

About

Skills-first Agent Plugin for bounded planning, routing, execution, and independent review—without CLI, MCP, server, or hidden runtime state.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

422 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Bearing Lite

npm license

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.

Situation

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.

Complication

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.

Question

How can AI-assisted repository work follow one input-to-evidence path that stays reviewable, portable, and bounded without pinning a provider?

Answer

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:

If Bearing Lite helps keep a long agent task scoped and reviewable, star the repository.

Onboarding

  1. Install the plugin or copy skills/ into a host skills directory.
  2. 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.
  3. Configure named role and session routes (including both test_implementer and implementer independently for tdd), optional catalog-level fellow, fallbacks, development strategy (single_implementer or tdd), 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; existing roles.coordinator entries are ignored on load and preserved only for frozen legacy journeys). Planning review is requested per Lifecycle, not stored in profiles.json. Validate before and after saving with skills/onboard-bearing/scripts/validate-profiles.mjs (and hooks/profiles.cjs when hooks are installed). No value is preselected.
  4. If you decline Reverify or decline its download, onboard-bearing persists reverify.enabled: false for 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.
  5. A leftover ~/.agents/bearing-lite/lineups.json is not live configuration. Runtime returns MIGRATION_REQUIRED until 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.

Quick start

Install the published skills package:

pi install npm:@alphazede/bearing-lite

Then 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

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.

Plugin with hooks

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 and npm on PATH (it reads the file set from npm pack --dry-run; no network).
  • --out must 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.

UI or TUI plugin installation

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-lite

GitHub 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.

CLI plugin installation

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

Antigravity CLI (AGY) installation

Stage the npm payload with the Antigravity manifest to install the skills and seven hook registrations. Follow the Antigravity installation instructions.

Skills-only installation

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
done

DeepCode 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.

What it does

  1. Fill only missing planning stages: Intake → Architectural Alignment and Scope.
  2. 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.md and assembles implementation.json and the Definition of Done Manifest; specialists keep requirements and seit.json. Design fixes owners, structures, and bounds per slice lens; programs add milestones, dependencies, estimates, notices, and replanning.
  3. 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.
  4. 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.
  5. 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), and authority.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.

Roles and cadence

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

Task state (explanatory)

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.

Implementation process (explanatory)

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]
Loading

Package layout

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.

Provider neutrality

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.

Contributing

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/.

Security

Report suspected vulnerabilities privately—not in a public issue. See SECURITY.md.

License

Licensed under the Apache License 2.0.

About

Skills-first Agent Plugin for bounded planning, routing, execution, and independent review—without CLI, MCP, server, or hidden runtime state.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages