Compass authoring guide

The Compass is the company's stated direction: its purpose, principles, and the goals that cascade into work. On the CLI and MCP path you author the Compass directly — you synthesize a finished document from the company's own context and submit it. The server validates and stores it; it does not re-write it. Read the exact contract first with command.describe (rost command schema compass.draft), which returns the JSON Schema and a validated worked example.

How to derive a Compass from company context

Attach the company's real documents as references first (onboarding.attach_reference): read each meaningful doc — strategy notes, planning decks, founder transcripts, metrics — convert it to markdown, and attach it with a title, kind, and source. If you are running under an implementation-bootstrap credential, that command is not yours to call — it is deny for the bounded principal, and while your run is active your (headless) invocation is refused outright, naming the missing implementation route, rather than falling back to the owner's session (DER-3255). An explicit interactive terminal remains the owner's own deliberate path for it, which is why a human at a keyboard can still attach one. Retain the same documents with onboarding.source_ingest instead, and reference them from the setup plan's sources[]. Then author the Compass from what those documents actually say, citing them through source_ids. Do not invent direction the company has not expressed; where the company has not decided something, record a gap instead of guessing. In the web app these attached documents appear in the Compass Context sources panel (/compass#context-sources, also reachable via /compass/context-sources).

Every Compass field is a "field" object

Each direction field (purpose, each principle, each goal title and definition of done) is an object, not a bare string:

{ "value": "the stated text", "citations": [], "confidence": 0.9, "placeholder": false }

• value: the statement itself, in the company's own words.
• citations: an array of source citations; may be empty when you author from first-hand company docs. When you do cite, reference an attached document.
• confidence: 0–1, how sure you are this reflects the company's real intent. Lower it when you inferred rather than read it.
• placeholder: true only when you are leaving a deliberate stub to be answered later. A placeholder should be paired with a gap.

Field-by-field

• purpose — why the company exists, beyond making money. Good: "Help small manufacturers ship quality products on time." Weak: "Be the best in our industry" (no one is served, nothing is testable).
• principles (1–5) — the few operating beliefs that actually decide trade-offs. Good: "Customers feel the quality of every order." Weak: "Integrity" (a value label, not a decision rule). Keep it to the handful that change behavior; more than five dilutes them.
• horizon_goals.ten_year (optional, schema_version 2), horizon_goals.three_year, and horizon_goals.one_year — each a goal object with a title and a definition_of_done, both "field" objects, plus a horizon of "ten_year", "three_year", or "one_year". The 10-year horizon is additive: a human adds it through a new, superseding Compass version — never by editing an accepted doc. The definition of done must be checkable: "Trailing-12-month ARR ≥ $3M and on-time delivery ≥ 99% for two consecutive quarters," not "grow a lot."
• cycle_objectives (1–3) — the goals for the current cycle, each a goal object with horizon: "cycle". These are what the company is actually working on now and should ladder up to the one-year goal.
• gaps — questions the documents did not answer. Each gap has an id, the field it blocks, a question, a severity (required or recommended), and a reason. Record a gap rather than fabricating a value.
• follow_up_tasks — concrete tasks that close a gap, each tied to a gap_id with acceptance_criteria.
• source_ids — the ids of the attached reference documents this Compass draws on; this is how the Compass cites its evidence.

The full JSON shape

{
  "schema_version": 2,
  "purpose": { "value": "Help small manufacturers ship quality products on time.", "citations": [], "confidence": 0.9, "placeholder": false },
  "principles": [
    { "value": "Bias to action; decide with the information we have.", "citations": [], "confidence": 0.9, "placeholder": false },
    { "value": "Customers feel the quality of every order.", "citations": [], "confidence": 0.9, "placeholder": false }
  ],
  "horizon_goals": {
    "ten_year": {
      "title": { "value": "Reach $250M enterprise value", "citations": [], "confidence": 0.6, "placeholder": false },
      "definition_of_done": { "value": "An independent valuation is at or above $250M.", "citations": [], "confidence": 0.6, "placeholder": false },
      "horizon": "ten_year"
    },
    "three_year": {
      "title": { "value": "Reach $10M ARR with a 25-person team", "citations": [], "confidence": 0.8, "placeholder": false },
      "definition_of_done": { "value": "ARR is at or above $10M and headcount is 25 with no key-role gaps.", "citations": [], "confidence": 0.8, "placeholder": false },
      "horizon": "three_year"
    },
    "one_year": {
      "title": { "value": "Hit $3M ARR and 99% on-time delivery", "citations": [], "confidence": 0.85, "placeholder": false },
      "definition_of_done": { "value": "Trailing-12-month ARR ≥ $3M and on-time delivery ≥ 99% for two consecutive quarters.", "citations": [], "confidence": 0.85, "placeholder": false },
      "horizon": "one_year"
    }
  },
  "cycle_objectives": [
    {
      "title": { "value": "Cut order-to-ship cycle time by 20%", "citations": [], "confidence": 0.8, "placeholder": false },
      "definition_of_done": { "value": "Median order-to-ship time is 20% below the prior cycle baseline.", "citations": [], "confidence": 0.8, "placeholder": false },
      "horizon": "cycle"
    }
  ],
  "gaps": [],
  "follow_up_tasks": [],
  "source_ids": []
}

A second example (services company)

A consultancy's purpose might be "Make expert tax guidance affordable for first-time founders"; a principle, "We turn around every client question within one business day"; a one-year goal, "Retain 90% of clients across a full tax year." The shape is identical — only the values change.

get_current is not the draft shape

compass.get_current returns the active and draft versions with version metadata and source documents; it is not the same shape you submit to compass.draft. Do not round-trip get_current output straight back into draft. Author the draft shape above and submit that.

When the vision is withheld

The surfaces that hand the ACTIVE version to you as the company's direction validate the stored document against the contract above first: the seat-context bundle, the agent runtime's own context, and compass.alignment. A document that was accepted under an older, looser contract — or written by an import or a direct database write — is withheld from those rather than passed off as the live company vision. Read that as the narrow claim it is, not a guarantee about every read of the table: a document you were handed somewhere else is not valid because you were handed it. Judge by the status field below, never by the fact that a document arrived. Repairing a rejected one is an owner's job on the Compass page — do not route around the withholding to fetch it yourself.

The seat-context bundle (rost_get_context, or rost://seat/{id}/context read with a seat-scoped token) always carries compass_status:

A null document alone cannot tell absent apart from invalid, which is why the status field exists: always read the status rather than inferring from the document. The other two surfaces that hand you the active version behave the same way — the agent runtime withholds a rejected document and tells the agent so, and rost command compass.alignment fails with the violated constraint instead of reporting that no vision is configured.

The repair is always a superseding version through compass.draft → compass.approve_version, never an edit to the stored document in place.

The authoring workflow

1. compass.draft — submit the document above. Drafting is safe for an agent; it returns a compass_version_id. 2. compass.list_gaps — see what is unanswered. compass.answer_gap records a human's answer and produces a fresh draft. 3. compass.update_draft — revise the draft as answers arrive. Pass the same compass_version_id from compass.draft as draft_id; the command replaces that unpublished draft in place and returns the draft row's current version number. If the id is missing, belongs to another tenant, or is already approved or rejected, start from compass.get_current instead of retrying blindly. 4. compass.approve_version — activation by supersession. This is human_required: a human approves it. Prepare the draft and surface the approve link; do not approve on a human's behalf. See the confirmations guide.