bearings

bearings is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records the generated files in a manifest, and leaves project-specific tailoring to your AI agent via /setup-repo.

Quick Start

npx bearings init
/setup-repo
bearings verify

1. npx bearings init writes the generic scaffold and prints the next step.
2. /setup-repo runs inside your AI agent to merge backups, fill placeholders, seed docs, and tailor skills.
3. bearings verify checks the scaffold for drift, missing files, broken exposures, and unresolved setup warnings.

What Gets Generated

AGENTS.md
CLAUDE.md
docs/
  CURRENT_STATE.md
  conventions/
    current-state.md
    doc-lifecycle.md
  adr/
    0000-template.md
  deferred/
    INDEX.md
.agents/
  bearings.json
  commands/
    current-state.md
    setup-repo.md
  skills/
    repo-navigation/SKILL.md
    implementing-task/SKILL.md
    installing-dependencies/SKILL.md
    secrets-handling/SKILL.md
    enforcement-gates/SKILL.md
    commit-convention/SKILL.md
    defer-work/SKILL.md
    resurface-deferred-work/SKILL.md
.claude/
  commands/*
  skills/*
.opencode/
  commands/*
  skills/*

Existing scaffold targets are backed up as <path>.bkp before replacement. Re-running init skips unchanged managed files.

The Model

Agent-friendly context is routed, not dumped.

user task
  -> root agent seed
  -> current-state map
  -> situation-specific skills
  -> task/runbook/spec docs when needed
  -> executable guardrails before completion

Commands Reference

bearings init

Scaffold the agent-friendly setup in the current repository.

| Flag | Meaning | |---|---| | --harness <name...> | Expose to claude and/or opencode. Defaults to detected harness dirs, or both in a fresh repo. | | --copy | Copy exposures instead of symlinking them. verify checks copy drift. | | -y, --yes | Accept defaults and do not prompt. |

bearings verify

Check the manifest and harness exposures for mechanical breakage. Exit code 0 means no failures; exit code 1 means one or more failures.

| Code | Severity | Condition | |---|---|---| | no-manifest | fail | .agents/bearings.json missing | | missing-file | fail | manifest entry path doesn't exist | | missing-exposure | fail | a child of .agents/skills or .agents/commands absent from a configured harness dir | | broken-symlink | fail | harness entry is a symlink whose target doesn't resolve | | copy-drift | fail | copy mode: harness file content differs from .agents source content | | unfilled-placeholder | warn | a bearings-generated file still contains <agent: | | unreviewed-backup | warn | manifest backup path still exists on disk |