the system

A polyculture, not a monoculture

The three sisters — corn, beans, and squash — grow together and feed one another. Deterministic, cultivated agriculture: order that yields abundance. That is the framework.

one tool, every caller

Built for two kinds of callers

Most PHP frameworks are built for one kind of caller: a human writing code, or a browser sending requests. Milpa is built for two — humans and agents operating the same application through the same declared surface.

final class NoteTools{    #[Tool('list_notes', 'List saved notes', scopes: ['notes:read'])]    public function listNotes(        #[Param('Page number', clamp: [1, 1000])] int $page = 1    ): ToolResult {        return ToolResult::success(['notes' => [], 'page' => $page]);    }}

→ the full lesson in the Academy

plugin → capability → tool → verification → event → result

agent-native · deterministic

Better rails, not more freedom

Agents don't need more freedom — they need better rails. coa is deterministic first: it inspects, validates and diagnoses with machine-readable answers, and generators produce the file in memory — you can inspect, diff or dry-run a generation before anything touches the filesystem.

The loop is generate → verify → inspect: scaffolding follows the same conventions the runtime enforces, verifiers reflect the real class against the real rules, and validators read the whole plugin ecosystem — every hard requires satisfied, the graph acyclic — before it becomes a boot-time failure.

next: every failure links to the concept it broke · coming soon

trust, by design

Executed by agents, verified by humans

Autonomy without brakes is a demo, not a system. In Milpa, verification is a first-class primitive: a mutating action can be gated behind a deterministic check, a human approval, or a pending async result — and every passage is recorded.

the harvest map

A field that keeps growing

The dependency graph is the milpa, literally: roots with zero dependencies, rows grown from the core, compositions that climb — and a skeleton where you harvest. Every layer builds with the one below, never couples downward — and new rows are sown all the time.

the first harvest

The design system is ready to sow

@milpa/design is published: dark-first tokens verified WCAG AA, motion with a reduced-motion contract, and 68 pieces, every one with a machine-readable contract. It's the framework's thesis proven small — and it stands on its own.

milpa applied to itself

Nothing is sown without a contract

A component, a plugin, a theme — every piece declares what it exposes and what it demands, in a machine-readable spec. A human or an agent can assemble the system knowing exactly what's there, without guessing.

{  "name": "button", "layer": "primitive", "class": "mui-btn",  "states": {    "loading": "[aria-busy=\"true\"] — ::before spinner; the text stays visible",    "disabled": "[disabled] — state is styled via ARIA attributes, never classes"  },  "a11y": { "contrast": "every pair verified in npm test" },  "motion": { "reducedMotion": "global contract — nothing moves against the user" }}

{  "name": "acme/mail-plugin", "version": "2.1.0",  "namespace": "Acme\\MailPlugin", "entrypoint": "MailPlugin.php",  "contracts": {    "provides": ["mail"],    "requires": ["database"]  }}// providers load before consumers — Kahn's algorithm, the graph must be acyclic

{  "requiredTokens": { "color": ["--bg", "--surface", "--accent", "…"] },  "contrast": { "pairs": "193 WCAG AA pairs — dark and light" },  "invariants": [    "reduced-motion parity — nothing moves against the user",    "--bg must be opaque (the composition reference)"  ]}

Drift fails CI. A theme is validated before it ships — the gate even composes translucent surfaces over --bg and measures the effective contrast. Nothing is sown without a contract; not even a skin.