MARCHESE.md: The Economics Layer for AI Agent Systems

The problem

Every agent system spends compute through one equation.

Compute Used = Tokens Consumed × Model Cost

Almost nobody governs either factor. That has three consequences.

01, INVISIBLE

Your context tax is invisible

A bloated CLAUDE.md, twenty preloaded skill descriptions, and a stack of always-on MCP servers are charged against every single session before the first useful token is produced. Nothing measures it, nothing caps it, and it compounds silently as the project grows.

02, UNROUTED

Your model spend is unrouted

Linting, parsing, and fixture runs execute on the same frontier model as architecture decisions, because routing is a per-call vibe rather than a declared policy. The Minimum Viable Model question, what's the cheapest model that does this correctly?, is never asked, so the answer is always the expensive one.

03, FORGETFUL

Your operations don't learn

The same edge case bites in week one and again in week six because the fix lived in a chat scrollback. Loops run without verification gates, verification runs without history, and history is never mined for the recurring failures that should have become scripts, skills, or ledger entries.

This isn't a prompting problem you fix with better instructions. It's a missing-contract problem: there's no portable file that declares how an agent system is allowed to spend compute, and how it's required to remember. MARCHESE.md fills that gap.

What it is

One file. Two required fields. Every block optional and independently useful.

A markdown file with YAML frontmatter that lives at the root of an agent project. The YAML is the machine-parseable contract; the markdown body is human rationale. Only marchese_version and name are required, everything else composes as needed.

---
marchese_version: "1.0"
name: my-agent-system
efficiency:
  context_limit_tokens: 150000
  compact_threshold_percent: 60
  claude_md_max_lines: 200
  rtk_compression: true
models:
  default_mvm: claude-haiku-4-5
  frontier_model: claude-sonnet-4-5
  task_routes:
    - task: linting
      model: claude-haiku-4-5
    - task: architecture
      model: claude-sonnet-4-5
      fork_context: true
gotchas:
  - id: GOTCHA-001
    title: Ajv draft-2020-12 requires Ajv2020
    issue: Default ajv only loads draft-07; compiling the schema throws
    resolution: Load ajv/dist/2020 and compile with Ajv2020
orchestration:
  loops:
    - name: dev-loop
      trigger: manual
      execution_skill: feature-builder
      verification_gate: npm test
      history_log: .history.jsonl
      training_mode: true
human_validation_zones:
  - name: production-deploy
    reason: High cost of error
    require_approval: true
---

A validator checks it against a canonical JSON Schema (draft 2020-12, three-way synced across TypeScript, spec, and Python). A CLI, an MCP server, and Claude Code hooks then enforce it at runtime.

Animated view of the core equation: Compute Used equals Tokens Consumed times Model Cost, with MARCHESE.md's four control surfaces, context budget, input compression, MVM routing, and loop verification, each pulling one factor down.

What it controls

Six control surfaces, each turning a governance idea into a checkable number.

Context budget

tokens

context_limit_tokens, compact_threshold_percent, and claude_md_max_lines turn context hygiene into checkable numbers. marchese audit measures the standing tax of your CLAUDE.md, preloaded skills, and MCP configs, and tells you when a session should compact. The reference repo holds itself to the same 200-line cap it recommends.

Input compression

RTK

A deterministic RTK-style compressor, blank-line collapse, consecutive-duplicate dedupe, log-noise stripping, optional lossy whitespace, for bulky payloads, plus live integration with the rtk binary. A PreToolUse hook rewrites eligible bash commands (git status → rtk git status) before they execute, emitting the Claude Code hookSpecificOutput protocol so rewrites actually apply.

Minimum Viable Model routing

MVM

marchese route resolves every task name through four stages: exact declared route → partial match → heuristic classification (lint/parse/test-class work drops to the MVM; architecture/security/review-class work escalates to the frontier model with an optional forked context) → declared default. Cheap work stops riding expensive models by accident.

Minimum viable model routing: task names resolve through exact route, partial match, heuristic classification, then default model, so cheap work never rides an expensive model by accident.

Gotcha ledger

memory

Append-only edge-case memory with unique IDs, searchable by symptom, persisted directly into the MARCHESE.md frontmatter by marchese gotcha add. The fix from week one is a queryable record in week six, not a scrollback archaeology dig.

4-block orchestration loops

loop → gate → log

Every loop is trigger → execution_skill → verification_gate → history_log. Training mode (the default) records the run without executing the shell gate; --run-gate makes it live. History is append-only JSONL, and marchese status mines it for recurring failures, exactly the entries that should be promoted into gotchas or scripts.

Animated 4-block orchestration loop: trigger fires an execution skill, a verification gate passes or fails the result, every run appends to the history log, and recurring failures are promoted into the gotcha ledger.

Middle-to-middle human validation

approval gates

human_validation_zones names the decisions that must not be automated: schema changes, public API breaks, production deploys. The human frames the goal, the agent executes the middle ~95%, and the declared zones gate the high-cost-of-error mutations at the end. session_reminders keep recurring rituals, Friday audit, Monday prune, attached to the project instead of someone's memory.

Middle-to-middle human validation: the human frames the goal, the agent executes the middle of the work, and declared human validation zones gate the high-cost-of-error mutations at the end.

Nuclear offload route

bulk mechanical work

For bulk mechanical execution, test generation, codemods, migrations, marchese route can classify a task for offload to the OpenAI Codex CLI, dry-run by default, with broken-install detection. The ~4× savings figure is the playbook's claim, not this repo's benchmark; the router treats it as a heuristic, and says so.

The self-improving layer

The system that runs your agents also learns how to run them better.

The knowledge and improvement blocks close the loop between running a system and getting better at running it. The knowledge base self-seeds from the repo, CLAUDE.md, MARCHESE.md, README, spec docs, the gotcha ledger, and loop history, so there's no "upload your life" prerequisite. raw/ holds ingested material, wiki/ holds a curated table of contents, and re-ingest is idempotent.

marchese improve runs a three-bucket pass over everything it finds:

Bucket	Behaviour
AUTO-APPROVE	Low-risk fixes, broken wiki links, missing TOC entries, applied directly and appended to `knowledge/change-log.md`.
NEEDS SIGN-OFF	Skill edits, structural rewrites, contradictions, `CLAUDE.md` bloat, written to `knowledge/outputs/review-*.md` as checkboxes; applied only after a human checks them, then the review file is retired.
MORE CONTEXT	Ambiguities written to `needs-context-*.md` as questions for the next session.

Protected paths, CLAUDE.md, the wiki root, skills directories, are never auto-modified for sign-off items. The whole cycle runs on a schedule at zero token cost, because the mechanical layer is deterministic Node. See docs/SCHEDULING.md for launchd, cron, and systemd wiring.

Animated improve-system cycle: scan the knowledge base and repo, bucket proposals into auto-approve, needs-sign-off, and more-context, apply the safe ones, wait for human checkboxes on the rest, and append everything to the change log before the next pass.

Self-improvement lifecycle: BASE, UPLOAD, INFLOW, LOOP, DRIVE, the knowledge base is self-seeded from the repo, ingested, cycled through the improve loop, and drives the next contract revision.

When to use it, and when not to

It's a discipline layer, not a silver bullet.

✓ Use MARCHESE.md when

Your agent sessions run long enough that context tax and compaction timing are real costs.
You run mixed workloads, mechanical tasks and frontier-class reasoning, and want routing declared once instead of decided per call.
The same edge cases keep resurfacing and you want an enforced, queryable ledger instead of tribal memory.
Your loops need verification gates and an audit trail of what passed and failed, mined weekly for patterns.
You want the improvement ritual, scan, bucket, sign off, log, to be a scheduled, deterministic process rather than a good intention.

You probably don't need it when

Your agent is a single short-lived call; there's no budget to govern.
You run one model for everything and are happy with that trade; MVM routing has nothing to route.
You're prototyping and the system's shape changes daily. Adopt the gotcha ledger first, it pays off earliest, and grow into the rest.

Honest disclosure on the numbers The headline ratios in this space, 60-90% input compression from RTK, ~4× savings from Codex offload, are engineering claims from the method's source material and the upstream tools, not benchmarks produced by this repo. What this repo does verify: the compressor's byte savings are measured per run, the audit's token estimates are labelled as estimates (~4 chars/token heuristic), and the router reports why it chose a model so the policy is auditable. Treat MARCHESE.md as a contract-and-discipline layer with measured mechanics, not a guaranteed-percentage product.

How it relates to the rest of the family

Four files, four axes, no overlap.

CLAUDE.md

Identity

Who the agent is, and its standing rules.

LOGIC.md

Flow

Step DAGs, typed handoffs, quality gates inside a reasoning pipeline. In what order, under which contracts, does the thinking proceed?

COVENANT.md

Boundary

The declared surface of a single skill, domain, interface, dependencies, contracts, proof fixtures. What may a caller depend on?

HARNESS.md

Substrate

Host OS bindings, daemon event loops, IPC channels, process sandboxes, physical hardware interfaces. Where, and under what isolation, does execution run?

MARCHESE.md

Economics and operations

Which model executes, under what token budget, verified by which gate, remembered in which ledger, improved on which cadence. It answers: how is compute spent, and how does the system learn from spending it?

A LOGIC.md step can invoke a skill bound by a COVENANT.md, running inside an isolated host environment managed by HARNESS.md, on a model chosen by a MARCHESE.md task route, inside a loop whose gate and history MARCHESE.md declares.

What exists today vs. MARCHESE.md

	Governs	Format
CLAUDE.md / AGENTS.md	Identity, project context, style	Markdown
SKILL.md	Procedural knowledge	Markdown
LOGIC.md	Reasoning flow, step DAGs, quality gates	Markdown / YAML
COVENANT.md	Skill surface contracts	Markdown / YAML
HARNESS.md	Host OS bindings, event loops, process isolation, hardware	Markdown / YAML
rtk (binary)	Token compression of tool output	CLI tool
Cost dashboards (ccusage et al.)	Spend observation, after the fact	CLI / UI
Model router libraries	Per-call routing, imperative	Code
MARCHESE.md	Budgets, routing policy, loops, ledger, self-improvement, declared ahead of time	Markdown / YAML

Observation tools tell you what you spent. MARCHESE.md is the contract for how you're allowed to spend it, checked before and during the run, with the ledger and improve loop feeding what happened back into the contract.

Format, packages, status

Eleven blocks. Three packages. A Python SDK. One schema, three-way synced.

efficiency models skills_config gotchas orchestration session_reminders human_validation_zones knowledge improvement marchese_version (required) name (required)

The canonical JSON Schema (draft 2020-12) lives in packages/core/schema.json, mirrored to spec/ and the Python SDK; conformance fixtures keep all three in verdict parity. This repo eats its own dog food, the root MARCHESE.md is a live spec with five real gotchas, three loops, Friday/Monday reminders, and a seeded knowledge base, validated by CI on every push.

4packages, core, cli, mcp, Python SDK

13CLI commands

12MCP tools exposed

105tests passing across 4 suites

A feel for the CLI

# Scaffold a spec, 8 templates including nextjs, mcp-server, data-pipeline
marchese init my-system --template nextjs

# Validate against the canonical schema + semantic rules
marchese validate MARCHESE.md

# Measure the standing context tax of this workspace
marchese audit .

# Route a task to its Minimum Viable Model
marchese route "generate unit tests for the parser"

# Record an edge case while it's fresh
marchese gotcha add "Ajv 2020 loader" --issue "draft-07 default" --resolution "use ajv/dist/2020"

# Run a 4-block loop, training mode records; --run-gate goes live
marchese loop dev-loop --run-gate

# Self-improving layer
marchese knowledge init && marchese knowledge ingest
marchese improve
marchese status .

Scheduling cadence: the ingest and improve cycle runs on launchd, cron, or systemd at zero token cost, because the mechanical layer is deterministic Node with no LLM in the loop.

Full demo

Watch the Marchese Method demo

Watch now →

Get the contract

Declare the economics once. Let the system enforce it every run.

MIT licensed. Built to compose with LOGIC.md, COVENANT.md, and HARNESS.md, not replace them.

View on GitHub →

Evidence stamp

Evidence: compiled from the marchese-method 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 economics and orchestration contract for AI agent systems.