Code for machines first
Code-for-Machines First is the design discipline that every inter-service contract, audit record, configuration file, and ontology must be machine-readable as its primary surface. Human-facing interfaces — the operator TUI, web interfaces, mobile clients — are skins over machine-first APIs.
The data formats
The platform uses a consistent set of formats across all surfaces:
Inter-service communication uses MCP (see MCP as substrate protocol). The audit ledger uses JSONL with schema versioning. Seed taxonomies use JSON. Service configuration uses TOML or YAML. Conventions and documentation use Markdown with structured frontmatter. Per-tenant configuration uses YAML.
Every artefact is machine-mutable and machine-introspectable. The MCP describe endpoint on any service returns the current tool catalog in a machine-readable form. There is no configuration surface that requires a human operator to interpret undocumented fields.
Why this matters
Consistent observability. Structured data at every layer means audit queries and metrics have a uniform shape across services and tenants. An operator query against the audit ledger and an automated compliance check query the same JSONL schema.
Customer extension without forking. Customers add vertical-specific data sources by writing MCP servers. They use the same protocol all built-in services use. There is no bespoke adapter required to connect a customer-built tool to the platform.
AI-native composition. The substrate is consumable by AI agents — task sessions, customer-built agents, partner integrations — without a retrofit step. This is what makes the Knowledge-graph-grounded apprenticeship pattern possible: the graph is already machine-readable; the Doorman can query it programmatically at inference time.
Migration ease. Data export is a routine machine operation producing an open-format bundle (see Substrate without inference — The base case). There is no migration project involving vendor cooperation, because the data was never locked in a vendor-specific format.
The two narrow exceptions
Doctrine and convention prose documents, including this article, have prose as their primary surface. The frontmatter is machine-readable; the body is written for human readers. Operations on the body — refining register, resolving citations — are AI-assisted, but the artefact's primary surface is human.
Topic and guide documentation follows the same pattern. Frontmatter is structured and machine-parseable; body prose is for readers. These exceptions are explicit and narrow. The default is machine-first.
Composition
This discipline is the structural claim that MCP as substrate protocol realizes at the wire level. Every service exposes its contract through MCP describe, which returns a machine-readable tool catalog. Human-facing surfaces consume this catalog the same way any automated client would.
See also
- MCP as substrate protocol — the structural realization of machine-first service contracts via MCP
- Knowledge-graph-grounded apprenticeship — graph queries are machine-first MCP tool calls
- Substrate without inference — The base case — export bundles are machine-readable open formats