Specifications#

The authoritative protocol and kernel-contract documentation for PluggableHarness Agent. This directory is the source of truth for anything it covers.

Start with conventions.md — it defines the requirement keywords and the anchor-only cross-reference rule every other file follows. Then glossary.md for terminology and architecture.md for the system-level narrative (microkernel philosophy, the seven provider categories, Emit→Render→Paint, transport, config, registry, sub-agents, policy, hook dispatch).

Reading order#

1. conventions.md — how to read everything else.
2. glossary.md — terminology.
3. architecture.md — the system narrative.
4. The seven plugin-category protocols (any order — cross-linked as needed):
5. model/ — model (LLM vendor) provider.
6. tool/ — tool provider (resource / data_source / interactive).
7. context/ — context provider.
8. memory/ — memory provider.
9. frontend/ — frontend provider and widget provider.
10. slashcommand/ — slash-command provider.
11. The kernel's own required behavior, not a plugin protocol:
12. agent-loop/ — the turn loop, hook dispatch, plan/apply, sub-agents.
13. configuration/ — agent.hcl, the policy DSL, agent profiles, global config, the lock file.
14. kernel-callbacks.md — the plugin→kernel direction (RunSession, CountTokens, Emit, Log, ExportSpans, RecordMetrics, GetTelemetryConfig, GetConfig, Publish, Subscribe, ReadEvents, GetSession).
15. event-bus.md — the ephemeral, best-effort cross-plugin pub/sub primitive behind Publish/Subscribe.
16. observability.md — the tracing/metrics relay behind ExportSpans/RecordMetrics/GetTelemetryConfig.
17. state-backend.md — session persistence and replay (sqlite, kernel-built-in, not pluggable in v1).

What's not here#

docs/first-party/tools/ — the first-party tool catalog, maintained separately. Not part of this protocol documentation; don't confuse it with tool/ (singular), the tool provider protocol.

Status#

Every category and kernel-behavior document describes a draft v1 contract.