agent-compiler plugin

Agents are compiled, not stored. Humans author small, addressable behavior modules; a model may turn fuzzy intent into a typed AgentQuery, but everything after that boundary is deterministic: a stdlib-only kernel resolves modules, expands dependencies, fails closed on conflicts and over-ceiling effects, and emits an immutable, content-hashed AgentImage that renders into a harness-native agent definition — every line traceable to its source module.

Install

/plugin marketplace add JRichlen/agent-plugins
/plugin install agent-compiler@jrichlen

No dependencies beyond python3 — the kernel, renderer, and MCP server are stdlib-only and fully offline. Enabling the plugin auto-starts the kernel MCP server (four pure tools: inspect, compile, explain, render); the CLI is the identical fallback on any other harness.

Why it exists

Agent personas are normally hand-written prose blobs: unversioned, unattributable, silently over-privileged, non-reproducible, impossible to diff. When one “works,” nobody can say which sentence did the work, and when it grows a new power, nobody approved it. agent-compiler replaces prose authoring with a compilation pipeline: behavior lives in small, versioned, addressable modules in a registry; agents are build outputs.

The one non-deterministic step is explicitly fenced off — the model may translate fuzzy intent (“make me a security reviewer for our AWS PRs”) into a typed query. From the query onward, compilation is a pure function. Three claims you can verify yourself in under a minute:

• Compile it twice — the bytes and the hash are identical.
• Add an unrelated module to the registry — the hash does not move.
• Ask for a write capability under a read-only ceiling — compilation fails with EFFECT_CEILING instead of shipping a quietly over-privileged agent.

The compiler metaphor, mapped

The pipeline

That last point was a real bug, found by running the kernel rather than reviewing it: hashing the whole-registry revision let an unrelated module change an existing image's identity, breaking the metamorphic invariance the evals now pin. The registry's own discipline.build-run-verify module carries the story as an example block — “a defect no amount of re-reading the design had surfaced.”

The registry

The bundled registry ships 22 modules across three kinds. --registry accepts any directory, so a repo can carry its own; the kernel treats both identically. A module's filesystem location never carries meaning — only its id does.

Module anatomy

---
id: security.iam.review
kind: behavior
version: 1.0.0
tasks: [pull-request-review]
domains: [aws, iam]
requires: [behavior.evidence]
capabilities: [scm.pull_request.read, scm.pull_request.files]
---

<rule id="least-privilege" strength="must">
Evaluate permissions against the minimum privileges required by the stated operation.
</rule>

<probe id="wildcard-scope">
Are wildcard resources, actions, or principals being introduced?
</probe>

<antipattern id="unsupported-vulnerability">
Do not describe a theoretical vulnerability without connecting it to
concrete evidence from the reviewed artifact.
</antipattern>

The frontmatter subset is deliberately tiny — scalars, inline lists, one-level dash lists; “no nesting, no multi-line scalars, no anchors.” Anything else is a compile error, never a guess. Even an unknown key is fatal (BAD_MODULE_KEY) — added after a typo'd task: (singular) compiled cleanly and silently deselected a module. Exactly four block kinds exist, none nested.

The three module kinds

Selection semantics worth memorizing

• Views are selected only when named in query.views.
• A behavior module is selected when its tasks contain the query task, its roles contain the query role, or its domains intersect the query domains — and only if its declared environments/risks (if any) admit the query. discipline.prove-the-undo is the shipped example: declared risks: [high, critical], so it is absent at risk: medium and appears at risk: high with no other change.
• requires edges and explicitly named views are exact asks — they bypass applicability gating.
• Every stance entry must be a trait of a selected view, or compilation fails with UNDECLARED_STANCE.

The governing ADR

ADR 0001 settles how the registry grows: “new registry dimensions are populated as content along existing coordinates, not as new module kinds or query coordinates.” An identity is a view; a preference is domain-scoped behavior; external material is paraphrased with attribution. A first-class identity kind and a preference block were rejected because every language addition is effectively permanent once modules are published against it. The reopening condition is recorded: if “prefer X over Y” as a should-strength rule reads forced as the preference corpus grows, revisit a preference block kind.

What the plugin ships

Day-to-day use

1. Say what you want. “Make me a security reviewer for our AWS PRs.” The prompt hook nudges toward the compiler; or invoke /agent-compile directly.
2. The model builds the query and shows it. Role, task, domains, views, stance, environment, risk — and an effect ceiling. A compile with no ceiling from either the query or a view is refused: “an unconstrained agent must be asked for by listing its effects, never implied by omission.”
3. Discover exact ids. inspect filters by kind or tag. Fuzzy discovery may suggest ids; the compile step consumes exact ids only.
4. Compile. Out comes an AgentImage and its hash — or structured diagnostics. On diagnostics, fix the source, not the check: resolve conflicts, add the missing module, raise the ceiling deliberately — never suppress the failure.
5. Render and save. render returns the agent markdown; you write it to .claude/agents/<name>.md. (That path is Claude Code's location; the AgentImage, not the rendered file, is the contract.)
6. Interrogate it later. “Why does this agent say X?” → explain --unit security.iam.review#least-privilege → module, version, source file, line range.
7. Missing behavior? Author a module, then recompile — never paste prose into the rendered agent. The guard hook enforces what the artifact's own header says: DO NOT EDIT BY HAND.

Try it from the command line

cd plugins/agent-compiler
python3 scripts/compile.py compile \
  --registry registry \
  --query examples/queries/security-pr-review.json \
  --out /tmp/image.json
python3 scripts/render_claude_agent.py --image /tmp/image.json

What you get

The rendered artifact for the shipped security-review query — note the provenance comment on every content line and the explicit capability-wiring section:

---
name: security-pr-reviewer
description: Compiled reviewer agent for pull-request-review. Effects capped at: network, scm:read.
---

<!-- compiled by agent-compiler; imageHash: sha256:ccb2af8b…; rendererVersion: 0.1.0;
     DO NOT EDIT BY HAND — edit the registry modules and recompile -->

# security-pr-reviewer

Stance: adversarial, evidence-driven.

## Rules

- **MUST** Every material finding must include concrete evidence or a precise
  source reference.  <!-- behavior.evidence#cite-findings -->
- **MUST** Evaluate permissions against the minimum privileges required by the
  stated operation.  <!-- security.iam.review#least-privilege -->

## Probes to run

- Could this change allow a principal to cross an existing trust boundary?
  <!-- security.iam.review#cross-boundary-access -->
- Are wildcard resources, actions, or principals being introduced?
  <!-- security.iam.review#wildcard-scope -->

## Never

- Do not present a conclusion whose supporting evidence you have not actually
  examined in this session.  <!-- behavior.evidence#unsupported-claim -->
- Do not describe a theoretical vulnerability without connecting it to concrete
  evidence from the reviewed artifact.  <!-- security.iam.review#unsupported-vulnerability -->

## Required capabilities

This agent needs implementations of these provider-independent
interfaces; wire them to the tools your harness actually exposes:

- `scm.pull_request.files`
- `scm.pull_request.read`

Effects this agent may exercise: `network`, `scm:read` (ceiling: network, scm:read).

The two shipped examples show the two shapes an agent takes: this narrow, capability-linked, read-only reviewer (6 units from 2 modules), and engineering-default — the daily-driver identity (17 units from 9 modules, zero capabilities, behavior-only under a broad ceiling), which also demonstrates applicability: discipline.prove-the-undo joins the image only when the query's risk reaches high.

Diagnostics — the fail-closed surface

Every failure is a structured {code, severity, message, nodeIds} diagnostic on stdout with exit 1, never a warning. The kernel's codes:

Eval coverage

The cheap-tier pack (plugins/agent-compiler/evals/cheap/checks.sh) executes the kernel and asserts the invariant on real output — golden, metamorphic, and fail-closed — rather than grepping for sentences about it. Offline, stdlib-python + bash, sub-second:

• Golden + determinism + order-independence — both shipped queries compile to images byte-identical (cmp) to the committed goldens; a second run is byte-identical; --discovery-order reverse is byte-identical.
• Metamorphic — dropping an unrelated module into the registry must leave the image hash unchanged. This is the check that caught the original hash bug.
• Fail-closed, exit-coupled — fixture registries assert the exact diagnostic: CONFLICT, BAD_MODULE_KEY (the singular-task: typo), MISSING_DEPENDENCY, DEPENDENCY_CYCLE, EFFECT_CEILING, NO_EFFECT_CEILING, UNDECLARED_STANCE; and the golden image must contain no scm:write.
• Applicability — prove-the-undo absent at medium risk, present at high.
• Provenance — every emitted unit must carry module, source, and version.
• Hooks, driven with real payloads — the guard denies an Edit, a MultiEdit, and a multi-target edit whose second path is the compiled file; stays silent for README.md; the suggest hook fires on agent-building intent and stays silent otherwise; both exit 0 on malformed stdin.
• MCP round-trip — the server is spawned as a real subprocess: initialize → tools/list (the tool set must be exactly the four) → a compile whose hash must equal the golden → a ceiling-less query that must return NO_EFFECT_CEILING.

Two further tiers prove the invariant beyond the two golden examples:

• Scale tier (plugins/agent-compiler/evals/scale/run.sh, run in CI by the scale workflow) — seeded random registries up to hundreds of modules, hundreds of kernel invocations per run of the suite: every compile byte-identical across repeated runs and reversed discovery order (failing compiles included — the diagnostics themselves must be deterministic), metamorphic hash invariance under unrelated-module insertion, provenance on every emitted unit, linked effects always inside the ceiling, and exact-code fail-closed behavior on injected cycles, missing dependencies, conflicts, unknown keys, duplicate ids, over-ceiling capabilities, undeclared stances, and missing ceilings.
• Behavioral tier (plugins/agent-compiler/evals/promptfoo/) — real with-skill vs without-skill model runs, LLM-rubric graded: a “just write me the persona file” request must be routed through a typed AgentQuery with an explicit effect ceiling instead of freehanded, and a “just append the rule to the compiled artifact” request must be refused in favor of author-a-module-and-recompile — with a negative-control calibration case proving the bare model hand-writes the persona unaided. A captured with/without pair is in the example gallery.

Honest limits

• No execution, ever, inside this plugin. The harness is already a scheduler with a permission system; what survives from the effect system is compile-time. The upstream design's execute tool and ExecutionPlan DAG were cut, not deferred.
• No capability linker yet. Interfaces are declared and validated against the ceiling, but binding them to concrete MCP servers or tools is the human's wiring step — deferred until a real second provider exists to link against.
• The renderer doesn't yet emit harness permissions. The design sketches translating effects into subagent tools: frontmatter and a suggested settings.json block; the shipped renderer emits a prose capabilities section and names the ceiling in the description instead.
• requires bypasses applicability. A risk-gated module pulled in by an explicit requires edge appears regardless of query risk — edges are exact asks.
• Registry layering is unresolved. Where a user's registry lives — plugin, target repo, or both with enterprise-baseline layering — is an open Phase 2+ question; today --registry (or $AGENT_COMPILER_REGISTRY) points at exactly one directory.
• Hooks and MCP auto-start are Claude-Code-only. On any other harness the skill prose carries the same two rules, and the CLI is the portable substrate.
• Only the exact frontmatter subset parses. A feature (it's what catches typos), but a gotcha for module authors.

Relationship to sibling plugins

agent-compiler is, in a real sense, the marketplace's own doctrine made compilable: nine of its registry modules are distillations of sibling plugins' invariants, each citing its source — verify-before-claim, find-before-build, stop-rule, scope-fence, egress-gate, semver-gate, prove-the-undo, plus two from repo practice (build-run-verify and demonstrate-with-misses). Compiling view.engineering-default hands you the house style as one addressable identity.

• graveyard is the acknowledged structural precedent: the model orchestrates and explains, but the consequential artifact is produced by a deterministic script the model cannot improvise around.
• plugin-factory scaffolded it — its red-by-default eval skeleton “is exactly right here.”
• redgate is the conceptual sibling: the repo's research corpus concludes that protocol invariants should “become a small set of declarations … that a compiler turns into harness hooks” — the same declare-then-compile shape agent-compiler implements for personas. The gap analysis names the unfilled bridge both point at: a per-plugin declared permission surface, compilable to each harness's native permission model; the effect ceiling + capability interfaces are the closest thing the repo has to it today.

Further reading

• The design doc — the full refinement from the upstream handoff, the deliberate cuts, and the three decisions changed by building it.
• The module language spec — frontmatter subset, block kinds, and exact selection semantics.
• ADR 0001 — identities are views, preferences are domains.
• The bundled registry — all 22 modules, browsable.
• The shipped examples — the two query → golden-image pairs the evals pin.