Briefs

When a fleet of agents does the implementation, work units written as prose in a task tracker fail silently. Dependencies written as "after the auth brief" break on a rename with no error. A brief is a machine-readable contract: typed IDs, explicit dependencies, a parseable Verify table. The form forces the structure that makes drift visible.

Every brief carries YAML frontmatter and a structured body. The frontmatter is the parseable record; the body motivates but never solely carries a fact a script needs. These eleven fields are required — a brief missing any of them fails lint.

Several optional fields sit alongside them. The most consequential is exec-tier, which asserts a minimum class of model for the work and is derived from three complexity questions rather than chosen — see Model tiering. Others let a brief record why its gate is what it is, what is blocking it, what it is worth, and which downstream consumers a shared value change has to reach.

One honest note about the schema check: the validator confirms that every required field is present and well-formed, but it does not reject an unrecognised top-level key. A field name typed slightly wrong is silently ignored rather than flagged — which is why the required set is checked by presence, and why a brief's real contract is the fields listed above rather than whatever it happens to contain.

The Task is the implementer's instructions: numbered steps, exact paths, specific actions. It is accompanied by a files: listing (exact paths — no repo exploration needed) and facts: (the 3–5 project facts required to execute, in key: value form). A brief that touches a shared value — a party, env var, config key, field meaning, wire format — enumerates every consumer under consumers: with a disposition (fixed-here / follow-up / out-of-scope).

Every brief carries a Verify table: a list of executable checks. Each row has a literal command and an expected exit code or output. A row without both is not a DoD item; it is a hope. Evidence over claims is the whole discipline, and it starts here.

For prose deliverables (docs, articles), Verify rows assert presence: a file exists, a section appears, a token is present. Quality is owned by the human review gate — presence gates do not prove quality, and claiming they do is the exact anti-pattern the system exists to catch.

• Typed IDs only. References are stream/NN, F-NN, I-NN — never fuzzy names.
• Self-contained. If executing needs knowledge from another brief, link it in facts: or state it in depends:.
• Dependencies are typed and inverse. A brief in depends: must list this brief in its unblocks: (and vice versa).
• Wave consistency. A brief at wave N must only depend on briefs at waves < N.
• Provenance required. An empty sources: fails lint.
• Gate derived from risk. A brief with gate: model and any risk yes fails lint.

Briefs should be roughly equal-sized. A brief doing two distinct roles becomes two briefs. Rough test: if the Task needs more than about five steps or touches more than two subsystems, split at authoring time. Uneven briefs stall a wave and hide the real critical path.

Splitting a brief mid-execution counts as authoring, and it carries a rule that sounds petty until you have watched it go wrong: the session doing the split keeps only the piece it was actively working on, and every other piece returns to the board as an unclaimed item. Keeping the whole split set is the rabbit-hole reflex at brief granularity — invisible to the board, and never re-examined for what tier or gate the new pieces should carry.

A short brief in full, frontmatter first:

Read the fields against each other and the record is self-checking. customer: yes is why gate reads human — a brief claiming a model gate with that answer set fails lint, so the gate cannot drift from the risk it was derived from. wave: 1 is consistent only because its one dependency sits at wave 0. The unblocks entry has to appear as a depends entry on the other side, or the graph is broken and lint says so. And sources names a finding, so a reader who wants to know why this work exists at all has somewhere to go.

The body then carries the Task, the facts an implementer needs, and the Verify table — for a change like this one, rows asserting that the old code path is gone, that the replacement is exercised, and that a neighbouring consumer of the same serializer still works.