Drivetrain: The Runtime That Unifies the Agent File Stack

Why this exists

Four specs, four reference validators, and no runtime that ran them together.

LOGIC.md, COVENANT.md, HARNESS.md, and MARCHESE.md each solve a real, narrow problem, and each ships (or is building toward) its own validator and CLI. What none of them had, on their own, was an engine that actually executed a HARNESS.md team, walked a LOGIC.md reasoning DAG against a live model, called a COVENANT.md-bound skill, and logged the run under a MARCHESE.md-declared gate. Drivetrain is that engine.

It's deliberately not a rewrite of any of the four formats. It imports the real packages, @logic-md/core, @covenant-md/core, @marchese-md/core, and adds the one thing none of them provide: a runtime loop that turns a static manifest into an actual running team of agents.

The four layers, as Drivetrain implements them

Not a reinterpretation. The same four axes, executed.

HARNESS.md

who does the work

3-tier team manifest, orchestrator, leads, workers, a till-done control loop, model rotation, and failure recovery. The runtime is implemented here in TypeScript, superseding the Python Drivetrain plan originally sketched in harness-md's own strategy doc.

LOGIC.md

how each agent reasons

Step DAGs, compiled prompts, verification gates. This binary is the live-LLM runtime that logic-md's own tooling always deferred to something else, here it actually walks the DAG against a real provider.

COVENANT.md

what skills promise

Validated by the toolchain; agents can call declared skills via the skill_invoke tool, backed by covenant-md's own createSkillRunner, a contract simulator by default, or the skill's declared process runner. Runner is cached per covenant path and domain-scoped.

MARCHESE.md

what it costs

Optional layer: human validation zones gate delegations, and MVM routing is logged as advisory rather than enforced. Cost governance without forcing every run through a strict budget.

The CLI

Four verbs. Init, validate, run, and inspect.

drivetrain init [--kind harness|logic|covenant|marchese] [dir]
drivetrain validate <path...>            # auto-detects all four formats
drivetrain run <HARNESS.md> [--task ...] [--dry-run] [--yes] [--model alias] [--max-iterations N]
drivetrain agent <LOGIC.md> "<task>" [--model provider/model]
drivetrain status [dir]                  # summarize the latest run from .drivetrain/

run executes a harness end to end: the orchestrator agent plans with a delegate tool (leads delegate to their team workers), quality/command/human gates run after gated agents complete, worker failure triggers lead takeover, lead failure bubbles up for orchestrator rerouting, and provider errors fall back through the declared model rotation. Every provider call and tool execution is appended to .drivetrain/run-<id>.jsonl.

A run, end to end

The demo team: one orchestrator, one lead, two workers.

The example shipped in the repo is deliberately minimal, small enough to read in full, real enough to prove the loop.

---
harness: demo-team
version: 0.1.0
models:
  primary: anthropic/claude-sonnet-4-5
  secondary: nvidia/meta-llama-3.3-70b-instruct
  rotation: [primary, secondary]
teams:
  - id: research
    lead: research-lead
    workers: [reader, writer]
agents:
  orchestrator:
    role: orchestrator
    reasoning: ./contracts/orchestrator.logic.md
    tools: [delegate, state_get, state_set, finish]
  research-lead:
    role: lead
    reasoning: ./contracts/research-lead.logic.md
    tools: [delegate, fs_read, fs_write]
  reader:
    role: worker
    reasoning: ./contracts/reader.logic.md
    tools: [fs_read, state_set]
  writer:
    role: worker
    reasoning: ./contracts/writer.logic.md
    tools: [fs_read, fs_write, state_set]
gates:
  - after: writer
    type: quality
    check: state.summaries_written > 0
control:
  loop: till_done
  max_iterations: 10
  on_worker_fail: lead_takeover
  on_lead_fail: orchestrator_reroute

The reader worker gathers source material, the writer worker produces summaries, and the quality gate refuses to finish until at least one summary has been written into shared state. Small enough to read end to end; real enough to exercise every control-loop path: delegation, gating, and the fallback rule.

The orchestrator plans and delegates to the research team via the delegate tool. It never does the work itself.

The research lead delegates to reader and writer, each executing its own LOGIC.md-compiled reasoning DAG against a live provider.

If a worker fails, the lead steps in and does the work itself, lead_takeover. If the lead then fails, the orchestrator reroutes, orchestrator_reroute.

The quality gate after writer checks state.summaries_written > 0 before the run is allowed to finish.

Every provider call and tool execution is appended to .drivetrain/run-<id>.jsonl, the full trace, not a summary.

Model providers

Mixed-provider rotation is the intended resilience path.

Model refs are provider/model. One team fails over to another provider mid-run, not a hypothetical, the actual designed behaviour.

anthropic

ANTHROPIC_API_KEY. The primary provider in the shipped example.

openai

OPENAI_API_KEY. Fetch-based, no extra SDK; maps Drivetrain's message/tool blocks to and from the OpenAI wire format.

nim

NVIDIA NIM and any OpenAI-compatible endpoint. NIM_API_KEY or NVIDIA_API_KEY, base URL overridable via NIM_BASE_URL. NIM model ids keep their own slash, e.g. nim/meta/llama-3.3-70b-instruct.

Status

Walking skeleton complete. Two v1.1 features landed since.

The drivetrain binary compiles, validates all four declarative formats, executes LOGIC.md contracts against a live provider, and runs full HARNESS.md orchestrations with failure recovery.

35vitest tests, all mock-provider

~62.5MBcompiled binary size

8built-in agent tools

5milestones, M0-M4, one day

Recently landed

The skill_invoke tool for COVENANT.md operations, an OpenAI-compatible provider (covering both openai and nim presets), and the switch of @marchese-md/core from a local file link to the published npm package.

Open item Publishing @logic-md/core 1.5.1 to npm is currently blocked: the npm token is read-only under npm's 2FA-bypass restriction. A local Bun patch (replacing createRequire/readFileSync loading with static imports so the package survives bun build --compile) stays in place until a proper OTP publish or granular publish token resolves it. The equivalent fix has already been made directly in the marchese-method repo.

v1 non-goals

Deliberately out of scope for this version, not overlooked:

MCP server VSCode extension Python SDK streaming output parallel step execution model rotation beyond ordered fallback literate execution npm publish Linux/Windows binaries checkpoint/resume

Development

Bun, vitest, tsc strict, biome.

bun install
bun run test         # vitest (35 tests, all mock-provider, no network)
bun run typecheck    # tsc strict
bun run lint         # biome
bun run gen-schema   # regenerate spec/harness.schema.json from the zod schema
bun run build        # compile dist/drivetrain (darwin-arm64)
./scripts/smoke.sh   # smoke the compiled binary in a clean temp dir

The runtime for the agent file stack

Four formats. One binary. A real running team.

Internal project, Single Source Studios. Not yet published to npm or GitHub publicly.

Internal, not yet released

Evidence

Evidence: compiled from the declarative_agent repository on 2026-08-03. Every number on this page traces to a file path or command output in the source tree. Last updated: 2026-08-03.

The runtime that unifies the agent file stack into one binary.