One file your agent reads before touching anything.

{
  "schemaVersion": "2026-06-13",
  "id": "booking",
  "name": "Booking",
  "version": "0.1.0",
  "status": "available",
  "class": "vertical",
  "runtime": { "platform": "cloudflare-workers", "frameworkNeutral": true },
  "resources": [
    { "type": "d1", "binding": "DB", "tables": ["services", "bookings", "domain_events"] }
  ],
  "permissions": ["booking.read", "booking.write", "booking.admin"],
  "requires": ["customer"],
  "optional": ["auth", "audit-log", "payment", "email"],
  "hooks": ["calculateAvailability", "beforeBookingCreate", "afterBookingConfirmed"],
  "events": ["booking.created", "booking.confirmed", "booking.cancelled"],
  "rpc": [{ "method": "listBookings", "scope": "booking.read", "public": false }],
  "customization": { "default": "config-hooks", "supported": ["config", "hooks", "overlay", "fork"] },
  "approval": {
    "risk": "medium",
    "requiresApprovalFor": ["migrations", "pii-fields", "production-deploy"]
  }
}

Abbreviated booking module contract. The real file also carries summary, entrypoint, and route adapters.

What each part guarantees.

id · version · status

Stable identity, a pinned semver, and a maturity label (available / planned / proposed). Your agent and your lockfile reference exactly this version — no silent drift.

class

How the module behaves: core, platform, vertical, provider, or sink. Tells the agent its role and what it can safely depend on.

resources

Every binding the module touches — D1 tables, KV, secrets, outbound fetch. Declared up front so provisioning and review are exact, not discovered at deploy time.

permissions

Scoped capabilities (e.g. booking.read / .write / .admin). Inter-module calls are checked against these scopes — a module can't quietly do more than it declared.

requires · optional

The dependency graph. requires must be present; optional unlocks extra behavior (e.g. booking gains payments when payment is composed). The agent resolves this, not guesses it.

hooks

Typed extension points with defined I/O and required tests. This is where your custom 30% goes — beforeBookingCreate, calculateAvailability — without forking the module.

events

Domain events the module emits and consumes (booking.created, …). Other modules subscribe; the audit-log sink records them. Decoupled by contract, not by convention.

rpc

Inter-service methods with their required scope and whether they're public. The agent knows the call surface and its auth before it wires anything.

customization

The supported ladder: config → hooks → overlay → fork. Default is config-hooks. Forking is allowed but flagged — it transfers the upgrade burden to you.

approval

A risk level and the actions that demand explicit sign-off: migrations, PII fields, payment/email side-effects, production deploys. The agent must stop and ask — it can't YOLO a migration.

The customization ladder.

Climb only as far as you need. The lower rungs stay upgrade-safe; forking is the escape hatch, not the default.

config

Change behavior through declared settings. Zero code, fully upgrade-safe.

hooks

Implement typed extension points for your custom logic. Tested, upgrade-safe.

overlay

Override specific files while keeping the module's update path mostly intact.

fork

Take full ownership of the source. Maximum control — you own upgrades from here.

Locked composition, reviewable upgrades.

Your app's modules are pinned in microservices.lock.json — same source, same version, every build. When a new module version lands, you upgrade through a checked, reviewable flow instead of a silent dependency bump.

pnpm microservices add payment --plan

pnpm microservices upgrade booking --plan

pnpm microservices check

--plan shows exactly what changes before anything runs. check returns agent-readable failures before any deploy.

Why your agent can trust a module before it composes.