Explanation
These docs explain the why behind protoWorkstacean’s architecture. Read them when you want to understand the reasoning behind a design decision, not just what the system does.
Available explanations
Section titled “Available explanations”| Document | What it explains |
|---|---|
| Executor layer | Why the executor layer exists, how resolution works, the registrar pattern, and why SkillDispatcherPlugin is the sole agent.skill.request subscriber |
| World engine | Why WorldState is a generic record, the GOAP loop design, domain discovery rationale |
| Distributed tracing | How correlationId (trace-id) and parentId (span-id) flow from the bus through RouterPlugin, A2AExecutor, external agents (protoMaker team, Quinn), and back |
| Plugin system | The plugin lifecycle, core vs integration vs workspace plugins, ordering guarantees |
Design philosophy
Section titled “Design philosophy”protoWorkstacean is built around three ideas:
-
The bus is the contract. Plugins communicate only through typed bus messages. No plugin holds a direct reference to another plugin. This makes it safe to add, remove, or replace plugins without touching existing code.
-
World state is ground truth. The GOAP loop does not make decisions based on ephemeral signals. It polls durable HTTP domains, computes a world state snapshot, and evaluates goals against that snapshot. Goals are declarative invariants — the system continuously works to satisfy them.
-
Executors are interchangeable. Whether a skill runs in-process via @protolabsai/sdk or over HTTP via A2A JSON-RPC, the bus sees no difference. The executor layer is an internal seam, not an external protocol boundary.