Coordination model

Agents coordinate through the environment — typed blackboard slots, decaying pheromone zones, and scheduler wake pressure. No conversation loops, router LLMs, or NL handoff chains.

Substrate primitives

Primitive	Role
Blackboard	Typed JSON slots; plugins read/write via `PluginContext`
Pheromone zones	Signal maps with exponential decay (`PheromoneField`)
Perception radius	Bounds how far an agent reads field signals
Pressure field	`PressureScheduler` queue — wake when deps + pressure ≥ threshold
Completion	`NextAction::Complete` deposits a `completion` signal; dependents wake

Wake pressure = min(base_pressure, min(dep signals)), boosted by multiplexer deposits (herdr_wake_boost).

Allowed vs forbidden

Pattern	Status
Deposit completion → dependent wakes	Allowed
Blackboard slot handoff (typed JSON)	Allowed
`NextAction::Delegate { task }`	Allowed
Multiplexer pane deposits	Allowed
Agent-to-agent chat	Forbidden
Router LLM choosing next agent	Forbidden
Re-encoding substrate as NL	Forbidden

Coordination flow

flowchart TB
    G[Goal] --> P[encode_task]
    P --> Q[Pending queue]
    Q --> RP[refresh_pressure]
    RP --> DEP{deps met?}
    DEP -->|no| DEFER[deferred]
    DEP -->|yes| DISPATCH[dispatch]
    DISPATCH --> HOST[RunHost]
    HOST --> OBS[observation]
    OBS --> BB[Blackboard]
    OBS --> FIELD[PheromoneField]
    OBS --> V[verify_goal]
    V --> COMP[deposit completion]
    COMP --> FIELD
    FIELD --> RP

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef substrate stroke:#8250df,stroke-width:2px
    classDef gate stroke:#1a7f37,stroke-width:2px

    class G,P,Q,RP,DISPATCH,HOST runtime
    class OBS,BB,FIELD substrate
    class V,COMP gate

Scheduler loop

CastellanEngine::run_goal:

Encode the initial task from the plugin manifest
Decay the field → refresh pressure → dispatch the ready batch
Read host output → apply deposits → coordinate in-zone
Verify → deposit completion → enqueue retries/delegates
Snapshot field, topology, and wake stats into episode JSON under .castellan/episodes/

Multiplexer deposits

Remote observations may include pane deposits:

{"pheromone_deposits": [{"zone": "herdr", "signal": "activity", "amount": 0.5}]}

These feed herdr_wake_boost, waking stalled tasks when panes report activity.

Keyboard shortcuts