MCP Task Orchestrator · Field guidePlate 10 of 10

A process that proposes its own fixes

Friction noticed during work becomes a tracked item. Friction that recurs becomes a trend. A trend seen twice becomes a concrete proposal to change the config, and a person decides whether to adopt it.

The loop

A run finishes items reach terminal notes, observations Retrospective scores the run on five dimensions findings, by key Trend one item per recurring finding Sessions ≥ 2 Proposal the exact change to make /review-proposals A person decides accept, reject or defer accept Config changes edited and pushed per project applies to new items
Every stage is an ordinary work item with its own schema and gates, so the loop is tracked, attributed and resumable like any other work. Nothing changes the config without the human step. An adopted change applies to new items; an item already in flight keeps the schema it was pinned to until items_write repin.

What starts a retrospective

A retrospective is owed for each closed run that is not yet marked retro. The retro-trigger hook watches runs_write and acts only on a successful close. At the end of every turn retro-backstop checks again, so a run closed by another session is found too, when the hook can reach REST with a project rootId. That pass looks back 24 hours and checks at most 5 runs. What happens next is set by extensions.claude-code.retrospective.mode in the project config.

nudge, the default

The session is told a retrospective is suggested and given the command to run. The user decides.

dispatch

When at least dispatchThreshold of the run's items (default 3) reached terminal, the hook tries to mark the run, and the session that wins the mark is told to launch one background retrospective agent. A session that loses the race stays silent. Smaller runs still get a nudge, and so does a run whose mark failed. A director session is always treated as dispatch unless the mode is off: a run that would only be nudged is named in its dispatch directive instead.

off

Nothing is emitted. Retrospectives run only when someone invokes /task-orchestrator:session-retrospective.

The dedupe is server-side: runs_write mark with key retro, first write wins, so two sessions never both dispatch. The mark is REST only. There is no cooldown. Without REST or a project rootId the hook only records the close, and the end-of-turn backstop nudges once. Work done outside a run has no trigger, so run the skill by hand. The settings are read only from extensions.claude-code.retrospective; a top-level retrospective: block is not read.

By hand, --run <runId> scopes the analysis to one run. --deep hands the trend matching to the retro-analysis workflow, in the main session only; the skill still performs every write.

What the retrospective reads and scores

It reads the session-tracking note on each item of the run (up to 20), plus the optional delegation-metadata note. Its provenance line records each seat's model and effort, the token and transcript meters, and any seats that ran outside the run. A layer-meters line adds the same four meters for the two layers above the seats, the tier-2 coordinator and the launching session, and the retrospective shows them in a separate per-layer table beside the seats' sum. That line is layer cost, not a delegation, so it is not scored. When the dispatch passes the session folder, it also sweeps every agent transcript of the session and writes a session coverage table to session-metrics: token volume by class and by meter, the main session on its own row, and the recorded share, the part of that volume whose agent label a run item's delegation-metadata names. No prices are involved. Then it scores five things.

The result is a retrospective item under the Session Retrospectives container, with queue notes session-metrics, workflow-evaluation and improvement-signals, and a work note actions-taken written last.

A trend is a counter with evidence

title:   trend: thin-review-checklist — review notes
         restate the plan instead of checking it
summary: Reviewers copy acceptance criteria without
         evidence. Sessions: 2. Last seen: 2026-09-30.
type:    retrospective-trend
tags:    ["retrospective-trend", "note-quality"]

notes:   evidence-2026-09-24-4c1e   (work)
         evidence-2026-09-30-b07a   (work)

Matched by key

The short key in the title is the trend's identity. A new finding is matched to an existing key first, then by search when the match is uncertain.

Recurrence adds evidence

Each session that sees the finding again adds one evidence note and increments the count. The summary is rewritten to stay short.

Two sessions make a proposal

A trend at Sessions: 2 or more graduates. Trend items are never started or completed. They are cancelled when archived. Evidence notes are added as needed, not required by the schema.

The example values are illustrative. The format is the skill's own.

Deciding a proposal

A proposal is a work item with three required notes, one per phase: proposal, adoption-decision and outcome-verification. Pick a scope and a decision to see where it ends up.

Scope of the proposal
Decision

A project proposal changes one project's schemas or workflow. A global proposal changes the shared server config or the plugin itself.

    Observations: the raw material

    An observation is a small item recording something the tooling got wrong or made hard. Each is its own root, low priority, tagged agent-observation plus one kind.

    optimizationfrictionbugmissing-capability

    Before one is created, the backlog is searched for the same issue, so repeats add context to an existing item. They stay outside every project because tool friction is not specific to one codebase.

    Process schemaNotes, by phase
    agent-observationqueue observation-detail · work resolution (optional)
    session-retrospectivequeue session-metrics, workflow-evaluation, improvement-signals · work actions-taken
    improvement-proposalqueue proposal · work adoption-decision · review outcome-verification
    retrospective-trendAutomatic lifecycle, no required notes. Evidence notes are added as the finding recurs.
    containerManual lifecycle, so a container never closes when its children do. An optional queue container-summary.
    projectPermanent lifecycle, no notes. The root that per-project config hangs from.

    These six schemas are the process-schema floor: the server config every project sharing the server inherits, imported into the database on every boot. An item gets its schema from its type; tags only filter. That is how the loop works across repositories with no per-project setup.