Agent-installable modules: a pattern for shipping with coding agents

When a human tells a coding agent "build me an app" or "add SSO login," the agent should not build from scratch — it should reach for pre-built parts. npm solved this for dependencies. It didn't solve it for parts: code that lands in your repo, that you own, that arrives with instructions an agent can execute and proof that the install worked.

An agent-installable module is four things:

If any of the four is missing, it is not a module. Here's why each part exists — and why the shape is stricter than it first looks.

The manifest: what exactly lands in your repo

module.json lists the files, dependencies, and install steps — the installer's source of truth. The contract that matters: a listed file that doesn't exist aborts the install before anything is copied. Agents are terrible at scoping their own writes ("while I'm here, I refactored your navigation"). The manifest makes the blast radius explicit and machine-enforced: everything listed, nothing else.

The runbook: instructions that travel with the code

AGENTS.md ships inside the module, so the installing agent needs nothing else. The convention that earns its keep: hard constraints come immediately after the title, before any instruction. "Requires a dev build — does NOT work in Expo Go" is stated first, because the alternative is the agent discovering it experimentally in your build queue. The rest: prerequisites, exact install commands, a field-by-field configure section, customization points, verify — and human-only steps (sandbox purchases, account sign-ups, money decisions) marked as human-only.

The bar: an agent that has never seen the module can install, configure, and verify it using AGENTS.md alone.

Fail-fast config: mistakes die at launch

One config file is the only thing a human edits. A strict schema validates it at app startup: unknown keys rejected, every error names its field. The failure it prevents is the agent-flavored one — plausible config, subtle typo, silent misbehavior for weeks. A named red screen at launch is a five-minute fix; a silent misconfiguration is a store review or a revenue report discovery.

The verify receipt: the deliverable is proof

After install, one script checks the concrete things — files present, dependencies installed, tsc --noEmit clean — printing PASS <label> / FAIL <label> per check, exit code 0 only when everything passed. It must be deterministic, fast, and offline.

The point isn't that these checks are clever. It's that the agent's job now ends at "receipt printed," not "code written." In AI-assisted development the bottleneck has moved from writing code to reviewing code you can't fully read; a receipt converts "trust me" into "run this." The agent can run the check and read its own result — and fix what failed unprompted. In CI, the same script re-runs against a fresh app on every module change, so the receipt can't rot while nobody's looking.

The install contract: what deliberately does NOT happen

An installer does three things: copies the listed files, installs the declared npm dependencies, and prints the remaining wiring steps (prebuild, config edit, verify) for the agent to do. What it never does:

• Execute module code at install time. No install hooks. The installer copies bytes; it doesn't run them. (This is a deliberate security posture for agent-era distribution: an agent shouldn't run arbitrary install scripts it can't read.)
• Transform your code. No codemods, no partial upgrades, no lockfile management.
• A central registry (in v0.1). The module is a zip plus semver; updates within a major version are the upgrade path.

Copy-in, deps, printed wiring, verify receipt — that is the whole contract. Small on purpose: every mechanism an installer adds is a mechanism an agent must be trusted with.

What qualifies as a module

The test is a one-question filter: is this something agents write plausibly and get subtly wrong — code you'd review nervously? Billing is the canonical case (silent purchase failures, entitlement races, restore flows, store-review guidelines). Store submission pipelines, SSO/SAML logins, audit logging — same shape. A settings screen doesn't qualify; nobody's launch week died of a settings screen.

The full spec (v0.1, formalized from a shipped paywall module and its installer) lives on a canonical spec page — link pending publication. The worked example — a RevenueCat paywall for Expo and bare RN — is the inno9 paywall module; you can see the four parts verbatim in its delivery zip. For the store-side failure modes this pattern grew out of, see the subscription rejection checklist.

FAQ