TECHNICAL DRAWING · SCHEMA + DIAGRAMHANDOVER® V4
One schema file · Two diagrams drawn from it

Field Kit
& Graph

The updated schema for Handover, with the diagram of the field kit and the diagram of the graph on one page. Tap any part of either diagram to see exactly where it lives in the schema.

A field kit is the reusable playbook for one field. A graph is how a run orders its work: units, links, splits, and joins. The schema describes both, and this page is drawn from data that validates against it.

SCHEMA JSON Schema Draft 2020-12 MATCHES SKILL.md v4 · Nov 5, 2026 ROOT anyOf: fieldKit | graph
Jump to full schema ↓

Where this lives in the repo

THE SCHEMA · UPDATED
skills/local-handover/handover-schema.json

The machine-readable contract. One file, two definitions: $defs/fieldKit and $defs/graph (with $defs/unit).

THIS PAGE · THE DIAGRAM
docs/field-kit-and-graph-diagram.html

The interactive diagram page. Same content as this artifact: tap the kit parts and the graph nodes, read the schema underneath each one.

THE SOURCE OF TRUTH
skills/local-handover/SKILL.md

Handover v4. Step 5 defines the field kit. The Graph section (items 1 to 8) defines the graph. The schema follows the skill, never the other way round.

12 + 4

Kit fields in total: 12 required, 4 optional, in $defs/fieldKit.

5

Required fields per unit: name, output, owner, check, passes. No output file means not a unit.

1

Field that ever changes while a run works: passes, false to true, per unit.

Schema at a glancehandover-schema.json

The root shape One JSON file can hold a field kit, a graph, or both together. That is the whole top level: everything else lives under $defs.

$id
github.com/richardsondx/handover/…/handover-schema.json

Canonical location of the schema file in the repo.

title
"Handover field kit and graph"

Matches Handover v4, skills/local-handover/SKILL.md.

$defs
fieldKit · graph · unit

Three definitions. Graph units point back to unit with $ref.

The one root rule: anyOf: [ { required: ["fieldKit"] }, { required: ["graph"] } ], a file with neither a kit nor a graph is not a Handover file. A file with both is the normal case: the kit that runs, and the graph it runs as.
Diagram ①: The field kit$defs/fieldKit · Step 5 of the skill

Anatomy of a field kit From Step 5: inspect, generate, prove, maintain. A minimum viable kit is one router, genuinely distinct playbooks, concise principles, four roles, verification and cleanup routines, and a capability map, plus a lever: a tool or API the agent can actually drive. Tap a part to inspect its schema entry.

Proof status is part of the schema, not a boast: proofStatus is an enum, "proven" | "draft" | "proof failed". One passing task does not establish coverage of a field, and a generated kit that was never executed is a draft.

Diagram ②: The graph$defs/graph + $defs/unit · Graph items 1–8

How a run is ordered Loop retries a fail. Graph orders the work. A link means the later unit needs the earlier unit's output: that is exactly what dependsOn says. No link means the units can run apart. Tap a node to inspect the unit.

Router decision for this example graph · graph.decision = { mode: "graph", reason: "…" }
Mode is "graph" because the job splits into parts with no dependency between them, some parts depend on others, and a later part needs both. Loop alone is the default for one straight line with one deliverable. The reason is always written in the graph file.
SOLID LINE = dependsOn · DASHED LINE = HANDOFF RESEARCH dependsOn: [] DRAFT parallel branch CHECK dependsOn: [research] ◆ JOIN needs all inputs EACH UNIT HAS ITS OWN LOOP · UP TO 5 FIX CYCLES PER RUN, SHARED DEAD END AFTER 3 DISTINCT APPROACHES FOR THE SAME FAILURE CLASS
Start unit, no dependency Join: 2+ dependsOn entries Handoff edge (item 8)
Join rule (item 3) and verification at the join (item 6): a join unit waits for all its inputs and never runs early. If an input is missing, the join waits or the run reports a dead end. At the join, a fresh checker reopens every link and every unit output: a link to a missing file is a fail, and the judge passes only if all links check out. In this environment serial execution stands in for parallel (item 7): independent units run one after the other, in order, with no dependency between them.
The per-unit listgraph.units · one entry per unit

Only passes ever changes The graph ships with a JSON list of every unit. Each entry starts with passes: false. Later agents change only that field, to true, when the unit's check passes. They never remove a unit, never edit a check, and never rename a unit to hide a failure. Try it: flip each unit below as if its check had passed.

Unit (name)OutputOwnerCheckdependsOnpasses
0 of 4 units pass · Not done. Done means every unit passes.

This is the same shape as skills/local-handover/units-template.json, extended with dependsOn from the graph definition. The template in the repo is the minimal starting file; the schema above is the full contract.

The updated schema, in fullJSON Schema Draft 2020-12

handover-schema.json This is the complete schema: every definition, requirement, and description from the file held with the skill, pretty-printed for reading. Copy it into the repo at skills/local-handover/handover-schema.json, or download it as a file. The diagrams above are drawn from the definitions in this text.

Diagram to schema mapEvery drawing has an address

Where each drawing lives If it is on a diagram above, its schema path is here. If it has no path, it does not belong on the diagram.

On the diagramSchema pathRule it carries
Kit tile: Router$defs/fieldKit.properties.routerRequired. Matches a task to the right playbook. Needs a description.
Kit tile: Playbooks$defs/fieldKit.properties.playbooksRequired, minItems 1. Each playbook needs a name and steps.
Kit tile: Roles$defs/fieldKit.properties.rolesRequired, all four: coordinator, generator, verifier, judge. Author is never verifier.
Kit tile: Capability map$defs/fieldKit.properties.capabilityMapRequired, minItems 1. Each area names its routes, requirements, checks, and known limits.
Kit tile: Lever$defs/fieldKit.properties.leverRequired. A tool or API the agent can actually drive, not just prose.
Kit tile: End-to-end check$defs/fieldKit.properties.endToEndCheckRequired. Steps a human would take on the real artifact, plus what passing looks like.
Graph decision box$defs/graph.properties.decisionRequired. mode is "loop" or "graph", and the reason is written in the file.
Graph node$defs/unitRequired: name, output, owner, check, passes. No output file means not a unit.
Solid arrow$defs/unit.properties.dependsOnEmpty means parallel. Two or more entries makes the unit a join.
Dashed arrow$defs/graph.properties.handoffsOptional. A transfer of control between agents, pattern "manager" or "handoff". Not a dependency.
Loop limits$defs/graph.properties.limitsOptional. fixCyclesMax defaults to 5, distinctApproachesBeforeDeadEnd defaults to 3.
passes pill$defs/unit.properties.passesBoolean. Starts false for every unit. Done means every unit passes.
Field kits on recordFrom FIELD-KITS.md, checked Nov 5, 2026

The index the schema describes These are the kits the "list field kits" command reads back. Proof status is stated plainly: a pilot is not field coverage.

  • Research brief kit

    Research briefs and evidence synthesis. Pilot, single supervised run, not field coverage.

    workspace/handover-v1/kits/research-brief/
    PILOT
  • Handover persistent loop kit

    Relentless fix loop for any Handover run: classify failure, distinct approach ladder, loop budget, fresh verifier each cycle. Proof passed Nov 5, 2026.

    workspace/orchestrator/handover-2026-11-05-persistent/kit/
    PROVEN
  • Handover graph kit

    Graph from a simple directive: router, units and links, split and join, loop per node. Proof passed Nov 5, 2026, judge PASS.

    workspace/orchestrator/handover-2026-11-05-graph-v3/kit/
    PROVEN

In schema terms, each entry above is a fieldKit with a name, a field, a proofStatus, and a path. Older kits are added when they are next reused, not backfilled by guessing.