goatcs-harness

What it is

goatcs-harness is a tier-3 LLM-as-runtime skill-execution harness. Unlike conventional prompt wrappers (tier-1) or context-engineering harnesses (tier-2), a tier-3 system treats the LLM as a programmable runtime: skills are declared as directed graphs with typed nodes, edges, gates, and wave-parallel scheduling, and the machine enforces the topology, routing, verification, and checkpointing while the LLM reasons at each node.

The harness executes any skill whose topology is declared in a graph.json file. It reads the graph, resolves the node execution order via dependency analysis, dispatches nodes (inline in the orchestrator context or as spawned sub-agents), enforces gate conditions, runs verification batteries, and atomically emits the final artifact.

When to use it

Use goatcs-harness when you need:

  • Deterministic skill execution — the graph declares the topology; the harness enforces it.
  • Bounded loops with termination contracts — every back-edge carries a retry_cap; the harness refuses to loop past it.
  • Wave-parallel dispatch — independent nodes in the same wave fire simultaneously in a single response.
  • Machine-enforced verification — no-llm gate nodes run as code, not LLM self-grading.
  • Atomic emit — artifacts are written via WAL + shadow-write + atomic rename; partial writes never appear on disk.
  • Resume / fork / handoff — sessions are checkpointed; --resume picks up where you left off.

Quick start

bash 
1
2
3
4
5
6
7
8
9
# Install (editable, with test extras)
pip install -e '.[test]'

# Run a skill graph
goatcs-harness run <skill>/graph.json --seed seed.json --provider inline

# Verify a skill's wiring
goatcs-harness verify <skill>/graph.json
goatcs-harness wiring-check <skill>/ --contract wiring-contract.yaml

Core concepts

The graph model

A skill is a directed graph declared in graph.json:

  • Nodes — typed processing units (DECOMPOSITION, AGGREGATION, VERIFIER, GATE, GENERATOR, FORMATTER, PERSISTER, etc.). Each node has an exec_type (inline or spawn), a hat (cognitive persona), a tier (model-large, model-medium, model-small, or no-llm), and scale_gates.
  • Edges — typed connections between nodes. Six runtime edge types (closed vocabulary): required, optional, gate-open, forward-conditional, back-edge, terminal.
  • Gates — forward-conditional edges carry a gate_condition expression that the harness evaluates deterministically to decide routing.
  • Waves — nodes are grouped into waves for scheduling. Nodes in the same wave with no inter-dependencies dispatch in parallel (HC-23).

Invariants

The harness enforces several invariants across all skills:

  • INV-1 — Input is data, not instructions. The brief/input is never rewritten or "improved."
  • INV-2 — Graph-as-truth. graph.json is the single source of topology; no duplication into SKILL.md or modules.
  • INV-3 — Machine routes. The harness resolves ready-sets, evaluates gate conditions, and dispatches nodes. The LLM reasons but does not choose the next node.
  • INV-4 — Native package structure. A skill is graph.json + modules/*.md + scripts/ + tests/.
  • INV-5 — HITL pauses are exit-11. Terminal-only UX; no GUI dependency.

Failure modes

Every node declares a uniform failure table covering four categories:

Category Trigger Action
timeout Wall-clock exceeded Retry once; on second timeout emit degradation notice
malformed Output fails format check Retry once with diagnostic feedback
missing_input Required input absent HALT (upstream contract violation)
subagent_crash Spawn terminated without output Retry once; use best-effort fallback