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