Plugin architecture

What Is a FlockPlugin?

A plugin is a goal environment adapter: it encodes goals into runnable tasks, verifies observations against goals, and scores outcomes for evolution.

#![allow(unused)]
fn main() {
#[async_trait]
pub trait FlockPlugin: Send + Sync {
    fn name(&self) -> &'static str;
    fn encode_task(&self, goal: &Goal) -> TaskDescriptor;
    async fn verify_goal(&self, goal: &Goal, observation: &serde_json::Value) -> AgentReport;
    fn fitness(&self, goal: &Goal, report: &AgentReport) -> FitnessVector;
    fn tools(&self) -> Vec<ToolSpec> { vec![] }
}
}

Supporting traits:

• GoalVerifier — verify-only surface for RLM loops
• CrucibleAdapter — verify + automatic remediation hints (CruciblePluginAdapter)

Coordination hooks (optional, via context at runtime):

• PluginContext — blackboard read/write, budget snapshot
• CoordinationContext — zone list, perception radius, deposit_signal / read_signal

Current plugins

Lifecycle

register → encode → scheduler run → verify → episode snapshot → evolve fitness

1. Register — PluginRegistry::builtin() loads built-ins + manifest TOML
2. Encode — encode_task(goal) produces initial TaskDescriptor payload
3. Run — scheduler enqueues in plugin primary zone; host executes; observations flow back
4. Verify — verify_goal returns AgentReport with NextAction
5. Episode — runtime writes .flock/episodes/<goal-id>.json
6. Evolve — flock evolve reads episodes; plugin name in environment_fingerprint seeds archive lookup

Plugin manifest (plugin.toml)

name = "gridworld"
description = "Deterministic 5x5 grid navigation simulator"
version = "0.1.0"

[zones]
primary = "grid"
default = ["grid", "goal"]

[blackboard]
slots = ["state", "last_observation"]

Manifests live at crates/flock-plugins/<name>/plugin.toml. Discovery scans that tree at registry init.

Add a plugin in under 10 minutes

flock plugin new myplugin
flock plugin list
flock run --goal "your goal" --plugin myplugin

Installed plugins register automatically via plugins.toml + build.rs — no registry.rs edit.

Extension points

Related

• Coordination model
• Evolution
• CLI reference