The builder

name interface-builderupdated 2026-08-31portable

ROLES.md describes this interface in section 12.1, as the primary interface of the package maker. Software reads its definition from interface-builder.json.

The builder interface holds the exchanges for turning a description of a needed agent into a package. There are three: build this, what did you build, and revise it.

This is the primary interface of the package maker role. Implementing it alone does not grant the role, because the role also carries its refusals, its draft rule, its own check, and the record its holders sign.

1. The purpose

Anything that builds agent packages has to be askable in a known way, or every requester learns a different intake for every builder. This interface publishes the asking side of that job, so a caller who has never met a particular builder can still describe an agent, get a package back, and revise it.

2. The exchanges

  1. Build this. The caller sends a description: a name, one sentence on what the agent does, the jobs it does, the systems it needs and at what access, what it refuses, what always goes to a person, and the records it has to leave. The answer is a package, or a refusal that says what the description was missing.
  2. What did you build? The answer is the manifest of a package the implementer produced: its name, version, skills, systems, and obligations, and the note that it is a draft.
  3. Revise it. The caller sends the same description with changes, and the implementer rebuilds it to a new version, with the same parts required.

3. What it does

  1. Every exchange is answered or refused with a reason. Silence is not an answer.
  2. A build request carries the judgment parts. An implementer refuses a description with no refusals or no records and names the missing part. It does not invent either.
  3. Every answer about a package says it is a draft. Nobody has run the agent a fresh package describes, and an answer does not present it as more.
  4. There is no document. The signed build record belongs to the package maker role, and this interface defines none. An implementer that does not hold the role answers these exchanges and signs nothing.

4. How an implementer is checked

The test is behavioural. A harness asks all three exchanges. Each is answered or refused with a reason. A description missing its refusals, and one missing its records, are each refused with the missing part named. Every answer about a built package calls it a draft.

v0.1.0-draft (2026-08-31): this is the first draft, extracted from the agent builder role, which previously carried these exchanges inline.