# Skill Organisms

`skill_organism(...)` is the current practical runtime for building one structured workflow out of multiple stages.

## Why It Exists

A lot of real multi-agent workflows are not “many agents everywhere.”

They look more like:

- normalize input
- classify or route cheaply
- do the ambiguous work with a stronger model
- attach telemetry, review, or other runtime concerns without rewriting the whole workflow

That is the use case `skill_organism(...)` is meant to serve.

## Core Pieces

- `SkillStage`
- `SkillOrganism`
- `TelemetryProbe`

Stages can be:

- deterministic handlers
- provider-bound agents using a fast nucleus
- provider-bound agents using a deep nucleus

## Practical Pattern

Typical workflow:

1. intake or normalization stage
2. cheap routing/classification stage
3. deeper planning or synthesis stage
4. optional attached telemetry or review

This lets one workflow behave more like a composed organism than a single prompt or an unstructured chain of scripts.

## Three-Layer Context Model

Stages within an organism have access to three layers of context, each with different lifetime and mutability:

1. **Topology** — the wiring diagram and observation structure. Structural and static within a single run.
2. **Ephemeral** — the `shared_state` dictionary. Carries routing hints, counters, and stage outputs. Mutable, not historically reconstructible.
3. **Bi-temporal** — an optional `BiTemporalMemory` substrate. Carries durable factual knowledge with dual time axes. Append-only and fully auditable.

### Ephemeral: shared_state

`shared_state` is still useful for lightweight orchestration data — routing labels, counters, temporary outputs.

### Bi-temporal: substrate

When you pass `substrate=BiTemporalMemory()` to `skill_organism(...)`, stages can:

- **Read** facts via `read_query` — a subject string or callable returning a `BiTemporalQuery`
- **Write** facts via `emit_output_fact=True` (auto-records output) or `fact_extractor` (custom event logic)

Stages receive a frozen `SubstrateView(facts, query, record_time)` rather than the raw memory instance, keeping them decoupled from memory internals.

This enables the audit question: "what did the organism know when stage X made its decision?" — answered via `retrieve_belief_state()` on the append-only history.

### Attachable components

For cross-cutting concerns you do not want to hardcode:

- telemetry (`TelemetryProbe`)
- runtime monitoring (`WatcherComponent`) — classifies signals as epistemic/somatic/species-specific, can retry/escalate/halt
- review and safety policies
- custom lifecycle hooks via `SkillRuntimeComponent`

## Recommended Examples

- [`examples/68_skill_organism_runtime.py`](../../examples/68_skill_organism_runtime.py) — deterministic intake, fast routing, deep planning, attached telemetry
- [`examples/71_bitemporal_skill_organism.py`](../../examples/71_bitemporal_skill_organism.py) — multi-stage workflow with bi-temporal substrate, belief-state reconstruction, and temporal diffs
- [`examples/73_watcher_component.py`](../../examples/73_watcher_component.py) — runtime monitoring with signal classification and retry/escalate/halt interventions
