battlegrid-officers

Strategy Officers

A Strategy Officer is a review the player schedules: on its hour, or when the player runs it now, it reads each in-scope agent's record and records at most one proposal per agent for the player to apply, push or dismiss. The officer writes its reviews on its own turn, on its own model and brief. This flow is the player's side of it: setting an officer up, running it, reading where it stands, and acting on what it proposed.

Every officer run is billed to the player's LLM credit, and an applied proposal changes a live strategy, agent or Radar deployment. So a setup goes through its own draft, a run is started only on the player's word, and Apply is confirmed before it is called.

The four failures this flow exists to prevent

1. Writing a review yourself. Cue: "what would my officer say about…", wanting to record a finding. You read an officer's reviews and give your own reading in the conversation; only the officer records a review. → §2.
2. Applying without confirmation. Cue: "apply it", "make it live". Apply publishes the proposal to a live target. Show the review, then confirm through ask_user. → §4.
3. Computing what is served. Cue: working out the next run from the schedule, counting open reviews. Every status figure is on the read. → §3.
4. Committing a setup unasked. Cue: a staged officer that looks right. The commit is the player's word. → §1.

1. Set up and update an officer through its draft

• Read first. list_officers for the roster (each officer's schedule, scope, last and next run) and the presets, list_officer_drafts for setups part-way through, get_officer_draft for one draft.
• Create. stage_officer_draft with no officerId and draftVersion: 0 mints a new create draft; every later call names the minted id. Stage only what the player asked for — every axis the draft does not hold starts at its default (name "Strategy Officer", the catalog's default model, no instructions, DAILY at 03:00 UTC, all active agents, all three levers). "Add an officer that reviews my agents every morning at six and focuses on stops" is NAME, SCHEDULE { cadence: 'DAILY', hourUtc: 6, weekdayUtc: null } and INSTRUCTIONS { focusText } in the player's words — and ask which timezone "six" means before converting it to a UTC hour. Worked inputs: references/officer-stage-examples.md.
• Presets are starting points, staged as ordinary axes. When the player names one of the presets list_officers serves, stage its name, focusText and scope as NAME, INSTRUCTIONS and SCOPE; the officer remembers no preset.
• Axes are whole. SCHEDULE carries cadence, hourUtc and weekdayUtc (0 Sunday … 6 Saturday, for WEEKLY only, otherwise null); SCOPE carries both agents ('ALL' or agent ids from list_intelligence_agents) and levers; MODEL names a modelId from list_approved_models. INSTRUCTIONS are the player's brief in their own words: at most 2,000 characters, naming no tool and no id — the commit refuses either.
• Show, then commit on the player's word. Read get_officer_draft and show the diff, the diagnostics and the impact — nextRunAt is when it first runs, and a create's admission says how many officers the player holds against their account plan's officer limit and how many more it admits (officersRemaining). Every unarchived officer counts, paused ones included; a create past the limit is refused as PLAN_LIMIT_REACHED, and archiving an officer frees its place. Commit with commit_officer_draft naming exactly the draftVersion and committedRevision the read returned, and only when the player says so. A cadence of OFF keeps the setup and runs nothing on a schedule.
• Archive with archive_officer only on the player's word: an archived officer runs no more, and its open reviews stay in the inbox.
• In the app, the player sets an officer up in its own console, where this conversation may be docked beside the form — stage into the officer it is scoped to.