---
type: standard
status: active
scope: core
appliesTo:
  - All dispatches between an orchestrator and a worker
---

# Briefing Contract Standard

The structured prompt an orchestrator hands to a worker. Every dispatch; whether a single subagent invocation, a task-group worker, or any future mechanism; uses this contract. The structure is mechanical because every missing field is a question the worker has to ask, and every question costs a round trip we cannot afford to a worker running detached.

The big rule, drawn from Cognition's published failure analysis, is the **trace field**: every brief must include the reasoning that led to the task, not just the task description. Without it, workers re-derive context from scratch and make locally consistent but globally incompatible choices.

---

## The contract

Every brief MUST include all of these fields, in this order. Section headings are mechanical; copy them verbatim.

```markdown
# <Task name>

## Goal
<one sentence; what success looks like>

## Trace; why we're doing this
<one paragraph; the reasoning that led to this task. Decisions already
made, alternatives ruled out, the broader context the worker needs to
make consistent choices. Do not skip this section. Cognition's Flappy
Bird failure happens when workers are briefed without context: they
embed conflicting assumptions and the integration step is forced to
reconcile two miscommunications.>

## Context
<paths, files, decisions already made, constraints, relevant operator
preferences. Extracted from the operator profile for this task; do not
send the full profile. Reference standards and existing patterns by
path so the worker reads the canonical source rather than a paraphrase.>

## Tools and sources
<which tools the worker should use, which to avoid, where to find
authoritative information. If the worker should consult specific
existing files, list them. If the worker should NOT touch certain
files or systems, say so explicitly.>

## Boundaries
<what is in scope, what is out of scope. The boundary between "decide
yourself" and "escalate to me" should be explicit. Reference the
worker's autonomy envelope if relevant.>

## Output format
<exactly what the worker returns. File paths, document structure,
length cap, format. Vague output specs produce vague outputs.>

## Done when
<concrete acceptance criteria the worker can self-check. "Tests pass"
is not enough; say which tests, how to run them, what counts as pass.>

## Escalation rule
<when the worker should stop and escalate rather than guess. Default:
"if any of the above fields is unclear or you encounter a constraint
not covered here, stop and report the question rather than guessing."
Customise per task.>
```

If your brief is missing any of these fields, **do not dispatch**. Write the missing field or fall back to in-thread execution.

---

## Field-by-field rationale

### Goal

One sentence, outcome-shaped. Not "implement function X"; "the system can do Y when Z". The goal is what the worker checks against when it thinks it might be done.

### Trace; the load-bearing field

This is the field most often missed and most often the cause of bad outcomes. The trace tells the worker *why* this task exists, what alternatives were considered, what decisions were already made and why. Without it, the worker re-derives context from scratch, and its derivation may not match the orchestrator's.

Cognition's Flappy Bird example: one subagent built Mario-style art, another built incompatible bird sprite, the integrator had to reconcile two miscommunications. The cause was not poor briefing; it was *briefing without trace*. Each subagent made consistent local choices that were globally incompatible.

The trace prevents this by sharing the orchestrator's reasoning. It does not need to be long. Three to six sentences is usually enough. What matters is that the worker reads it before acting.

For task groups of 2+ workers, the trace lives in the shared context store and every worker reads it at the start of every action. The brief still includes a per-worker trace summarising the *worker-specific* reasoning, but the broader trace is in the context store.

### Context

The "what"; paths, files, constraints, operator preferences. Distinct from the trace (which is the "why"). Extracted and tailored; never the full operator profile. The worker should not need to read the operator profile to do its job; the orchestrator has already extracted what's relevant.

Reference existing standards by path. Do not paraphrase a standard in a brief; the worker should read the canonical source so the standard's evolution propagates.

### Tools and sources

Explicit. Workers default to "use whatever tool seems right" which is sometimes wrong. If the task requires WebFetch, say so. If the task forbids modifying files outside a specific path, say so. If the worker should consult a specific reference document before starting, list it.

### Boundaries

Where decision authority sits. The default is "decide-alone within the goal, escalate everything else". A more constrained envelope might be "decide-alone within these specific files, decide-and-log everything else, escalate anything affecting external systems". A more permissive envelope might be "you have full latitude on architecture and implementation; report decisions in your final output".

The autonomy envelope of the worker's role is the default. The brief can tighten it for this task but should not loosen it without explicit reason.

### Output format

Exactly what the worker returns. File paths, length cap, structure. Vague output specs produce vague outputs and force the orchestrator to re-derive structure when integrating.

For detached dispatches: the worker writes a report file at a known path. The orchestrator reads the report, not the worker's full context.

### Done when

Concrete acceptance criteria. The worker checks against these before declaring done. "Tests pass" alone is not enough; which tests, how to run them, what counts as pass. Vague done criteria produce work that "looks done" but isn't.

### Escalation rule

The default escalation rule is the standard one: *if any field is unclear or you encounter a constraint not covered here, stop and report the question rather than guessing*. The brief can customise this; for example, "if you discover the existing implementation is broken in a way that affects your task, fix it and report; do not escalate for a same-file fix".

The escalation rule is also where the brief makes peer coordination explicit when the worker is part of a task group: "do not communicate with other workers in this group directly; coordinate via the shared context store at <path>".

---

## Brief size signals

A brief shorter than ~50 lines for a detached dispatch is **usually** under-specified. The fields above can all be terse, but the trace and the done criteria in particular are rarely complete in fewer than ten lines combined. If your brief is short, check whether you're missing the trace; that's the most common cause.

A brief longer than ~300 lines is **usually** over-specified. If you're prescribing every step, you're not delegating, you're remote-controlling. Step back and ask whether the worker has enough autonomy to actually be useful.

---

## Bolt-on: worktree-isolated dispatches

Any dispatch with `isolation: "worktree"` must include the following in its **Boundaries** section, verbatim or equivalent:

> **Phase 0; cwd verification:** Before ANY file-write or git op, run `pwd` and verify the output is inside `.claude/worktrees/agent-<id>/`. If not, `cd` to the worktree root before proceeding.
>
> **Worktree absolute-path rule:** Every absolute path passed to Write, Edit, MultiEdit, or Bash (for writes) MUST begin with the worktree root; typically `<project-root>/.claude/worktrees/agent-<id>/...`. Paths beginning with the main worktree root (no worktree segment) are the MAIN worktree and writing to them is forbidden for source changes. Absolute paths are still fine for READING context files from main; the rule applies to writes only.

**Why both rules:** Phase 0 catches shell-cwd drift. The absolute-path rule catches Write/Edit tool calls that use absolute paths (the default behaviour in some agent runtimes), which bypass `cwd` entirely. Phase 0 alone is necessary but not sufficient; field experience has shown dozens of file changes landing in main via absolute paths despite a passing `pwd` check.

**Recovery playbook** (when a worker writes to the wrong worktree):
1. `cp <file-in-main> <worktree>` for every intended edit
2. `git -C <main> checkout -- <file>` on files the worker themselves modified (surgical; never `git checkout .`)
3. `rm <main>/<file>` for untracked files the worker created

---

## Bolt-on: specification quality checklist

When a brief's **Context** or **Goal** includes consuming a structured payload (API response, config file, event schema) to gate decisions or rendering, the brief must address:

1. **Effective-value rule.** If the payload contains multiple fields describing the same phenomenon (e.g. `overall.indicator` vs per-incident `impact`), the brief MUST define how to reconcile disagreement. Do not pick one field arbitrarily.

2. **Shell-path test coverage.** If the output is UI rendered inside an iframed shell (a workspace shell or any future wrapper), the **Done when** must include at least one e2e test that navigates through the shell, not just direct-to-page loads.

Both rules derive from incidents where individually-passing specs missed real user-path failures.

---

## See also

- [`tooling.md`](./tooling.md); the tooling standard that briefs reference for any worker that writes internal tooling.
- Operator extensions: an operator's `operator/knowledge/engineering/standards/briefing-contract.md` (when present) MAY add operator-specific bolt-ons but MUST NOT relax this contract.