Components

Schemas

The four JSON Schemas in spec/schemas/ — the contract every file in a workspace must satisfy. doctor enforces the parts that matter operationally; the schema files are the readable spec of the rest.

Core schemas

Every message, event, and workspace marker in the system validates against one of these four documents.

📐
agent.schema.json
agents/<name>/agent.json — identity card. Required: name, role, escalation_target.
spec/schemas/agent.schema.json
capabilities — machine-checkable, prevents v1's "assigned QA to an agent with no browser" failure
"capabilities": { "runtimes": ["node","bun","python"], "tools": ["browser","playwright","shell"], "mcp": ["asana","slack","supabase"] }
secrets_env — names only, doctor fails the workspace if a value-shaped string appears
"secrets_env": { "type":"object", "additionalProperties": { "pattern": "^[A-Z][A-Z0-9_]*$" } }
lane Planned — not yet a field
"lane": { "enum": ["heavy","light"] } # heavy = deep-context/high-stakes, eligible as a Convene scout # light = budget-constrained (e.g. Codex Plus-tier) — joins at # TEAM_SELECT/EXECUTE, never as scout. docs/07 §16.
📐
message.schema.json
Flat key:value header between --- fences atop every message file. Files are immutable after delivery.
spec/schemas/message.schema.json
id / thread patterns
"id": "^[MB]-\\d{8}T\\d{6}Z-[a-z2-9]{4}$" "thread": "^[TMB]-\\d{8}T\\d{6}Z-[a-z2-9]{4}$" "to": recipient slug, or '*' for broadcast "priority": ["normal","urgent"]
x-body / x-filename (informative, not JSON Schema keywords)
"x-body": { "maxLength": 2000 } "x-filename": "{thread}--{id}.md in recipient's inbox/ and sender's sent/"
📐
event.schema.json
One JSON object per line in events/YYYY-MM/events-YYYYMMDD.jsonl — the single source of truth. Readers skip malformed lines; doctor reports them.
spec/schemas/event.schema.json
type enum — 13 values
workspace.init, agent.added, message.sent, message.read, message.archived, status.set, ledger.note, checkpoint.created, escalation.raised, escalation.resolved, lock.acquired, lock.released, lock.expired, sweep.completed
x-data-shapes.status.set (informative)
{ "state": "WORKING|IDLE|BLOCKED|WAITING|OFFLINE", "task": "string", "blocked_by": "string", "note": "string" }
📐
workspace.schema.json
.ujima/workspace.json — its presence IS the definition of the workspace root. Committed to git.
spec/schemas/workspace.schema.json
Required + const
"protocol": { "const": "1.0" } "required": ["name","protocol","created"]
Real instance — this repo's own marker would read
{ "name":"my-team","protocol":"1.0", "created":"2026-07-18T...Z","ujima_version":"1.0.0" } # fleet-collab's ACTUAL .collab/workspace.json instead reads # protocol "3.0" / collab_version "3.0.0" — pre-rename, still live.