Skip to content

docs: show how Bearing connects Wayfinder work to project direction #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lagrangee merged 1 commit into from
Oct 2, 2026
Merged

docs: show how Bearing connects Wayfinder work to project direction #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 89 additions & 120 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,183 +1,152 @@
# Bearing

## Stay on the same page with your coding agents.
<a id="stay-on-the-same-page-with-your-coding-agents"></a>

Bearing gives long-running coding-agent projects a local, inspectable project-governance layer. It keeps accepted direction, Planning Reviews, evidence, and current Audit findings visible to you and your agents, so new work can start from the same project picture instead of from a fragile memory of old chats.
## Let Wayfinder chart the work. Keep the project in view.

Local-first · Open-source Public Preview · Agent-mediated installation · Matt-native local Markdown work management
Bearing adds local-first project governance to [Matt Pocock's skills](https://github.com/mattpocock/skills). It connects Wayfinder Maps and delivery work to the project's direction, milestones, and decision evidence.

[Quickstart](#quickstart-complete-one-real-alignment-loop) · [Is Bearing for you?](#is-bearing-for-you) · [Data boundary](#local-first-data-and-trust-boundary) · [中文 README](README.zh-CN.md)
Keep using the workflow you know. Bearing helps you and your coding agent see why each piece of work matters, how it relates to the rest, and what still needs a decision.

## The aha moment

You ask an agent to do the next thing on an active project:

> Add team accounts next.

A Bearing-aware agent can answer from the current project truth:

> The focused Gate is proving the single-user workflow. The accepted Roadmap puts multi-user authentication later. We can keep the current direction and capture this as future work, revise the Roadmap, or split a separate outcome horizon. I will not treat this as aligned until you choose.

That is the point of Bearing: not perfect agent memory, and not a second task tracker, but continuous alignment confidence. You can feel that the agent is on the same page, and you can see the source of that shared picture.

## What Bearing connects

```text
You + your coding agent
↕
Bearing Project Governance
↕
Matt-native Maps and Tickets

Portal reads the same project picture
```

Bearing owns durable project governance: Project Summary, Roadmaps, Milestone Gates, Effort bindings, Authorities, Assets, Planning Reviews, Planning Audit, and evidence relationships.

Your work-management adapter still owns Maps, Tickets, dependencies, claims, blockers, and resolution. Your executor still owns implementation and verification. Bearing keeps those layers connected without pretending to be all of them.
Open-source Public Preview · macOS · Local Markdown · MIT

Already using Matt Pocock's planning workflow? Bearing is designed to read the same local Markdown Map and Ticket shape, so you can add governance and Portal orientation without migrating work into another tracker.
[Try the Portal demo](https://lagrangee.github.io/bearing/) · [Get started](#quickstart-complete-one-real-alignment-loop) · [中文 README](README.zh-CN.md)

## Is Bearing for you?
## The aha moment

Bearing is likely a fit if:
You have a Wayfinder Map for onboarding, another for billing, and a third for performance. Each has a destination and a record of decisions. Now you need to answer a project-level question:

- you use coding agents on software projects that continue across many sessions;
- you want new requests checked against accepted direction before work starts;
- you already use, or are willing to use, the supported Matt-native local Markdown Map and Ticket workflow;
- you want local repository truth, a local Portal, and no automatic telemetry;
- you are comfortable with a macOS-first `0.x` Public Preview that may make documented breaking changes.
> Which of these efforts brings us closer to the next milestone? Does adding team accounts still fit the direction we agreed on?

Bearing is probably not a fit yet if:
Bearing connects the work you select to an accepted Roadmap and Milestone Gates. You and your agent can trace a Map back to the commitment it serves, inspect the evidence, and decide whether to continue, change direction, or take on a separate goal.

- your work is mostly one-off coding tasks with little durable context;
- you want a Kanban board, hosted issue tracker, autonomous project manager, or general memory database;
- you do not want to use the supported local Markdown work-management adapter;
- you need hosted multi-user operation, product-managed authentication, cloud sync, or a public Internet Portal;
- you need officially supported Linux or Windows today.
Wayfinder preserves the route through an effort. Bearing keeps that effort connected to the whole project.

## Public Preview support
## What Bearing connects

| Area | Public Preview support |
| When you need to… | Bearing helps you… |
| --- | --- |
| Platform | macOS |
| Node.js | Node.js 24.15.0 or later; CI verifies Node.js 24.15.0 and 26 |
| Work Management Adapter | Matt-native local Markdown Maps and Tickets |
| Telemetry | None. Bearing performs no analytics, crash upload, repository upload, or update polling. |
| Understand how several Maps fit together | Follow each selected effort back to its project direction and milestone. |
| Decide whether a new request fits | Inspect relevant planning and work, then surface conflicts and decision paths. |
| Review progress | Connect Efforts, native Maps and Tickets, evidence, and human acceptance without treating them as the same status. |
| Understand what your agent is using | Read the project's planning lineage, source provenance, and attention items in the local Portal. |

## Interactive browser sample
A typical Wayfinder-based project looks like this:

```text
Roadmap — the project direction
└─ Milestone Gate — the outcome to prove
├─ Effort — one accepted commitment
│ └─ Wayfinder Map and related native work
└─ Effort — another accepted commitment
└─ Wayfinder Map and related native work
```

[Open the interactive browser sample](https://lagrangee.github.io/bearing/). It is a browser-only
Portal demo with fixed mock Northstar data. The demo is a static sample, not a hosted Bearing
project, real repository, canonical planning surface, or proof of product value. It does not start
the local Portal Host, read a repository, call a provider or API, use analytics, or persist browser
state.
An **Effort** is Bearing's unit for one accepted work commitment. When you bring a Wayfinder effort into Bearing, the Map's native work scope connects to that Effort. The Map continues to organize exploration and decisions; the Effort records why the work exists and which project milestone it serves.

Supported product use starts with [local installation](#quickstart-complete-one-real-alignment-loop)
and a loopback Portal. Demo availability does not prove installation success. Read the
[data and security boundary](docs/data-and-security.md) before sharing Portal captures or changing
private reachability. The demo remains independent from production Portal runtime and is excluded
from the npm package.
A resolved Map can lead into specification and delivery while the Effort continues. Ticket completion and acceptance remain visible as separate facts. You choose which work to include; planned Efforts and direct delivery work can also exist without a Map.

## Feedback and support
### Alongside Matt's workflow

- Use [Bug report](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) or [Documentation problem](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml) for reproducible bugs and actionable documentation problems. Blank Issues are disabled.
- Use [Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a) for questions and troubleshooting, and [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas) for experiences, scenarios, pain points, suggestions, and feature ideas that still need shaping.
- Report suspected vulnerabilities only through [GitHub private vulnerability reporting](https://github.com/lagrangee/bearing/security/advisories/new), never in a public Issue or Discussion.
- **Wayfinder** works through the unknowns and retains decisions in a Map.
- **Specification and ticket skills** turn accepted decisions into delivery work when needed.
- **Your executor** implements and verifies that work.
- **Bearing** connects these activities to project direction, milestones, and evidence. Its local Portal lets you inspect the same picture your agent uses.

Issues and Discussions are public GitHub data. Do not submit tokens, secrets, private source, complete planning state, real absolute repository paths, or unredacted screenshots. Bearing uploads no diagnostics automatically; logs, diagnostics, and repository excerpts are shared only when you explicitly submit them. Community support is best-effort with no SLA, and public feedback is not a scheduling or delivery commitment.
The supported Public Preview path reads Matt-native local Markdown Maps, Specs, and Tickets. Your tracker keeps its native files, status, dependencies, claims, and resolution rules. Bearing's Portal is read-oriented; canonical planning decisions stay in the agent conversation.

## Quickstart: complete one real alignment loop

### 1. Ask your Agent to install Bearing
You need macOS, Node.js 24.15.0 or later, a coding agent that can install packages and integrate a skill, and a real Git project. The supported work-management path uses Matt-native local Markdown Maps and Tickets.

Give your Agent this prompt. It can follow the separate
[Agent installation guide](docs/agent-installation.md) without adding implementation detail to this
README.
### 1. Ask your agent to install Bearing

```text
Install Bearing from https://github.com/lagrangee/bearing. Follow the repository's Agent installation guide, use the released package, integrate the Bearing skill with your Skill Directory, and stop before repository setup.
```

#### Terminal fallback
The [Agent installation guide](docs/agent-installation.md) verifies one exact published package and separates installation, skill integration, and repository setup. It does not install from mutable `main` as the normal payload.

If your Agent cannot perform the installation, select and verify an exact released version, then
run that candidate's explicit installer:
If your agent cannot install it, first verify an exact released version and its package identity, then use the terminal fallback:

```bash
npx @lagrangee/bearing@<resolved-version> install
npx --yes @lagrangee/bearing@<resolved-version> install
```

Install stages and validates one complete bundle, then either switches it as a unit or restores the
previous complete bundle. It does not initialize a repository or launch Portal. Bare `bearing`
shows concise help. Explicit `bearing uninstall` removes only the Global Kit, canonical CLI, and
known owned Agent Surface links; it preserves the Project Catalog and every repository. An older
candidate and an unverifiable current Kit are no-write outcomes; see
[Troubleshooting](docs/troubleshooting.md). Successful install prints classic PATH guidance without
writing or sourcing a shell profile.
Installation prints PATH guidance without changing your shell profile. See [Getting started](docs/getting-started.md) and [Troubleshooting](docs/troubleshooting.md) for setup and recovery.

Advanced users and agents can use explicit commands; see [CLI reference](docs/cli.md).
### 2. Enable Bearing in your project

### 2. Choose a real project

Start with a real Git repository that already has, or is ready to use, the supported local Markdown Map and Ticket workflow. Bearing creates first value when it can connect real direction to real work; an empty toy repository proves very little.

### 3. Ask your Agent to set up Bearing

Open the repository with your Agent and ask:
Open the project with your agent and ask:

```text
Set up Bearing for this project. Use the existing Map and Tickets as work context, and guide me through the minimum governance baseline.
Set up Bearing for this project. Help me connect one existing Wayfinder Map and its work to the project's direction and milestones. Show me the proposed scope and planning baseline before applying them.
```

The minimum useful baseline is:

- one current Project Summary;
- one active Roadmap and focused Milestone Gate;
- one Effort that binds an existing Map or Ticket scope to that Gate.
Start with a Project Summary, a Roadmap and Milestone Gate, and an Effort connecting the selected work to that Gate. Use a Map you actually work with. Your agent should make proposed direction and scope visible for your decision; repository files alone do not accept a plan.

Accepted direction remains a human decision. Repository Configuration must not infer governance truth from repository files without asking.

### 4. Bring one real request

Ask something you actually want to do next:
### 3. Bring one real request

```text
Before we start, check this against the current direction, accepted decisions, and active work. Surface any conflict before acting.
```

The first alignment loop is complete when the agent either explains how the request fits or exposes a material conflict with explicit decision paths. Installation success alone is not the value milestone.
The first useful loop is complete when your agent explains how the request fits or surfaces a material conflict with clear decision paths.

### 5. Inspect the current project
### 4. Inspect the shared picture

```bash
bearing inspect project --repo .
bearing portal
```

Open the loopback URL printed by the Portal Host and inspect the Project Summary, focused Roadmap and Gate, contributing Effort, Attention, and source provenance.
Open the loopback URL printed by the Portal Host. Inspect the Project Summary, Roadmaps and Gates, contributing Efforts, Attention, and source provenance. Advanced usage is in the [CLI reference](docs/cli.md).

## Is Bearing for you?

Bearing is likely a fit if you already use Matt Pocock's skills, especially Wayfinder, on a software project with several ongoing efforts. It is useful when individual Maps and Tickets are understandable, but their relationship to the project's direction needs to stay visible.

The `0.x` Preview may make documented breaking changes; Linux and Windows are not officially supported today.

One-off tasks with little lasting context may get less value. If you need a hosted issue tracker, Kanban board, autonomous project manager, general memory database, multi-user service, or cloud sync, those are outside the current product boundary.

## Public Preview support

| Area | Public Preview support |
| --- | --- |
| Platform | macOS |
| Node.js | Node.js 24.15.0 or later; CI verifies Node.js 24.15.0 and 26 |
| Work Management Adapter | Matt-native local Markdown Maps and Tickets |
| Telemetry | None. No analytics, crash upload, repository upload, or update polling. |

## Interactive browser sample

[Open the interactive browser sample](https://lagrangee.github.io/bearing/) to explore the Portal with fixed mock Northstar data.

The demo is a static browser sample. It does not start the local Portal Host, read a repository, call a provider or API, use analytics, or persist browser state. It is excluded from the npm package. Demo availability does not prove installation success or product value; real use starts with local installation and a loopback Portal.

## Local-first data and trust boundary

- Repository governance truth lives under the repository's Bearing state and native local Markdown work scope.
- User-level installation and Project Catalog data live under the user's Bearing home directory.
- `.bearing/cache` is disposable projection data; source truth remains in canonical state and native work files.
- Portal's owner-facing Catalog API and UI show absolute repository roots. Screenshots and user-shared diagnostics may therefore reveal local paths and must be redacted before sharing.
- Direct loopback Portal uses HTTP, so its session cookie is not marked `Secure`; restarting the foreground Portal Host invalidates the session.
- Private Tailscale Serve or an owner-managed reverse proxy may provide private reachability, but the owner is responsible for TLS, authentication, access control, and exposure. Public unauthenticated Internet exposure is unsupported.
- Bearing is a local trusted-checkout tool. It is not a filesystem sandbox and does not claim safety against hostile concurrent filesystem mutation.
- Canonical project governance lives in `.bearing/state/`; native work stays in its selected local Markdown scope. `.bearing/cache` is disposable projection data.
- The Global Kit and Project Catalog live under your local Bearing home directory.
- Bearing performs no analytics, crash upload, repository upload, or update polling. An explicit install or update check accesses the package registry; feedback leaves your machine only when you submit it.
- Portal's owner-facing Catalog shows absolute repository roots. Redact local paths and private data before sharing screenshots or diagnostics.
- Direct loopback Portal uses HTTP; its session cookie is not marked `Secure`, and restarting the foreground Host invalidates the session.
- Private Tailscale Serve or an owner-managed reverse proxy requires you to manage TLS, authentication, access control, and exposure. Public unauthenticated Internet exposure is unsupported.
- Bearing is a trusted-checkout tool. It is not a filesystem sandbox and does not claim safety against hostile concurrent filesystem mutation.

Read [Data and security](docs/data-and-security.md) and [SECURITY.md](SECURITY.md) before sharing captures or changing private reachability.

## Feedback and support

- [Bug report](https://github.com/lagrangee/bearing/issues/new?template=bug_report.yml) and [Documentation problem](https://github.com/lagrangee/bearing/issues/new?template=documentation.yml): reproducible defects and actionable documentation problems. Blank Issues are disabled.
- [Q&A](https://github.com/lagrangee/bearing/discussions/categories/q-a) and [Ideas](https://github.com/lagrangee/bearing/discussions/categories/ideas): troubleshooting, experiences, and proposals that still need shaping.
- [GitHub private vulnerability reporting](https://github.com/lagrangee/bearing/security/advisories/new): suspected vulnerabilities. Never post them in a public Issue or Discussion.

Read more in [Data and security](docs/data-and-security.md) and [SECURITY.md](SECURITY.md).
Issues and Discussions are public GitHub data. Do not submit tokens, secrets, private source, complete planning state, real absolute repository paths, or unredacted screenshots. Share only the smallest redacted excerpt needed. Community support is best-effort with no SLA; public feedback is not a scheduling or delivery commitment.

## Learn, recover, and contribute

- [Getting started](docs/getting-started.md)
- [Everyday workflows](docs/everyday-workflows.md)
- [Data and security](docs/data-and-security.md)
- [Troubleshooting](docs/troubleshooting.md)
- [CLI reference](docs/cli.md)
- [Contributing](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Third-party notices](THIRD_PARTY_NOTICES)
[Getting started](docs/getting-started.md) · [Everyday workflows](docs/everyday-workflows.md) · [Troubleshooting](docs/troubleshooting.md) · [CLI reference](docs/cli.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Third-party notices](THIRD_PARTY_NOTICES)

Bearing is open-source under the MIT License.
Loading
Loading