Nexus

Nexus is a modular AI agent harness built on a pure event-driven architecture in Go. The core manages only the event lifecycle and plugin registry — all behavior is delivered through composable plugins.

This means you can assemble exactly the agent you need by choosing which plugins to activate, how to configure them, and optionally writing your own.

Why Nexus?

• Event-driven core — Plugins never call each other directly. All communication flows through a central typed event bus, making the system loosely coupled and easy to extend.
• Composable by design — Pick an agent strategy (ReAct, Plan & Execute, Orchestrator), pair it with tools, memory, and an I/O interface, and you have a working agent.
• Minimal dependencies — Only gopkg.in/yaml.v3 beyond the Go standard library. The Anthropic API is called via raw HTTP — no SDK required.
• Configuration-driven — YAML profiles let you define entirely different agent behaviors without changing code.
• Session persistence — Every session captures conversation history, thinking steps, plans, and file artifacts to a structured workspace on disk.

What You Can Build

• Coding assistants with shell access, file I/O, and planning capabilities
• Research agents with large context windows and no tool access
• Multi-agent workflows using the orchestrator to decompose tasks across worker subagents
• Document analysis pipelines with PDF extraction and skill-based instructions
• File-driven multi-stage workflows with the ICM plugin — a folder on disk is the workflow, contracts per stage, loops + fan-out + human gates included
• Custom domain agents by writing your own plugins and skills

How This Documentation is Organized

Quick Start

# Clone and build
git clone https://github.com/frankbardon/nexus.git
cd nexus
make build

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Run with the default profile
bin/nexus -config configs/default.yaml

See Installation for full details.

Installation

Prerequisites

• Go 1.21+ — Nexus is written in Go and builds with the standard toolchain
• An API key for at least one LLM provider — Nexus ships with first-party providers for Anthropic (Claude) and OpenAI (GPT / o-series). Bring your own key for whichever provider(s) your config activates.

Optional:

• poppler-utils — Required only if you use the PDF reader plugin (pdftotext, pdfinfo)

Building from Source

git clone https://github.com/frankbardon/nexus.git
cd nexus
make build

This produces a binary at bin/nexus.

Available Make Targets

Setting Your API Key

Each provider plugin reads its key from an environment variable. The default names match the upstream convention: ANTHROPIC_API_KEY for the Anthropic plugin, OPENAI_API_KEY for the OpenAI plugin. Set whichever your active config needs:

# Using Claude
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Or using OpenAI
export OPENAI_API_KEY="sk-your-key-here"

Or place them in a .env file in the project root:

ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here

You can also pass the key inline (api_key:) or point at a different env var (api_key_env:) per-provider. See the Anthropic and OpenAI plugin pages for the full options, plus Fallback and Fanout for using multiple providers together.

Running Nexus

Run with a specific configuration file:

bin/nexus -config configs/default.yaml

CLI Flags

Resuming a Session

To resume a previous session, pass the session ID:

bin/nexus -recall abc123def456

This loads the session’s config snapshot so the agent starts with the same configuration it had originally.

Your First Configuration

Nexus configuration is a single YAML file with two top-level sections: core (engine settings) and plugins (what to activate and how to configure it).

Minimal Configuration

Here’s the simplest useful configuration — a conversational agent with no tools:

core:
  log_level: warn
  models:
    default: balanced
    balanced:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.memory.capped

  nexus.agent.react:
    max_iterations: 10
    system_prompt: "You are a helpful assistant."

  nexus.memory.capped:
    max_messages: 100
    persist: true

Save this as my-agent.yaml and run it:

bin/nexus -config my-agent.yaml

Understanding the Structure

Core Section

The core section configures the engine itself:

core:
  log_level: warn          # debug | info | warn | error
  tick_interval: 5s        # heartbeat interval
  max_concurrent_events: 100

  models:
    default: balanced      # which role to use when none specified
    reasoning:             # high-capability model for planning
      provider: nexus.llm.anthropic
      model: claude-opus-4-20250514
      max_tokens: 16384
    balanced:              # general-purpose model
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    quick:                 # fast model for simple tasks
      provider: nexus.llm.anthropic
      model: claude-haiku-4-5-20251001
      max_tokens: 4096

  sessions:
    root: ~/.nexus/sessions
    retention: 30d
    id_format: datetime_short

Plugins Section

The plugins section has two parts:

1. active — a list of plugin IDs to load (order doesn’t matter; dependencies are resolved automatically)
2. Per-plugin config — each key matching a plugin ID provides that plugin’s settings

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.tool.shell
    - nexus.tool.file

  nexus.tool.shell:
    allowed_commands: ["ls", "cat", "grep", "find"]
    timeout: 30s
    sandbox: true

Adding Tools

To give your agent capabilities, add tool plugins to the active list and configure them:

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.tool.shell          # Shell command execution
    - nexus.tool.file           # File read/write/list
    - nexus.control.hitl        # ask_user tool + HITL approvals
    - nexus.memory.capped

  nexus.tool.shell:
    allowed_commands: ["go", "git", "ls", "cat", "grep", "make"]
    timeout: 30s
    sandbox: true

Tools register themselves automatically when the agent starts. The agent discovers available tools through the event bus — no explicit wiring needed.

Adding Planning

To enable a planning phase before the agent acts, add a planner plugin and set planning: true on the agent:

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.planner.dynamic
    - nexus.observe.thinking
    # ... other plugins

  nexus.agent.react:
    max_iterations: 10
    planning: true
    system_prompt: |
      You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

      ## Guidelines

      1. Always explain your reasoning before making changes
      2. Run tests after modifications to verify correctness
      3. Prefer minimal, targeted changes over broad refactors
      4. Ask for clarification when requirements are ambiguous
      5. Read files in chunks 16kb or less
      6. Follow the existing code style and conventions of the project

  nexus.planner.dynamic:
    approval: auto          # always | never | auto
    max_steps: 10
    model_role: reasoning   # use the high-capability model for planning

See Dynamic Planner and Static Planner for details.

Using System Prompts

System prompts can be defined inline or loaded from a file:

# Inline
nexus.agent.react:
  system_prompt: "You are a coding assistant. Be concise and precise."

# From file
nexus.agent.react:
  system_prompt: |
      You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

      ## Guidelines

      1. Always explain your reasoning before making changes
      2. Run tests after modifications to verify correctness
      3. Prefer minimal, targeted changes over broad refactors
      4. Ask for clarification when requirements are ambiguous
      5. Read files in chunks 16kb or less
      6. Follow the existing code style and conventions of the project

Next Steps

• Learn about the architecture to understand how plugins communicate
• Browse the plugin reference to see what’s available

Architecture Overview

Nexus follows a strict event-driven architecture. The engine is intentionally minimal — it provides the event bus, plugin registry, lifecycle management, and session workspace. All behavior comes from plugins.

Core Principle

Plugins never call each other directly. Every interaction flows through the central event bus as typed events. This keeps plugins decoupled and makes the system easy to extend or reconfigure.

flowchart TB
    subgraph Engine["🛠 Engine (pkg/engine)"]
        direction TB
        EB[EventBus]
        REG[PluginRegistry]
        LM[LifecycleManager]
        EB --- REG --- LM
        DISPATCH{{Event Dispatch}}
        EB --> DISPATCH
    end

    DISPATCH --> IO[IO Plugins<br/>tui · browser · wails]
    DISPATCH --> AG[Agent Plugins<br/>react · planexec · orchestrator]
    DISPATCH --> LLM[LLM Providers<br/>anthropic · openai · fallback]
    DISPATCH --> TL[Tool Plugins<br/>shell · file · web · knowledge_search]
    DISPATCH --> MEM[Memory Plugins<br/>capped · summary · longterm · vector]
    DISPATCH --> OBS[Observers<br/>logger · otel · thinking]

    classDef engine fill:#1e3a5f,stroke:#4a90e2,stroke-width:2px,color:#fff;
    classDef plugin fill:#2d4a3e,stroke:#5fb878,stroke-width:1.5px,color:#fff;
    classDef dispatch fill:#4a3a5f,stroke:#9b59b6,stroke-width:2px,color:#fff;
    class EB,REG,LM engine;
    class IO,AG,LLM,TL,MEM,OBS plugin;
    class DISPATCH dispatch;

Engine Components

The engine (pkg/engine/) contains these components:

Boot Sequence

When Engine.Run() is called:

1. Config loaded — YAML file is parsed, defaults merged, per-plugin configs extracted
2. Session created — A new session workspace is set up on disk (or an existing one is resumed)
3. core.boot emitted — Signals the start of the boot process
4. Plugins initialized — Topologically sorted by dependencies, then Init() called serially
5. Plugins readied — Ready() called in parallel on all initialized plugins
6. core.ready emitted — All plugins are up and listening
7. Event loop — The engine listens for events until a shutdown signal arrives
8. Shutdown — Plugins shut down in reverse dependency order, core.shutdown emitted

sequenceDiagram
    autonumber
    participant Caller as Caller<br/>(CLI / Embedder)
    participant Engine
    participant Session
    participant Bus as EventBus
    participant Plugins

    Caller->>Engine: Run(ctx)
    Engine->>Engine: Load YAML config
    Engine->>Session: Create session workspace
    Engine->>Bus: emit core.boot
    Bus->>Plugins: Init() in dependency order
    Plugins-->>Bus: subscriptions registered
    Engine->>Plugins: Ready() in parallel
    Engine->>Bus: emit core.ready
    Note over Bus,Plugins: Event loop —<br/>plugins drive behavior
    Caller-->>Engine: SIGINT / Stop()
    Engine->>Plugins: Shutdown() in reverse order
    Engine->>Bus: emit core.shutdown

Event Flow Example

Here’s a typical request flow through the system:

sequenceDiagram
    autonumber
    actor User
    participant IO as nexus.io.tui
    participant Agent as nexus.agent.react
    participant LLM as nexus.llm.anthropic
    participant Gates as before:* gates
    participant Tool as nexus.tool.shell

    User->>IO: types message
    IO->>Agent: io.input
    Agent->>LLM: llm.request
    LLM->>LLM: call Claude API
    LLM-->>Agent: llm.response

    alt response contains tool calls
        Agent->>Gates: before:tool.invoke (vetoable)
        Gates-->>Agent: pass
        Agent->>Tool: tool.invoke
        Tool->>Tool: execute
        Tool->>Gates: before:tool.result (vetoable)
        Gates-->>Tool: pass
        Tool-->>Agent: tool.result
        Agent->>LLM: llm.request (loop)
    else final answer
        Agent->>IO: io.output
        IO-->>User: display response
    end

Key Design Decisions

Synchronous Dispatch

Events are dispatched synchronously — handlers execute one at a time, ordered by priority. This makes the system predictable and avoids race conditions.

Vetoable Events

Events prefixed with before: are vetoable. Any handler can block the action by setting a veto on the payload. This enables approval workflows (e.g., confirming tool execution).

Plugin Dependencies

Plugins declare their dependencies by ID. The lifecycle manager topologically sorts them to ensure correct init order. Circular dependencies cause a boot failure.

Multi-Instance Plugins

Some plugins (like nexus.agent.subagent) support multiple instances via ID suffixes. For example, nexus.agent.subagent/researcher creates an instance with InstanceID set to the full suffixed ID.

Next Steps

• Event Bus — How events are dispatched, filtered, and prioritized
• Plugin System — The plugin interface, lifecycle, and how to write your own
• Sessions — How session data is persisted to disk

Event Bus

The event bus is the central nervous system of Nexus. Every plugin communicates exclusively through it — emitting events when something happens, and subscribing to events it cares about.

Interface

type EventBus interface {
    Emit(eventType string, payload any) error
    EmitEvent(event Event[any]) error
    EmitAsync(eventType string, payload any) <-chan error
    Subscribe(eventType string, handler HandlerFunc, opts ...SubscribeOption) (unsubscribe func())
    SubscribeAll(handler HandlerFunc) (unsubscribe func())
    EmitVetoable(eventType string, payload any) (VetoResult, error)
    Drain(ctx context.Context) error
}

Events

Every event is a typed container with metadata and a Causation block that records its provenance:

type Event[T any] struct {
    Type      string         // Dotted namespace (e.g., "llm.request")
    ID        string         // Random hex identifier
    Timestamp time.Time      // When the event was created
    Source    string         // Plugin ID that emitted this event
    Payload   T              // The event-specific data
    Causation EventCausation // Auto-filled by the bus — see Causation, below
}

See Causation for the full discussion of how ParentID, SessionID, AgentID, Sequence, and Depth are populated and how plugins push their own CausationContext. The short version: the bus does the bookkeeping. Plugin authors don’t have to thread session identity through every emit site.

Event types follow a dotted namespace convention:

Subscribing to Events

Plugins declare their subscriptions in the Subscriptions() method:

func (p *MyPlugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "io.input", Priority: 50},
        {EventType: "tool.result", Priority: 50},
    }
}

Or subscribe dynamically during Init():

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    ctx.Bus.Subscribe("some.event", p.handleEvent, engine.WithPriority(10))
    return nil
}

Subscribe Options

Priority Ordering

Handlers for the same event type execute in priority order (ascending). This is how the system ensures, for example, that the LLM provider processes requests before observers log them.

Common conventions:

• 5–10 — High priority (providers, cancellation handlers)
• 50 — Normal priority (most plugins)
• 90 — Low priority (observers, persistence)

Wildcard Subscriptions

SubscribeAll() registers a handler that receives every event, regardless of type. This is used by the event logger to capture all activity:

ctx.Bus.SubscribeAll(func(event engine.Event[any]) {
    // Logs every event in the system
})

Emitting Events

Plugins emit events by calling Emit() with a type string and payload:

ctx.Bus.Emit("tool.result", events.ToolResult{
    ID:     callID,
    Name:   "shell",
    Output: output,
})

Plugins must declare all event types they may emit in the Emissions() method:

func (p *MyPlugin) Emissions() []string {
    return []string{"tool.result", "tool.register", "core.error"}
}

Async Emit

EmitAsync() dispatches an event in a separate goroutine, returning immediately with a channel that receives nil on success or an error:

ch := ctx.Bus.EmitAsync("llm.request", request)
// ... do other work ...
if err := <-ch; err != nil {
    // handle error
}

Handlers still run synchronously within the goroutine — EmitAsync only makes the dispatch non-blocking relative to the caller. Used by the fanout plugin to send parallel requests to multiple providers.

Vetoable Events

Events prefixed with before: support vetoing. This enables approval workflows — for example, the TUI can present an approval dialog before a tool runs.

result, err := ctx.Bus.EmitVetoable("before:tool.invoke", toolCall)
if result.Vetoed {
    // Action was blocked
    fmt.Println("Vetoed:", result.Reason)
    return
}
// Proceed with the action
ctx.Bus.Emit("tool.invoke", toolCall)

Handlers veto by modifying the payload:

func (p *MyPlugin) handleBeforeToolInvoke(event engine.Event[any]) {
    vr := event.Payload.(*engine.VetoResult)
    vr.Vetoed = true
    vr.Reason = "User denied tool execution"
}

Event Filters

Filters are predicate functions that gate handler execution:

ctx.Bus.Subscribe("llm.response", p.handleResponse,
    engine.WithPriority(10),
    engine.WithFilter(func(meta engine.EventMeta) bool {
        return meta.Source == "nexus.llm.anthropic"
    }),
)

Draining

Drain() waits for all in-flight events to complete. This is used during shutdown to ensure no events are lost:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
bus.Drain(ctx)

Thread Safety

The event bus is safe for concurrent use. Handler registration and event dispatch use read-write locks. Handler slices are copied before dispatch to allow concurrent emits without blocking.

Events

The pkg/events package defines every typed payload that flows over the engine bus. Plugins import these types directly; the journal (pkg/engine/journal/) writes them to disk; out-of-tree consumers (replay tools, dashboards, MCP servers, embedders) read those journals and depend on the same struct shapes.

Because the contract is observable to many parties, every change to a payload struct is a potential compatibility event. Nexus uses a simple per-event-type versioning scheme to make those events explicit and auditable.

Versioning convention

Every top-level event-payload struct carries two things:

1. A version constant: <StructName>Version = 1.
2. A SchemaVersion int \json:“_schema_version”`` field as the first declared field on the struct.

Producers stamp SchemaVersion = <StructName>Version on every emitted literal. The journal records the stamped value verbatim, so downstream consumers can branch on the contract version without correlating to build metadata or git revisions.

Example:

const LLMRequestVersion = 1

type LLMRequest struct {
    SchemaVersion int `json:"_schema_version"`

    Role     string
    Model    string
    Messages []Message
    // ...
}

// Producer:
_ = bus.Emit("llm.request", events.LLMRequest{
    SchemaVersion: events.LLMRequestVersion,
    Role:          "balanced",
    // ...
})

Versions start at 1. Nexus is a fresh project — there is no historical drift to encode in a 0-baseline. The only place 0 appears is the deserialization rule below.

Why per-type versions, not a global one

Because event payloads churn at very different rates. llm.request may gain a field every quarter; core.tick is unlikely to ever change. Coupling them into a single global version forces a cascade of consumer-side compatibility code that is mostly noise.

The v0 == v1 deserialization rule

When a journal record (or a third-party producer that hasn’t yet adopted the field) leaves out _schema_version, JSON deserializes it to Go’s zero value: 0. Consumers MUST treat 0 as v1 — the running code’s contract — rather than reject the payload.

This keeps:

• Journals written before the field existed replayable. Idea 01 (durable journal) shipped before Phase 4 of Idea 10. Replay must flow through the new code path without rewriting old records.
• Embedders that haven’t pulled the latest Nexus minor interoperable. Producers running an older Nexus emit payloads without the field; the new bus should accept them.

The rule is implicit while v1 is the only shipped version: nothing special happens during unmarshal. The first v2 to ship will register a {Type, From: 0, To: 1} no-op in pkg/events/compat/ plus the real {Type, From: 1, To: 2} migrator chained after it. compat.Apply is the single entry point.

Compat package

pkg/events/compat/ holds field-level migrations between versions. The public surface is small:

type Key struct {
    EventType string  // "llm.request"
    From, To  int
}

type Migrator func(payload map[string]any) (map[string]any, error)

var Migrations = map[Key]Migrator{}

func Apply(eventType string, from, to int, payload map[string]any) (map[string]any, error)

Apply chains one-step migrators from from up to to. With the registry empty — today’s state — Apply is a no-op pass-through.

Compat is wired into the journal-replay path in two places:

• pkg/engine/engine.go — replayPayloadConverter calls compat.Apply before journal.PayloadAs[T] re-types map payloads back into structs for live re-emission during engine.ReplaySession.
• pkg/eval/runner/runner.go — same pattern for the eval harness’s case-driven replay path.

When a future PR ships v2 of an event type, the migrator goes into pkg/events/compat/ and replay-time data flows through it without touching the engine. No engine code change required.

Lint rule guarantee

make check-events (alias of scripts/check-event-versions.sh, backed by internal/cmd/check-event-versions/) compares the working tree’s pkg/events/*.go against a base git revision (default HEAD~1, override via CHECK_EVENTS_BASE). It fails the build when:

• A field was removed from an existing struct without bumping the matching <Name>Version constant.
• A field was renamed (heuristic: same position + same type, but different name) without a bump.
• A field’s type changed without a bump.

Additive changes (new fields with sensible zero defaults) pass without a bump because they are forward-compatible — older consumers ignore the unknown field, JSON round-trips preserve it.

The rule wires into make lint so existing Go-quality CI gates catch schema regressions automatically.

False positives (e.g., reordering fields with identical types) are tolerable — the operator just bumps the version trivially. False negatives (a rename slipping through) are the failure case the rule guards against; the position+type+name comparator catches that class.

Author guide

Adding a new event type

1. Define the struct in the appropriate per-domain file (core.go, llm.go, agent.go, …) with SchemaVersion int \json:“_schema_version”`` as the first declared field.
2. Add <Name>Version = 1 to that file’s version-constants block.
3. List the struct in pkg/events/version_test.go’s versionedPayloads() table so the round-trip test covers it.
4. Producers must stamp SchemaVersion: events.<Name>Version on every literal they emit.

Mutating an existing event type

• Adding a field with a sensible zero default — go ahead. No bump needed; the lint check passes.
• Removing a field — bump <Name>Version and register a {Type, From: oldVer, To: newVer} migrator in pkg/events/compat/ that drops the field from old payloads (or rewrites it onto a replacement field).
• Renaming a field — same as removal: bump the version, register a migrator that copies the old key to the new key.
• Changing a field’s type — same: bump and register a converter.

The pkg/events/compat/compat_test.go placeholder test demonstrates the registration pattern; copy it for new migrators.

What NOT to version

Helper structs that exist only as nested fields inside top-level payloads (Message, Citation, ToolCallRequest, Usage, etc.) deliberately do not carry SchemaVersion. They have no independent identity on the wire — their version is the version of the enclosing payload. Versioning them would double-count migrations and clutter every literal.

When in doubt, version it; the cost of an extra int is dwarfed by the cost of an undetected breaking change.

Causation

Every dispatched event in Nexus carries a Causation block that records its provenance: the parent event that caused it, the session it belongs to, the agent that produced it, and a monotonic per-session sequence number. The bus populates these fields automatically — plugin authors don’t have to remember to set them.

Why

Causation is the substrate the Replay primitive walks, the attribution observability collectors filter on, and the dimension the Sub-agent delegation runtime uses to distinguish a parent’s work from a specialist’s. Once it’s present on every event, you can:

• Walk an entire session’s causation DAG to debug what happened.
• Filter envelopes by AgentID to inspect just one specialist’s work.
• Branch and fork: replay to a sequence, then continue along a different path.

Schema

type EventCausation struct {
    ParentID  string // EventID of the event whose handler emitted this one
    ParentSeq uint64 // Mirrors ParentID via the per-session monotonic sequence
    SessionID string // Session this event belongs to
    AgentID   string // Agent that produced it (sub-agent identity for delegate work)
    Sequence  uint64 // Monotonic per session; assigned at dispatch
    Depth     int    // Sub-agent recursion depth at emission time
}

Causation lives on both Event[T] and EventMeta. Wildcard subscribers and filters see it without unwrapping the payload.

How it’s filled

Three sources, in priority order:

1. Caller-set fields win. Replay tools and sub-agent runtimes that need to override the auto-derived values do so by populating Causation on the Event[any] they pass to EmitEvent. The bus respects any non-zero / non-empty field.
2. Dispatch stack supplies ParentID and ParentSeq. The bus tracks the in-flight event per goroutine; anything emitted inside that goroutine’s handler chain inherits the in-flight event as its parent.
3. Causation context supplies SessionID, AgentID, Depth. Two sources here:
   • PushCausationContext(c) func() — per-goroutine stack pushed by callers that have explicit knowledge of who they’re running for (sub-agent dispatch, IO transports binding to a session).
   • SetDefaultCausationContext(c) — bus-wide fallback applied when the calling goroutine has nothing pushed. Engine.StartSession installs the SessionID here so every dispatched event carries session attribution even when emitters never call PushCausationContext.

Pushing context

The typical pattern: push at the start of a scoped operation, defer the pop.

if cc, ok := bus.(engine.CausationController); ok {
    pop := cc.PushCausationContext(engine.CausationContext{
        AgentID: "delegate/analyst/" + subSessionID,
        Depth:   parentDepth + 1,
    })
    defer pop()
}
// Every event emitted from this goroutine until pop() carries the AgentID
// and Depth above.

CausationController is an optional interface — checking the assertion at call sites keeps embedders using a custom bus implementation untouched.

Journal

The journal.Envelope written by pkg/engine/journal carries Seq, ParentSeq, ParentID, SessionID, AgentID, and Depth alongside the payload, so downstream replay (pkg/replay) and projection tools can reconstruct the full causation DAG without re-deriving anything.

Excluded events

Events on the journal exclusion set (core.tick by default) skip seq assignment, dispatch-stack tracking, and the replay ring — and therefore have Sequence = 0 and no ParentSeq / ParentID. They still carry the default SessionID / AgentID from the causation context so observability tooling can attribute the heartbeats.

Plugin System

Every piece of behavior in Nexus is delivered through plugins. The engine itself only manages the event bus, plugin lifecycle, and session workspace.

Plugin Interface

All plugins implement the engine.Plugin interface:

type Plugin interface {
    ID() string                              // Unique identifier (e.g., "nexus.tool.shell")
    Name() string                            // Human-readable name
    Version() string                         // Version string
    Dependencies() []string                  // IDs that must ALREADY be active (orders boot)
    Requires() []Requirement                 // IDs to auto-activate if absent (see below)
    Init(ctx PluginContext) error             // Initialize with engine services
    Ready() error                            // Called after all plugins initialized
    Shutdown(ctx context.Context) error       // Graceful teardown
    Subscriptions() []EventSubscription      // Events this plugin listens to
    Emissions() []string                     // Event types this plugin may emit
}

Dependencies() vs Requires()

Two related but distinct methods:

• Dependencies() only validates that the listed IDs are already active and orders boot (topological sort). If an ID in the list is missing, boot fails. It never activates anything.
• Requires() activates missing siblings with default config. At boot, the lifecycle walks Requires() transitively from the user-declared active list and appends any missing IDs before the topological sort runs.

Return Requires() []Requirement { return nil } when a plugin has no hard siblings.

Auto-activation semantics

type Requirement struct {
    ID       string            // plugin to auto-activate
    Default  map[string]any    // config used only when user has not configured ID
    Optional bool              // true → skip silently with WARN when factory is unregistered
}

Merge rule: whole-object replace. If the user supplies any config for the required ID, the user’s config wins entirely and Default is discarded. There is no field-level merge. This keeps precedence predictable and avoids surprise overrides.

Cycles. A cycle in Requires() is detected the same way as a Dependencies() cycle — boot fails with a clear error.

Visibility. Every auto-activation emits an INFO log at boot:

auto-activating plugin nexus.memory.capped (required by nexus.agent.react); config_source=default

After expansion completes, a single "active plugin set resolved" line lists every entry annotated [user] (declared in config) or [auto: required-by=X,config=default|user-override]. Missing optional requirements log WARN and boot proceeds.

Example: ReAct’s Requires().

func (p *Plugin) Requires() []engine.Requirement {
    return []engine.Requirement{
        {
            ID: "nexus.memory.capped",
            Default: map[string]any{"max_messages": 100, "persist": true},
        },
        {ID: "nexus.control.cancel"},
        {ID: "nexus.tool.catalog"},
    }
}

When a user’s config lists only nexus.agent.react in plugins.active, the engine automatically brings in the conversation, cancel, and catalog plugins at boot. Users can still override any of them by listing the ID in plugins.active with their own config map.

Plugin Context

During initialization, each plugin receives a PluginContext with access to engine services:

type PluginContext struct {
    Config     map[string]any     // This plugin's config from YAML
    Bus        EventBus           // The central event bus
    Logger     *slog.Logger       // Structured logger scoped to this plugin
    DataDir    string             // Session-scoped directory for this plugin's data
    Session    *SessionWorkspace  // The active session workspace
    Models     *ModelRegistry     // Resolve model roles to concrete configs
    Prompts    *PromptRegistry    // Register dynamic system prompt sections
    System     *SystemInfo        // Platform info (OS, arch, open command)
    InstanceID string             // Full ID including suffix for multi-instance plugins
}

Plugin ID Convention

Plugin IDs use a dotted namespace: nexus.<category>.<name>

Plugin Registration

Plugins are registered as factories in main.go:

eng.Registry.Register("nexus.tool.shell", shell.New)
eng.Registry.Register("nexus.tool.file", fileio.New)

The factory function signature is:

func New() engine.Plugin

Registration makes the plugin available — it won’t be instantiated unless it appears in the config’s active list.

Lifecycle

stateDiagram-v2
    direction LR
    [*] --> registered: factory registered
    registered --> initialized: Init(ctx) — serial
    initialized --> ready: Ready() — parallel
    ready --> ready: handle events
    ready --> shutdown: SIGINT / Stop()
    shutdown --> [*]: Shutdown() — reverse order

    note left of registered
        Plugin appears in config
        active list — factory
        produces an instance.
    end note
    note right of ready
        Plugins talk only
        through the event bus.
    end note

Boot Phase

1. The lifecycle manager reads the active list from config
2. Plugins are topologically sorted by their declared Dependencies()
3. Init() is called serially in dependency order — each plugin receives its PluginContext
4. Ready() is called on all plugins (can run in parallel)

Runtime

During runtime, plugins interact exclusively through the event bus. They emit events and handle events they’ve subscribed to.

Shutdown Phase

1. A shutdown signal arrives (SIGINT, SIGTERM, or programmatic)
2. Shutdown() is called on each plugin in reverse dependency order
3. The event bus drains remaining in-flight events

Dependencies

Plugins declare dependencies on other plugin IDs:

func (p *MyPlugin) Dependencies() []string {
    return []string{"nexus.llm.anthropic", "nexus.agent.react"}
}

The lifecycle manager ensures dependencies are initialized before dependents. Circular dependencies cause a boot-time error.

Instance-Aware Dependencies

For multi-instance plugins (e.g., nexus.agent.subagent/researcher), the dependency resolver first tries an exact match, then falls back to the base ID (without the suffix).

Multi-Instance Plugins

Some plugins support running multiple instances. In the config, use a slash suffix:

plugins:
  active:
    - nexus.agent.subagent/researcher
    - nexus.agent.subagent/writer

  nexus.agent.subagent/researcher:
    system_prompt: "You are a research specialist."
    tool_name: spawn_researcher

  nexus.agent.subagent/writer:
    system_prompt: "You are a writing specialist."
    tool_name: spawn_writer

Each instance receives its full ID (including suffix) in PluginContext.InstanceID. The instance should use this as its identity rather than the hardcoded base ID.

Subscriptions and Emissions

Plugins declare what they listen to and what they emit. This serves as documentation and enables future validation:

func (p *MyPlugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "io.input", Priority: 50},
        {EventType: "tool.result", Priority: 50},
    }
}

func (p *MyPlugin) Emissions() []string {
    return []string{"io.output", "llm.request"}
}

Subscriptions declared here are automatically registered by the lifecycle manager. Plugins can also subscribe dynamically in Init() or Ready().

Plugin Data Directory

Each plugin gets a session-scoped directory for persisting data:

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    // ctx.DataDir points to: ~/.nexus/sessions/<id>/plugins/<plugin-id>/
    // Write plugin-specific data here
    return nil
}

This directory is created lazily when accessed via Session.PluginDir(pluginID).

Sessions

Every Nexus run creates a session — a persistent workspace on disk that captures conversation history, thinking steps, plans, and plugin data.

Directory Structure

Sessions are stored under the configured root directory (default: ~/.nexus/sessions/):

~/.nexus/sessions/<session-id>/
├── context/
│   └── conversation.jsonl    # Conversation history (from memory plugin)
├── files/                    # Files created during the session
├── journal/
│   ├── active.jsonl          # Live event journal (every bus event,
│   │                         #   including thinking.step + plan.progress)
│   └── *.jsonl.zst           # Rotated, zstd-compressed segments
├── metadata/
│   ├── session.json          # Session metadata
│   └── config-snapshot.yaml  # Config used for this session
└── plugins/
    └── <plugin-id>/          # Per-plugin data directories

Thinking steps and plan progress are no longer kept in dedicated thinking.jsonl / plans.jsonl files — they live in the journal alongside every other event. Read them via journal.Writer.SubscribeProjection (live) or journal.ProjectFile (post-mortem).

The journal records every bus event except the types listed in journal.exclude_events (default ["core.tick"]). Excluded events still dispatch to bus subscribers — only the durable log skips them, and their seq is not consumed, so on-disk envelopes stay gap-free. The default suppresses the engine heartbeat, which replay regenerates from the live tick goroutine and which otel / eval already treat as noise. See configuration reference for the full key.

Session Metadata

Each session tracks metadata in metadata/session.json:

type SessionMeta struct {
    ID                   string            // Random hex identifier
    StartedAt            time.Time         // When the session began
    EndedAt              *time.Time        // When the session ended (nil if active)
    Profile              string            // Config profile name
    Plugins              []string          // Active plugin IDs
    Labels               map[string]string // User-defined labels
    TurnCount            int               // Number of conversation turns
    TokensUsed           int               // Total tokens consumed
    PromptTokensUsed     int               // Input tokens consumed
    CompletionTokensUsed int               // Output tokens consumed
    CostUSD              float64           // Accumulated cost in USD
    Status               string            // "active" or "ended"
}

Session Workspace API

Plugins interact with the session through the SessionWorkspace struct:

// Write a file to the session workspace
session.WriteFile("context/mydata.json", data)

// Read a file back
data, err := session.ReadFile("context/mydata.json")

// Append to a file (useful for JSONL logs)
session.AppendFile("context/events.jsonl", line)

// List files in a subdirectory
files, err := session.ListFiles("context")

// Check if a file exists
exists := session.FileExists("context/conversation.jsonl")

Directory Helpers

session.ContextDir()          // ~/.nexus/sessions/<id>/context/
session.FilesDir()            // ~/.nexus/sessions/<id>/files/
session.MetadataDir()         // ~/.nexus/sessions/<id>/metadata/
session.PluginDir("nexus.tool.shell")  // ~/.nexus/sessions/<id>/plugins/nexus.tool.shell/

PluginDir() creates the directory lazily on first access.

File Events

When files are written to the session, events are emitted automatically:

These events carry the file path, session ID, and file size. The TUI plugin subscribes to these to show file creation notifications.

Session Lifecycle

Creating a Session

When Engine.Run() starts, it calls NewSessionWorkspace() which:

1. Generates a random hex session ID
2. Creates the directory structure (context/, files/, metadata/, plugins/)
3. Writes initial metadata with status "active"

Resuming a Session

When launched with -recall <sessionID>:

1. The engine loads the session’s config snapshot from metadata/config-snapshot.yaml
2. LoadSessionWorkspace() opens the existing directory
3. The session metadata is updated back to "active"
4. Plugins find their persisted data in their PluginDir()

Ending a Session

On shutdown, the engine:

1. Sets EndedAt on the session metadata
2. Updates status to "ended"
3. Saves a config snapshot for future recall

The snapshot is the original config YAML bytes verbatim, not a re-serialization of the typed Config struct. core.models and per-plugin configs are parsed via a second-pass raw map (yaml:"-" on the typed fields), so re-marshaling would silently drop them and break recall. Configs constructed in-memory via DefaultConfig() (no source bytes) fall back to yaml.Marshal of the typed struct.

Configuration

Session behavior is configured in the core.sessions section:

core:
  sessions:
    root: ~/.nexus/sessions   # Where sessions are stored
    retention: 30d            # How long to keep old sessions
    id_format: datetime_short # ID generation format

Per-Plugin Storage

Every plugin can request a SQLite-backed storage handle scoped at session, agent, or application level. The storage primitive is engine-native (no plugin needs to be activated) and is exposed through PluginContext.Storage.

The backend is modernc.org/sqlite — pure Go, no CGO, FTS5 included. WAL mode and a 5-second busy timeout are on by default.

Scopes

Multi-agent embedders (the desktop shell) set core.agent_id per engine instance so each agent gets its own ScopeAgent partition. CLI and single-agent embedders leave it empty, which collapses agent scope to app scope so plugins do not end up with two separate connection pools pointing at the same file.

The data root can be overridden via core.storage.root (defaults to ~/.nexus).

Plugin API

func (p *Plugin) Init(ctx engine.PluginContext) error {
    st, err := ctx.Storage(storage.ScopeSession)
    if err != nil {
        return err
    }

    // KV sugar — convenient for trivial put/get cases.
    if err := st.Put("last_run", []byte(time.Now().String())); err != nil {
        return err
    }
    val, ok, err := st.Get("last_run")

    // Raw SQL — for joins, transactions, virtual tables (FTS5).
    if _, err := st.DB().Exec(`CREATE TABLE IF NOT EXISTS jobs (
        id INTEGER PRIMARY KEY, payload TEXT
    )`); err != nil {
        return err
    }

    // Transactions.
    return st.Tx(func(tx *sql.Tx) error {
        _, err := tx.Exec(`INSERT INTO jobs(payload) VALUES(?)`, "work")
        return err
    })
}

Handles are pooled — repeated calls to ctx.Storage(scope) return the same underlying *sql.DB for that (scope, pluginID) pair. The handle lives for the lifetime of the engine; do not call Close on the returned *sql.DB.

The kv table is created lazily on the first KV-method call. Plugins that only use DB() never see it.

Configuration

See Configuration Reference for the authoritative list. The relevant block:

core:
  agent_id: ""                 # set by multi-agent embedders
  storage:
    root: ~/.nexus             # data root for app + agent scope
    busy_timeout_ms: 5000
    cache_size_kb: 2048
    pool_max_idle: 2
    pool_max_open: 4

Concurrency

App-scope storage is shared across every session on the machine. SQLite WAL mode handles concurrent readers cleanly, and writers serialize behind the busy timeout. Multiple processes (two CLIs sharing the same app-scope DB file) work but are not the design target — prefer agent or session scope for concurrent independent workloads.

Within a single process, Storage is safe for concurrent use across goroutines.

Model Registry

The model registry maps abstract role names to concrete model configurations. This lets plugins request a model by capability (e.g., “reasoning”, “quick”) without hardcoding specific model IDs.

Role-Based Model Selection

Define model roles in the core.models config section:

core:
  models:
    default: balanced        # Role to use when none specified
    reasoning:               # High-capability model for complex tasks
      provider: nexus.llm.anthropic
      model: claude-opus-4-20250514
      max_tokens: 16384
    balanced:                # General-purpose model
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    quick:                   # Fast, cost-effective model
      provider: nexus.llm.anthropic
      model: claude-haiku-4-5-20251001
      max_tokens: 4096

How Roles Are Used

Plugins reference roles by name in their configuration:

nexus.planner.dynamic:
  model_role: reasoning     # Use the high-capability model for planning

nexus.memory.compaction:
  model_role: quick         # Use the fast model for summarization

nexus.agent.react:
  model_role: balanced      # Default agent model (optional, uses default role)

When a plugin emits an llm.request, the LLM provider resolves the role to a concrete model:

// Plugin requests by role
config, found := models.Resolve("reasoning")
// Returns: ModelConfig{Provider: "nexus.llm.anthropic", Model: "claude-opus-4-20250514", MaxTokens: 16384}

Resolution Rules

1. If the role name matches a defined role, return that config
2. If the role is empty, use the default role
3. If the role is not found but contains a hyphen (e.g., claude-sonnet-4-20250514), treat it as a raw model ID for backward compatibility
4. Otherwise, return not found

Provider Fallback Chains

Role values can be ordered arrays instead of single maps. First entry = primary, subsequent entries are tried in order when the primary fails with a non-retryable error or exhausts its retry budget.

core:
  models:
    balanced:
      - provider: nexus.llm.anthropic
        model: claude-sonnet-4-20250514
        max_tokens: 8192
      - provider: nexus.llm.openai
        model: gpt-4o
        max_tokens: 8192
    quick:
      provider: nexus.llm.anthropic    # single entry = no fallback
      model: claude-haiku-4-5-20251001

Single-map format is backward compatible — parsed as a chain of length 1.

Requires: nexus.provider.fallback in plugins.active + both provider plugins active.

Trigger conditions: Fallback occurs when a provider error is non-retryable (4xx except 429, auth failures), or when the provider’s own retry logic (429, 5xx backoff) has exhausted max_retries.

Streaming partial failure: If a provider fails mid-stream, the fallback plugin emits io.output.clear to wipe partial content, then provider.fallback notification, then re-emits llm.request targeting the next provider. Clean restart — no spliced output from two models.

Provider Fanout

Roles with fanout: true send requests to all listed providers in parallel instead of sequential fallback. The fanout plugin collects responses and returns them as a single LLMResponse with Alternatives.

core:
  models:
    compare:
      fanout: true
      providers:
        - provider: nexus.llm.anthropic
          model: claude-sonnet-4-20250514
          max_tokens: 4096
        - provider: nexus.llm.openai
          model: gpt-4o
          max_tokens: 4096

Requires: nexus.provider.fanout in plugins.active + all listed provider plugins active.

Deadline: Configurable via nexus.provider.fanout.deadline_ms (default 30s). If a provider doesn’t respond in time, the fanout proceeds with available responses.

No per-leg fallback: A fanout provider that fails is simply marked as failed. Fallback chains and fanout are separate concepts — a role is either a fallback chain or a fanout group, not both.

API

type ModelConfig struct {
    Provider  string  // Plugin ID of the LLM provider
    Model     string  // Model identifier string
    MaxTokens int     // Maximum tokens for this model
}

type ModelRegistry struct {
    Resolve(role string) (ModelConfig, bool)              // Primary model for a role (index 0)
    Fallback(role string, attempt int) (ModelConfig, bool) // Model at chain index
    ChainLen(role string) int                             // Number of entries in fallback chain
    IsFanout(role string) bool                            // Whether a role uses parallel fanout
    FanoutProviders(role string) []ModelConfig            // All providers in a fanout role
    Default() ModelConfig                                 // Get the default model
    Roles() []string                                      // List all registered role names
}

Default Role

The default key in the models config is a string alias pointing to another role:

models:
  default: balanced   # When no role specified, use "balanced"

This means models.Resolve("") and models.Default() both return the balanced config.

Prompt Registry

The prompt registry allows plugins to inject dynamic sections into the system prompt at runtime. This is how skills catalogs, dynamic variables, and other context get appended to the agent’s system prompt without hardcoding.

How It Works

1. Plugins register prompt sections during initialization, each with a name and priority
2. When the LLM provider builds a request, it calls prompts.Apply(systemPrompt) to assemble the final prompt
3. Each registered section function is called — if it returns a non-empty string, that content is wrapped in an XML <prompt_section> tag and appended
4. Sections are appended in priority order (lower priority numbers first)
5. If a base system prompt is provided, it’s wrapped in <system_instructions> tags

XML Structure

All prompt content uses XML tag boundaries for clean structural separation. The assembled prompt looks like:

<system_instructions>
You are a helpful assistant.
</system_instructions>

<prompt_section name="skill-catalog">
<available_skills>
  <skill name="code-review" scope="project">
    <description>Review code for quality, bugs, security issues, and style.</description>
  </skill>
</available_skills>
</prompt_section>

<prompt_section name="dynvars">
- Date: 2026-04-08
- OS: darwin
- CWD: /Users/frank/projects/myapp
</prompt_section>

Registering a Section

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    ctx.Prompts.Register("my-context", 50, func() string {
        return "Some dynamic information here."
    })
    return nil
}

The function is called every time a prompt is assembled, so it can return different content based on current state. The returned content is automatically wrapped in <prompt_section name="my-context"> tags by the registry.

Built-in Sections

Agent-Level Semantic Tags

Beyond the structural <prompt_section> wrapping, each agent type uses semantic XML tags for its dynamic content:

User-provided content and LLM outputs are wrapped in CDATA blocks to prevent parsing conflicts.

XML Helpers

Shared XML utilities in pkg/engine/xml.go:

engine.XMLWrap("tag", content, "attr", "value")  // wrap content in <tag attr="value">...</tag>
engine.XMLTag(&builder, "tag", "attr", "value")   // write opening tag
engine.XMLClose(&builder, "tag")                   // write closing tag
engine.XMLCDATA(content)                            // wrap in <![CDATA[...]]>
engine.XMLEscape(s)                                 // escape &, <, >, "

API

type PromptSectionFunc func() string

type PromptRegistry struct {
    Register(name string, priority int, fn PromptSectionFunc)
    Unregister(name string)
    Apply(systemPrompt string) string
}

• Register — Adds a named section. If a section with the same name already exists, it is replaced.
• Unregister — Removes a named section.
• Apply — Takes the base system prompt, wraps it in <system_instructions>, and appends all registered sections wrapped in <prompt_section> tags, in priority order.

Use Cases

• Skill catalogs — The skills plugin registers available skills so the agent knows what’s available
• Dynamic variables — The dynvars plugin injects current date/time and system info
• Custom context — Your plugins can inject any context the agent should be aware of

Hot Reload

Engine.ReloadConfig(newConfig *Config) error applies a config change to a running engine without restarting unaffected plugins. Phase 5 of Idea 10 (engine resilience) introduced it; the design is intentionally cautious so operators can adjust gate thresholds, model assignments, and tool allowlists in production without dropping every active session.

Architecture

The reload runs in two phases.

1. Validate (atomic)

• The new config is run through the same JSON-schema validation pass that Boot performs. Every active plugin’s ConfigSchemaProvider is re-checked against the new config map; engine-level fields (engine.shutdown.drain_timeout, engine.config_watch) are validated against the engine schema (pkg/engine/engine_schema.json).
• Capability provider identity is pinned. If a capability bound at boot (e.g. memory.history) would resolve to a different concrete plugin under the new active set, the reload is rejected. The session has in-flight state bound to the existing provider; a silent swap would strip the operator’s history.
• The active-set diff is computed: which IDs are added, which removed, which kept with a config change.

Any error here returns immediately. The engine is unchanged.

2. Apply (best-effort)

The diff is walked:

Atomicity caveat

The validate phase is atomic — failures here leave the engine state untouched. The apply phase is best-effort. If a per-plugin ReloadConfig or Init / Ready fails partway through, prior changes have already taken effect (a restarted plugin has already re-subscribed to the bus and may have written to journals or storage). The engine logs the failure and surfaces it to the caller; we do not attempt to roll back. “Undoing” a Shutdown is not generally possible — the plugin’s in-memory state is gone.

If a partial reload leaves the engine in a state the operator dislikes, re-issue ReloadConfig with the previous config to revert.

ConfigReloader opt-in

// pkg/engine/plugin.go
type ConfigReloader interface {
    ReloadConfig(old, new map[string]any) error
}

A plugin that implements ConfigReloader receives the in-place hook on a config-only change instead of going through the restart path. Both paths are supported; the hook is purely an optimization for plugins where a full restart would drop in-progress work (e.g. an HTTP listener with established WebSocket connections, an MCP client mid-stream).

Implementations must be transactional from the bus’s perspective: returning an error must leave the plugin in its prior state — bus subscriptions, in-memory data, persisted scratch — unchanged. The engine makes no attempt to restart on top of a failed in-place reload.

Capability pinning

Capability provider identity is pinned for the lifetime of a session. The constraint is enforced in the validate phase: if a capability that the running engine has resolved (e.g. memory.history → nexus.memory.capped) would resolve to a different provider in the new config, the reload is rejected with the error:

capability provider "memory.history" cannot change at runtime (nexus.memory.capped -> nexus.memory.summary_buffer); restart required to rebind session state

Restart the engine to change capability providers — the new session boots with the new provider from clean state.

Triggers

Three triggers feed ReloadConfig:

SIGHUP (CLI)

The cmd/nexus binary’s main loop intercepts SIGHUP, re-reads the original -config path, and calls ReloadConfig. SIGINT and SIGTERM continue to terminate the engine.

kill -HUP $(pgrep -f 'nexus -config')

POST /admin/reload-config (browser plugin)

When nexus.io.browser is active, its HTTP server exposes POST /admin/reload-config. Body is empty (re-read the original path) or {"path": "/abs/path/to/new.yaml"} for an ad-hoc reload. The endpoint returns 200 OK with {"ok": true} on success or 400 with {"ok": false, "error": "..."} on a validation failure; a stuck reload returns 504 after 30s.

No auth layer yet — alpha-only; front with a reverse proxy if exposed. Implementation lives in plugins/io/browser/server.go.

fsnotify watcher

Off by default. Opt in via:

engine:
  config_watch:
    enabled: true
    debounce: 1s

The CLI starts a watcher on the -config path and fires ReloadConfig after each debounced edit. The watcher lives in pkg/engine/configwatch/. It watches the parent directory rather than the file itself because editors that swap-on-save (Vim’s default) replace the file’s inode — a watcher on the original path would miss the swap.

The debounce window collapses bursts of Write/Create events on the same path into a single reload. Editors commonly fire two or three Write events when saving; reading a half-written YAML through the validator would surface a confusing schema error. 1s is well above the typical storm and short enough that the operator perceives the reload as instant. Tune downward for fast feedback during dev; leave at the default (or higher) in production where rapid re-saves rarely happen.

Bus events

External triggers can also dispatch core.config.reload.request on the event bus and listen for core.config.reload.result. The browser admin endpoint uses this internally — the engine subscribes to the request event during Boot and emits the result back. Custom plugins or embedders that don’t want to hold an *Engine reference can use the same path.

Code locations

Context Engineering

The conversation history is the LLM’s working memory. Every byte costs tokens, slows the model, and competes with other content for attention. Nexus exposes a layered context-curation stack so operators can shed weight aggressively without losing the reasoning chain.

Layers

The stack runs in cost order on every before:llm.request. Cheaper deterministic layers fire first; LLM-touching layers run only when the prior layers leave the request still over budget.

Curators never edit the static section — system prompt and operator-set content are off-limits.

Stability Descriptor

Every layer emits a memory.curated envelope event carrying a stability-impact descriptor:

type MemoryCurated struct {
    Layer            string             // which layer ran
    SectionsTouched  []CurationSection  // section_id, kind, tokens_delta
    CacheInvalidates bool               // does any touched section cross the cache prefix?
    AtTurn           int                // turn boundary
}

CurationSection.Kind is one of:

• volatile — recent turns; no cache impact.
• session — session-long content (compaction summary, tool definitions); controlled re-cache, charged once and amortised.
• static — system prompt / tool defs (forbidden — curator must not touch).

A future cache-aware prompt builder (Idea 05) consumes this descriptor to scope re-cache cost. Until that lands, curations batch at turn boundaries to keep cache invalidations predictable.

Replay Determinism

Curation is heuristic and classifier-driven, so curators emit one event per decision (memory.tool_result_cleared, memory.tool_def_pruned, memory.topic_shift_detected, memory.summary_replaced). The durable journal (Idea 01) records every envelope so replay reproduces curation by replaying decisions, not by re-running heuristics.

Provider-side vs Harness-side

Anthropic’s server-side tool_result_clear and system_message_edit primitives, and OpenAI Responses API truncation policies, do similar work in-provider. Nexus defaults to harness-side curation for portability — every layer works the same regardless of which provider the request lands on. Provider-native primitives can be enabled as an opt-in optimisation when the configured provider supports them.

Eval-Driven Tuning

The eval harness (Idea 07) supports curation-on/off pivots so operators can compare task-success-rate against the cost savings of an aggressive preset. Keep defaults conservative until eval data justifies tightening.

Composing the Stack

A typical full stack:

plugins:
  active:
    - nexus.agent.react
    - nexus.memory.summary_buffer       # base history with reasoning-preserving summary
    - nexus.memory.tool_result_clear    # layer 1
    - nexus.memory.tool_def_pruner      # layer 2
    - nexus.memory.topic_pruner         # layer 3
    - nexus.discovery.progressive       # complements layer 2 (class-level scoping)
    - nexus.gate.context_window         # last-resort compaction trigger

Layer 5 (compaction-and-restart) is implicit when the context-window gate fires the existing nexus.memory.compaction coordinator.

Postures

A posture is a registered, named, versioned configuration that describes how a sub-agent should run: which system prompt, which subset of tools, which model, and what default resource budget. Postures are the contract that the delegate runtime resolves at invocation time, and the value operators tune in production to change agent behavior without code changes.

Schema

type AgentPosture struct {
    Name              string         // Registry key parent agents reference
    Description       string         // Human-facing copy (introspection prompts)
    SystemPrompt      string         // The posture's prompt
    AllowedTools      []string       // Closed list of permitted tool names
    OutputSchema      string         // Named schema validated against final output (optional)
    Model             ModelConfig    // Model tier / explicit Provider+Model override
    DefaultBudget     ResourceBudget // Timeout, MaxTokens, MaxToolCalls
    MaxRecursionDepth int            // Per-posture depth cap (0 falls back to runtime MaxDepth)
    Version           string         // Content hash, assigned by the loader / registry
}

type ResourceBudget struct {
    Timeout      time.Duration
    MaxTokens    int
    MaxToolCalls int
}

pkg/posture defines the type and an in-memory Registry. The nexus.agent.postures plugin loads YAML from disk and exposes the posture.registry capability.

YAML

Postures live in a directory of *.yaml files. The filename (minus extension) supplies a fallback name if the YAML omits one. Example:

name: analyst
description: deep reader; quotes sources verbatim
system_prompt: |
  You are a careful analyst. Cite sources by URL. Be concise.
allowed_tools:
  - web_search
  - web_fetch
  - read_pdf
output_schema: analyst_report
model:
  model_role: reasoning
  max_tokens: 4000
default_budget:
  timeout: 60s
  max_tokens: 50000
  max_tool_calls: 20
max_recursion_depth: 2

Versioning

The registry hashes each posture’s content (name, system prompt, allowed tools, output schema, model selectors) into a 16-character Version string. Two postures with the same Name but different content are not “different versions” — the new content replaces the old, but the Version change flows into the delegate result cache key, invalidating any stale entries automatically.

Hot reload

nexus.agent.postures watches every configured scan_dirs entry with fsnotify. Edits and adds re-load the affected file after a small debounce (debounce_ms, default 250ms); deletes drop the posture from the registry. Active sub-sessions keep their old configuration; new invocations resolve the new one. This is how operators tune prompts in production without restarts.

The watcher swallows individual parse errors with a WARN log — a single malformed file does not block the rest from registering.

Capability resolution

The plugin advertises:

Capabilities: posture.registry

The delegate plugin requires this capability, so the lifecycle manager pins the active provider at boot and the delegate runtime resolves the registry through LookupPlugin without plugin-to-plugin imports or bus handshake races.

Watching change events

Operators that want to react to posture edits (warm caches, alert on removals) can subscribe to the posture.registered / posture.removed bus events; see the events reference. The in-process posture.Registry.Watch(ctx) channel provides the same notifications inside the process for plugins that need them.

Configuration

See nexus.agent.postures in the configuration reference.

Sub-agent Delegation

Delegation is the first-class operation a parent agent uses to call another agent with a different reasoning posture, system prompt, allowed-tools subset, and resource budget. From the parent’s perspective a delegate call is a single tool invocation; underneath, the runtime spawns a sub-session that has its own context window, its own envelope identity (Causation.AgentID and Depth), and its own budget.

The runtime lives at pkg/delegate.Runtime; the tool surface is the nexus.agent.delegate plugin.

Lifecycle of a call

1. The parent’s LLM emits a delegate tool call.
2. The plugin resolves the posture by name through the posture registry.
3. The runtime checks recursion depth (per-posture max_recursion_depth first, then the global MaxDepth).
4. The runtime computes a cache key. On a hit, the cached Output returns immediately as StatusCacheHit — no model calls, no tool calls, no budget consumption.
5. The runtime pushes a CausationContext carrying the sub-agent’s AgentID and Depth, then enters the isolated LLM loop.
6. Each iteration emits an llm.request tagged with the sub-session’s source, collects the response, runs any tool calls (filtered to the posture’s AllowedTools), and appends results to the sub-session’s history.
7. The loop exits on a tool-call-free response (StatusSuccess), budget exhaustion (StatusPartial), error (StatusError), timeout (StatusTimeout), or ctx cancel (StatusCancel).
8. Successful and partial outputs are cached. The final tool.result returns the Output to the parent agent as JSON.

Budgets

Budgets are non-negotiable, enforced by the runtime, and resolved per-call:

type Overrides struct {
    MaxTokens    int
    MaxToolCalls int
    Timeout      time.Duration
}

Per-call overrides win when non-zero; otherwise the posture’s DefaultBudget applies. Timeout becomes a context.WithTimeout around the loop. MaxTokens is checked after each LLM response and short-circuits with StatusPartial. MaxToolCalls is checked before dispatching each tool batch and likewise short-circuits with StatusPartial.

The parent receives the Output.Status and decides whether to retry with a larger budget, fall back to handling the task itself, or surface the partial result.

Recursion

Sub-agents can themselves call delegate. Two caps gate the depth:

• The runtime’s MaxDepth (default 3, configurable via the plugin’s max_depth) is the global ceiling.
• Each posture may set max_recursion_depth to tighten the ceiling for itself.

Exceeding either cap returns ErrRecursionLimit (StatusError) without spinning up a sub-session.

Caching

The runtime’s Cache interface (default: MemoryCache, an in-process LRU) keys results on the SHA-256 of:

• Posture Name
• Posture Version (the content hash; edits invalidate cached results)
• The Task string
• The canonicalized Context map (keys sorted, values JSON-marshaled)
• The sorted AllowedTools list

Cache hits return Status = cache_hit and a fresh SubSessionID; Elapsed reflects only the lookup time. Operators can plug in a Redis-backed cache by implementing the Cache interface and assigning it on the runtime.

The cache is bypassed for errors and timeouts — operators want a retry to re-execute, not replay a transient failure.

Tool filtering

AllowedTools is a closed list. The runtime snapshots the live tool catalog on every invocation, intersects it with AllowedTools, and offers only the intersection to the sub-agent’s LLM. An empty list means “all tools the catalog currently advertises” — useful for trusted postures.

Observability

Every call emits a delegate.start / delegate.complete pair on the bus; see the events reference. Every LLM and tool envelope from inside the sub-session carries the sub-agent’s AgentID and Depth so observability tooling (otel spans, log shipping) can attribute the work.

Public API

type Input struct {
    Posture     string
    Task        string
    Context     map[string]any
    ParentTurn  string
    ParentDepth int
    Overrides   Overrides
}

type Output struct {
    Result        string
    Status        Status // success / partial / error / timeout / cancelled / cache_hit
    Error         string
    TokensUsed    int
    ToolCallsUsed int
    Elapsed       time.Duration
    SubSessionID  string
    PostureName   string
    PostureVer    string
    Depth         int
}

func (r *Runtime) Run(ctx context.Context, in Input) (Output, error)

Configuration

See nexus.agent.delegate in the configuration reference.

Scenes

A Scene is a named, structured, mutable entity that lives for the lifetime of a session. Agents use scenes to construct durable visual output (charts, dashboards, multi-section documents) that is addressable across tool calls, patchable over time, and persisted to disk.

The runtime is schema-agnostic — Nexus stores the content blob and journals patches; downstream renderers (UIs, exporters) interpret the schema-specific content.

Schema

type SceneHandle struct {
    ID        string // Stable, session-scoped — "scene_<hex>"
    SessionID string
    Schema    string // Names the schema the content conforms to
    Version   int    // Incremented on each patch
}

type Scene struct {
    Handle    SceneHandle
    Content   any          // Current state
    CreatedAt time.Time
    UpdatedAt time.Time
    History   []SceneEvent
}

type SceneEvent struct {
    Sequence  int
    Timestamp time.Time
    AgentID   string
    Patch     any
    Initial   bool
}

pkg/scene defines these types plus the Store interface that nexus.scene implements with a goroutine-safe in-memory backend.

Behavior

• Stable IDs. Scene IDs are session-scoped and never change after creation. Agents reference them by ID in subsequent tool calls.
• Patches are journaled. Every patch appends a SceneEvent to the scene’s in-memory history and a JSONL line to <session>/plugins/nexus.scene/scenes.jsonl. This is the substrate the replay primitive reads to reconstruct historical state.
• Bus events. Creation, patching, and deletion each emit a scene.* event — see the events reference. agent_id flows from Event.Causation.AgentID so a sub-agent’s contribution is attributable.
• Schema is advisory. The runtime does not validate content against the named schema; renderers do.
• Linearization. Concurrent patches (parent + sub-agent, two parallel sub-agents) serialize through the store mutex. First patch at a given key wins; later patches see post-first-patch state.

Patcher

Patches merge through a Patcher implementation. The default is ShallowMerge:

• Map patch + map content → key-by-key merge, patch keys overwrite.
• Anything else → patch replaces content entirely.

Schema-specific renderers that need richer semantics can swap in their own Patcher via MemoryStore.WithPatcher.

Tool surface

nexus.scene registers five tools the LLM uses to manipulate scenes:

Persistence

• Per-patch JSONL append to scenes.jsonl — the durable source of truth for time-travel reconstruction.
• Full state snapshot to scenes.json on Shutdown — what a clean restart loads to pick up where the prior run left off.

Sessions configured to drop scene history can compact scenes.jsonl to the current state only; correctness does not depend on a complete log.

Configuration

See nexus.scene in the configuration reference. No config keys today — activate the plugin and the default tools register at boot.

Streaming Tools

A standard Nexus tool is request-response: an agent emits tool.invoke, the tool runs, the tool emits tool.result. For long-running operations that produce incremental output, the agent has to wait for the whole call to complete — UIs and observability collectors see nothing in between.

pkg/streamtool defines the contract a tool implements when it wants to publish intermediate output while it runs.

When to use it

A tool should be channel-aware when:

• The work takes more than a few seconds.
• It produces meaningful intermediate output a consumer might render (token stream, report sections, file-by-file progress).
• It can be cancelled cleanly.

For quick request-response operations, the standard tool interface is fine.

Contract

type ChannelTool interface {
    Name() string
    Stream(ctx context.Context, input map[string]any) (<-chan ToolEvent, error)
}

type ToolEvent struct {
    Kind     Kind   // Progress / Partial / Complete / Error
    Sequence int    // Monotonic per Stream invocation, starts at 1
    Payload  any
    Progress float64 // 0.0–1.0 if known, -1 otherwise
    Err      error   // Set on KindError
}

The tool owns the channel’s lifetime: it must close the channel when work completes or ctx cancels, and it must end the stream with KindComplete or KindError.

Bridge

streamtool.Bridge(ctx, bus, tool, call) drains the channel and projects each event onto the bus:

• KindProgress → tool.stream.progress
• KindPartial → tool.stream.partial
• KindComplete → final tool.result carrying the payload
• KindError → final tool.result with the error

All projected envelopes inherit the originating tool.invoke’s ID as their Causation.ParentID automatically — the bus’s per-goroutine dispatch context handles the propagation. UIs subscribed to tool.stream.partial for live rendering, observability collectors shipping the stream to Otel, and the parent agent’s tool.result handler all see the same call linked through causation.

Bridge blocks until the channel closes or ctx cancels and returns nil on graceful completion, the stream’s error on KindError.

Wiring it into a plugin

A tool plugin keeps its Init and tool registration unchanged. In the tool.invoke handler it instantiates a ChannelTool, hands it to Bridge, and lets Bridge emit the final tool.result instead of doing that itself:

func (p *Plugin) onToolInvoke(ev engine.Event[any]) {
    call, _ := ev.Payload.(events.ToolCall)
    if call.Name != p.toolName {
        return
    }
    go func() {
        _ = streamtool.Bridge(context.Background(), p.bus, &myStreamingTool{...}, call)
    }()
}

The plugin still declares tool.stream.progress, tool.stream.partial, and tool.result in its Emissions().

Events

See tool.stream.* events in the events reference.

Replay

Given a session ID, pkg/replay reconstructs the full causation DAG and walks it. Replay is read-only and deterministic — it reads from the durable journal and the scene patch journal; it does not re-run agents, LLMs, or tools.

This is the foundation for debugging, audit trails, time-travel, and reproducibility.

API

type Replay struct {
    SessionID string
    Events    []Event       // In seq order
    Scenes    []SceneSnap   // Scene state at the requested point in time
    LastSeq   uint64
}

type Event struct {
    Seq       uint64
    ParentSeq uint64
    ParentID  string
    EventID   string
    Type      string
    AgentID   string
    Depth     int
    Vetoed    bool
    Payload   any
}

type Options struct {
    SessionsRoot  string // Engine session root (typically ~/.nexus/sessions)
    AtSeq         uint64 // Stop after this seq; zero = full journal
    IncludeVetoed bool   // Keep vetoed before:* envelopes (default true)
}

func Session(ctx context.Context, sessionID string, opts Options) (Replay, error)
func SessionAt(ctx context.Context, sessionID string, atSeq uint64, opts Options) (Replay, error)

Walking the DAG

The Replay value exposes three convenience walkers:

For richer traversal, the flat Events slice is in seq order — most custom walks are a single loop over it.

Use cases

• Debugging. A user reports an issue with a session; Session(ctx, id, opts) reconstructs the events to read what happened.
• Audit. Compliance review walks the DAG to verify what the session did. ByAgent answers “what did the analyst posture decide?”
• Time-travel. SessionAt(ctx, id, atSeq, opts) rebuilds state as it looked at atSeq. Renderers consume the returned Scenes to show historical visual state.
• Branch and fork. Replay to a point, then resume the session along a different path with a new agent message. (The engine’s existing rewind primitive consumes the DAG produced here.)

Scene reconstruction

For every session whose <session>/plugins/nexus.scene/scenes.jsonl exists, replay folds the JSONL stream through scene.ShallowMerge and returns a SceneSnap per scene at the requested point in time. Sessions without scenes return events without error.

The scene journal currently records its own per-scene mutation order, not the bus seq — AtSeq filters by the number of scene-journal lines read, not the bus dispatch seq. Improving this is a follow-up that adds a bus seq to each scene journal line.

Performance

For long sessions (thousands of events), full replay can be slow. The engine’s journal supports periodic snapshots in pkg/engine/replay.go that replay can start from; integrating snapshot recovery into pkg/replay.Session is a future optimization. Correctness does not depend on snapshots.

Desktop Shell

The desktop shell framework (pkg/desktop/) provides everything needed to embed one or more Nexus agents inside a Wails desktop application. Your application supplies agent definitions, config YAML, and a frontend — the framework handles engine lifecycle, event bridging, settings persistence, session management, and OS integration.

The framework lives inside the Nexus repository. Desktop applications that use it are built as separate Go modules that import github.com/frankbardon/nexus/pkg/desktop. A reference implementation ships at cmd/desktop/ to demonstrate the full feature set.

Architecture

flowchart TB
    subgraph App["📦 Your Wails App  (cmd/your-app/main.go)"]
        direction LR
        Run["desktop.Run(&desktop.Shell{ Agents, Assets })"]
    end

    subgraph FW["🧩 pkg/desktop  (framework)"]
        direction LR
        Shell["Shell<br/><sub>orchestrator</sub>"]
        Store["Store<br/><sub>settings + keyring</sub>"]
        Sess["Sessions<br/><sub>per-agent index</sub>"]

        subgraph EngA["Engine (agent-a)"]
            direction TB
            IOA["nexus.io.wails<br/>+ scopedRuntime"]
            PluginsA["your plugins"]
        end

        subgraph EngB["Engine (agent-b)"]
            direction TB
            IOB["nexus.io.wails<br/>+ scopedRuntime"]
            PluginsB["your plugins"]
        end

        Shell --> EngA
        Shell --> EngB
    end

    subgraph Web["🖥 Wails webview  (single process, shared)"]
        Front["Frontend JS<br/>scoped events:<br/><code>agent-a:nexus</code> · <code>agent-b:nexus</code>"]
    end

    App --> FW
    FW --> Web
    EngA <-. namespaced events .-> Front
    EngB <-. namespaced events .-> Front

    classDef app fill:#3a2d4a,stroke:#9b59b6,stroke-width:2px,color:#fff;
    classDef framework fill:#1e3a5f,stroke:#4a90e2,stroke-width:1.5px,color:#fff;
    classDef engine fill:#2d4a3e,stroke:#5fb878,stroke-width:1.5px,color:#fff;
    classDef web fill:#5f3a1e,stroke:#e2904a,stroke-width:1.5px,color:#fff;
    class Run app;
    class Shell,Store,Sess framework;
    class IOA,IOB,PluginsA,PluginsB engine;
    class Front web;

Key concepts

One engine per agent. Each agent gets its own engine.Engine instance with its own bus, plugin set, session workspace, and config. Agents never share an engine or bus — isolation is structural.

Lazy boot. Engines are created on demand when the frontend selects an agent (EnsureAgentRunning). No engine runs until the user navigates to it.

Scoped runtimes. Each agent’s nexus.io.wails plugin receives a scopedRuntime that namespaces Wails event channels by agent ID. The plugin itself is unaware of multi-agent — it talks to its Runtime interface, and the scoped wrapper handles the namespace. This means outbound events go to "{agentID}:nexus" and inbound events come from "{agentID}:nexus.input".

Config-driven event bridging. Domain events flow through the bus, not through Wails-bound Go methods. The nexus.io.wails plugin config declares exactly which events cross the bus-to-frontend boundary via subscribe (outbound) and accept (inbound) lists.

No eng.Run(). Desktop apps must use Boot/Stop directly. Run installs its own SIGINT/SIGTERM handler, which conflicts with Wails owning the process lifecycle.

Components

Lifecycle

1. desktop.Run(shell) — Configures and starts the Wails app. Blocks until the app exits.
2. onStartup — Initializes the settings store, session index, file watcher, and agent state entries. Runs session maintenance (cleanup expired, reconcile orphans).
3. Frontend selects agent — Calls EnsureAgentRunning(agentID).
4. bootAgent — Resolves ${var} placeholders in the agent’s config YAML, creates the engine via engine.NewFromBytes, registers plugin factories, installs the scoped runtime on the wails plugin, calls eng.Boot(ctx), installs bus subscriptions for session metadata and UI state, creates the session index entry.
5. Agent runs — Domain events flow between plugins and frontend through the bus bridge.
6. New session / recall — StopAgent tears down the current engine (unsubs, eng.Stop, marks session completed), then bootAgent creates a fresh engine (or one with RecallSessionID set for history replay).
7. onShutdown — Stops all running engines, closes the file watcher.

What the framework does NOT do

• Own your frontend. The framework ships a minimal base template in frontend/dist/, but you embed your own assets via Shell.Assets. Your frontend is yours — Alpine.js, React, vanilla JS, whatever fits.
• Define your domain plugins. All agent behavior comes from plugins you register in Agent.Factories. The framework only manages the nexus.io.wails plugin lifecycle.
• Restrict agent count. One agent, five agents — the framework scales. Each gets its own engine and scoped runtime.

Building Your Desktop App

This guide walks through creating a Nexus desktop application from scratch. By the end you will have a Wails app hosting a custom agent with settings, session management, and a frontend that communicates with the agent through the bus bridge.

The reference implementation at cmd/desktop/ demonstrates every feature covered here. When in doubt, consult it as the living example.

Prerequisites

• Go 1.22+
• Wails v2 CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest)
• Nexus as a Go module dependency

Project structure

A typical desktop app looks like this:

cmd/my-app/
  main.go                  # Entry point — registers agents, calls desktop.Run
  config.yaml              # Embedded Nexus config for your agent
  internal/
    myplugin/              # Your domain plugin(s)
      plugin.go
      events.go
  frontend/
    dist/                  # Your frontend assets (HTML/CSS/JS)
      index.html
  build/                   # Wails build artifacts (icons, Info.plist)

Step 1: Create your domain plugin

Your agent’s behavior lives in a standard Nexus plugin. It subscribes to events from the frontend, does work, and emits results back.

package myplugin

import (
    "github.com/frankbardon/nexus/pkg/engine"
)

type Plugin struct {
    bus    engine.EventBus
    logger engine.Logger
}

func New() engine.Plugin { return &Plugin{} }

func (p *Plugin) ID() string { return "myapp.agent.worker" }

func (p *Plugin) Init(ctx engine.PluginContext) error {
    p.bus = ctx.Bus
    p.logger = ctx.Logger
    return nil
}

func (p *Plugin) Ready() error { return nil }

func (p *Plugin) Shutdown(_ context.Context) error { return nil }

func (p *Plugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "work.request", Handler: p.handleRequest},
    }
}

func (p *Plugin) Emissions() []string {
    return []string{"work.result", "session.meta.title"}
}

func (p *Plugin) handleRequest(event engine.Event[any]) {
    payload, _ := event.Payload.(map[string]any)
    input, _ := payload["input"].(string)

    // Do your work here...

    p.bus.Emit("work.result", map[string]any{
        "output": "Processed: " + input,
    })

    // Contribute session metadata so the session list shows
    // a meaningful title instead of "Untitled".
    p.bus.Emit("session.meta.title", map[string]any{
        "title": "Work: " + input,
    })
}

Step 2: Write your agent config

The config YAML declares which plugins are active and how the nexus.io.wails plugin bridges events. Use ${var} placeholders for values that come from user settings.

# config.yaml
core:
  log_level: info
  tick_interval: 5s

  sessions:
    root: ~/.nexus/sessions
    retention: 30d
    id_format: datetime_short

plugins:
  active:
    - nexus.io.wails
    - myapp.agent.worker

  nexus.io.wails:
    # Events bridged outbound: bus -> frontend
    subscribe:
      - "work.result"
      - "ui.state.restore"
    # Events accepted inbound: frontend -> bus
    accept:
      - "work.request"
      - "ui.state.save"

  myapp.agent.worker:
    api_key: "${shell.api_key}"
    data_dir: "${data_dir}"

Config-driven bridging is explicit. Only events listed in subscribe and accept cross the bus-to-frontend boundary. If your frontend isn’t receiving an event, check these lists first.

Step 3: Write your entry point

The entry point registers agents and calls desktop.Run. Config YAML is embedded at compile time — the shipped binary has no filesystem dependency on config files.

package main

import (
    "embed"
    "log"

    "github.com/frankbardon/nexus/pkg/desktop"
    "github.com/frankbardon/nexus/pkg/engine"
    wailsio "github.com/frankbardon/nexus/plugins/io/wails"

    "my-module/cmd/my-app/internal/myplugin"
)

//go:embed all:frontend/dist
var assets embed.FS

//go:embed config.yaml
var agentConfig []byte

func main() {
    if err := desktop.Run(&desktop.Shell{
        Title:  "My App",
        Width:  1024,
        Height: 768,
        Assets: assets,
        Agents: []desktop.Agent{
            {
                ID:          "my-agent",
                Name:        "My Agent",
                Description: "Does useful work",
                Icon:        "fa-solid fa-gear",
                ConfigYAML:  agentConfig,
                Factories: map[string]func() engine.Plugin{
                    "nexus.io.wails":    wailsio.New,
                    "myapp.agent.worker": myplugin.New,
                },
                Settings: []desktop.SettingsField{
                    {
                        Key:      "shell.api_key",
                        Display:  "API Key",
                        Type:     desktop.FieldString,
                        Secret:   true,
                        Required: true,
                    },
                    {
                        Key:      "data_dir",
                        Display:  "Data Folder",
                        Type:     desktop.FieldPath,
                        Required: true,
                    },
                },
            },
        },
    }); err != nil {
        log.Fatalf("app: %v", err)
    }
}

Key registration details

• nexus.io.wails must be in Factories. The framework needs to intercept this plugin to install the scoped runtime before boot. Always register it via the factories map.
• Every plugin in plugins.active needs a factory. Either through Agent.Factories (for custom and wails plugins) or the engine’s built-in registry (for stock Nexus plugins like nexus.llm.anthropic).
• Assets is optional. If omitted (zero-value embed.FS), the framework uses its built-in base template. For anything beyond a demo, provide your own.

Step 4: Build your frontend

Your frontend communicates with the agent through scoped Wails events. The pattern:

// Create a bus helper scoped to your agent ID.
function createBus(agentID) {
    return {
        // Listen for events from the Go side.
        on(eventType, callback) {
            window.runtime.EventsOn(
                `${agentID}:nexus`,
                (envelopeJSON) => {
                    const envelope = JSON.parse(envelopeJSON);
                    if (envelope.type === eventType) {
                        callback(envelope.payload);
                    }
                }
            );
        },

        // Send an event to the Go side.
        emit(eventType, payload) {
            window.runtime.EventsEmit(
                `${agentID}:nexus.input`,
                JSON.stringify({ type: eventType, payload })
            );
        },

        // Request-response pattern: emit a request, wait for
        // a specific response event type.
        call(requestType, responseType, payload) {
            return new Promise((resolve) => {
                const off = window.runtime.EventsOnce(
                    `${agentID}:nexus`,
                    (envelopeJSON) => {
                        const envelope = JSON.parse(envelopeJSON);
                        if (envelope.type === responseType) {
                            resolve(envelope.payload);
                        }
                    }
                );
                this.emit(requestType, payload);
            });
        }
    };
}

Usage in your UI:

const bus = createBus('my-agent');

// Listen for results.
bus.on('work.result', (data) => {
    document.getElementById('output').textContent = data.output;
});

// Send a request.
document.getElementById('submit').addEventListener('click', () => {
    const input = document.getElementById('input').value;
    bus.emit('work.request', { input });
});

Calling shell methods

Shell services (settings, sessions, file dialogs) are Wails-bound Go methods on the Shell struct. Call them from JavaScript via the generated Wails bindings:

// List available agents.
const agents = await go.desktop.Shell.ListAgents();

// Boot an agent.
await go.desktop.Shell.EnsureAgentRunning('my-agent');

// Open a native file dialog.
const path = await go.desktop.Shell.PickFile('my-agent', 'Select File', '*.pdf');

// Manage sessions.
const sessions = await go.desktop.Shell.ListSessions('my-agent');
await go.desktop.Shell.NewSession('my-agent');
await go.desktop.Shell.RecallSession('my-agent', sessionID);
await go.desktop.Shell.DeleteSession('my-agent', sessionID);

Session list updates

Session list changes arrive as Wails events (not bus events):

window.runtime.EventsOn('my-agent:sessions.updated', (jsonStr) => {
    const sessions = JSON.parse(jsonStr);
    renderSessionList(sessions);
});

Step 5: Settings

Agents declare settings via Settings []SettingsField on the Agent struct. The framework handles persistence, UI rendering, and config injection.

Field types

Scope and sharing

Settings keys prefixed with shell. are stored in shell scope and shared across all agents. During config resolution, the framework checks agent scope first, then falls back to shell scope.

Common pattern: declare shell.api_key as a required secret on every agent that needs it. The user enters it once — the shell-scoped value resolves for all agents.

Settings: []desktop.SettingsField{
    {
        Key:      "shell.api_key",    // shell-scoped: shared
        Display:  "API Key",
        Type:     desktop.FieldString,
        Secret:   true,
        Required: true,
    },
    {
        Key:      "data_dir",         // agent-scoped: per-agent
        Display:  "Data Folder",
        Type:     desktop.FieldPath,
        Required: true,
    },
},

Secrets

Fields with Secret: true are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) via go-keyring. The JSON settings file stores the sentinel "__keychain__" so the frontend knows a value exists without exposing it.

Required field gating

If an agent has required settings with no value and no default, the framework refuses to boot the engine. The frontend should check HasMissingRequired() and redirect to the settings page.

Config injection

${var} placeholders in config YAML are replaced with resolved settings values before the engine is created. The resolution order:

1. Agent-scoped value for the key
2. Shell-scoped value for the key (fallback)
3. Default from the SettingsField definition
4. If still unresolved and Required: true — boot fails with an error listing the missing keys

Step 6: Session management

The framework tracks session history per agent automatically.

How it works

Every bootAgent call creates a session index entry in ~/.nexus/desktop/sessions.json. Your agent contributes metadata via bus events:

The shell subscribes to these events on each engine’s bus and updates the index. The frontend receives updates via {agentID}:sessions.updated Wails events.

Session lifecycle

Cleanup

On startup, the framework removes sessions older than the configured retention period (default 30 days, configurable via session_retention_days shell setting) and reconciles orphaned engine directories.

Step 7: UI state persistence

The framework provides a mechanism for frontends to persist and restore UI state across sessions.

Save state

Emit ui.state.save from your frontend with an opaque state object:

bus.emit('ui.state.save', {
    state: {
        selectedTab: 'results',
        scrollPosition: 450,
        formData: { name: 'Jane', role: 'Engineer' }
    }
});

The shell writes this to ui-state.json in the engine session directory. Call this after meaningful UI interactions — not on every keystroke.

Restore state

On session recall, the shell emits ui.state.restore with the saved payload:

bus.on('ui.state.restore', (data) => {
    if (data.state) {
        applyUIState(data.state);
    }
});

Both events must be in the wails IO plugin’s accept/subscribe config:

nexus.io.wails:
  subscribe:
    - "ui.state.restore"
  accept:
    - "ui.state.save"

Step 8: File portal (optional)

If your agent works with files, the framework provides a standardized file access layer.

Declare directories

Add input_dir and optionally output_dir to your agent’s settings:

Settings: []desktop.SettingsField{
    {Key: "input_dir", Display: "Input Folder", Type: desktop.FieldPath, Required: true},
    {Key: "output_dir", Display: "Output Folder", Type: desktop.FieldPath},
},

Use shell methods

// List files in the agent's input directory.
const files = await go.desktop.Shell.ListFiles('my-agent', '*.pdf');

// Get the output directory (creates if needed).
const outDir = await go.desktop.Shell.OutputDir('my-agent');

// Copy a file into the input directory (drag-and-drop).
const dest = await go.desktop.Shell.CopyFileToInputDir('my-agent', '/path/to/file.pdf');

// Start watching for file changes.
go.desktop.Shell.WatchInputDir('my-agent');
window.runtime.EventsOn('my-agent:files.changed', () => {
    refreshFileList();
});

Bus events for plugins

Plugins that need file access use bus events instead of shell methods:

Adding multiple agents

Register additional agents in the Agents slice. Each gets its own engine, config, plugins, settings, and sessions:

Agents: []desktop.Agent{
    {
        ID:         "agent-a",
        Name:       "Agent A",
        ConfigYAML: configA,
        Factories:  factoriesA,
        Settings:   settingsA,
    },
    {
        ID:         "agent-b",
        Name:       "Agent B",
        ConfigYAML: configB,
        Factories:  factoriesB,
        Settings:   settingsB,
    },
},

The frontend receives scoped events per agent ("agent-a:nexus", "agent-b:nexus"). Create a bus helper per agent and switch the active one when the user navigates.

Using LLM providers

If your agent needs an LLM provider (like Anthropic), register it in the factories and reference the model in your config:

import "github.com/frankbardon/nexus/plugins/providers/anthropic"

Factories: map[string]func() engine.Plugin{
    "nexus.io.wails":      wailsio.New,
    "nexus.llm.anthropic": anthropic.New,
    "myapp.agent.worker":  myplugin.New,
},

core:
  models:
    default: quick
    quick:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-6
      max_tokens: 4096

plugins:
  active:
    - nexus.llm.anthropic
    - nexus.io.wails
    - myapp.agent.worker

  nexus.llm.anthropic:
    api_key: "${shell.api_key}"

Your plugin requests LLM completions via the bus using the model registry — see the Model Registry documentation.

Building and running

# Development mode (live reload).
cd cmd/my-app
wails dev

# Production build.
wails build

The wails dev command watches for Go and frontend changes and rebuilds automatically. Production builds produce a single binary with embedded frontend assets.

Common patterns

Session metadata from plugins

Emit session.meta.title after completing meaningful work so the session list shows useful titles:

p.bus.Emit("session.meta.title", map[string]any{
    "title": "Analysis: Q4 Revenue Report",
})

For richer session list entries, emit session.meta.preview with agent-specific summary data:

p.bus.Emit("session.meta.preview", map[string]any{
    "itemCount": 5,
    "topResult": "Jane Smith",
    "score":     0.95,
})

Output files

When your plugin writes a file, emit session.file.created so the shell and frontend can track it:

p.bus.Emit("session.file.created", map[string]any{
    "path":     outputPath,
    "filename": filepath.Base(outputPath),
    "type":     "application/json",
})

Error handling in boot

If EnsureAgentRunning returns an error, the agent status is set to "error". Common causes:

• Missing required settings — the framework lists which keys are missing. Redirect to the settings page.
• Invalid config YAML — check ${var} placeholder names match the SettingsField.Key values.
• Plugin init failure — check the plugin’s Init method for errors.

Next steps

• Desktop Shell Overview — Architecture and component details
• API Reference — All shell methods, types, and events
• Wails IO Plugin — Plugin-level configuration and manual embedding

Desktop Shell API Reference

Complete reference for the pkg/desktop/ framework types, shell methods, settings system, and event contracts.

Types

Shell

Top-level orchestrator. Pass to desktop.Run() to start the app.

type Shell struct {
    Title   string      // Window title
    Width   int         // Window width (default 900)
    Height  int         // Window height (default 720)
    Agents  []Agent     // Registered agents
    Assets  embed.FS    // Frontend assets; zero value uses built-in base template
}

Agent

Registration data for a single agent hosted by the shell.

type Agent struct {
    ID          string                            // Unique key: "my-agent"
    Name        string                            // Display name: "My Agent"
    Description string                            // Short blurb for agent selector
    Icon        string                            // Font Awesome class: "fa-solid fa-gear"
    ConfigYAML  []byte                            // Embedded Nexus config YAML
    Factories   map[string]func() engine.Plugin   // Custom plugin factories
    Settings    []SettingsField                   // User-configurable fields
}

AgentInfo

JSON-serializable projection of Agent returned by ListAgents().

type AgentInfo struct {
    ID          string `json:"id"`
    Name        string `json:"name"`
    Description string `json:"description"`
    Icon        string `json:"icon"`
    Status      string `json:"status"` // "idle", "booting", "running", "error"
}

AgentStatus

const (
    AgentStatusIdle    AgentStatus = "idle"
    AgentStatusBooting AgentStatus = "booting"
    AgentStatusRunning AgentStatus = "running"
    AgentStatusError   AgentStatus = "error"
)

SessionMeta

Shell-level metadata for a single engine session.

type SessionMeta struct {
    ID        string    `json:"id"`
    AgentID   string    `json:"agent_id"`
    Title     string    `json:"title"`
    Status    string    `json:"status"`     // "running", "completed", "failed"
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
    Preview   any       `json:"preview,omitempty"` // Agent-specific summary data
}

FileInfo

File entry returned by ListFiles().

type FileInfo struct {
    Name     string    `json:"name"`
    Path     string    `json:"path"`
    Size     int64     `json:"size"`
    Modified time.Time `json:"modified"`
    IsDir    bool      `json:"is_dir"`
}

Settings types

SettingsField

Declares a single configurable value for the settings UI.

type SettingsField struct {
    Key         string           // Machine key: "data_dir"
    Display     string           // Human label: "Data Folder"
    Description string           // Help text shown below the field
    Type        FieldType        // UI control type
    Secret      bool             // Stored in OS keychain, masked in UI
    Default     any              // Default value if unconfigured
    Required    bool             // Agent refuses to boot without this
    Validation  *FieldValidation // Optional constraints
    ConfigPath  string           // Template variable in config YAML
    Options     []SelectOption   // For FieldSelect only
}

FieldType

const (
    FieldString FieldType = iota // Single-line text input
    FieldPath                    // Text input + Browse button
    FieldText                    // Multiline textarea
    FieldNumber                  // Number input (optional min/max)
    FieldBool                    // Toggle switch
    FieldSelect                  // Dropdown
)

FieldValidation

type FieldValidation struct {
    Regex   string   `json:"regex,omitempty"`
    Min     *float64 `json:"min,omitempty"`
    Max     *float64 `json:"max,omitempty"`
    Message string   `json:"message,omitempty"` // Validation error message
}

SelectOption

type SelectOption struct {
    Value   string `json:"value"`
    Display string `json:"display"`
}

SettingsSchema

Top-level schema sent to the frontend for dynamic UI rendering.

type SettingsSchema struct {
    Shell  []SettingsFieldInfo            `json:"shell"`
    Agents map[string][]SettingsFieldInfo `json:"agents"`
}

SettingsFieldInfo

JSON projection of SettingsField sent to the frontend.

type SettingsFieldInfo struct {
    Key         string           `json:"key"`
    Display     string           `json:"display"`
    Description string           `json:"description,omitempty"`
    Type        string           `json:"type"`      // "string", "path", "text", "number", "bool", "select"
    Secret      bool             `json:"secret,omitempty"`
    Required    bool             `json:"required,omitempty"`
    Default     any              `json:"default,omitempty"`
    Validation  *FieldValidation `json:"validation,omitempty"`
    Options     []SelectOption   `json:"options,omitempty"`
}

Shell methods (Wails-bound)

All methods below are exposed to the frontend via Wails bindings. Call them from JavaScript as go.desktop.Shell.MethodName(args).

Agent lifecycle

Session management

OS integration

File portal

RAG ingestion

IngestState has Active []IngestEntry and Recent []IngestEntry. Each IngestEntry carries Path, Namespace, Status (active / completed / failed), Chunks, SkippedCached, and Error. The shell tracks ingest activity by subscribing to rag.ingest (priority 10, before the ingest plugin runs the synchronous work) and rag.ingest.result. In-memory only — recent history resets on shell restart.

Settings

Event contracts

Bus events (plugin to shell)

Events emitted by agent plugins that the shell subscribes to internally. These do not need to be in the wails IO plugin’s subscribe/accept config — the shell installs its own bus subscriptions.

Bus events (shell to plugin)

Bus events (frontend bridge)

These events cross the bus-to-frontend boundary and must be listed in the wails IO plugin’s subscribe/accept config.

Wails events (shell direct)

Events emitted by the shell directly via wailsruntime.EventsEmit, bypassing the bus bridge. Listen with window.runtime.EventsOn.

Settings store

Persistence

• Plaintext: ~/.nexus/desktop/settings.json — JSON file with { version, shell: {}, agents: {} } structure.
• Secrets: OS keychain via go-keyring, service name "nexus-desktop", account "{scope}.{key}".
• Sentinel: Secret fields store "__keychain__" in the JSON file so the frontend knows a value exists without exposing it.

Scope resolution

When resolving a ${var} placeholder in config YAML:

1. Check agent scope for the key
2. Fall back to shell scope
3. Fall back to SettingsField.Default
4. If still unresolved and Required: true, boot fails

Keys prefixed with shell. (e.g. shell.api_key) are always looked up in shell scope directly.

Built-in shell settings

Session index

Persisted at ~/.nexus/desktop/sessions.json.

Maintenance (runs on startup)

• Cleanup: Removes sessions older than session_retention_days from both the index and disk.
• Reconcile: Adopts orphaned engine directories (on disk but not in index) if newer than the retention cutoff. Removes stale index entries whose directories no longer exist on disk.

File watcher

Single-directory watcher using fsnotify. Debounced at 200ms.

• Only fires on Create, Remove, and Rename operations.
• Calling Watch(newDir) automatically unwatches the previous directory.
• Calling Watch("") stops watching without starting a new watch.
• Notifications arrive as {agentID}:files.changed Wails events.

Config resolution

resolveConfig() performs ${key} placeholder substitution on raw YAML bytes before engine creation. For each SettingsField:

1. If ${field.Key} appears in the YAML, resolve it
2. Shell-prefixed keys (shell.xxx) look up in shell scope directly
3. Other keys check agent scope, then fall back to shell scope
4. Unresolved required fields are collected and returned as an error
5. Unresolved optional fields are left as literal ${key} — the plugin sees the placeholder string and can handle or ignore it

Nexus Desktop Design System — Priming Brief

Paste this whole document into Claude Design as a system/priming prompt. It describes the existing desktop UI system so any new screens or components remain consistent with what’s already shipped.

What you are working on

You are designing UI for Nexus desktop apps — Go/Wails-based native apps that embed AI agents. Each desktop app hosts one or more “agents” (domain-specific AI workflows) in a consistent shell. Examples in the repo: a multi-agent reference app (hello-world + staffing-match) and a single-agent phased workflow app (tech lead).

Your job is to design UI that slots into this existing system without reinventing it. Prefer existing primitives and class recipes over new ones.

Tech stack (non-negotiable)

• Tailwind CSS via CDN (https://cdn.tailwindcss.com)
• DaisyUI 4 as the component layer (https://cdn.jsdelivr.net/npm/daisyui@4/dist/full.min.css)
• Font Awesome 6.5.1 (free, solid style by default: fa-solid)
• AlpineJS 3 for state and reactivity (Alpine.store, x-data, x-show, x-for, x-transition, x-model)
• No build step. Everything ships as a single index.html per app with inline <script> and <style>.
• No other libraries. No React, Vue, Svelte, or component kits. No CSS-in-JS.

Always use DaisyUI utility classes first (btn, card, input, alert, badge, collapse, loading, textarea, toggle, select). Fall back to raw Tailwind only for layout, spacing, and DaisyUI gaps.

Theme

• Dark theme is default and primary. <html data-theme="dark">. Light mode is not currently supported — don’t design light-first mockups.
• Semantic color tokens come from DaisyUI: primary, secondary, accent, success, warning, error, info, base-100 (app bg), base-200 (panel bg), base-300 (borders/hover), base-content (text).
• Opacity is the workhorse for hierarchy. Use text-base-content at /40 /50 /60 /80 instead of introducing new grays. Example: section headers use opacity-50, body meta uses opacity-40.
• Primary color is used sparingly — reserved for active nav items, primary CTAs, and “this is the focused thing” accents. Common active-state pattern: bg-primary/15 text-primary, icon slot bg-primary/20.
• Status colors: success = done/running-healthy, warning = booting/attention, error = failed/destructive, info = neutral context, primary = active/pulsing.

Typography

• Base font = Tailwind default sans-serif. Monospace (font-mono) is used for file paths, IDs, token counts, and code/specs.
• Section headers: text-xs font-semibold uppercase tracking-wider opacity-50 — used for “SESSIONS”, “ARTIFACTS”, “FILES”, “GENERAL”, etc.
• Page title: font-semibold text-base leading-tight in headers, text-xl font-bold for phase/view titles in main content.
• Labels: text-sm font-medium for form labels; text-xs opacity-50 for field descriptions/helper text.
• Body text: text-sm default; text-xs for meta, timestamps, counts.
• Never use custom font sizes in px. Stick to Tailwind’s text-[10px], text-xs, text-sm, text-base, text-lg, text-xl.

Layout archetypes

Two shell archetypes exist. Pick the one that matches the app and keep within it.

Archetype A — Multi-agent shell (horizontal)

┌─────┬──────────┬───────────────────┬────────┐
│ Nav │ Sessions │ Main              │ Files  │
│ 64↔ │  256px   │ flex-1            │ 288px  │
│220px│ (cond.)  │                   │(toggle)│
└─────┴──────────┴───────────────────┴────────┘

• Left nav (w-16 collapsed ↔ w-[220px] expanded, bg-base-200 border-r border-base-300): logo + agent list + settings. Each agent row is an icon with a status dot and an optional label. Active agent uses bg-primary/15 text-primary.
• Sessions panel (w-64, bg-base-200/50 border-r border-base-300): visible when an agent is active. Conditional via x-show.
• Main (flex-1): per-agent content. Header on top with title, description, and inline action buttons. The header is draggable (wails-drag).
• File browser (w-72, bg-base-200/50 border-l border-base-300): toggleable right panel rooted in the agent’s input_dir.

Archetype B — Single-agent phased shell (vertical)

┌──────────────────────────────────────────┐
│  ① ━ ② ━ ③ ━ ④ ━ ⑤     [sessions] [⚙]  │  ← phase stepper bar
├──────────┬─────────────────┬─────────────┤
│ Sessions │  Main content   │ (optional)  │
│ 224px    │  flex-1         │             │
│ (toggle) │                 │             │
├──────────┴─────────────────┴─────────────┤
│ Artifact tree (224px, left)              │
└──────────────────────────────────────────┘

• Phase stepper bar on top (bg-base-200 border-b border-base-300 px-6 py-3, also wails-drag): numbered step chips with connector lines. Active step = bg-primary text-primary-content, completed = bg-success/20 text-success with ✓, future = text-base-content/40 cursor-default.
• Artifact tree (w-56): grouped list of generated artifacts (documents, epics → stories nested, notes, timeline, comms). Each group has an uppercase section header.
• Main switches content per active phase via x-show="$store.reqflow.phase === N".

Shell chrome (apply to both archetypes)

• Dragging the window uses the class wails-drag (with CSS --wails-draggable: drag;). Put it on the topmost header bar.
• Body: bg-base-100 text-base-content, overflow-hidden, root is h-screen flex (horizontal shells) or h-screen flex flex-col (vertical shells).
• Panels: bg-base-200/50, borders via border-base-300. Don’t invent new panel backgrounds.
• Transitions for panel enter/exit:

  x-transition:enter="transition ease-out duration-150"
  x-transition:enter-start="opacity-0 -translate-x-2"
  x-transition:enter-end="opacity-100 translate-x-0"
  

  150ms ease-out, 8px slide + fade. Use translate-x-2 for right-side panels entering from the right.

Component recipes (memorize these)

Buttons

• Primary action: btn btn-primary btn-sm
• Secondary/tertiary: btn btn-ghost btn-sm (common) or btn btn-outline btn-sm
• Icon-only square: btn btn-ghost btn-sm btn-square (toolbar), btn btn-ghost btn-xs btn-square (in-row)
• Destructive inline: btn btn-ghost btn-xs btn-square hover:text-error or ... text-error
• Inside a button: icon first (<i class="fa-solid fa-... text-xs">), then a label span. Loading state swaps icon for <span class="loading loading-spinner loading-xs">.
• Size ladder: btn-xs (dense toolbars, in-row actions) → btn-sm (default) → btn (rare, page-level CTA).

Nav/list items (active/hover pattern)

Reused across the agent nav, session list, artifact tree, and file list:

<button
  class="w-full flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors text-left group"
  :class="isActive
    ? 'bg-primary/15 text-primary'
    : 'hover:bg-base-300 text-base-content/70 hover:text-base-content'">
  <div class="w-8 h-8 rounded-lg flex items-center justify-center"
       :class="isActive ? 'bg-primary/20' : 'bg-base-300'">
    <i class="fa-solid fa-icon text-sm"></i>
  </div>
  <div class="min-w-0 flex-1">
    <div class="text-sm font-medium truncate">Label</div>
    <div class="text-xs opacity-50 truncate">Sub-label</div>
  </div>
</button>

Status dots

<div class="w-2.5 h-2.5 rounded-full border-2 border-base-200"
     :class="{
       'bg-success': status === 'running',
       'bg-warning animate-pulse': status === 'booting',
       'bg-error': status === 'error'
     }"></div>

Small-size variant for list rows: w-1.5 h-1.5 rounded-full.

Cards

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">...</div>
</div>

Badges

• Count/label: badge badge-sm
• Semantic: badge-success, badge-warning, badge-error, badge-primary, badge-ghost
• Tiny inline: badge badge-xs

Inputs

• Text: input input-bordered input-sm w-full
• Textarea: textarea textarea-bordered w-full text-sm (add min-h-[7rem] for multi-line prompts)
• Select: select select-bordered select-sm w-full
• Toggle: input type="checkbox" class="toggle toggle-primary toggle-sm"
• Secret (password): same input, add an eye-toggle button absolutely positioned right (absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle).
• Invalid/required: add input-warning class when the field is required and empty.

Alerts

• Error: alert alert-error py-2 text-sm with leading <i class="fa-solid fa-triangle-exclamation"></i>
• Warning/missing-config: alert alert-warning
• Inline error under a form: text-xs text-warning with <i class="fa-solid fa-circle-exclamation">

Empty states

<div class="flex items-center justify-center h-full">
  <div class="text-center max-w-sm">
    <div class="w-16 h-16 rounded-2xl bg-primary/10 flex items-center justify-center mx-auto mb-4">
      <i class="fa-solid fa-icon text-primary text-2xl"></i>
    </div>
    <h2 class="text-lg font-semibold mb-1">Short headline</h2>
    <p class="text-sm opacity-60">One-sentence explainer with a call to action.</p>
  </div>
</div>

Compact variant for narrow panels: drop the icon tile to text-2xl opacity-20, text to text-xs opacity-40, center vertically in the panel.

Loading states

• Inline (inside a button): loading loading-spinner loading-xs
• Panel-level: loading loading-spinner loading-sm opacity-40
• Hero / boot overlay: loading loading-spinner loading-lg text-primary centered with a subtitle
• “Thinking…” dots: loading loading-dots loading-sm
• Full-screen boot overlay: absolute inset-0 flex items-center justify-center bg-base-100/80 z-10

Collapsible sections (settings)

DaisyUI collapse: collapse collapse-arrow bg-base-200 border border-base-300, with <input type="checkbox" checked> inside to drive state. Title row: collapse-title font-semibold flex items-center gap-2 with a leading icon.

Drag-and-drop

Drop overlay (appears while dragging):

<div class="absolute inset-0 z-20 bg-primary/10 border-2 border-dashed border-primary rounded-lg flex items-center justify-center pointer-events-none">
  <div class="text-center">
    <i class="fa-solid fa-cloud-arrow-up text-primary text-2xl mb-2"></i>
    <p class="text-sm font-medium text-primary">Drop files here</p>
  </div>
</div>

Persistent drop zone (phase 1 import style):

<div class="border-2 border-dashed border-base-300 rounded-xl p-8 text-center transition-all"
     :class="{ 'drop-active': dragOver }">
  <i class="fa-solid fa-cloud-arrow-up text-4xl text-base-content/20 mb-4 block"></i>
  <p class="text-base-content/40 mb-3">Drop markdown files here</p>
  <button class="btn btn-sm btn-primary">Browse Files</button>
</div>

Chat messages (agent conversation)

• User: right-aligned, bg-primary text-primary-content bubble, no avatar or avatar on the right
• Assistant: left-aligned, bg-base-200 bubble, avatar is w-8 h-8 rounded-full bg-primary/20 with fa-robot icon
• Note/annotation: bg-warning/10 border border-warning/20 bubble, fa-sticky-note avatar
• Max-width bubble: max-w-[75%] rounded-lg px-4 py-3
• Auto-scroll on new message via x-effect="$refs.chatScroll && ($refs.chatScroll.scrollTop = $refs.chatScroll.scrollHeight)"

Interaction rules

• Hover reveal: destructive or secondary actions inside list rows use opacity-0 group-hover:opacity-100 transition-opacity. Never show delete buttons unconditionally.
• Keyboard: chat textareas support @keydown.enter.meta="send()" and @keydown.enter.ctrl="send()" (Cmd/Ctrl+Enter). Show the hint as text-xs opacity-30 below the input.
• Required-field gating: when required settings are missing, show a alert alert-warning banner at the top of settings, and mark each missing field with an inline text-xs text-warning “Required” hint and input-warning class.
• Restart nudge: when a running agent has dirty settings, show badge badge-warning badge-xs “restart required” on the section and a btn btn-warning btn-sm at the bottom.

Data flow (so designs match reality)

• All agent domain communication flows through a scoped event bus bridge (createBus(agentID)), not Wails-bound methods. Your designs should assume async, event-driven updates — never blocking waits.
• The shell owns: agent lifecycle (boot/stop), sessions, settings, file dialogs, file browser, drag-and-drop.
• The agent owns: its own UI section, its own Alpine store, its own input/output events.
• State that survives session recall lives in ui.state.save/ui.state.restore events — designs should gracefully rehydrate partial state.

What NOT to do

• Don’t introduce a new CSS framework, component library, or JS framework. Alpine + Tailwind + DaisyUI is the entire toolbox.
• Don’t add light mode without checking first — everything assumes dark.
• Don’t invent new named colors. Stick to the DaisyUI semantic tokens.
• Don’t use raw gray scales (text-gray-500). Use opacity-* on text-base-content.
• Don’t add routing. Views switch via x-show against a single activeView string.
• Don’t design multi-page flows with URLs. Everything is SPA-style, single index.html.
• Don’t add modals/dialogs casually — the existing apps don’t use them. Use inline collapsibles, side panels, or dedicated views instead. If you need a confirm, use inline “Are you sure?” patterns.
• Don’t design for mobile or narrow widths. Desktop only, min width roughly 900×720.
• Don’t add animations beyond DaisyUI animate-pulse and the existing 150ms panel transitions. No hero scroll effects, no motion beyond utility.
• Don’t add icons from other sets — Font Awesome 6 solid only.

When proposing something new

If your design needs a component not listed above, say so explicitly and propose either (a) a DaisyUI component that isn’t yet used, or (b) a raw-Tailwind recipe that matches the existing visual weight. Flag it as a net-new primitive so we can decide whether to adopt it.

Quick reference — the 10 classes you’ll use constantly

Nexus Desktop Design System — Full Reference

Comprehensive reference for the Nexus desktop UI system. Derived from the shipped frontends at cmd/desktop/frontend/dist/index.html and cmd/techlead/frontend/dist/index.html, plus the shell framework at pkg/desktop/. Pair with design-system-brief.md for a shorter priming version.

1. Scope and context

Nexus ships desktop apps via Wails v2 — each app is a Go binary wrapping a webview. The webview loads a single index.html containing the entire UI. Two kinds of apps exist today:

• Multi-agent shells (reference: cmd/desktop) — host several domain-specific agents under one roof, each with its own UI section.
• Single-agent workflow apps (reference: cmd/techlead) — one agent, one workflow, typically organized as a phased progression.

Both share the same visual language, component vocabulary, and tech stack. A designer working on either should be able to port patterns between them without friction.

Integration with the engine

The UI does not directly “call” the agent. All domain communication flows through a scoped event bus bridge (createBus(agentID)) that wraps Wails event APIs. Every design should assume:

• Actions emit bus events; results arrive as inbound bus events (asynchronous).
• The shell (not the agent) owns file dialogs, the file browser, settings, and session management — these appear in UI via Wails-bound methods on the shell.
• UI state that must survive session recall is saved via ui.state.save events and rehydrated via ui.state.restore.

What doesn’t exist yet

• No light theme. Everything assumes data-theme="dark".
• No modals or dialog components are in use. New screens should avoid them unless explicitly requested.
• No routing library. Views switch via Alpine stores against activeView/phase number.
• No component library beyond DaisyUI. No icon set beyond Font Awesome 6 solid.
• No responsive/mobile layouts. Min window size ~900×720.

2. Tech stack

Everything is CDN-loaded; there is no bundler, no npm install, no TypeScript, no build step. A new frontend is one self-contained index.html.

3. Design tokens

3.1 Color tokens (DaisyUI semantic)

Never introduce raw gray scales. Use DaisyUI’s semantic tokens.

Opacity for hierarchy — the conventional ladder:

Common /N accent patterns:

3.2 Spacing scale

Follows Tailwind’s default 4px-based scale. Conventions observed:

3.3 Typography scale

All sizes come from Tailwind defaults. Do not use custom px.

Weight conventions: font-medium for item labels, font-semibold for headers, font-bold for h2 page titles.

Font family: Tailwind’s default sans-serif. font-mono for: file paths, artifact IDs (epic/story IDs like E-001), token counts, USD cost, code, raw markdown, session preview paths.

3.4 Radii

3.5 Shadows, transitions, motion

• Default transition on interactive surfaces: transition-colors.
• Panel enter/exit: transition ease-out duration-150 with an 8px slide + fade.
• Hover card: transition-shadow + hover:shadow-md on epic cards, hover:border-primary/40 elsewhere.
• Status pulse: animate-pulse on booting/running indicator dots.
• Loading spinner: DaisyUI loading loading-spinner, never custom keyframes.
• loading-dots for chat “thinking” indicator.
• No parallax, no hero scroll effects, no Framer Motion.

4. Shell archetypes

4.1 Multi-agent horizontal shell

┌─────┬──────────┬─────────────────────────┬────────┐
│ Nav │ Sessions │ Header (wails-drag)     │  Files │
│     │          ├─────────────────────────┤        │
│     │          │ Main content            │        │
│     │          │                         │        │
│     │          │                         │        │
└─────┴──────────┴─────────────────────────┴────────┘
  64px     256px    flex-1                    288px
  (coll.)  (cond.)                           (toggle)

Skeleton:

<body class="bg-base-100 text-base-content">
  <div x-data class="h-screen flex" x-init="$store.shell.init()">
    <nav class="nav-sidebar flex-shrink-0 bg-base-200 border-r border-base-300 flex flex-col h-full"
         :style="{ width: $store.shell.collapsed ? '64px' : '220px' }">...</nav>

    <aside x-show="activeAgent" class="flex-shrink-0 w-64 bg-base-200/50 border-r border-base-300 flex flex-col h-full">
      <!-- Sessions panel -->
    </aside>

    <div class="flex-1 flex flex-col min-w-0 h-full">
      <header class="px-6 py-3 border-b border-base-300 flex items-center gap-3 bg-base-100 wails-drag">...</header>
      <div class="flex-1 flex overflow-hidden relative">
        <main class="flex-1 overflow-hidden relative">...</main>
        <aside x-show="filesOpen" class="flex-shrink-0 w-72 bg-base-200/50 border-l border-base-300 flex flex-col h-full">
          <!-- File panel -->
        </aside>
      </div>
    </div>
  </div>
</body>

Key properties:

• body { overflow: hidden; } — the UI is not scrolled; individual panels manage their own overflow.
• Nav width animates via inline CSS transition: .nav-sidebar { transition: width 200ms ease; }.
• Nav collapse state is persisted in Alpine.store('shell').collapsed.
• Active-agent switch triggers lazy engine boot via window.go.desktop.Shell.EnsureAgentRunning(agentID).

4.2 Single-agent phased vertical shell

┌──────────────────────────────────────────────────┐
│ ①━②━③━④━⑤━⑥━⑦          [sessions] [⚙]         │  wails-drag
├──────────┬──────────┬────────────────────────────┤
│ Sessions │ Artifacts│ Main content              │
│ (toggle) │ tree     │                            │
│  224px   │  224px   │ flex-1                     │
│          │          │                            │
│          │          ├────────────────────────────┤
│          │          │ Bottom bar                 │
└──────────┴──────────┴────────────────────────────┘

Skeleton:

<div x-data class="h-screen flex flex-col" x-init="$store.reqflow.init()">
  <!-- Top phase stepper bar (wails-drag) -->
  <div class="wails-drag flex-shrink-0 bg-base-200 border-b border-base-300 px-6 py-3">
    <!-- phase chips + toolbar -->
  </div>

  <!-- Body -->
  <div class="flex-1 flex overflow-hidden">
    <aside x-show="showSessions" class="w-56 flex-shrink-0 bg-base-200/50 border-r border-base-300 p-3 overflow-y-auto flex flex-col">...</aside>
    <aside class="w-56 flex-shrink-0 bg-base-200/50 border-r border-base-300 p-3 overflow-y-auto">...</aside>
    <main class="flex-1 flex flex-col overflow-hidden">
      <div class="flex-1 overflow-y-auto p-6">...</div>
      <!-- Bottom action bar -->
      <div class="flex-shrink-0 border-t border-base-300 bg-base-200/50 px-6 py-3 flex items-center justify-between">...</div>
    </main>
  </div>
</div>

4.3 Window dragging

Wails exposes --wails-draggable: drag; as a CSS custom property. Apply via:

.wails-drag { --wails-draggable: drag; }

Put this on the topmost chrome surface only (header bar in horizontal shell, phase stepper bar in vertical shell). Don’t apply it to anything interactive — dragging steals click events.

5. Component catalog

5.1 Buttons

Button size ladder: btn-xs (toolbars, in-row) → btn-sm (default) → btn (rare; used only for page-level CTAs inside empty-state cards like hello-world’s “Say hello”).

Tab/segment group for mode switches (editor/preview):

<div class="btn-group">
  <button class="btn btn-xs" :class="mode === 'split' ? 'btn-active' : ''">
    <i class="fa-solid fa-columns"></i>
  </button>
  <button class="btn btn-xs" :class="mode === 'edit' ? 'btn-active' : ''">
    <i class="fa-solid fa-code"></i>
  </button>
  <button class="btn btn-xs" :class="mode === 'preview' ? 'btn-active' : ''">
    <i class="fa-solid fa-eye"></i>
  </button>
</div>

Button loading state: Swap icon for <span class="loading loading-spinner loading-xs mr-1"></span> while still showing the label.

5.2 Nav / list item

The single most reused pattern in the app. Same shape serves agent nav, session list, file list, artifact rows.

<button
  class="w-full flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors text-left group"
  :class="isActive
    ? 'bg-primary/15 text-primary'
    : 'hover:bg-base-300 text-base-content/70 hover:text-base-content'">

  <!-- Icon slot with optional status dot -->
  <div class="relative flex-shrink-0 w-8 h-8 rounded-lg flex items-center justify-center"
       :class="isActive ? 'bg-primary/20' : 'bg-base-300 group-hover:bg-base-100'">
    <i class="fa-solid fa-icon text-sm"></i>
    <div x-show="status !== 'idle'"
         class="absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full border-2 border-base-200"
         :class="{
           'bg-success': status === 'running',
           'bg-warning animate-pulse': status === 'booting',
           'bg-error': status === 'error'
         }"></div>
  </div>

  <!-- Labels -->
  <div class="min-w-0 flex-1">
    <div class="text-sm font-medium truncate">Primary label</div>
    <div class="text-xs opacity-50 truncate">Secondary label</div>
  </div>
</button>

Density variants:

• Artifact tree rows (single-agent): px-2 py-1 rounded text-sm — smaller, no icon slot background.
• Nested list rows (stories under epics): pl-6 pr-2 py-0.5 rounded text-xs.
• Session list in multi-agent: uses the group pattern so a delete button appears on hover (opacity-0 group-hover:opacity-50 hover:!opacity-100).

5.3 Cards

Basic container card:

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">
    <!-- content -->
  </div>
</div>

Grid of cards (epics):

<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
  <div class="card bg-base-200 shadow-sm cursor-pointer hover:shadow-md transition-shadow">
    <div class="card-body p-4">
      <div class="flex items-center gap-2 mb-1">
        <span class="badge badge-primary badge-sm font-mono">E-001</span>
        <h3 class="card-title text-sm">Epic title</h3>
      </div>
      <p class="text-xs text-base-content/50 line-clamp-3">Description excerpt...</p>
      <div class="card-actions justify-end mt-2">
        <span class="text-xs text-base-content/30">5 stories</span>
      </div>
    </div>
  </div>
</div>

Candidate/ranked-result card:

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">
    <div class="flex items-start gap-3">
      <div class="shrink-0 w-10 h-10 rounded-full bg-primary/10 text-primary flex items-center justify-center font-semibold text-sm">1</div>
      <div class="flex-1 min-w-0">
        <div class="flex items-center gap-2 mb-1">
          <span class="font-semibold text-base truncate">Jane Doe</span>
          <span class="badge badge-sm badge-success">0.92</span>
        </div>
        <p class="text-sm opacity-80">Reasoning...</p>
        <div class="mt-2 text-xs opacity-40 font-mono">/path/to/resume.pdf</div>
      </div>
    </div>
  </div>
</div>

5.4 Badges

Score badges in candidate cards are threshold-driven:

c.Score >= 0.85 ? 'badge-success' : c.Score >= 0.7 ? 'badge-warning' : 'badge-ghost'

5.5 Forms

Text input (small default):

<input type="text" class="input input-bordered input-sm w-full">

Required + empty: add input-warning, with inline hint:

<div x-show="field.required && !hasValue()" class="text-xs text-warning mb-1">
  <i class="fa-solid fa-circle-exclamation"></i> Required
</div>

Number:

<input type="number" class="input input-bordered input-sm w-full"
       :min="field.validation?.min" :max="field.validation?.max">

Textarea:

<textarea class="textarea textarea-bordered w-full min-h-[7rem] text-sm leading-snug" rows="5"></textarea>

Variants: textarea-sm for dense settings; add font-mono text-sm leading-relaxed resize-none for markdown/spec editors.

Select:

<select class="select select-bordered select-sm w-full">
  <option value="...">Label</option>
</select>

Toggle:

<input type="checkbox" class="toggle toggle-primary toggle-sm">

Secret (password) with visibility toggle:

<div class="relative flex-1">
  <input :type="showSecret ? 'text' : 'password'"
         class="input input-bordered input-sm w-full pr-10"
         :placeholder="hasValue() ? '********' : 'Enter value...'"
         @change="saveSecret($event.target.value); $event.target.value = ''">
  <button class="absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle"
          @click="showSecret = !showSecret">
    <i class="fa-solid text-xs" :class="showSecret ? 'fa-eye-slash' : 'fa-eye'"></i>
  </button>
</div>

Secret inputs never bind :value — they show placeholder ******** when a value exists, and only commit on @change, clearing the DOM input after save so the raw value never lingers in the DOM.

Path input + browse:

<div class="flex gap-2">
  <input type="text" class="input input-bordered input-sm flex-1"
         :value="currentValue()" @change="save($event.target.value)">
  <button class="btn btn-ghost btn-sm" @click="browse()">
    <i class="fa-solid fa-folder-open text-xs"></i> Browse
  </button>
</div>

The browse() handler calls window.go.desktop.Shell.PickFolder(...) or PickFile(...).

Form label + description:

<label class="block text-sm font-medium mb-1">Display name</label>
<div class="text-xs opacity-50 mb-2">Optional description.</div>

5.6 Alerts

Standard error shape:

<div class="alert alert-error py-2 text-sm">
  <i class="fa-solid fa-triangle-exclamation"></i>
  <span>Error message</span>
</div>

5.7 Collapsible sections (settings)

DaisyUI collapse with arrow, open by default:

<div class="collapse collapse-arrow bg-base-200 border border-base-300">
  <input type="checkbox" checked>
  <div class="collapse-title font-semibold flex items-center gap-2">
    <i class="fa-solid fa-sliders text-sm opacity-60"></i>
    Section title
    <span class="badge badge-warning badge-xs ml-2">restart required</span>
  </div>
  <div class="collapse-content space-y-4">
    <!-- fields -->
  </div>
</div>

Highlight a collapse when it has missing required fields: :class="missingRequired ? 'border-warning' : ''".

5.8 Empty states

Primary pattern (main content area):

<div class="flex items-center justify-center h-full">
  <div class="text-center max-w-sm">
    <div class="w-16 h-16 rounded-2xl bg-primary/10 flex items-center justify-center mx-auto mb-4">
      <i class="fa-solid fa-magnifying-glass text-primary text-xl"></i>
    </div>
    <h2 class="text-lg font-semibold mb-1">No matches yet</h2>
    <p class="text-sm opacity-60">Upload a PDF and click Find matches.</p>
  </div>
</div>

Muted variant (used in phases 1–7 of single-agent shell): drops the tinted icon tile and uses a large low-opacity glyph:

<div class="flex-1 flex items-center justify-center">
  <div class="text-center text-base-content/30 max-w-md">
    <i class="fa-solid fa-file-code text-4xl mb-4 block"></i>
    <p class="font-medium mb-2">No specification yet</p>
    <p class="text-sm mb-4">Generate from your PRD and discussion notes.</p>
    <button class="btn btn-primary btn-sm"><i class="fa-solid fa-wand-magic-sparkles mr-1"></i> Generate Spec</button>
  </div>
</div>

Compact (narrow panels, file list empty):

<div class="text-center">
  <i class="fa-solid fa-file-circle-plus text-2xl opacity-20 mb-2"></i>
  <p class="text-xs opacity-40">No files found</p>
  <p class="text-xs opacity-30 mt-1">Drop files here or add to input folder.</p>
</div>

5.9 Loading states

Boot overlay (covers a section while the engine is starting):

<div x-show="status === 'booting'"
     x-transition
     class="absolute inset-0 flex items-center justify-center bg-base-100/80 z-10">
  <div class="text-center">
    <span class="loading loading-spinner loading-lg text-primary"></span>
    <p class="mt-3 text-sm opacity-60">Starting engine...</p>
  </div>
</div>

Generation overlay (long-running content creation):

<div class="flex-1 flex items-center justify-center">
  <div class="text-center">
    <span class="loading loading-spinner loading-lg text-primary"></span>
    <p class="mt-4 text-base-content/60">Generating timeline estimates...</p>
    <p class="text-sm text-base-content/30 mt-1">Analyzing epics and stories</p>
  </div>
</div>

5.10 Chat / conversation

Layout:

<div class="flex gap-3" :class="msg.role === 'user' ? 'justify-end' : ''">
  <!-- Avatar (non-user only) -->
  <div x-show="msg.role !== 'user'"
       class="w-8 h-8 rounded-full flex items-center justify-center flex-shrink-0"
       :class="msg.role === 'note' ? 'bg-warning/20' : 'bg-primary/20'">
    <i class="text-xs" :class="msg.role === 'note'
      ? 'fa-solid fa-sticky-note text-warning'
      : 'fa-solid fa-robot text-primary'"></i>
  </div>
  <!-- Bubble -->
  <div class="max-w-[75%] rounded-lg px-4 py-3"
       :class="{
         'bg-primary text-primary-content': msg.role === 'user',
         'bg-base-200': msg.role === 'assistant',
         'bg-warning/10 border border-warning/20': msg.role === 'note'
       }">
    <div x-show="msg.role === 'note'" class="text-xs font-semibold text-warning/70 mb-1">Technical Note</div>
    <div class="text-sm whitespace-pre-wrap doc-preview" x-text="msg.content"></div>
  </div>
  <!-- Avatar (user) -->
  <div x-show="msg.role === 'user'"
       class="w-8 h-8 rounded-full bg-primary/20 flex items-center justify-center flex-shrink-0">
    <i class="fa-solid fa-user text-xs text-primary"></i>
  </div>
</div>

Auto-scroll to bottom:

<div x-ref="chatScroll"
     x-effect="$refs.chatScroll && ($refs.chatScroll.scrollTop = $refs.chatScroll.scrollHeight)"
     class="flex-1 overflow-y-auto space-y-4 mb-4 pr-2">...</div>

Chat input with Cmd/Ctrl+Enter send:

<div class="flex gap-2">
  <textarea class="textarea textarea-bordered flex-1 text-sm" rows="2"
            placeholder="..."
            @keydown.enter.meta="send()" @keydown.enter.ctrl="send()"></textarea>
  <button class="btn btn-primary btn-sm self-end">
    <i class="fa-solid fa-paper-plane"></i>
  </button>
</div>
<div class="text-xs text-base-content/30 mt-1">Cmd+Enter to send</div>

5.11 Phase stepper

<div class="flex items-center gap-1">
  <template x-for="phase in phases" :key="phase.number">
    <div class="flex items-center">
      <button class="phase-step flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium transition-colors"
        :class="{
          'active bg-primary text-primary-content': phase.number === current,
          'bg-success/20 text-success': phase.number < current,
          'text-base-content/40 cursor-default': phase.number > current
        }"
        :disabled="phase.number > current"
        @click="phase.number < current && goToPhase(phase.number)">
        <span class="w-5 h-5 rounded-full flex items-center justify-center text-xs font-bold"
              :class="{
                'bg-primary-content/20': phase.number === current,
                'bg-success/30': phase.number < current,
                'bg-base-300': phase.number > current
              }"
              x-text="phase.number < current ? '✓' : phase.number">
        </span>
        <span x-text="phase.label" class="hidden sm:inline"></span>
      </button>
      <div x-show="phase.number < phases.length"
           class="w-4 h-0.5 mx-0.5"
           :class="phase.number < current ? 'bg-success/40' : 'bg-base-300'"></div>
    </div>
  </template>
</div>

Supporting CSS:

.phase-step { transition: all 200ms ease; }
.phase-step.active { transform: scale(1.05); }

Rules:

• Future phases are disabled, cursor-default, at 40% opacity.
• Completed phases are green (bg-success/20 text-success) with a ✓.
• Active phase is primary-filled and slightly scaled up.
• Connectors between steps mirror step state.

5.12 Drag-and-drop

Overlay on a panel while dragging:

<aside @dragover.prevent="dragOver = true"
       @dragleave.prevent="dragOver = false"
       @drop.prevent="handleDrop($event)"
       class="relative ...">
  <div x-show="dragOver" x-transition
       class="absolute inset-0 z-20 bg-primary/10 border-2 border-dashed border-primary rounded-lg flex items-center justify-center pointer-events-none">
    <div class="text-center">
      <i class="fa-solid fa-cloud-arrow-up text-primary text-2xl mb-2"></i>
      <p class="text-sm font-medium text-primary">Drop files here</p>
    </div>
  </div>
</aside>

Persistent drop zone (centerpiece of a page):

<div x-data="{ dragOver: false }"
     class="border-2 border-dashed border-base-300 rounded-xl p-8 text-center transition-all"
     :class="{ 'drop-active': dragOver }"
     @dragover.prevent="dragOver = true"
     @dragleave.prevent="dragOver = false"
     @drop.prevent="dragOver = false; handleDrop($event)">
  <i class="fa-solid fa-cloud-arrow-up text-4xl text-base-content/20 mb-4 block"></i>
  <p class="text-base-content/40 mb-3">Drop markdown files here</p>
  <button class="btn btn-sm btn-primary"><i class="fa-solid fa-folder-open mr-1"></i> Browse Files</button>
  <p class="text-xs text-base-content/30 mt-3">Supports .md, .markdown, .txt</p>
</div>

Supporting CSS (drop-active emphasis):

.drop-active {
  border-color: oklch(var(--p)) !important;
  background-color: oklch(var(--p) / 0.05);
}

5.13 Markdown preview

Content rendered via doc-preview class gets basic markdown styling:

.doc-preview h1 { font-size: 1.5rem; font-weight: 700; margin: 1rem 0 0.5rem; }
.doc-preview h2 { font-size: 1.25rem; font-weight: 600; margin: 0.75rem 0 0.5rem; }
.doc-preview h3 { font-size: 1.1rem; font-weight: 600; margin: 0.5rem 0 0.25rem; }
.doc-preview p { margin: 0.25rem 0; }
.doc-preview ul, .doc-preview ol { padding-left: 1.5rem; margin: 0.25rem 0; }
.doc-preview li { margin: 0.1rem 0; }
.doc-preview code { background: oklch(var(--b3)); padding: 0.1rem 0.3rem; border-radius: 0.25rem; font-size: 0.875rem; }
.doc-preview pre { background: oklch(var(--b3)); padding: 0.75rem; border-radius: 0.5rem; overflow-x: auto; }
.doc-preview pre code { background: none; padding: 0; }
.doc-preview hr { border-color: oklch(var(--bc) / 0.1); margin: 1rem 0; }
.doc-preview blockquote { border-left: 3px solid oklch(var(--bc) / 0.2); padding-left: 1rem; opacity: 0.8; }

Use oklch(var(--*)) to reference DaisyUI theme variables directly: --p (primary), --b3 (base-300), --bc (base-content), etc. This is the only place in the system where CSS custom property access is routine.

5.14 Split editor / preview

Three-mode toggle (split/edit/preview) + synchronized textarea and preview pane:

<div class="flex-1 flex gap-4 min-h-0 overflow-hidden">
  <div x-show="viewMode !== 'preview'"
       class="flex-1 flex flex-col min-h-0"
       :class="viewMode === 'split' ? 'max-w-[50%]' : ''">
    <div class="flex items-center justify-between mb-2">
      <span class="text-xs font-semibold text-base-content/50 uppercase tracking-wider">Editor</span>
      <span x-show="dirty" class="text-xs text-warning">
        <i class="fa-solid fa-circle text-[6px] mr-1"></i>Unsaved
      </span>
    </div>
    <textarea class="textarea textarea-bordered flex-1 font-mono text-sm leading-relaxed resize-none"
              x-model="editContent"
              @input="dirty = true"
              @blur="saveEdit()"
              @keydown.meta.s.prevent="saveEdit()"
              @keydown.ctrl.s.prevent="saveEdit()"></textarea>
  </div>
  <div x-show="viewMode !== 'edit'"
       class="flex-1 flex flex-col min-h-0"
       :class="viewMode === 'split' ? 'max-w-[50%]' : ''">
    <div class="flex items-center mb-2">
      <span class="text-xs font-semibold text-base-content/50 uppercase tracking-wider">Preview</span>
    </div>
    <div class="flex-1 overflow-y-auto bg-base-200 rounded-lg p-4 doc-preview">
      <div x-html="renderPreview()"></div>
    </div>
  </div>
</div>

5.15 Bottom action bar (single-agent only)

<div class="flex-shrink-0 border-t border-base-300 bg-base-200/50 px-6 py-3 flex items-center justify-between">
  <span x-show="status" x-text="status" class="text-sm text-base-content/60"></span>
  <button class="btn btn-sm btn-outline" :disabled="phase >= phases.length" @click="advance()">
    Next Phase <i class="fa-solid fa-chevron-right ml-1"></i>
  </button>
</div>

5.16 Copy-to-clipboard button

<button class="btn btn-ghost btn-xs" @click="copyToClipboard()">
  <i class="fa-solid fa-copy mr-1"></i>
  <span x-text="copied ? 'Copied!' : 'Copy'"></span>
</button>

Toggle the copied flag to true for ~1.5s after success, then reset.

5.17 Tabs (in-content)

The comms phase uses a button-row “tabs” pattern rather than DaisyUI’s tabs component:

<div class="flex gap-1 mb-3 flex-shrink-0">
  <template x-for="item in items" :key="item.template">
    <button class="btn btn-xs"
            :class="selected === item.template ? 'btn-primary' : 'btn-ghost'"
            @click="selected = item.template"
            x-text="item.title"></button>
  </template>
</div>

6. Font Awesome icon inventory

Every icon that appears in the shipped apps, grouped by role. Use these first before reaching for alternatives.

App/brand: fa-bolt (Nexus logo)

Nav/chrome: fa-gear, fa-angles-left, fa-angles-right, fa-xmark, fa-plus, fa-chevron-right, fa-arrow-left, fa-rotate-right, fa-arrows-rotate

Files: fa-folder-open, fa-folder, fa-folder-plus, fa-file, fa-file-lines, fa-file-code, fa-file-circle-plus, fa-paperclip, fa-cloud-arrow-up, fa-arrow-up-right-from-square (open external)

Chat / communication: fa-comments, fa-paper-plane, fa-robot, fa-user, fa-sticky-note, fa-bullhorn

Generation / action: fa-wand-magic-sparkles, fa-magnifying-glass, fa-copy

Workflow: fa-layer-group (epics), fa-list-check (stories), fa-calendar-days (timeline)

Settings/fields: fa-sliders, fa-eye, fa-eye-slash, fa-trash-can, fa-circle-exclamation, fa-triangle-exclamation, fa-circle (tiny marker dot)

Edit/view mode toggle: fa-code, fa-columns, fa-eye

Session / history: fa-clock-rotate-left

Always fa-solid (solid style). All icons are the free tier — don’t introduce Pro-only glyphs. Sizing is driven by the wrapping element, not fa-* size classes; use text-xs, text-sm, text-lg, text-2xl, text-4xl on the <i>.

7. State management patterns

Alpine stores are the state spine. No Redux, no Pinia, no context API.

7.1 Store declaration

document.addEventListener('alpine:init', () => {
  Alpine.store('storename', {
    // reactive state
    items: [],
    loading: false,

    // methods
    async init() { ... },
    async load() { ... },
  });
});

7.2 Scoped bus bridge

Every agent’s UI talks to its engine via createBus(agentID) — a thin wrapper over Wails events with scoping:

const bus = createBus('agent-id');
bus.emit('domain.request', { data });
bus.on('domain.result', (payload) => { /* handle */ });
bus.off('domain.result', handler);
await bus.call('req.request', 'req.response', payload, timeoutMs);

Outbound channel: {agentID}:nexus (engine → UI). Inbound channel: {agentID}:nexus.input (UI → engine). Envelope: { type: "event.name", payload: {...}, timestamp: "ISO" }.

7.3 Wails-bound shell services

The shell (pkg/desktop/shell.go) exposes Wails methods directly on window.go.desktop.Shell.* — these are the only places UI calls non-bus APIs:

Rule: shell services are only called from the UI layer; agents communicate with the shell via bus events, not by invoking these methods.

7.4 Settings schema → UI rendering

The shell returns a settings schema with fields like:

{
  "shell": [{ "key": "shared_data_dir", "display": "Shared data folder", "type": "path" }],
  "agents": {
    "my-agent": [
      { "key": "input_dir", "display": "Input folder", "type": "path", "required": true },
      { "key": "api_key", "display": "API key", "type": "string", "secret": true, "required": true }
    ]
  }
}

Types and their rendering:

Secrets never render a current value — just ******** placeholder when present.

7.5 Session list

Sessions are tracked per agent. The shell emits {agentID}:sessions.updated via Wails events (not through the bus bridge) when the list changes. Session metadata includes:

• id, title (from session.meta.title event), created_at, status, preview (arbitrary JSON from session.meta.preview event)

Session-list rendering uses the standard nav/list-item pattern (§5.2) with a status dot, title, timestamp, and optional preview line.

7.6 UI state persistence

Two bus events drive cross-session UI state:

• ui.state.save — UI emits with opaque { state: {...} } payload. Shell writes to ui-state.json in the engine session dir.
• ui.state.restore — Shell emits on session recall. UI rehydrates.

Designs that have non-trivial UI state (partially filled forms, scroll positions, expanded panels, active tab) should persist + rehydrate via these events. Keep the payload JSON-serializable and opaque to the shell.

8. Interaction and accessibility patterns

8.1 Keyboard

• Cmd+Enter / Ctrl+Enter — submit in chat textareas (@keydown.enter.meta, @keydown.enter.ctrl)
• Cmd+S / Ctrl+S — save in spec/timeline editors (@keydown.meta.s.prevent, @keydown.ctrl.s.prevent)
• Enter — submit in single-line inputs (hello world)
• No global shortcuts currently.

Show hints inline as text-xs opacity-30 or text-xs text-base-content/30 mt-1.

8.2 Hover reveal

Destructive or secondary in-row actions hide by default, appear on hover of the parent .group:

<div class="group ...">
  <span>Content</span>
  <button class="btn btn-ghost btn-xs btn-square opacity-0 group-hover:opacity-50 hover:!opacity-100 hover:text-error">
    <i class="fa-solid fa-xmark text-xs"></i>
  </button>
</div>

8.3 Transitions

Side panel enter/exit (left panel):

x-transition:enter="transition ease-out duration-150"
x-transition:enter-start="opacity-0 -translate-x-2"
x-transition:enter-end="opacity-100 translate-x-0"

For right-side panels, reverse the translate (translate-x-2). For vertical reveals (add-note input), use default x-transition for a simple fade/slide.

8.4 Titles and tooltips

Native title attribute is the standard tooltip. No tooltip library is used.

<button title="Refresh file list">...</button>

8.5 Required-field gating

Shell’s HasMissingRequired() returns a map of agentID → [missingKeys]. Pattern:

1. Top-of-settings banner: alert alert-warning summarizing “Required settings missing”.
2. On the offending collapse: :class="missing ? 'border-warning' : ''".
3. On the field: input-warning class + inline “Required” hint.
4. Agents with missing required settings cannot boot — nav-click routes to settings instead.

8.6 Dirty / unsaved

• Textarea-based editors track a dirty flag set on @input, cleared on @blur / save.
• Display inline text-xs text-warning with a <i class="fa-solid fa-circle text-[6px] mr-1"></i> dot.
• Show a Save button (btn btn-xs btn-primary) only when dirty.

8.7 Restart required

When a running agent has changed settings:

• Badge in section title: badge badge-warning badge-xs ml-2 “restart required”
• Restart button at bottom of section: btn btn-warning btn-sm with fa-rotate-right icon

9. Multi-agent vs single-agent — differences at a glance

When extending multi-agent: check whether the feature is in-session (both kinds of shell) or wrapper (desktop shell only). See the CLAUDE.md parity rule.

When extending single-agent: new phases should follow the existing N-ary pattern — empty state → generating state → content → edit mode → unsaved indicator.

10. Opinionated “what NOT to do” list

• No new frameworks. Alpine + Tailwind + DaisyUI is the full toolbox. No React, Vue, Svelte, jQuery, Lodash, etc.
• No light theme unless explicitly requested — dark theme is the reference experience.
• No raw gray scales. Use opacity-* on text-base-content / border-base-300 etc.
• No modals or dialogs in the absence of a strong reason. Prefer inline reveals, collapsibles, side panels, or dedicated views.
• No routing. Views switch via x-show driven by a store property.
• No animations beyond utility. DaisyUI animate-pulse + 150ms panel slides are the entire vocabulary.
• No custom icon sets. Font Awesome 6 solid free only.
• No responsive / mobile layouts. Desktop-only, min ~900×720.
• No font imports. Stick to the system/Tailwind default font stack.
• No toasts/snackbars. Errors go in alert or inline. Success is silent or a tiny inline “Copied!”.
• No component abstractions until a pattern is used three times. Inline the classes.

11. Extensibility hooks

When Claude Design proposes something new, validate against these hooks so it slots into the real system:

• Is it a bus event or a Wails-bound shell method? If it changes agent state, design around an event round-trip (request → response). If it asks the OS or shell, call a window.go.desktop.Shell.* method.
• Does it need session-recall persistence? If yes, design the UI state payload and plan on ui.state.save/ui.state.restore.
• Does it touch files? Use the shell’s file portal (input_dir, output_dir, ListFiles, PickFile). Don’t design a bespoke file picker.
• Does it share with another agent? If yes, it probably belongs in pkg/ui/ shared code, not a single app.
• Is it a multi-session concern? If yes, it only belongs in multi-agent / wrapper scopes — don’t back-port to single-agent shells that are session-scoped.

12. Reference quick-lookup

13. Glossary

ICM Workflows — Overview

Nexus ships an agent loop for file-driven multi-stage workflows: nexus.workflows.icm. The shorthand for what it does is short — a folder on disk is your workflow — but the consequences are worth a section of its own. This page makes the case for the feature and gives you the mental model needed to read the walkthrough and the plugin reference without getting lost.

What is ICM?

ICM is short for Interpretable Context Methodology (Van Clief & McDermott, arXiv:2603.16021). The methodology argues that production LLM workflows should be assembled out of small, human-reviewable contracts rather than handed off to one large, opinionated agent loop. Each step has a written brief, declared inputs, a single declared output, and validators that decide whether the step is done. The methodology is paper-shaped — the Nexus plugin gives it a runtime.

The plugin reduces the methodology to a single rule: the workflow is a folder on disk. Stages are subfolders. Contracts are markdown files with YAML frontmatter. Predicates are inline. Skills are subfolders. Artifacts land in the session directory at run time, never in the workspace.

~/work/screenplay-pipeline/
  workspace.md              # the brief — required, non-empty
  stages/
    01_outline/contract.md  # YAML frontmatter + body
    02_script/contract.md
    03_review/contract.md
  shared/skills/...         # optional reusable bundles
  scripts/...               # optional command predicates
  rubrics/...               # optional LLM-judge rubrics

That folder is the entire workflow. The plugin loads + validates the workspace at boot, derives one AgentPosture per stage, and dispatches each stage as a sub-agent through a private delegate.Runtime whenever an io.input arrives.

Why this deserves its own surface

A normal ReAct agent is excellent at exploratory work — give it a goal and some tools and let it churn. But three pressures push real workflows past what a single ReAct loop can hold:

1. Repeatability. A research pipeline that runs every Monday morning needs the same shape every time. Free-form ReAct drift makes “the same shape” hard to guarantee.
2. Reviewability. Stakeholders need to read what the agent will do before it runs, not infer it from a transcript afterward.
3. Surgical iteration. When stage 3 is wrong, you want to fix stage 3 in isolation — not re-prompt a system message that drives all 7 stages.

The nexus.workflows.icm plugin solves all three by making the workflow a literal folder you can read, diff, and ship. It also proves a deeper claim about Nexus’s design:

A non-trivial multi-stage agent system can be expressed without writing Go. Posture registration, sub-agent dispatch, schema-validated outputs, HITL gates, loop convergence, and fan-out parallelism are already in the engine — you compose them with YAML and markdown.

This is the first plugin to combine all of them. The walkthrough exists because doing so end-to-end is a worked example for everything Nexus offers, not because the ICM plugin itself is unusually complex.

Mental model

Three vocabulary boundaries decide whether the docs read clearly.

Workspace, run, session

The workspace is the source of truth for the workflow; the run directory is the source of truth for the artifacts. Edits to the workspace are authoring; edits to a run directory are tampering. Treating them as different objects is the single biggest reason the plugin’s surface stays simple.

Stage, iteration, turn, item

A stage is one folder with one contract.md. Inside a stage’s lifetime three nested loops are possible:

• Turns — the inner conversation. turns.policy: fixed | until_valid | until_human_approves. A turn is one LLM call within a single stage invocation.
• Iterations — convergence loops. loop.max_iterations: N with until predicates. The entire stage runs as a fresh invocation each iteration, with the prior iteration’s exit failures included in the next payload.
• Items — data-driven fan-out. fan_out.source: ... points at a JSON array produced by an earlier stage; the stage runs once per item, up to max_parallel concurrently.

Turns sit inside iterations, iterations sit inside the stage, and fan-out is the stage being dispatched once per item. You almost never mix all three in a single stage — but the orchestrator supports it because fan-out + loop composes cleanly (each item independently iterates).

Posture, delegate, predicate

These are reused engine concepts; ICM does not reinvent any of them.

• Posture — pkg/posture.AgentPosture from nexus.agent.postures. ICM derives one per stage at Ready(), layering operator prompt + body
  • overlay + tools + budget on top of a base posture, then registers it.
• Delegate — pkg/delegate.Runtime. The same primitive delegate plugin uses to dispatch sub-agents. ICM keeps its own private delegate.Runtime so workflow stages don’t pollute caller tool budgets.
• Predicate — the unified shape used by output.validators, loop.until, and verifier outputs. Six types: schema, regex, native, command, llm, human. The loader compiles each at boot.

If you’ve configured postures + delegate + HITL + the schema registry before, ICM should feel like wiring those four together into a single user surface.

What ICM is not

It is not a replacement for nexus.agent.react or nexus.agent.orchestrator. They solve different problems:

It is not a new abstraction over LLM providers. Every model call routes through delegate (sub-agents) or through the configured judge posture (LLM predicates). It does not mutate the workspace — artifacts live in the session. It does not auto-discover skills from nexus.skills.scan_paths — skills live under the workspace and are loaded only when a stage’s inputs.skills references them.

What you get out of the box

The plugin is fully implemented today. The walkthrough exercises everything in this list:

• Workspace + contract loader with aggregated validation errors (boot once to see every problem, fix in one pass).
• One derived AgentPosture per stage, registered before the engine finishes boot. Tools, model role, budget, and operator prompt are baked in.
• Stage-level plan.created + plan.progress surface so generic UIs render the workflow without ICM-specific knowledge, plus a richer icm.* event family for iteration / turn / item detail.
• Six predicate types with four shipped native handlers (word_count_under, word_count_over, contains_required_ids, json_path_exists).
• Loop convergence with on_exhausted: human_gate | error and a configurable restart ceiling.
• Fan-out with optional parallelism, per-item folders, and an aggregate artifact downstream stages can reference.
• Per-workspace skill resolution (stages/<NN>/skills/<name> wins over shared/skills/<name>) plus an LLM-facing read_skill_reference tool that surfaces only when a stage actually uses skills.
• Multi-instance support via nexus.workflows.icm/<suffix> so two workspaces can coexist in one engine.

Authoring tools

You do not need to write contracts by hand. The repo ships a Claude Code skill that interviews you about the workflow you want, validates each answer against the loader’s rules, and writes a workspace that loads on the first try:

• .claude/skills/icm-workspace-builder/SKILL.md — invoke with /icm-workspace-builder once the skills plugin is configured to scan .claude/skills/. The skill enforces the same rules the loader does (folder regex, reserved 00_input, predicate args, fan-out sources).

The walkthrough is hand-authored so you can read every file; the skill is the on-ramp for everything else.

Where to go next

• End-to-end walkthrough — build a real workspace from an empty folder, run it, watch the events, inspect the artifacts.
• Plugin reference — every field on every block, every event, every troubleshooting case.
• Configuration reference — every plugin config key with defaults.
• Postures — the base postures stages inherit from.
• Sub-agent delegation — the dispatch primitive ICM stands on.
• HITL — where every human gate is routed.

ICM Workflows — End-to-End Walkthrough

This page builds a working ICM workspace from an empty folder, runs it through Nexus, and shows you exactly what to expect at each step: the events that fire, the files that land on disk, the human gates that pause the run, and the failure modes that bite first-time authors.

The example is a two-stage research brief pipeline. Stage 1 produces an outline from a topic; stage 2 expands the outline into a brief, looping until the brief passes a word-count rubric. It is deliberately small enough to fit on one screen and deliberately rich enough to exercise loops, predicates, human gates, and the full event surface.

By the end of this walkthrough you will have:

• A working workspace under ~/work/research-brief/.
• A Nexus config that wires posture + delegate + HITL + ICM.
• A bin/nexus session that runs the workflow end-to-end against a real LLM provider.
• Familiarity with the exact icm.* events that drive any UI you build on top.

If you only want to read the surface area, the overview is the conceptual map and the plugin reference is the field-by-field manual. This page sits between them.

Prerequisites

You need:

1. A built bin/nexus. From the repo root: make build.
2. An LLM provider API key in env or a .env file. The walkthrough uses ANTHROPIC_API_KEY; switch to OPENAI_API_KEY or GEMINI_API_KEY if you prefer — the workspace itself is provider-agnostic because every stage names a model_role, not a raw model.
3. A place to put the workspace. The walkthrough uses ~/work/research-brief/; adjust paths as needed.

You do not need an existing posture library. Step 1 below ships a minimal two-posture file you can copy into place.

Step 1 — Provision postures

ICM derives one posture per stage at boot, but each derived posture inherits from a base posture registered with nexus.agent.postures. Wire a minimal two-posture library so the workflow has somewhere to stand:

mkdir -p ~/.nexus/postures

~/.nexus/postures/writer_base.yaml:

name: writer_base
description: Long-form writing posture for ICM stages.
system_prompt: |
  You are a writer. Follow the stage contract exactly. Produce one
  artifact in the format the contract specifies. Do not add
  commentary outside the artifact.
allowed_tools: []
model:
  model_role: writer
default_budget:
  timeout: 180s
  max_tokens: 8000

~/.nexus/postures/judge_basic.yaml:

name: judge_basic
description: JSON-verdict judge for ICM `type: llm` predicates.
system_prompt: |
  You judge an artifact against a rubric and return a JSON verdict.
  Output only JSON conforming to the icm.judge.response schema.
allowed_tools: []
model:
  model_role: judge
default_budget:
  timeout: 60s
  max_tokens: 2000

The names matter — the workspace references them by name. The model_role fields route to whatever your core.models config maps writer and judge to. A single-provider setup with one model is fine; map both roles to the same model entry.

Step 2 — Author the workspace

Create the workspace folder. Every path inside is required unless flagged optional.

mkdir -p ~/work/research-brief/stages/01_outline
mkdir -p ~/work/research-brief/stages/02_brief
mkdir -p ~/work/research-brief/rubrics

Workspace brief

~/work/research-brief/workspace.md:

# Research Brief Pipeline

A two-stage research pipeline. Stage 1 reads a topic and produces a
five-point outline. Stage 2 expands the outline into a brief between
600 and 1200 words. The brief loops until a writer-judge agrees it
covers every outline point.

Required, non-empty. Shows up at the top of every operator prompt so the stage agent knows where it sits in the larger workflow.

Workspace defaults

~/work/research-brief/icm.yaml is optional but useful for shared defaults:

defaults:
  agent:
    posture: writer_base
    model_role: writer
  judge_posture: judge_basic

Anything a stage doesn’t override falls back here, then to plugin defaults.

Stage 1 — outline

~/work/research-brief/stages/01_outline/contract.md:

---
display: Outline the brief in five bullets
turns:
  policy: fixed
  max: 1
human_gate: end
output:
  format: text
  filename: outline.md
  validators:
    - type: native
      handler: contains_required_ids
      args:
        ids: ["1.", "2.", "3.", "4.", "5."]
inputs:
  artifacts:
    - 00_input/topic.txt
---

Read the topic in `<artifact path="00_input/topic.txt"/>`. Produce a
markdown outline with exactly five numbered points. Each point is one
sentence. No prose around the list.

What this does:

• turns.policy: fixed, max: 1 — one LLM call, no retry.
• human_gate: end — pause after the artifact is written so the human can approve before stage 2 starts.
• contains_required_ids validator — refuses any output that drops one of the five numbered points. Without until_valid semantics this just surfaces as icm.predicate.failed; we keep it for visibility.
• inputs.artifacts: 00_input/topic.txt — the reserved 00_input namespace is where io.input content lands.

Stage 2 — brief

~/work/research-brief/stages/02_brief/contract.md:

---
display: Expand the outline into a 600-1200 word brief
turns:
  policy: until_valid
  max: 3
human_gate: end
output:
  format: text
  filename: brief.md
  validators:
    - type: native
      handler: word_count_over
      args:
        min_words: 600
    - type: native
      handler: word_count_under
      args:
        max_words: 1200
loop:
  max_iterations: 3
  until:
    - type: llm
      rubric: rubrics/coverage.md
  on_exhausted: human_gate
inputs:
  artifacts:
    - 01_outline/outline.md
agent:
  budget:
    max_tokens: 4000
---

Expand the outline in `<artifact path="01_outline/outline.md"/>` into a
research brief between 600 and 1200 words. Cover every outline point.
Use a brief introduction, one paragraph per point, and a one-sentence
conclusion. Markdown allowed.

This stage exercises three loops at once:

• Turns — until_valid retries up to 3 times within an iteration if the word-count validators fail. The retry payload includes the prior attempt’s failure feedback.
• Iterations — loop.max_iterations: 3 reruns the entire stage if the coverage.md LLM rubric is not satisfied. Each iteration writes its artifact to 02_brief/iter_NN/brief.md.
• Human gate — human_gate: end pauses after the loop exits so the human can approve, restart, or fail.

Rubric

~/work/research-brief/rubrics/coverage.md:

The brief passes coverage when every numbered point in the outline is
addressed in its own paragraph. A point that is mentioned but not
expanded is a failure. Return JSON only.

The judge posture (judge_basic) sees this rubric plus the candidate artifact and must return JSON conforming to the baked-in icm.judge.response schema (verdict + score + feedback).

Step 3 — Wire the Nexus config

~/work/research-brief.yaml:

core:
  models:
    default: writer
    writer:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    judge:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 2048

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.postures
    - nexus.agent.delegate
    - nexus.control.hitl
    - nexus.memory.capped
    - nexus.workflows.icm

  nexus.agent.postures:
    scan_dirs:
      - ~/.nexus/postures

  nexus.workflows.icm:
    workspace: ~/work/research-brief
    default_judge_posture: judge_basic
    default_workflow_posture: writer_base

Note what’s not here: no nexus.agent.react, no nexus.agent.orchestrator, no separate planner. ICM is itself the agent loop — when io.input arrives it owns the conversation until the run completes.

Two config details worth double-checking before you run:

• The provider: value in each core.models entry takes the full plugin ID (nexus.llm.anthropic), not a short name like anthropic. Wrong provider IDs surface at runtime as “delegate status error: no LLM response (provider not active for this role?)”.
• Every role a posture references must be defined. The writer_base posture above declares model_role: writer, and judge_basic declares model_role: judge, so core.models must define both.

Step 4 — Run it

Start the TUI:

bin/nexus -config ~/work/research-brief.yaml

At the prompt, type a topic — the economics of mechanical keyboards, say — and hit enter.

You will see this sequence of events. The TUI renders the plan progress inline; richer UIs subscribe to the typed events documented in the plugin reference.

io.input                            { content: "the economics of mechanical keyboards" }
plan.created                        { steps: 2 (01_outline, 02_brief) }
icm.run.started                     { run_id: r_<id>, stages: 2 }
plan.progress                       { step: 01_outline, status: active }
icm.stage.started                   { stage_id: 01_outline, order: 1 }
llm.request → llm.response          (stage 1 turn 1)
icm.turn                            { stage_id: 01_outline, turn: 1 }
hitl.requested                      { action: icm.stage.end, stage_id: 01_outline }

The run pauses at hitl.requested. The TUI surfaces a prompt with three choices: continue, restart this stage, abort the run. Press continue.

hitl.responded                      { action: icm.stage.end, choice: continue }
plan.progress                       { step: 01_outline, status: completed }
icm.stage.completed                 { stage_id: 01_outline, artifact_path: ... }
plan.progress                       { step: 02_brief, status: active }
icm.stage.started                   { stage_id: 02_brief, order: 2 }
icm.stage.iteration                 { iteration: 1, max: 3 }
llm.request → llm.response          (stage 2 iter 1 turn 1)

If stage 2’s first attempt is under 600 words, the until_valid retry fires inside the same iteration. If three turns can’t satisfy the word count, the iteration writes its best attempt to 02_brief/iter_01/brief.md and the LLM judge runs against the coverage.md rubric. If the judge says no, iteration 2 starts.

What if the loop exhausts?

Likely on the first run. The coverage.md rubric in this walkthrough is deliberately strict — “every numbered point in the outline is addressed in its own paragraph” — and small judge models often read that too literally and reject an otherwise fine brief. When the loop hits loop.max_iterations: 3 without converging, on_exhausted: human_gate fires a HITL prompt:

Loop on stage Expand the outline... did not converge after 3 iterations.

  1. Accept handoff   — take the last iteration's brief as the artifact
  2. Restart loop     — wipe iter_*/, run the whole loop again
  3. Reject           — fail the stage and halt the run

Pick Accept handoff if the actual brief reads well. The judge being picky shouldn’t gate you. Before deciding, inspect the per-iteration artifacts and the judge’s verdicts on disk:

ls ~/.nexus/sessions/*/plugins/nexus.workflows.icm/r_*/02_brief/iter_*/
cat ~/.nexus/sessions/*/plugins/nexus.workflows.icm/r_*/02_brief/iter_03/brief.md.icm.json

The .icm.json sidecar carries each iteration’s verdict + feedback so you can tell whether the brief is genuinely weak or the rubric is unreasonable. If you keep hitting this every run, three knobs (in ascending effort):

1. Loosen the rubric in rubrics/coverage.md — “each outline point is addressed somewhere in the body; interleaved coverage is fine.”
2. Use a stronger judge — point the judge model_role at a more capable model. Judge calls are single-shot, so cost impact is small.
3. Drop the LLM rubric from loop.until and keep only the word-count native validators. Move the LLM check to a verifiers/ entry instead — failures get logged but don’t loop.

When the loop exits — convergent or exhausted-then-accepted — human_gate: end fires again. Approve, and:

icm.stage.completed                 { stage_id: 02_brief, iterations_run: 2, convergence_failed: false }
icm.run.completed                   { stages_run: 2, elapsed_seconds: 47 }

Step 5 — Inspect the run

Every artifact, every iteration, and every per-artifact sidecar lives in the engine session under <session>/plugins/nexus.workflows.icm/<runID>/:

~/.nexus/sessions/<sid>/plugins/nexus.workflows.icm/r_<runID>/
  .icm/
    run.json              # workspace path, started at, plan
    state.json            # per-stage progress
  00_input/
    topic.txt             # what you typed
  01_outline/
    outline.md
    outline.md.icm.json   # sidecar: writer + validator results
  02_brief/
    iter_01/
      brief.md
      brief.md.icm.json
    iter_02/
      brief.md
      brief.md.icm.json
    brief.md              # aggregate (last iteration after convergence)
    brief.md.icm.json

The sidecar files (.icm.json) record which posture wrote the artifact and which validators passed or failed. They are how downstream tooling can answer “why did stage 2 take two iterations?” without re-reading the artifact.

You can re-run the workflow on a different topic by sending another io.input. ICM creates a fresh r_<runID> directory; prior runs are untouched.

Step 6 — Watch a failure

Edit ~/work/research-brief/stages/01_outline/contract.md and change filename: outline.md to filename: outline/v1.md. Restart Nexus.

workspace load failed (1 errors):
  stages/01_outline/contract.md: output.filename must not contain path
  separators (got "outline/v1.md")

ICM aggregates every validation error into one message at boot so you can fix all of them in a single pass instead of restart-fix-restart cycles. Revert the change and ICM boots cleanly.

Other failure modes worth provoking once for muscle memory:

• Duplicate stage prefix (01_outline + 01_summary) — boot fails with “duplicate stage prefix 01”.
• A type: llm predicate with no default_judge_posture configured — runtime fails the predicate with “default_judge_posture is not configured”.
• An inputs.artifacts ref to a later stage (02_brief/... inside 01_outline/contract.md) — boot fails at load.

Each failure surfaces with the workspace-relative path + line number.

Step 7 — Iterate the workspace

The workflow you just built is the floor. Everything else ICM offers is incremental:

• Add a fan-out stage. Replace the brief stage’s monolithic output with one paragraph per outline point. Produce a topics.json from stage 1 and fan_out.source: 01_outline/topics.json from stage 2.
• Add a type: command predicate. Drop a scripts/lint_brief.sh into the workspace, mark it executable, and reference it from stage 2’s validators. The script reads the artifact on stdin and exits 0/non-0.
• Add skills. Put a shared/skills/house_voice/SKILL.md under the workspace and reference it from stages/02_brief/contract.md via inputs.skills: [house_voice]. The skill body inlines into the grounding; references load on demand via the read_skill_reference tool.
• Add verifiers. Move the rubric check out of stage 2’s loop and into a reusable verifiers/coverage.md. Stages that need coverage reference it via top-level verifiers: [coverage].

Each is one or two contract edits. The walkthrough deliberately stops short of all of them so the on-ramp stays short; the plugin reference covers each in detail.

Using the workspace builder skill

If hand-authoring contracts feels tedious, the .claude/skills/icm-workspace-builder/SKILL.md skill interviews you for the workflow shape and writes the workspace for you. Invoke it via the configured Claude Code skill surface — the skill validates each answer against the same loader rules above and produces a workspace that boots cleanly on the first try.

What you proved

• A non-trivial agent workflow — two stages, loop convergence, an LLM judge, native validators, a human gate, and a 00_input initial artifact — fit in five files under 100 lines.
• The same workflow runs in any IO surface Nexus supports (TUI, browser, oneshot, wails) without a code change. Adding a new IO means activating a new plugin, not modifying the workspace.
• The icm.* event surface plus the engine-generic plan.* events give any UI everything it needs to render workflow progress, including fan-out items and loop iterations.
• The workspace is source-control-friendly — every change to the workflow is a markdown / YAML diff you can review on a PR.

Where to go next

• Overview — the rationale, the mental model, the full list of orthogonal features.
• Plugin reference — every contract field, predicate type, event payload, and troubleshooting case.
• Configuration reference — every plugin config key with defaults.
• Postures — the base postures stages inherit from.
• HITL — how human gates route.

nexus.workflows.icm

File-driven multi-stage workflow runner. A workspace is a folder on disk: each stage is a subfolder with a YAML-fronted contract, optional grounding, optional skills, and a declared output. The plugin loads + validates the workspace at boot, registers one AgentPosture per stage, and dispatches each stage as a sub-agent via a private delegate.Runtime whenever an io.input arrives.

Source: plugins/workflows/icm/. New to ICM? Start with the overview for the rationale + mental model, then follow the end-to-end walkthrough to build a workspace from scratch. This page is the field-by-field reference. Configuration table: configuration reference.

Overview

ICM (Interpretable Context Methodology, Van Clief & McDermott, arXiv:2603.16021) treats an LLM workflow as a sequence of small, human-reviewable contracts rather than one big agent loop. The Nexus implementation reduces a workspace to disk structure: the loader parses contracts, compiles regex + gojq + JSON-schema at load time, and the orchestrator dispatches stages strictly in folder-numeric order.

What the plugin does:

• Resolves posture.registry (provided by nexus.agent.postures) at boot.
• Loads + validates the workspace; aggregates errors so the user can fix in one pass.
• Derives one AgentPosture per stage and per verifier; tools, model role, budget, and operator prompt are baked in at registration.
• Subscribes to io.input. Each input begins a fresh run with its own <runID> directory under the plugin’s data dir.
• Dispatches stages as sub-agents through a private delegate.Runtime. Stages never talk to one another — they read declared inputs and write declared outputs through the session helper.
• Emits a stage-level plan.created + plan.progress surface plus a richer icm.* event family for iteration / turn / fan-out detail.
• Routes every human checkpoint through hitl.requested; cancellation is surfaced via hitl.cancel.

What the plugin does NOT do:

• It does not directly call an LLM provider. Every model call routes through delegate (sub-agents) or through the configured judge posture (LLM predicates).
• It does not mutate the workspace. Artifacts live in the session directory.
• It does not auto-discover skills. Skills are loaded from the stage-local skills/ and shared/skills/ folders inside the workspace.

Quick start

1. Add the plugin to plugins.active and point it at a workspace.

plugins:
  active:
    - nexus.agent.postures
    - nexus.control.hitl
    - nexus.workflows.icm

  nexus.workflows.icm:
    workspace: ~/work/screenplay-pipeline
    default_judge_posture: judge_strict
    default_workflow_posture: workflow_base

2. Scaffold the workspace. Below is a working three-stage screenplay pipeline. Every file shown is necessary; everything else is optional.

~/work/screenplay-pipeline/
  workspace.md
  stages/
    01_outline/
      contract.md
    02_script/
      contract.md
    03_review/
      contract.md

workspace.md — required, non-empty. Describes the workflow at the highest level. Surfaces to the operator prompt and to anyone reading the folder.

# Screenplay Pipeline

A three-stage pipeline that converts a one-line premise into a short-form
screenplay: outline, draft, peer review. Each stage hands a single artifact
to the next; humans gate the start and end of every stage.

stages/01_outline/contract.md — YAML frontmatter then process body. The body is rendered into the operator system prompt for this stage.

---
display: Outline a three-act structure
turns:
  policy: fixed
  max: 1
human_gate: end
output:
  format: text
  filename: outline.md
inputs:
  artifacts:
    - 00_input/premise.txt
agent:
  model_role: writer
  budget:
    max_tokens: 4000
---

Read the premise in `<artifact path="00_input/premise.txt"/>`. Write a
three-act outline with beat counts per act. No prose. Markdown headings
allowed.

stages/02_script/contract.md — consumes the outline; loops up to three times until the validator passes.

---
display: Draft the screenplay
turns:
  policy: until_valid
  max: 3
human_gate: end
output:
  format: text
  filename: script.md
  validators:
    - type: native
      handler: word_count_over
      args: { min_words: 800 }
    - type: native
      handler: word_count_under
      args: { max_words: 2400 }
inputs:
  artifacts:
    - 01_outline/outline.md
agent:
  model_role: writer
  budget:
    max_tokens: 8000
---

Expand the outline in `<artifact path="01_outline/outline.md"/>` into a
screenplay between 800 and 2400 words. Use industry-standard formatting
(INT./EXT., character names in caps before dialogue).

stages/03_review/contract.md — judges the script with an LLM rubric.

---
display: Peer review the screenplay
turns:
  policy: fixed
  max: 1
human_gate: none
output:
  format: text
  filename: review.md
  validators:
    - type: llm
      rubric: rubrics/review_quality.md
      model: judge_strict
inputs:
  artifacts:
    - 02_script/script.md
agent:
  model_role: reviewer
---

Read the script in `<artifact path="02_script/script.md"/>`. Produce a
review covering structure, character voice, dialogue, and pacing. Be
specific; cite scene numbers.

3. Start Nexus. Send the initial premise via io.input (the engine writes it to <runID>/00_input/premise.txt). ICM creates the run, dispatches stage 01, gates at its end via HITL, then continues.

Workspace layout

The workspace is the source of truth for the workflow; artifacts are the source of truth for the run. They live in different directories.

<workspace>/
  icm.yaml                  optional — layer name overrides + defaults
  operator.md               optional — Layer 0 operator prompt template
  operator.overlay.md       optional — appended to operator body
  workspace.md              required — high-level workflow description
  stages/
    01_<slug>/
      contract.md           required per stage
      grounding/            optional — reference files inline at dispatch
      skills/<name>/        optional — stage-local skills
    02_<slug>/...
  shared/
    grounding/              optional — cross-stage reference files
    skills/<name>/          optional — workspace-wide skills
  schemas/                  optional — JSON schemas referenced from contracts
  scripts/                  optional — command-predicate executables
  rubrics/                  optional — LLM-predicate rubric files
  verifiers/                optional — verifier stage definitions
  inputs/                   optional — initial-run input fixtures

Folder-name rules enforced by the loader:

• Stage folders match ^\d+_[a-z0-9_]+$. Execution order is the numeric prefix, sorted numerically (so 9_x runs before 10_x).
• 00_input is reserved — it names the synthetic input stage in artifact refs. Declaring a stage folder named 00_input is a load error.
• Duplicate numeric prefixes (05_foo + 05_bar) are rejected: execution order would be ambiguous.
• A stage folder containing an artifacts/ subdirectory is rejected. Artifacts live in the session, not the workspace.

icm.yaml

icm.yaml is optional. When present it overrides any subset of the layer filenames and supplies workspace-level defaults that stages inherit unless they override.

# All sections are optional.
layer_names:
  operator: operator.md       # default
  workspace: workspace.md     # default
  contract: contract.md       # default
  grounding: grounding        # default (folder name)

defaults:
  turn_policy: fixed          # fixed | until_valid | until_human_approves
  human_gate: none            # none | start | end | both
  on_error: halt              # halt | retry | human_gate
  judge_posture: judge_basic  # used for type: llm predicates with no `model:`
  agent:
    posture: workflow_base    # base posture each stage inherits
    model_role: writer
    tools: [read_file]
    budget:
      timeout_seconds: 120
      max_tokens: 8000
      max_tool_calls: 16
    max_recursion_depth: 3

operator:
  overlay: |
    Always cite section numbers when referencing scripts.

The judge posture and base workflow posture can also be configured at the plugin level (default_judge_posture, default_workflow_posture). The plugin-level keys win when both are set.

Stage contracts

Each stage is a single file: contract.md. It is YAML frontmatter (between --- lines) followed by a markdown body. The body is the stage’s role instructions — it is rendered into the operator system prompt at dispatch time. Verifiers may be a single .md file directly under verifiers/ with the same shape.

Frontmatter

Output spec

output declares the file the stage writes and any validators that run against it. Validators that fail under turns.policy: until_valid trigger a retry; under any other policy they surface as icm.predicate.failed and (depending on on_error) may halt the run.

output:
  format: text                  # text (default) | json
  persist: file_ref             # file_ref (default) | context | both
  filename: outline.md          # required; no path separators
  schema: schemas/outline.json  # required when format: json
  validators:
    - type: regex
      pattern: '^# '
      anchor: first_line
      message: "Outline must begin with an H1."

persist: file_ref writes the artifact and references it by logical ref downstream. context keeps the body in conversation context only (use sparingly — large bodies bloat downstream turns). both does both. JSON outputs always parse + validate against schema before the validators run.

Inputs

inputs declares what files the stage reads. The loader verifies each path exists at boot.

inputs:
  grounding:
    - style_guide.md            # under <stage>/grounding/
    - examples/sample_act_1.md
  shared_grounding:
    - house_voice.md            # under shared/grounding/
  artifacts:
    - 00_input/premise.txt      # initial input from io.input
    - 01_outline/outline.md     # prior stage's declared output
  skills:
    - markdown-screenplay       # resolved through skill precedence

Artifact refs are validated cross-stage at load: the referenced stage must run before this one, and the filename must match that stage’s output.filename. The reserved 00_input/... prefix points at files copied into the session by io.input (or by workspace_inputs_dir).

Inline-vs-ref selection happens at dispatch: artifacts under inline_artifact_limit_bytes (default 32 KiB) inline as <artifact>; larger or binary content emits <artifact_ref/> and the LLM picks it up via read_file.

Agent block (posture, model_role, tools, budget)

Stage-level agent fields override workspace defaults; absent fields fall through to defaults, then to the registry defaults at runtime.

agent:
  posture: writer_posture       # optional; existence checked at runtime
  model_role: writer            # role into the engine model registry
  tools:                        # AllowedTools for this stage's posture
    - read_file
    - run_code
  prompt_overlay: |             # appended to operator body for this stage
    Be concise. Bullet lists over prose.
  budget:
    timeout_seconds: 120
    max_tokens: 8000
    max_tool_calls: 16
  max_recursion_depth: 3        # caps sub-agent nesting

posture is a base posture from nexus.agent.postures. ICM derives a per-stage posture on top of it, layering operator prompt + role body + overlay + tools + budget + skill-tool registration. The derived posture name appears as icm.<runID>.<stage_id> in icm.stage.started events.

auto_include_skill_reference_tool: true (the default) appends the read_skill_reference tool to any stage that declares inputs.skills. For multi-instance setups the tool name becomes read_skill_reference_<suffix> so two ICM instances can coexist in one engine without colliding.

Turns

Turns control the inner loop within a single stage invocation.

turns:
  policy: until_valid      # fixed | until_valid | until_human_approves
  max: 3                   # default 1 for fixed, 3 for until_valid

• fixed runs max turns unconditionally. Most common.
• until_valid retries while any validator fails. Requires at least one output.validators entry — the loader rejects the contract otherwise.
• until_human_approves loops while the human selects continue at the per-turn HITL gate (icm.stage.turn). Free-text feedback from the human arrives in the next turn’s <previous_attempt><human_feedback>.

Human gates

Human gates fire at stage boundaries. They are independent from per-turn loop gates and per-iteration loop predicates.

human_gate: end           # none (default) | start | end | both

start emits a HITL icm.stage.start action before the stage’s first dispatch; end emits icm.stage.end after the artifact is written. The end gate offers a restart choice that wipes the stage directory and re-runs (subject to loop_max_restarts).

For looping stages the gate fires at the bounds of the entire stage, not per iteration. Use a type: human predicate inside loop.until if you need per-iteration human review.

Loops

Loops drive convergence: the entire stage runs as a fresh invocation each iteration, with prior-iteration artifact + exit failures included in the next payload.

loop:
  max_iterations: 5
  until:
    - type: native
      handler: word_count_over
      args: { min_words: 1200 }
    - type: llm
      rubric: rubrics/coherence.md
  on_exhausted: human_gate     # human_gate (default) | error

until predicates run after each iteration’s artifact is written. All must pass for the loop to exit. When max_iterations runs out without convergence, on_exhausted: human_gate raises an icm.loop.exhausted HITL request offering accept / restart / error; on_exhausted: error halts the stage immediately. Restart-loop count is bounded globally by the plugin’s loop_max_restarts config.

Iteration artifacts persist under <stageDir>/iter_NN/. The aggregate <stageDir>/<filename> is written from the last iteration after convergence (or the last attempt if a human accepts).

Fan-out

Fan-out runs the stage once per item in a JSON list. Distinct from loop: loops are convergence-driven; fan-outs are data-driven. They compose — a stage with both fans out per item and each item independently iterates.

fan_out:
  source: 02_research/topics.json   # earlier stage's JSON output
  jsonpath: .topics                 # optional gojq expression; default "."
  item_var: topic                   # name surfaced into payload's <fan_out_item>
  item_id: .slug                    # optional gojq for per-item folder name
  max_parallel: 4                   # default 1
  on_item_failure: continue         # continue (default) | halt

source must resolve to a JSON artifact produced by an earlier stage (or to 00_input/...). The orchestrator parses it, applies jsonpath, and expects an array; non-arrays surface as a stage error. Each item writes under <stageDir>/items/<itemID>/<filename>, and the orchestrator emits an icm.fanout.item event at each item lifecycle boundary (active → completed | failed).

The aggregate output filename is also written at the plain stage path so downstream stages can reference it via the normal <stage_id>/<filename> ref. Aggregation is a flat join of every item’s artifact for text outputs and a JSON array for JSON outputs.

Verifiers

Verifiers are reusable stage-shaped contracts kept under verifiers/. A stage references them by ID via the top-level verifiers: list. The loader validates that every referenced ID exists. They run after the stage’s own validators and may declare their own posture, tools, and predicates.

# stages/03_review/contract.md
---
verifiers:
  - house_voice_check
  - structural_balance
---

# verifiers/house_voice_check.md
---
display: House voice check
output:
  format: text
  filename: house_voice.md
  validators:
    - type: llm
      rubric: rubrics/house_voice.md
inputs:
  artifacts:
    - 02_script/script.md
---

Compare the script against the house style guide and flag violations.

Predicates

A predicate is the unified shape used by output.validators, loop.until, and verifier outputs. The type field discriminates; the loader compiles regex / gojq / JSON-schema at load time and rejects malformed predicates before boot completes.

schema

JSON-schema validation against the stage output.

- type: schema
  schema: schemas/outline.json
  name: outline_shape          # optional; default "<type>_<index>"

Path resolves against the workspace root. The loader reads the file, parses it as JSON, and compiles it as draft-2020 to catch malformed schemas at boot.

regex

Regex match against text output.

- type: regex
  pattern: '^FADE IN:'
  anchor: first_line           # whole (default) | first_line | last_line
  message: "Screenplay must open with FADE IN:."

The loader compiles the pattern at load time; failures surface in the load error aggregate. message populates the predicate’s Feedback field, so LLMs retrying under until_valid see your authored guidance.

native (builtin handlers)

Native predicates dispatch to a Go handler registered in the plugin. ICM ships four built-ins.

- type: native
  handler: contains_required_ids
  args:
    ids: [PROTAGONIST, ANTAGONIST]
    case_insensitive: false

command

Shell-out predicate. The script reads the artifact on stdin and exits 0 to pass, non-zero to fail. Stderr becomes the feedback.

- type: command
  run: scripts/lint_screenplay.sh
  timeout_seconds: 30          # optional; falls back to plugin default

The loader resolves run against the workspace root, verifies the file exists, and verifies it has the executable bit set. Scripts run inside the engine sandbox (the same engine.Sandbox injected into the plugin), so the workflow’s command surface is constrained by the host’s sandbox policy.

llm

LLM judge predicate. The judge sees the artifact and a rubric, and returns a structured verdict.

- type: llm
  rubric: rubrics/coherence.md
  model: judge_strict          # optional posture override
  name: coherence_check        # optional

model names a registered posture (not a raw model). When omitted, the plugin uses default_judge_posture from its config. Workspaces that use type: llm predicates without setting either are rejected at runtime with default_judge_posture is not configured.

The judge posture must return JSON conforming to a baked-in judge schema (verdict + score + feedback). The plugin registers this schema at boot.

human

In-loop human predicate. The orchestrator emits a HITL request and waits. This is the right tool when “looks good” is the gating criterion for convergence.

- type: human
  prompt: "Does this iteration meet the brief?"
  require_feedback_on_continue: true   # optional

continue (without selecting the explicit pass / fail choice) under turns.policy: until_human_approves advances to the next turn and routes the human’s free-text response into <previous_attempt><human_feedback>.

Skills

Skills are bundles a stage can load at dispatch. Each skill is a folder containing SKILL.md (YAML frontmatter name + description, then a body) and an optional references/ subfolder with deferred-load files.

Discovery is workspace-scoped — ICM does not use the global nexus.skills scan_paths. The loader walks two locations in precedence order:

1. stages/<NN_slug>/skills/<name>/ — stage-local (wins on conflict).
2. shared/skills/<name>/ — workspace-wide.

Reference shape:

shared/skills/markdown-screenplay/
  SKILL.md
  references/
    fade_transitions.md
    standard_formatting.md

SKILL.md:

---
name: markdown-screenplay
description: How to format screenplays in markdown for downstream parsing.
---

Always use INT./EXT. headers. Capitalize character names before dialogue.
See references/standard_formatting.md for the full house spec.

Stages opt in via inputs.skills. At dispatch the orchestrator inlines SKILL.md body into <grounding> and registers the read_skill_reference[_<suffix>] tool so the agent can pull a specific reference on demand. References are NOT inlined by default — that is the point of progressive disclosure.

XML payload reference

Each turn assembles a single XML user message. The shape is uniform across stage modes; loop iterations and fan-out items add their own elements but the surrounding skeleton is invariant. Inline blocks contain the content; _ref variants point at filesystem paths.

<icm_turn stage="02_script" turn="1" iteration="3" run_id="r_abc">
  <grounding>
    <skill name="markdown-screenplay" source="workspace">
      <description><![CDATA[How to format screenplays...]]></description>
      <body><![CDATA[Always use INT./EXT. headers...]]></body>
      <references_available>
        <ref path="standard_formatting.md" description="House spec"/>
      </references_available>
    </skill>
    <file path="style_guide.md"><![CDATA[...]]></file>
    <shared_file path="house_voice.md"><![CDATA[...]]></shared_file>
  </grounding>
  <layer_data>
    <artifact path="01_outline/outline.md"><![CDATA[# Act I...]]></artifact>
    <artifact_ref path="01_outline/huge.json" size_bytes="48000"/>
    <fan_out_item key="topic"><![CDATA[{"slug":"act1","title":"Setup"}]]></fan_out_item>
  </layer_data>
  <previous_attempt turn="2">
    <output><![CDATA[FADE IN: ...]]></output>
    <validator_feedback>
      <failure name="word_count_over" type="native">
        word count 420 is not strictly greater than min_words=800
      </failure>
    </validator_feedback>
    <human_feedback><![CDATA[Tighten Act 2.]]></human_feedback>
  </previous_attempt>
  <previous_iteration index="2">
    <artifact path="02_script/iter_02/script.md"><![CDATA[...]]></artifact>
    <exit_failures>
      <failure name="coherence_check" type="llm">Act II drifts.</failure>
    </exit_failures>
  </previous_iteration>
  <instructions><![CDATA[Expand the outline...]]></instructions>
</icm_turn>

Notes:

• _ref elements appear when an artifact exceeds inline_artifact_limit_bytes, fails resolution (missing="true"), or contains non-UTF-8 bytes.
• Passing validator / exit-condition results are filtered out — the agent only sees actionable failures.
• The instructions block contains the stage contract body verbatim.

Plan + progress events

ICM emits the engine’s generic plan.created once at run start and plan.progress after each stage transition, so generic UIs that render a plan see the workflow without ICM-specific knowledge. On top of that, the following typed events surface richer detail. All payloads carry a _schema_version field and live in plugins/workflows/icm/icmtypes/types.go.

In addition, with emit_progress_thinking_steps: true (default) ICM emits thinking.step events tagged Phase="icm.<stage_id>" so UIs that render thinking surfaces show inline stage transitions without subscribing to the typed event family.

UI feedback surfaces

Both bundled IO plugins (nexus.io.tui, nexus.io.browser) wire ICM progress directly so users see real-time feedback during long runs without enabling extra observers:

• Scrollback (thinking-step stream) — every icm.* event is formatted into a one-line audit row via the helpers in plugins/workflows/icm/icmtypes/format.go and rendered alongside other thinking steps. Long runs leave a complete trail of stage transitions, iteration retries, predicate failures, and fan-out item ticks.
• Dedicated workflow panel — the generic workflow.progress event drives a sticky surface (TUI right-rail panel, browser chip indicator) that updates in place: workflow name, stage X/Y, iter N/M, turn N/M, fan-out items done/total, status badge, and the names of any predicate failures from the last iteration.

The two surfaces complement each other: scrollback for “what happened”, dedicated panel for “where are we now”.

Session layout + artifacts

Every run owns a directory under <dataDir>/<runID>/. dataDir is the plugin’s per-session data dir provided by the engine, so multiple concurrent runs do not collide.

<engine_session>/plugins/<instance>/<runID>/
  .icm/
    run.json              run metadata: workspace path, started at, plan
    state.json            mutable per-stage progress (updated as stages run)
  00_input/
    premise.txt           copied from io.input.Content or workspace_inputs_dir
  01_outline/
    outline.md
    outline.md.icm.json   per-artifact sidecar: writer, validators, schema
  02_script/
    iter_01/
      script.md
      script.md.icm.json
    iter_02/
      script.md
      script.md.icm.json
    script.md             aggregate (last iteration after convergence)
    script.md.icm.json
  03_review/
    items/                fan-out items live here
      act1/
        review.md
      act2/
        review.md
    review.md             flat aggregate written for downstream refs
    review.md.icm.json

Logical refs (<stage_id>/<filename> in inputs.artifacts or fan_out.source) resolve as follows:

1. Plain stage path wins when present.
2. Otherwise the highest-numbered iter_NN/<filename> wins (numeric sort — iter_10 beats iter_9).
3. For fan-out stages, the aggregate at the plain stage path is what downstream stages see; per-item files are addressable only inside the fan-out itself.

<instance> is nexus.workflows.icm for the default instance, or the instance-suffixed ID (nexus.workflows.icm.script, etc.) for additional instances. The engine maps slashes in instance IDs to dots when computing the on-disk directory.

Multi-instance setup

Multiple ICM instances coexist in one engine via the nexus.workflows.icm/<suffix> form. Each instance pins its own workspace, judge posture, and tool namespace.

plugins:
  active:
    - nexus.agent.postures
    - nexus.control.hitl
    - nexus.workflows.icm/script
    - nexus.workflows.icm/research

  nexus.workflows.icm/script:
    workspace: ~/work/screenplay-pipeline
    default_judge_posture: judge_strict
    default_workflow_posture: writer_base

  nexus.workflows.icm/research:
    workspace: ~/work/topic-research
    default_judge_posture: judge_basic
    cache_size: 64        # research is read-heavy; caching is safe here
    auto_include_skill_reference_tool: false

Per-instance details:

• The skill-reference tool name is namespaced per instance: read_skill_reference_script, read_skill_reference_research. Default instances (no suffix) get the unsuffixed read_skill_reference.
• Derived posture names embed the instance suffix so the registry stays unambiguous.
• Each instance carries a distinct <runID> namespace and a distinct data-dir prefix.
• The icm_validate LLM tool is similarly suffixed (icm_validate_script, icm_validate_research).

A single judge / human-gate plugin services all instances. The HITL request’s RequesterPlugin field carries the suffixed instance ID so operators can route gates per workflow.

Troubleshooting

Workspace fails to load.

ICM aggregates every validation error before returning, so the boot log shows them as a bulleted list (workspace load failed (N errors):). Common causes:

• Duplicate numeric prefixes (01_outline + 01_intro) — execution order is ambiguous; renumber one.
• Stage folder named 00_input — reserved name; rename.
• output.filename containing / — must be a bare filename; the loader builds the path.
• inputs.artifacts ref to a later stage — refs must point at the reserved 00_input or at a stage with a lower numeric prefix.
• output.format: json without output.schema — JSON outputs always require a schema.
• turns.policy: until_valid with empty output.validators — without validators there is nothing to retry against.
• type: command predicate pointing at a non-executable script — chmod +x the file.

The aggregated error message includes the exact file path and line number when applicable.

Stage halts with default_judge_posture is not configured.

A type: llm predicate ran and the plugin had no posture to dispatch the judge against. Wire a judge in one of two ways:

# Plugin-level fallback (every llm predicate without an explicit `model:`).
plugins:
  nexus.workflows.icm:
    default_judge_posture: judge_basic

# Per-predicate override.
output:
  validators:
    - type: llm
      rubric: rubrics/quality.md
      model: judge_strict

The named posture must be registered with nexus.agent.postures (typically via its scan_dirs config) before ICM boots.

Loop never converges.

loop.max_iterations is the per-pass cap. When it runs out under on_exhausted: human_gate (the default), the human is offered accept / restart / error. restart wipes the stage directory and reruns from iteration 1. The plugin’s loop_max_restarts caps the number of restarts per run (default 3, 0 for unlimited) so a never-converging workspace cannot spin forever. If you see repeated restarts, the root cause is usually:

• Exit conditions that the writer model cannot satisfy (rubric too tight, or contradicts an earlier rubric).
• Operator prompt that does not reference the prior-iteration failure block. The default operator template handles this; custom operators must read <previous_iteration><exit_failures> and address each failure.
• on_exhausted: error makes failures loud and immediate — useful in CI.

Fan-out source doesn’t resolve.

The loader validates fan_out.source shape and that the named stage runs earlier, but the artifact filename is checked against the prior stage’s declared output.filename. Two common mistakes:

• Filename typo (topics.json vs topic.json) — change one or the other.
• Source stage’s output.format is text; fan-out always parses JSON. Make the producer JSON or change the consumer.

At runtime, if the source produces a non-array (or the jsonpath lands on a non-array), the stage emits icm.stage.failed with a reason of fan_out.source did not resolve to an array. Inspect the source artifact in the session directory directly — the orchestrator never modifies it.

Run cancelled mid-HITL.

When the run context cancels while ICM is blocked on a HITL response, the plugin emits hitl.cancel with the pending request ID so the UI can clear its pending prompt. The run then completes with icm.run.halted, cancelled: true.

See also

• configuration reference — every config key with defaults.
• agent postures — base postures stages inherit from; required at boot.
• HITL — the registry ICM routes gates through.
• skills — the engine-level skill machinery; ICM’s per-workspace skills are independent but share the same SKILL.md shape.
• plugins/workflows/icm/schema.json — JSON schema for the config block.
• plugins/workflows/icm/workspace/types.go — full Go type model.
• plugins/workflows/icm/icmtypes/types.go — icm.* event payload structs.

Plugin Overview

Nexus ships with 21 built-in plugins organized into categories. Activate only the plugins you need — the engine handles dependency resolution and boot ordering automatically.

Plugin Categories

Choosing Plugins

A minimal useful agent needs at least:

• One I/O plugin — How the user interacts (nexus.io.tui or nexus.io.browser)
• One LLM provider — Which AI model to use (nexus.llm.anthropic, nexus.llm.openai)
• One agent — The reasoning strategy (nexus.agent.react is the most common)

Everything else is optional. Add tools to give the agent capabilities, memory to persist conversations, planners for complex task decomposition, and observers for debugging.

Common Combinations

Conversational Agent (no tools)

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.memory.capped

Coding Assistant

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.control.hitl
  - nexus.skills
  - nexus.memory.capped

Planned Coding Workflow

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.planner.dynamic
  - nexus.observe.thinking
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.control.hitl
  - nexus.skills
  - nexus.memory.capped
  - nexus.memory.compaction

Multi-Agent Orchestration

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.orchestrator
  - nexus.agent.subagent
  - nexus.agent.react
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.memory.capped
  - nexus.control.cancel

Plugin Documentation Format

Each plugin page in this reference covers:

• ID — The plugin identifier used in config
• Purpose — What it does and when to use it
• Configuration — All config options with types and defaults
• Events — What it subscribes to and emits
• Dependencies — Other plugins it requires
• Usage examples — Config snippets and common patterns

Agent Plugins

Agents are the brain of a Nexus harness. They receive user input, orchestrate LLM calls and tool usage, and produce output. You must activate exactly one agent plugin (unless using the orchestrator pattern, which depends on subagent + react).

Available Agents

Choosing an Agent

• ReAct — Best for most use cases. Simple, flexible, supports planning as an optional phase. Start here.
• Plan & Execute — When you want a mandatory planning phase with explicit step tracking and optional replanning on failure.
• Orchestrator — For complex tasks that benefit from parallel decomposition across multiple subagent workers.
• Subagent — Not used standalone. Provides a spawn_subagent tool that other agents (or the orchestrator) can invoke.

Agent + Planner Interaction

The ReAct and Plan & Execute agents can optionally integrate with planners:

• ReAct + Dynamic Planner — LLM generates a plan before the agent starts iterating. The plan is injected into the system prompt.
• ReAct + Static Planner — Fixed steps from config are injected into the system prompt.
• Plan & Execute — Has its own built-in planning phase (uses LLM directly, no separate planner plugin needed).

ReAct Agent

The ReAct (Reason + Act) agent is the default and most commonly used agent strategy. It runs an iterative loop: send messages to the LLM, parse the response, execute any tool calls, feed results back, and repeat until the LLM produces a final answer.

Details

Configuration

Iteration limits are not an agent setting — enforce them with nexus.gate.endless_loop (default cap: 25 LLM calls per turn).

Events

Subscribes To

Emits

How It Works

1. User sends a message → io.input arrives
2. Agent builds the message history and sends llm.request
3. LLM responds with text and/or tool calls
4. If tool calls exist:
   • Agent emits before:tool.invoke (can be vetoed for approval)
   • Agent emits tool.invoke for each tool call
   • Tool plugin emits before:tool.result (vetoable — gates can inspect/block)
   • Waits for tool.result events
   • Loops back to step 2 with tool results appended
5. If no tool calls, the LLM’s response is the final answer → io.output
6. Stops when nexus.gate.endless_loop vetoes the next llm.request (default: 25 calls per turn)

Planning Integration

When planning: true, the agent requests a plan before starting iteration:

1. Agent emits plan.request with the user’s input
2. A planner plugin (dynamic or static) generates a plan
3. Agent receives plan.result
4. The plan steps are injected into the system prompt as context
5. Normal ReAct iteration begins with the plan as guidance

Tool Choice

Controls whether the LLM must use tools. Supports static defaults, per-iteration sequences, and dynamic overrides.

Static default (shorthand or object)

nexus.agent.react:
  tool_choice: required              # shorthand: force tool use every iteration
  # or
  tool_choice:
    mode: auto                       # "auto" | "required" | "none" | "tool"
    name: shell                      # only when mode == "tool"

Per-iteration sequence

nexus.agent.react:
  tool_choice:
    sequence:
      - mode: required               # iteration 1: force tool use
      - mode: tool                   # iteration 2: force specific tool
        name: shell
      - mode: auto                   # iteration 3+: last entry repeats

Dynamic override

Any plugin can emit agent.tool_choice with AgentToolChoice{Mode, ToolName, Duration}:

• Duration: "once" — applies to next LLM request only, then reverts to config default.
• Duration: "sticky" — persists until replaced by another override. Reset on new turn.

Example Configuration

nexus.agent.react:
  planning: true
  model_role: balanced
  system_prompt: |
    You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

    ## Guidelines

    1. Always explain your reasoning before making changes
    2. Run tests after modifications to verify correctness
    3. Prefer minimal, targeted changes over broad refactors
    4. Ask for clarification when requirements are ambiguous
    5. Read files in chunks 16kb or less
    6. Follow the existing code style and conventions of the project
  tool_choice:
    sequence:
      - mode: required
      - mode: auto

Tool Discovery

The agent discovers tools dynamically through tool.register events. When tool plugins initialize, they emit their tool definitions. The agent collects these and includes them in every llm.request.

This means adding a tool to your agent is as simple as adding it to the active list — no explicit wiring needed.

Plan & Execute Agent

The Plan & Execute agent separates planning from execution. It delegates plan generation to whichever planner plugin is active on the bus (e.g. nexus.planner.dynamic or nexus.planner.static) while retaining full control of the surrounding flow: phase transitions, approval, step execution, re-planning on failure, and final synthesis.

This means you can change how plans are produced — LLM-driven, static, role-specialized, or a custom planner you build — without modifying the agent.

Details

Configuration

Per-step iteration limits are enforced by nexus.gate.endless_loop, not by planexec itself. Plan-step counts are managed by the planner that produces plan.result.

Plan-generation options (model, prompt, max steps, planner-side approval) now live on the planner plugin itself. See the planner docs.

Approval layers

Two independent approval gates may apply:

1. Planner-side — e.g. nexus.planner.dynamic supports always / auto / never. When the planner denies or the user rejects, the planner emits plan.result with Approved: false and planexec will end the turn.
2. planexec-side — even when the planner returns an approved plan, setting planexec’s own approval: always will emit a second plan.approval.request before execution begins.

To avoid double-prompting, pick one side to own approval and set the other to never.

Events

Subscribes To

Emits

Phases

The agent transitions through these phases:

stateDiagram-v2
    direction LR
    [*] --> idle
    idle --> planning: agent.turn.start
    planning --> awaiting_approval: approval == always
    planning --> executing: approval skipped
    awaiting_approval --> executing: user approves
    awaiting_approval --> idle: user rejects
    executing --> executing: next step
    executing --> planning: step failed + replan_on_failure
    executing --> synthesizing: all steps complete
    synthesizing --> idle: agent.turn.end
    idle --> [*]

1. Planning — Emits plan.request; waits for plan.result from the active planner.
2. Awaiting Approval — Only entered if planexec’s own approval: always.
3. Executing — Runs each step sequentially, with its own message history and iteration budget.
4. Synthesizing — After all steps complete, generates a summary of results.

Replanning

When replan_on_failure: true and a step fails, the agent:

1. Collects the status and results of completed/failed/pending steps.
2. Emits a fresh plan.request whose Input contains the original request plus a structured summary of what happened.
3. Waits for the new plan.result and resumes execution with the revised plan.

Because re-planning is just another plan.request, any planner implementation automatically participates.

Example Configuration

plugins:
  active:
    - nexus.agent.planexec
    - nexus.planner.dynamic    # any planner plugin works
    # ...

  nexus.agent.planexec:
    execution_model_role: balanced
    replan_on_failure: true
    approval: never
    system_prompt: |
      You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

      ## Guidelines

      1. Always explain your reasoning before making changes
      2. Run tests after modifications to verify correctness
      3. Prefer minimal, targeted changes over broad refactors
      4. Ask for clarification when requirements are ambiguous
      5. Read files in chunks 16kb or less
      6. Follow the existing code style and conventions of the project

  nexus.planner.dynamic:
    model_role: reasoning
    max_steps: 8
    approval: auto

When to Use

Choose Plan & Execute over ReAct when:

• Tasks are complex and benefit from upfront decomposition.
• You want explicit step tracking and progress visibility.
• You want to swap planning strategies (LLM, static, domain-specific) without touching the agent.
• You need a different model tier for planning vs. execution.

Subagent

The subagent plugin provides a tool that spawns independent child agents. Other agents (or the orchestrator) can invoke it to delegate subtasks. Each instance can be configured with its own system prompt, tool name, and model role.

Details

Configuration

Tool Definition

The subagent registers a tool (default name: spawn_subagent) with these parameters:

Events

Subscribes To

Emits

Multi-Instance Usage

Each instance creates its own spawn tool. Use instance suffixes to create specialized spawners:

plugins:
  active:
    - nexus.agent.react
    - nexus.agent.subagent/researcher
    - nexus.agent.subagent/writer

  nexus.agent.subagent/researcher:
    max_iterations: 15
    model_role: reasoning
    system_prompt: "You are a research specialist. Gather information thoroughly."
    tool_name: spawn_researcher

  nexus.agent.subagent/writer:
    max_iterations: 10
    model_role: balanced
    system_prompt: "You are a technical writer. Produce clear, concise documentation."
    tool_name: spawn_writer

The parent agent will see two tools: spawn_researcher and spawn_writer.

Subagent Events

When a subagent runs, these events are emitted:

Example

A ReAct agent with a research subagent:

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.agent.subagent
    - nexus.memory.capped

  nexus.agent.react:
    max_iterations: 10
    system_prompt: "You can delegate research tasks using the spawn_subagent tool."

  nexus.agent.subagent:
    max_iterations: 10
    system_prompt: "Take in the user input and summarize the problem."

Orchestrator

The orchestrator implements a manager-worker pattern. It uses an LLM to decompose complex tasks into subtasks, then dispatches them to parallel subagent workers. Results are synthesized into a final response.

Details

Configuration

Events

Subscribes To

Emits

Phases

stateDiagram-v2
    direction LR
    [*] --> idle
    idle --> decomposing: agent.turn.start
    decomposing --> dispatching: subtasks ready
    dispatching --> executing: workers spawned
    executing --> executing: subtask completed
    executing --> synthesizing: all subtasks done
    synthesizing --> idle: agent.turn.end
    idle --> [*]

    note right of decomposing
        orchestrator LLM
        breaks task into
        subtasks
    end note
    note right of executing
        parallel workers
        respect max_workers
    end note

1. Decomposing — The orchestrator LLM breaks the task into subtasks with descriptions and optional dependencies
2. Dispatching — Subtasks are queued and sent to subagent workers (respecting max_workers concurrency)
3. Executing — Workers run in parallel; the orchestrator tracks progress and collects results
4. Synthesizing — All results are gathered and the synthesis LLM produces a unified response

Subtask Dependencies

The orchestrator can recognize dependencies between subtasks. Dependent subtasks wait until their prerequisites complete before dispatching.

Failure Handling

• fail_fast: false (default) — Other workers continue even if one fails. Failed results are included in synthesis.
• fail_fast: true — All remaining workers are cancelled when any worker fails.

Example Configuration

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.orchestrator
    - nexus.agent.subagent
    - nexus.agent.react
    - nexus.tool.shell
    - nexus.tool.file
    - nexus.memory.capped
    - nexus.control.cancel

  nexus.agent.orchestrator:
    max_workers: 3
    max_subtasks: 6
    orchestrator_model_role: reasoning
    worker_model_role: balanced
    synthesis_model_role: balanced
    fail_fast: false

  nexus.agent.subagent:
    max_iterations: 10

When to Use

The orchestrator is ideal for:

• Complex tasks that naturally decompose into independent subtasks
• Research across multiple topics that can be explored in parallel
• Code analysis across multiple files or modules simultaneously
• Any task where parallel execution significantly reduces total time

Posture Registry (nexus.agent.postures)

Loads AgentPosture YAML files from disk and exposes the posture.registry capability that nexus.agent.delegate consumes. fsnotify watches every configured directory for live edits; active sub-sessions keep their old posture, new invocations resolve the new one.

See the Postures architecture page for the full conceptual model and delegation for how the registry is consumed.

Details

Configuration

If scan_dirs is empty, no postures load; the plugin still advertises the capability so nexus.agent.delegate boots cleanly (delegate calls will fail with posture: not found).

Posture YAML

Each file in a scan dir is parsed as a single AgentPosture. The filename (minus extension) supplies the name if the YAML omits one.

name: analyst
description: deep reader; quotes sources verbatim
system_prompt: |
  You are a careful analyst. Cite sources by URL. Be concise.
allowed_tools:
  - web_search
  - web_fetch
  - read_pdf
model:
  model_role: reasoning
  max_tokens: 4000
default_budget:
  timeout: 60s
  max_tokens: 50000
  max_tool_calls: 20
max_recursion_depth: 2

A 16-character content hash lands on Version, included automatically in delegate cache keys so any edit invalidates stale entries.

Events

Emits

See events reference for payload shape.

Subscribes To

None.

Example

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.agent.postures
    - nexus.agent.delegate
    - nexus.memory.capped

  nexus.agent.postures:
    scan_dirs:
      - ~/.nexus/postures
      - ./configs/postures
    debounce_ms: 250

Delegate (nexus.agent.delegate)

Exposes the delegate tool — the LLM-facing surface of the sub-agent delegation primitive. A parent agent picks a registered posture by name; the runtime spawns an isolated sub-session with its own envelope identity, runs the LLM loop filtered to the posture’s AllowedTools, and enforces the posture’s DefaultBudget with optional per-call overrides.

Details

Configuration

Tool definition

The plugin registers a single tool, delegate, with these parameters:

The tool’s JSON output is a delegate.Output:

{
  "Result": "...",
  "Status": "success",   // success | partial | error | timeout | cancelled | cache_hit
  "Error": "",
  "TokensUsed": 1832,
  "ToolCallsUsed": 4,
  "Elapsed": 8421000000,
  "SubSessionID": "abcd...",
  "PostureName": "analyst",
  "PostureVer": "a1b2c3d4e5f6...",
  "Depth": 1
}

The parent agent branches on Status to decide whether to retry with a larger budget, fall back to handling the task itself, or surface the partial result.

Events

Subscribes To

Emits

See delegate events for delegate.start / delegate.complete payload shape.

Example

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.agent.postures
    - nexus.agent.delegate
    - nexus.tool.web
    - nexus.memory.capped

  nexus.agent.postures:
    scan_dirs:
      - ~/.nexus/postures

  nexus.agent.delegate:
    max_depth: 3
    cache_size: 512

  nexus.agent.react:
    system_prompt: |
      When a task benefits from a different reasoning style or a restricted
      tool surface, call the delegate tool with the appropriate posture
      (analyst, summarizer, auditor, ...).

Causation

Every event emitted from inside a sub-session carries the sub-agent’s AgentID (delegate/<posture>/<sub_session_id>) and Depth on Event.Causation. The replay primitive and observability tooling use this to attribute work to the right specialist.

Remote AG-UI Agents (nexus.agent.agui_remote)

The consume side of Nexus’s AG-UI integration. Where nexus.io.agui serves a Nexus agent over the AG-UI wire, nexus.agent.agui_remote lets a Nexus agent call a remote AG-UI agent — any service that speaks the AG-UI protocol, including another Nexus instance running nexus.io.agui — as if it were a local delegate.

Each configured remote agent is registered as an LLM-facing tool (default name delegate_agui_<name>). When the parent agent calls it, the plugin builds an AG-UI RunAgentInput from the delegated task, streams the remote run over the AG-UI wire (HTTP POST + SSE) via the reusable AG-UI client, maps the remote run’s event stream back onto the Nexus bus, and returns the remote run’s terminal outcome as the tool.result the parent expects.

From the parent agent’s perspective a remote AG-UI call is a single tool call, exactly like the local delegate and subagent primitives — the transport just happens to be the AG-UI wire instead of an in-process sub-session.

Details

Configuration

The full, authoritative key list lives in the configuration reference. In brief:

Each agents[] entry:

Authentication

Secrets never live in config files: prefer bearer_token_env and point it at an environment variable. When set, the client sends Authorization: Bearer <token> on the POST that opens the remote run — matching the bearer auth nexus.io.agui enforces on the serve side. bearer_token (an inline literal) is supported for quick local testing but is only used when bearer_token_env is unset.

Tool definition

Each remote agent registers one tool. The default name is delegate_agui_<name> (the name lowercased with non-alphanumeric runs collapsed to _); override it with tool_name.

Event & result mapping

While the remote run streams, the plugin translates the incoming AG-UI events onto the caller’s bus so local observers (journal, TUI, observability) see the remote work as a sub-run:

The terminal outcome — accumulated text deltas, or the RunFinished result payload when the remote streamed no text — becomes the tool.result Output returned to the parent agent. The whole tool.result passes through the vetoable before:tool.result gate first.

Every mapped event carries the remote sub-run’s causation identity (AgentID = agui_remote/<name>/<spawn_id>, Depth = parent + 1), so remote work slots into the causation tree beneath the caller just like a local delegate.

Failure behavior

All failure modes surface as a clean tool error (tool.result.Error) — never a hang or panic — and are mirrored on subagent.complete.Error:

The parent agent’s loop consumes the error tool.result and continues normally, so a flaky or unreachable remote never stalls the caller.

Caching

Identical calls replay from an in-process LRU keyed by endpoint + task + canonicalized context (mirroring the local delegate cache), so repeated delegations do not re-hit the remote endpoint. A cache hit still emits a subagent.started / subagent.complete pair so observers see the call. Errors are never cached. Set cache: false to disable.

Example

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.agent.agui_remote
    - nexus.memory.capped

  nexus.agent.agui_remote:
    timeout_seconds: 90
    agents:
      - name: researcher
        endpoint: https://research.internal/agui
        bearer_token_env: RESEARCH_AGUI_TOKEN
        description: A specialist research agent reachable over AG-UI.
      - name: legal
        endpoint: https://legal.internal/agui
        tool_name: ask_legal

  nexus.agent.react:
    system_prompt: |
      When a task needs specialist knowledge, delegate it: call
      delegate_agui_researcher for research questions or ask_legal for
      legal review. Pass a clear task and any relevant context.

Loopback (serve ↔ consume)

Because nexus.io.agui speaks the same AG-UI wire, you can point nexus.agent.agui_remote at another Nexus instance’s serve endpoint. This loopback topology is the cheapest faithful end-to-end proof of the consume path and is exactly what the integration test (tests/integration/agui_consume_test.go) exercises: a caller engine delegates to a loopback nexus.io.agui serve engine and receives the remote agent’s result back as a tool.result.

See also

• AG-UI Serve (nexus.io.agui) — the serve side of the same wire.
• Delegate / Subagent — the local sub-agent primitives this mirrors.
• Sub-agent delegation — the shared delegation model.

LLM Providers

LLM provider plugins handle communication with AI model APIs. They receive llm.request events, call the external API, and emit llm.response (or streaming chunks).

Available Providers

Provider Architecture

Providers are low-level plugins that:

1. Subscribe to llm.request at high priority (10)
2. Resolve the requested model role via the Model Registry
3. Apply prompt registry sections to the system prompt
4. Make the API call (with streaming support)
5. Emit llm.response or llm.stream.chunk / llm.stream.end

Providers don’t know about agents, tools, or conversations — they only translate between the Nexus event model and the external API.

Structured Output

When ResponseFormat is set on an LLMRequest, providers map it to their native structured output mechanism if supported, or simulate it otherwise.

Capability Matrix

Metadata Flag

Providers set LLMResponse.Metadata["_structured_output"] = true when structured output enforcement was used (native or simulated). Downstream consumers (like the json_schema gate) can check this flag to skip redundant validation.

Anthropic (Claude) Provider

The Anthropic provider calls the Claude API via direct HTTP requests — no SDK dependency. It supports streaming, tool use, request cancellation, and automatic retries.

Details

Configuration