MARCHESE.md

The efficiency and orchestration contract layer for AI agent engineering.

A portable, framework-agnostic file format for declaring the economics of an agent system: context budgets, input compression, Minimum Viable Model routing, script-driven skills, an append-only gotcha ledger, 4-block orchestration loops, and a self-improving knowledge layer. Where prose conventions give you habits, MARCHESE.md gives you an enforceable operating contract for how compute is spent.

Fourth file in a family. LOGIC.md declares the flow between reasoning steps. COVENANT.md declares the contract of each skill those steps invoke. HARNESS.md declares the environment and system substrate in which it lives: host OS bindings, event loops, process isolation, and physical hardware capabilities. MARCHESE.md declares the economics and runtime discipline under which all of it executes: which model, at what token cost, verified by which gate, remembered in which ledger. They compose, and none of them overlaps.

---

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:

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.

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 is the cheapest model that does this task correctly? — is never asked, so the answer is always "the expensive one".

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 is not a prompting problem you fix with better instructions. It is a missing-contract problem: there is no portable file that declares how an agent system is allowed to spend compute and how it is required to remember.

MARCHESE.md fills that gap.

---

What it is

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. Two fields are required (marchese_version, name); every block is optional and independently useful.

---
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.

---

What it controls

Context budget. 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. 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. 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), then the declared default. Cheap work stops riding expensive models by accident.

Gotcha ledger. 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. 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 — which are exactly the entries that should be promoted into gotchas or scripts.

Middle-to-middle human validation. 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 the recurring rituals (Friday audit, Monday prune) attached to the project instead of someone's memory.

Nuclear offload route. 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 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 is no "upload your life" prerequisite. raw/ holds ingested material, wiki/ holds a curated table of contents, and re-ingest is idempotent.

marchese improve then runs a three-bucket pass:

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 with zero token cost, because the mechanical layer is deterministic Node — see docs/SCHEDULING.md for launchd, cron, and systemd wiring.

---

When to use it, and when not to

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 itself (scan, bucket, sign off, log) to be a scheduled, deterministic process rather than a good intention.

You probably don't need MARCHESE.md when:

• Your agent is a single short-lived call; there is 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 you can audit the policy. Treat MARCHESE.md as a contract-and-discipline layer with measured mechanics, not a guaranteed-percentage product.

---

How it relates to LOGIC.md, COVENANT.md and HARNESS.md

LOGIC.md is flow. Step DAGs, typed handoffs, quality gates inside a reasoning pipeline. It answers: in what order, under which contracts, does the thinking proceed?

COVENANT.md is boundary. The declared surface of a single skill — domain, interface, dependencies, contracts, proof fixtures. It answers: what may a caller depend on?

HARNESS.md is substrate and environment. Host OS bindings, daemon event loops, IPC channels, process sandboxes, and physical hardware interfaces. It answers: where, and under what system isolation and permissions, does execution actually run?

MARCHESE.md is 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. Four files, four axes, no overlap.

---

What exists today vs MARCHESE.md

	Governs	Portable 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, daemon event loops, process isolation, hardware capabilities	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.

---

Packages

Published on npm — install directly, no clone required.

Package	Install	Description
@marchese-md/core	npm install @marchese-md/core	Parser, Ajv 2020 schema validator, context budget auditor, MVM router, gotcha ledger, RTK compressor + PreToolUse processor, 4-block loop engine + JSONL history, knowledge base, improve-system engine, Codex offload router
@marchese-md/cli	npm install -g @marchese-md/cli (or npx @marchese-md/cli)	13-command marchese CLI: validate, audit, init, optimize, gotcha, loop, status, rtk, route, knowledge, improve, image, models
@marchese-md/mcp	npx @marchese-md/mcp (stdio MCP server)	Exposes 12 marchese_* tools for Claude Code, Claude Desktop, and any MCP host
marchese-md	pip install marchese-md	marchese_md — parser + jsonschema validator with verdict parity against the shared fixtures
Claude Code plugin	/plugin marketplace add SingularityAI-Dev/marchese-method then /plugin install marchese-method (see Install & test the plugin)	Bundles the marchese-method skill, all /marchese-method:* slash commands, hooks, and the MCP server registration in one install

---

Getting started

From npm (recommended)

npm install -g @marchese-md/cli
marchese validate MARCHESE.md

No global install needed either — npx @marchese-md/cli <command> works standalone.

From source

git clone https://github.com/SingularityAI-Dev/marchese-method.git
cd marchese-method
npm install
npm run build
npm link -w @marchese-md/cli   # optional: puts `marchese` on PATH

Install & test the Claude Code plugin

The plugin bundles the marchese-method skill, nine /marchese-method:* slash commands, three hooks (SessionStart + Bash Pre/PostToolUse), and the marchese MCP server (npx -y @marchese-md/mcp).

Add and install (from the terminal):

# Add the marketplace — from GitHub, or from a local checkout:
claude plugin marketplace add SingularityAI-Dev/marchese-method
# claude plugin marketplace add /path/to/marchese-method   # local alternative

# Install (marketplace name is marchese-method-marketplace):
claude plugin install marchese-method@marchese-method-marketplace

The equivalent in-session form is /plugin marketplace add SingularityAI-Dev/marchese-method then /plugin install marchese-method. Plugins are per CLAUDE_CONFIG_DIR, so run the two commands under each config (e.g. a claude-personal / claude-work alias) to install into both.

Test it:

claude plugin list                     # marchese-method shows enabled
claude plugin details marchese-method  # inventory: 9 commands, 1 skill, 3 hooks, 1 MCP + token cost
claude plugin validate .               # from the repo: validates the manifests

Then, inside a session: run a slash command (/marchese-method:audit ., /marchese-method:init, /marchese-method:improve), confirm the marchese server under /mcp, and run any Bash tool call to exercise the RTK PreToolUse hook (it passes the command through untouched when rtk is not on PATH). For a throwaway load that never touches your config, claude --plugin-dir /path/to/marchese-method enables it for one session only.

Claude Desktop has no plugin marketplace; it only consumes MCP. Add just the server to claude_desktop_config.json and restart:

{ "mcpServers": { "marchese": { "command": "npx", "args": ["-y", "@marchese-md/mcp"] } } }

CLI tour

# Scaffold a spec (templates: default, minimal, nextjs, client-os,
# python-daemon, data-pipeline, mcp-server, research)
marchese init my-system
marchese init my-app --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 is 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
marchese loop dev-loop --run-gate

# Compress a bulky payload before it hits context
marchese optimize ./big-log.txt --json

# Self-improving layer
marchese knowledge init && marchese knowledge ingest
marchese improve            # three buckets + change-log
marchese status .           # status line: model tier, budget, loops, history

# List configured models, or swap model ids across MARCHESE.md
marchese models list
marchese models swap --swap claude-sonnet-4-5=claude-opus-4-8 --dry-run

# Image-encoded context path: encode a payload as SVG + report token economics
marchese image ./big-log.txt --json

MCP server

{
  "mcpServers": {
    "marchese": {
      "command": "node",
      "args": ["/path/to/marchese-method/packages/mcp/dist/server.js"]
    }
  }
}

Twelve tools become available, including marchese_audit_context, marchese_mvm_route, marchese_run_loop, marchese_log_gotcha, marchese_improve_system, and marchese_knowledge.

Claude Code integration

integrations/claude-code/ ships hooks and slash commands: the PreToolUse hook chain (native rtk hook claude → marchese rtk hook → pass-through), SessionStart day-of-week reminders, and /marchese:audit, /marchese:gotcha, /marchese:loop, /marchese:optimize, /marchese:route, /marchese:improve, and friends.

Python

pip install marchese-md
python -c "from marchese_md import parse, validate"

On a schedule

The ingest/improve cadence the spec declares can run under launchd, cron, or systemd with zero token cost — the mechanical layer needs no LLM. See docs/SCHEDULING.md.

---

Format overview

Eleven top-level blocks: efficiency, models, skills_config, gotchas, orchestration, session_reminders, human_validation_zones, knowledge, improvement, plus the required marchese_version and name. The canonical JSON Schema lives at packages/core/schema.json, mirrored at spec/schema.json and sdks/python/src/marchese_md/schema.json; conformance fixtures at spec/fixtures/ keep all three in verdict parity.

Full prose specification: docs/SPEC.md.

This repo eats its own dog food: the root MARCHESE.md is a live spec with five real gotchas, three loops (including improve-system), Friday/Monday reminders, and a seeded knowledge/ base — and CI validates it on every push.

---

Status

• v1.0.0 — monorepo with three packages, Python SDK, spec + fixtures, Claude Code integration, worked examples (basic, advanced, improve-system).
• 90 tests passing: 61 Vitest (core + CLI end-to-end), 14 MCP (node:test), 7 conformance fixtures, 8 pytest.
• CI on Node 20/22 and Python 3.9/3.11/3.12: build, typecheck, all suites, lint, CLI smoke.
• Hardened by a full line-by-line sweep (docs/SWEEP-2026-07-23.md): gotcha persistence, hook protocol shape, YAML coercion, loop gate safety, idempotent ingest.

---

Roadmap

Near term

• npm publish for the three packages
• Stored auto-fix payloads for mechanically applicable sign-off kinds; stable proposal IDs across improve runs
• Coverage thresholds in CI

Medium term

• Image-encoded context path (text→image token arbitrage)
• External model swap helpers via env config
• Expanded template library and skill-script scaffolder

---

Development

npm install
npm run build         # core → cli → mcp (required before tests: CLI/MCP suites run against dist/)
npm test              # Vitest across core + cli
npm run test:mcp      # node:test against the built MCP server
npm run test:fixtures # conformance sweep
npm run test:python   # Python SDK
npm run lint          # Biome
npm run typecheck

Stack: TypeScript strict mode, ESM, Node 20+, npm workspaces, Vitest, Biome, Ajv 2020, commander, yaml, @modelcontextprotocol/sdk, zod.

Schema changes follow the three-way sync rule: edit packages/core/schema.json, mirror to spec/ and the Python SDK, update fixtures. It is GOTCHA-005 in the root spec for a reason.

---

Contributing

Issues and pull requests are welcome. Keep changes surgical, keep CLAUDE.md under its own 200-line budget, and run the full suite before pushing — the repo's own verify-monorepo loop is the definition of green.

---

Designed by Austin Marchese. Built by Rainier Potgieter, Durban, South Africa. MIT licensed. Sibling of LOGIC.md and COVENANT.md.