North Star

The North Star constellation is the live, versioned, weighted representation of your project’s aim — the set of documents the whole loop pulls the product toward. It is a product object, not passive documentation: analyzers score against it, proposals cite it, and prioritization is justified by it.

Documents

A constellation is made of North Star documents. Each document is a set of tenets typed by concern — the recommended types are product, design, engineering, and agent experience, and you can define custom types per project. Documents move through a simple lifecycle:

draft ── activate ──► active ── archive ──► archived ── restore ──► active

Only active documents form the live aim. Activation mints a version, so an active document always has a citable head.

Versions

Documents are edited collaboratively in a rich editor (markdown in, markdown out — agents edit the same content over the API and their changes appear live in an open editor). Versions are minted explicitly, never per keystroke:

• Save version — an explicit save, with an optional message.
• Activation — activating a document with unsaved changes mints one.
• Analysis — when an analyzer is about to score against a document with unsaved changes, a version is pinned first, so every score cites an exact, immutable version.
• Repo sync — a synced document’s version records the git commit it came from.

Version history includes server-computed diffs between any two versions, and any version can be restored.

Repository import and sync

If your principles already live in git — a VISION.md, a design doctrine — import them. Two modes:

• Copy — a one-time import; the document becomes app-managed.
• Sync — the repository stays the source of truth. The document is read-only in the app, each push that changes the file mints a new version citing the commit, and sync failures are reported plainly on the document rather than going silently stale. You can detach a synced document later to make it app-managed, keeping its history.

Weights and the composite

Each document carries a weight. Effective weights are normalized over the active documents, and per-document scores roll into the project’s composite score through them — so if design matters more than engineering this quarter, the composite reflects that. Weight changes never mint versions, and each analysis run snapshots the weights it used so historical composites stay interpretable.

Tensions

Sometimes two documents pull in opposite directions — “ship fast” versus “never regress accessibility”. Stella Loop records that as a tension: a first-class object on the document pair, created by analyzer findings or by hand, with an open → acknowledged → resolved lifecycle and a required resolution note. Conflicts are surfaced, never silently averaged.

Working with the constellation

Keyboard on the constellation surface: n new document, j/k traverse, e focus editor, w weights, t tensions.

Where it flows

North Star-driven intents reference constellation documents in their scope; analysis scores against pinned versions and rolls the composite through the weights; review’s north-star lens grounds findings in your own doctrine; and every epic ultimately traces back to an aim expressed here.