Work Orders & Context Packs

A Work Order is a bounded, versioned brief assembled before an agent run, so every launch is reproducible and the run ledger can answer exactly what the agent knew, could use, and was governed by at launch time. A Context Pack is the versioned, checksummed bundle of source context attached to a Work Order version.

The Work Order says what to do; the Context Pack records what the agent was allowed to know and use.

Lifecycle

Draft. Prepare a Work Order from a task's detail panel ("Prepare agent work"). A deterministic skeleton (objective, constraints from the task and its project) is generated so one click yields an editable draft. Edit the objective, acceptance criteria, non-goals, constraints, evidence required, and escalation owner. Draft edits are mutable and not individually audited.
Version. "Mint version" freezes the current draft into an immutable WorkOrderVersion plus a ContextPack, each carrying a sha256 checksum over its canonical JSON. Editing the draft afterward and minting again produces a new monotonic version — a running job never silently inherits edits.
Launch. The launch preview shows the context budget, source manifest, tool manifest, a policy-checks placeholder, and warnings. Launching pins (workOrderVersionId, contextPackId) onto a WorkOrderLaunch record — the run-ledger back-link. A completed run links back to the exact versions used.

Quick run

"Quick run" launches with a restricted tool set without authoring a full version: the system auto-mints a minimal QUICK-mode version + pack so the launch stays pinned and reproducible, skipping the high-severity warning gate.

Launch preview warnings

The preview computes advisory warnings before launch. High-severity codes gate the full Launch button (Quick run bypasses them):

Code	Severity	Fires when
`MISSING_ACCEPTANCE_CRITERIA`	high	No acceptance criteria defined
`MISSING_REVIEWER`	high	No escalation owner set
`AMBIGUOUS_OBJECTIVE`	warning	Objective is short or vague
`STALE_SOURCE`	warning	A pinned context source is stale
`HIGH_RISK_TOOL`	warning	A high-risk tool is in the manifest
`BUDGET_OVERRUN`	warning	Token estimate exceeds the project budget
`DECISION_CONFLICT`	warning	The brief appears to contradict an accepted decision

Decision-conflict detection is deliberately conservative (keyword overlap + an explicit contradiction marker) — it is advisory, never a hard block.

Launch-manifest projections

Context Packs project live governed state without making the bundle unbounded:

Budget remains a deterministic heuristic (≈chars/4) and records budgetSource: "heuristic".
Memory contains only non-expired ACCEPTED_TO_MEMORY items visible to the Work Order's workspace/project/board scope, capped for a stable token budget.
Skills contains the exact verified SkillVersion pins of the routed agent release; an unpinned launch correctly produces an empty list.
Runs links orchestrated AgentJobs/AgentRuns back to the immutable Work Order version and Context Pack they used. A bare request_run remains the lightweight fallback: it records a PENDING launch for an external runner.
Policy checks are still a legacy preview placeholder in the Context Pack. The live Policy Engine evaluates authority at each action boundary instead of trusting the frozen preview.

MCP tools

Work Orders have both read and write tools over MCP. The read tools below are read scope with readOnlyHint; dates are ISO strings and lists paginate.

Tool	Returns
`list_work_orders`	Work Orders in a workspace (task key, status, version/launch counts). Filter by `taskId` / `projectId` / `status`. Paginated via `cursor`/`nextCursor`.
`get_work_order`	A Work Order's draft fields, status, current immutable version, and latest launch (pinned version + context-pack ids).
`get_context_pack`	A Context Pack's manifest, checksum, token estimate, and budget source.

The Context Pack manifest has a stable shape:

{
  "sources": [{ "kind": "task|decision|doc|comment|artifact|repoPath", "refId": "...", "label": "...", "stale": false }],
  "memories": [{ "id": "...", "summary": "...", "provenance": "...", "freshness": "..." }],
  "repo": { "repos": [{ "repoId": "...", "branch": "main", "paths": [] }] },
  "tools": [{ "name": "get_task", "scope": "read", "riskClass": "low" }],
  "skills": [{ "id": "skill-version-id", "version": "3" }],
  "approvalPolicy": { "summary": "..." },
  "credentialGrants": [],               // intentionally empty; never secret material
  "budget": { "tokenEstimate": 1234, "source": "heuristic" }
}

Write tools (`write` scope)

Tool	What it does
`create_work_order`	Create a Work Order draft on a task (idempotent via `idempotencyKey`)
`version_work_order`	Freeze the current draft into an immutable version + Context Pack
`request_run`	Launch: pin a version and request an agent run (PENDING until a runner claims it)

Agents can never mutate a Work Order with an in-flight launch — the in-flight guard blocks version_work_order while a launch is pending or running.

For the orchestrated plan → review → execute → review loop, where a Work Order version is the reviewed, revised plan body advanced under human gates, start with request_agent_workflow rather than a bare request_run. See Agent workflows.