Skip to content

v1.5.0 — Accessibility Through Abstraction

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 08:15
· 11 commits to main since this release

What's new in v1.5.0

A seventh core principle — Accessibility through abstraction — and the audience-lens model as its canonical realisation.

Most people understand what a beehive is and what the queen bee does, but will never understand the processes, jobs, and roles all the bees perform unless they become beekeepers. The same must be true of an Agent Colony. Most audiences need a metaphor and an outcome, not a mechanism. Forcing them to read the specification to benefit from the pattern was a violation of a principle that had not yet been named. v1.5.0 names it.

Principle 7 — Accessibility through abstraction

The colony must be understandable at every audience's depth, no deeper. Complexity is an investment paid once, upfront, so that each audience sees only what it needs.

Corollary — ease is earned: the simple surface is the output of hard substrate work, not the absence of it. An implementation that is easy to use because the mechanisms aren't there is violating Principle 6 (mutual defence), not fulfilling Principle 7.

The audience-lens model

Five sequential lenses, each served by a specific artefact in this repository:

# Lens Depth Canonical artefact
1 Newcomer Metaphor It takes a village (Medium + knowledge-base/writings/)
2 Observer Outcome Agent outputs themselves — invisibility is the point
3 Operator Health Colony snapshot + equilibrium playground
4 Beekeeper Mechanism Agent Mirrors + hello-colony-runtime + graduation checklists
5 Architect Substrate Specification + thesis + schemas

Key properties:

  • Sequential by default. Natural traversal is 1→2→3→4→5. Most audiences stop at Observer.
  • Re-entry is always possible. Anyone meeting an unfamiliar colony is briefly a Newcomer again, regardless of their role elsewhere.
  • View, not configuration. All mechanisms — Comprehension Contract, classifier, Mirror fields, Review Regime — are present and enforced at every lens. Switching lenses changes what the audience sees, not what the colony does.
  • Pacing can compress. A colony can be instantiated in an afternoon, so the traversal may take days rather than decades.
  • Artefact mapping is required for conformance. Claiming Principle 7 conformance means naming which artefact serves which lens.

New in the specification

  • §1 Audience Lenses — new subsection parallel to Scales of Application, describing the model, the five lenses, and their properties
  • §8.5.1 anti-pattern #8 — Lens inversion — forcing low-depth audiences to read high-depth artefacts to use the colony at all

New diagram

  • diagrams/agent-colony-lens-traversal.svg — the five sequential lenses, their artefacts, the re-entry curve, and the view-not-configuration note in a single visual

Known gap (deferred to v1.6+)

The existing six mechanism diagrams (four-layer architecture, equilibrium system, maturity model, agent mirror, memory cycle, evolutionary context) are pitched at the Beekeeper/Architect level. By Principle 7's own test, the Newcomer and Observer lenses are under-served in diagram form — they would need companion "village-level" visual explanations that do not yet exist. This is deferred to v1.6+ rather than shipping v1.5.0 pretending the existing diagrams already serve all five lenses. Naming the gap is more honest than hiding it.


Status: The pattern remains practically untested at production scale — no full LLM-backed reference implementation exists yet. Principle 7 is additive: it describes how the colony presents itself to its audiences, not how it works. Prior v1.4.x conformance claims are not invalidated.

Cite as:

Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.5.0). https://github.com/DavidROliverBA/agent-colony-pattern