Skip to content

v1.6.1 — Teaching Colony design artefacts + usage walkthrough

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 10:17
· 8 commits to main since this release

What's new in v1.6.1

Docs-only patch for the Teaching Colony example. Fixes two gaps a first-time reader would notice in v1.6.0:

Design spec and implementation plan are now in the public repo

Both documents lived only in the author's vault at v1.6.0. They are now at examples/teaching_colony/docs/ with provenance headers:

  • design-spec.md — the scope, motivation, substrate contract, agent composition, lifecycle, and deferrals
  • implementation-plan.md — the five-sub-agent parallel execution strategy that actually built v1.6.0, including coordination rules, write-scope boundaries, and the research risk

These are the Architect-lens artefacts for the example. Both substrate READMEs now link to them from their "Design context" line.

The README now has a three-scenario usage walkthrough

v1.6.0 had the commands but not a guided path. The new examples/teaching_colony/README.md walks a reader through three progressive runs:

  1. Run 1 — see the whole lifecycle on Claude Code. Install, run, read the summary table, open state/events.jsonl, inspect the updated Mirror, check the graduation checklist.
  2. Run 2 — reset and re-run to verify determinism. Confirm the same mock-mode colony produces the same observable events on repeated runs.
  3. Run 3 — same colony on the Managed Agents substrate. See the portability claim concretely — same six Mirrors, same classifier, same observable graduation, different adapter.

Each scenario states what to run, what to expect on stdout, where to look in state/, and how to verify the graduation happened.

Honest about the event-count gap

The walkthrough does not pretend the two substrates produce identical output at v1.6.0. Claude Code emits ~42 events; Managed Agents emits ~22. The README explains why (mock update_mirror and write_kb are no-ops on Managed Agents, dispatch.complete events not emitted), points at gaps.md for the documented reason, and confirms the portability parity tests remain in skip state for v1.6.0. Full parity is a v1.7+ deliverable.

No code changes

  • Adapters unchanged
  • Colony definition unchanged
  • Tests unchanged (26 passed, 2 skipped, 4 xfailed — identical to v1.6.0)

Known follow-up flagged for v1.7+

The Claude Code adapter writes Mirror updates back to colony/mirrors/ which is git-tracked. Real runs pollute the committed example. This was caught during v1.6.1 verification when a walkthrough test-run left graduation entries in teacher-agent.yaml. The fix (move Mirror writes to state/ or make the adapter copy-on-write) is targeted for v1.7+.


Cite as:

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