Cadora · design spec

The surfaces of a run

Everything needed to rebuild or extend the two surfaces a gated run is watched on — the dashboard DAG canvas and the terminal. The exact tokens, the node's anatomy, its states, the run-line grammar, and how each control behaves. The rendered components are live HTML; edit them here or lift the specs into Figma.

Palette

Dark instrument surface · light node chips carry status by hue

Ink--bg · #0f172aPage & canvas ground

Green--green · #16c784Gate pass · completed

Red--red · #fb7185Gate fail · stopped

Amber--amber · #ffd08aHuman needed · warn

Blue--blue · #3b82f6Running · in review

Muted--muted · #9aa8bcSecondary · captions

Canvas--canvas · #111c2fInset panels

Line--line · #334158Borders

Text--text · #f5f7fbPrimary

Green-soft--green-soft · #75f0a8Completed node fill

The DAG node is a light chip on the dark canvas: completed fills #75f0a8, running / in-review #93c5fd, failed #fda4af, idle #d5dbe7 — status is legible from the fill alone, before you read a word.

Type & metrics

System sans for reading · monospace for the instrument voice

Role	Family	Size / weight	Notes
Node title	system-ui	13px / 800	The topology node id
Node role · sub	system-ui	11px / 600	analyst · architect · engineer, 0.72 opacity
Status pill · badge	system-ui	10px / 700	Sentence case; badge label is <kind> <value>
Cost · tokens	system-ui	10px / 700	$0.0000 (4 dp) · 22.4k / 1.20M
Terminal line	mono	12px	Glyph + node + fields, single line
Time · duration	system-ui	13px	2m 30s · 1.4s — never raw ISO

Metric	Value	Metric	Value
Node width	170px	Node radius	6px
Badge radius	4px	Pill radius	999px
Canvas ground	#0f172a	Edge stroke	2.5px #f8fafc
Dashboard bind	127.0.0.1:8765	Live poll	5s (pauses in review)

Anatomy — the DAG node

The one component the whole run turns on

1 completed

construction

engineer

gate okintegrity okreview approve

4 5

$1.2700ctx 58.1k

1Node name — the topology node id, with a status pill that colors the whole chip (see States). The completed fill is the same green the gate signs off with.

2Role — the hat the agent wears for this node: analyst, architect, engineer, and so on. Purely descriptive; it does not change verification.

3Badges — one per deterministic check, labelled <kind> <value>: the gate outcome, the toolchain-integrity result, and — under --hitl — the human-review decision. Green ok, amber warn, red bad.

4Cost — dollars attributed to this node, $0.0000 to four places. Token-only backends (Codex) are computed from the rate table and flagged estimated.

5Context tokens — input + output + cache read + cache create for the node, humanized (22.4k, 1.20M). Arrows to dependent nodes are drawn as white DAG edges.

Node states

Every condition a node box must render — the fill carries the state

idle · not yet run

idle

construction

engineer

—ctx —

running

design

architect

$0.4600ctx 31.8k

review_waiting · --hitl

review_waiting

requirements

analyst

review required

$0.3100ctx 22.4k

completed · passed

completed

requirements

analyst

gate okintegrity ok

$0.3100ctx 22.4k

failed · gate blocked

failed

construction

engineer

gate vacuousintegrity ok

$1.0200ctx 54.9k

Idle and completed share no badge but differ in fill; running and review_waiting share the blue fill (both are "in flight") and separate on the pill and badge. A gate badge of vacuous, packaging_failed, or blocked_prerequisite surfaces a construction gate that did not truly pass — right on the node.

The terminal run line

One line per node — the glyph is the verdict

cadora · executor=claude · funding=subscription · run=build-a-service-20260717-0904 ▶ requirements · claude-opus-4-8 · running… (generating documents; this can take a few minutes) ✓ requirements $0.3100 gate:spec-check ok integrity:ok ✗ construction $1.0200 gate:build-test VACUOUS integrity:ok ✗ stopped at node 'construction': gate 'build-test' blocked -> runs/build-a-service-20260717-0904

Line	Grammar	Means
▶ announce	▶ <node> · <model> · running…	Node started; a heartbeat spins on a TTY until the agent returns.
✓ passed	✓ <node> $<cost> gate:<name> ok integrity:ok	Cadora re-ran the gate itself and it passed. Fields append only when present.
✗ did not pass	✗ <node> … gate:<name> VACUOUS	Gate status upper-cased: FAILED · VACUOUS · PACKAGING_FAILED · BLOCKED_PREREQUISITE.
✗ stopped	✗ stopped at node '<node>': <reason> -> <archive>	Fail-closed: the run halts here and points at the archived evidence.
appended	funding=… · integrity:N BLOCKING · remediate:<state> xN	Extra fields render only when they apply to that node.

Controls & behavior

What each flag does, and the rules that keep green honest

Control	Action	Result on the run
cadora run <topology>	Drive the DAG	Nodes execute in dependency-order waves; each is gated, integrity-scanned, and archived.
--executor	Pick the agent CLI	claude · codex · kiro · glm · antigravity — every node runs on that backend.
--vision <path>	Supply the product spec	Installs the AI-DLC workspace into --cwd; nodes read it as context.
gate: <name> (node)	Deterministic ShellGate	The gate command re-runs after the node; a non-zero exit or vacuous pass blocks.
--integrity-mode enforce	Scan the toolchain	A blocking finding — tool impersonation, hollow code — fails the node.
--max-parallel N	Concurrency	Independent wave nodes run at once; gates, integrity, and archiving stay sequential.
--remediate N	Bounded repair	A remediable gate feeds up to N fresh sessions; the same gate decides green.
review: true + --hitl	Human gate	Pauses for approve / request-changes / abort before downstream work (see HITL spec).
--yes · CADORA_ASSUME_YES=1	Trust gate	Prints the blast-radius banner for the record and skips the interactive confirm.

Rule	Why
Green means proven, not claimed	The agent's own "ok" never decides a line — Cadora re-runs the real gate and reads the real result.
Fail-closed	Ambiguity resolves against the agent; a suite that ran zero tests does not pass.
Deterministic ordering	Only agent sessions parallelize. Gates, integrity, review, and archiving are sequential, so the manifest is reproducible.
Every verdict archived	The gate command, its output, the status, and the cost are serialized whole — green is a record you can read.

Voice

Words are part of the design

Do	Not
Name the verdict — gate:build-test ok	“Success!”
Sentence case — “Proceed with an autonomous run?”	Title Case — “Proceed With An Autonomous Run?”
Say why it stopped — “gate 'build-test' blocked”	“Error”
$1.2700 · 2m 30s · 58.1k	2026-07-17T09:04:06.215+00:00

Tokens and metrics are taken verbatim from cadora/dashboard/static/style.css; the terminal grammar from cadora/runner.py. Edit the rendered components in place, or hand the palette and metrics tables to a Figma library.

Design specification for Cadora's gated-run surfaces: the color and type tokens taken from the dashboard, the DAG node's anatomy, its five states, the terminal run-line grammar, and the run's controls and voice.

The surfaces of a run

Palette

Type & metrics

Anatomy — the DAG node

Node states

The terminal run line

Controls & behavior

Voice