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

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.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 "three_year" or "one_year". 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": 1,
  "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": {
    "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.

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.