Capabilities, agents, and the Brief

A capability is one registered analysis — a name, a parameter model, a scope list, a function. Adding a domain adds an entry, never a tool.

That constraint sets the shape. Tool definitions load into every model turn, so a tool per domain degrades the model with each addition — and on the MCP side forces every connected user to re-add their connector. Entries are data; the tool surface stays fixed.

registry.py

What exists. Parameters are a pydantic model, so the description a model reads and the validation the dispatcher runs come from one class and cannot drift. A duplicate name raises at import.

dispatch.py

The single path in: validate, authorise, run, shape. Scope enforcement lives here, not in the route — a second enforcement point is a second place to forget.

envelope.py

One response shape, two independent guards. limit bounds rows; a byte ceiling bounds bytes, because fat rows breach an output cap without breaching a row count.

Several capabilities compute nothing of their own. regional_instock calls two others and judges what they return; the stock distribution matrix is a composition that registers nothing at all. If two surfaces could disagree about a figure, one of them is recomputing.

It is hired for a beat, told what it is accountable for, and every morning it files the same three things: what is working, what is not, and what to do about it. It exists before its first run and survives every rebuild.

The framing is not decoration. A report is defined by its output, so when it produces nothing you delete it. An employee is defined by its job, so a quiet morning is itself the report — and when it cannot do the work, yesterday’s still stands and somebody is told why.

Agents are named for the job, never the metric: Buying Planner, Transfer Planner, Run Rate Watch. Nobody asks a colleague for the days-of-cover report; they ask who is watching cover.

The anatomy

What it is expected to file

The morning report is a reading of the data, not a summary of it. Hits are what is going right and worth leaving alone — the half most reporting drops, and the half that stops a reader treating every morning as a crisis. Misses are what moved against the business, ranked by what they cost rather than by how bad they look. Next steps are what a person could actually do today.

An agent is also expected to say when it cannot answer. A refusal — no day in the last ten carries enough settled volume to judge a run rate — is a report, and a more useful one than a number computed on a feed that has stopped arriving.

Two ids, and confusing them is the defect

The agent id is minted once and never changes — it is the employee. The response id is minted per run and names one morning’s numbers — it is the memo. What a reader pins is the employee; a pin keyed to a memo would dangle every night.

Push, pull, and the gate

Agents push: they arrive on a schedule, unasked. Answering on request goes through the partner analyst instead, which already works with the reader’s standing context in front of it. A second answering path would be a second place for the groundedness rules to live, and a second place for them to drift.

The gate refuses loudly, with the reason in the sentence. An agent that silently answers nothing looks identical to an agent with nothing to say.

The morning pass

A team fires once and works its agents in order, sharing one timestamp, so “did the 06:00 pass happen” is one question. One agent’s failure is not the team’s failure — it is recorded, the pass moves on, and that agent’s previous reading stays up. Yesterday’s cover with an honest date beats an empty page.

A skill is authored judgment in markdown — how to read an answer, what is material, who owns the response. Prose is the only form a non-engineer can argue with.

Skills are not loaded whole. The spine is short and always loaded. Each block is its own file with a when: line naming the condition to pull it, and a manifest that parses when: lines only — never bodies. Instructions the model does not need now are not free; they compete for attention with the ones it does.

# knowledge/today_composition/blocks/
03-which-rung-to-show.md
  when: an answer carries more than one rung —
        channel, category, family
  cost: 600

06-when-the-answer-is-missing.md
  when: an entry is unanswered or stale, or a rung
        reports it could not be judged
  cost: 520

Two stores. Domain skills ride into a capability's payload, so the doc is reachable before you run an analysis and after you hold its result. Agent skills sit beside the code that reads them — a skill two directories from its only consumer goes stale when that consumer is rewritten.

The findings pass reads one agent. The Composer is the same seam one level up: it reads every watched risk and every agent at once, and decides what deserves a reader's first ten minutes.

It used to compose on every request — twenty readers got twenty different pages of one morning, behind a proxy ceiling of 120 seconds. Now the route is a read.

Four files, four jobs

the register

What is watched: each risk with a question, a capability, a freshness bound and a must_print flag.

pack build

Runs them. No model is involved and none ever will be — separating the choosing from the fetching is what stops a model deciding what the page looks at.

the composition

Picks emphasis, form and the lead, by reference.

the strip

Six figures code owns outright. No model sees them, orders them, or writes a word of them.

What an entry can come back as

Every strip tile names its frame (“across rows that fell short”), its denominator (“147 of 218 products costed”), its scope, and its freshness. A missing figure renders as unread, never as zero.

One place code overrules the model

Sections are a grouping over the register, not a second register. Their order is the model's ranking, with one exception: actions always lead. “Move 2,408 units from Mumbai to PMR” asks the reader to do something today; “cover is thin on four families” asks them to know something. A reader who only reads the top should still reach what they can act on.