DEVELOPER DOCUMENTATION

Set Up Shared Job Operations

Let OpenTrain detect missing operating context and guide one authorized agent through a safe, shared setup for the whole employer team.

You do not need to know which Shared Job Context records a new job requires. When an authorized agent enters a job through a synchronized CLI or MCP operation, OpenTrain checks the job’s operational setup automatically.

If the operating brief, typed readiness workflow, or a required operating choice is missing, the response recommends guided setup and names the exact next operation. The agent reads the setup packet, explains the missing decisions, and walks the responsible employer team member through them.

What happens automatically

On every covered job-management response, the agent inspects the additive sync envelope. While setup is incomplete, it includes recommendation.job_setup_incomplete. A new session’s sync.nextOperations leads with job_operations.setup.get.

The setup packet tells the agent:

which setup components are complete, missing, deferred, or indeterminate;
the canonical evidence behind each result;
the ordered questions that still require a person;
proposed defaults supported by current job data;
the exact canonical writes that an approved answer would produce;
whether another agent already owns the setup flow; and
how to recover when the bounded evidence scan is incomplete.

An agent should not ask the user to discover this page or guess that setup is needed. The recommendation and MCP/CLI instructions drive the flow.

One agent guides the team

Several project managers may enter the same job at once. OpenTrain uses a write-ahead setup.* intent to ensure only one agent presents the setup questions.

The safe sequence is:

Read setup

The agent reads the current setup packet and its complete in-progress view. If another setup intent or proposal is active, the agent stands down and coordinates with its owner.

Declare the work

The agent declares a setup.* intent before prompting anyone. If OpenTrain returns DUPLICATE, that response identifies the current winner but does not transfer ownership.

Prove session ownership

The winning agent confirms that the intent’s non-null sessionId equals the current response’s non-null sync.session.sessionId, with the same principal. Knowing another agent’s intent ID is never enough. A null or mismatched session means the agent must establish its own durable identity or coordinate with the owner.

Present a zero-write plan

The winning agent presents the questions, evidence-backed defaults, and exact proposed changes to the responsible person. Unanswered required choices remain unresolved; the agent does not guess.

Apply only after approval

Immediately before applying an approved plan, the agent reads setup again and proves that the same session still owns the intent. It then uses the normal guarded brief and typed-policy operations with the current context revision and idempotency keys.

Verify and hand off

The agent reads setup again, resolves its intent, and records a handoff. Once the shared status is COMPLETE or DEFERRED, every employer agent stops prompting the team about that component.

This ownership check is important when two agents use the same employer account. The visible winner ID coordinates the agents; only the server-confirmed durable session proves which process owns the flow.

Use the CLI wizard

The CLI exposes a staged, machine-readable wizard:

opentrain manager setup status --job-id <job-id> --json

opentrain manager intents declare --job-id <job-id> \
  --idempotency-key setup-guided-<job-id> \
  --kind WORKFLOW_CHANGE \
  --intent-key setup.guided \
  --title "Guided setup"

opentrain manager setup plan --job-id <job-id> \
  --adopt-intent <your-intent-id> \
  --objective-file objective.txt \
  --workflow-file workflow.json \
  --training-gate COURSE_COMPLETION \
  --out approved-setup-plan.json

opentrain manager setup apply --job-id <job-id> \
  --plan-file approved-setup-plan.json \
  --confirm-live

status and plan are read-only. plan emits a deterministic receipt and lists unresolved choices. apply rejects an edited or stale plan, a copied plan from another session, unapproved execution without --confirm-live, and any ownership or context change detected after approval.

The example flags are illustrative. The setup packet tells the agent which questions and flags apply to the current job.

Use MCP without a separate prompt

The MCP initialize response teaches the guided flow automatically. The agent begins with opentrain_get_job_setup, then uses the existing intent, brief, policy, verification, and handoff tools.

The setup tool is read-only. It does not create a brief, select a workflow, defer a requirement, or contact a team member. The agent presents the proposed plan for approval and applies approved changes through the normal authorized tools.

Defer a decision explicitly

If the responsible employer approves postponing one setup component, the agent records an attributed, typed setup-deferral policy. A deferral can expire and does not pretend the missing component was completed.

If the packet reports INDETERMINATE, the agent does not prompt or plan from it. It follows the packet’s evidenceRecovery read and retries after the missing evidence is available.

Shared Job Context

Understand the shared operational model, authority, and synchronization.

Manage a live job

Continue with priorities, claims, canonical checks, and handoffs after setup.

Agent Guide

The guidance document every agent reads after setup: typed projection plus the human-published Playbook.

CLI: Shared Job Context

See the complete opentrain manager command family.

MCP: Shared Job Context

See the tools and automatic initialize protocol.