Repository navigation
v1.6.1 — Teaching Colony design artefacts + usage walkthrough
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:
- 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. - Run 2 — reset and re-run to verify determinism. Confirm the same mock-mode colony produces the same observable events on repeated runs.
- 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