The execution layer for
agentic workflow packages

Specorator Runtime turns typed WorkflowPackage definitions into running, observable, in-memory sessions — and provides the harness that lets the Specorator Agent Orchestrator dispatch automated agents reliably.

View Hello World Demo GitHub ↗

The problemWhy this exists

Knowledge work teams using the Specorator ecosystem can define workflows and configure agents, but nothing runs them reliably. Workflows sit as static definitions. Agents are invoked manually, without shared context, structured output capture, or quality controls.

There is no unified lifecycle, no session state to query, and no event stream for a UI to follow in real time. Specorator Runtime closes that gap.

It interprets typed workflow packages assembled from agentic-workflow, invokes agents from agentonomous, and coordinates execution through a typed event bus. Every step emits a lifecycle event. The result is a stateful, observable session that any part of the ecosystem can subscribe to and query.

CapabilitiesWhat it does

Start and stop workflow sessions
Create a runtime session from a typed WorkflowPackage. Query its state at any point via getSession. Stop cleanly and emit final lifecycle events.
Dispatch commands and scripts
runCommand orchestrates the full agent dispatch chain with permission enforcement. runScript invokes typed TypeScript scripts with a narrow capability surface.
Host agents in context
spawnAgent instantiates an agentonomous agent as an ECS entity with provisioned capabilities (LLM, vault-read, workflow-reference). submitTask drives the agent loop with typed input.
Enforce permissions
A Permission Guard gates every dispatch against each agent's declared allowedSkills, allowedCommands, allowedScripts. Denied calls emit permission.denied events for full visibility.
Stream trace-correlated events
Subscribe to any RuntimeEvent from any part of the system. Events carry traceId and parentId correlated across the plugin, runtime, and agent-internal buses.
Automated stage dispatch (SAO)
The orchestrator engine polls the vault, dispatches Claude CLI agents into isolated worktrees, evaluates output via a sensor hierarchy, and advances stages — with configurable human review gates.

ArchitectureHow it fits in

agentic-workflow  (workflow definitions)
       │  WorkflowPackage assembled by Specorator
       ▼
Specorator  (Obsidian plugin)
       │  startSession · runCommand · submitTask · bus.subscribe
       ▼
specorator-runtime  ← this package
       │  agent habitat · permission guard · event bus
       │  SAO: dispatches Claude CLI → worktrees → artifacts
       │
       └─► agentonomous  (agent library as ECS entities)
import RuntimeKernel from 'specorator-runtime'; import type WorkflowPackage from 'specorator-runtime'; const session = await kernel.startSession(workflowPackage, capabilities); session.bus.subscribe(event => /* handle RuntimeEvent */); await kernel.runCommand(session.id, '/spec:requirements', args);

All public types are re-exported from a single barrel entry point. No deep or path-based imports required.

StatusDelivery plan

Every design decision — runtime kernel, data model, orchestrator engine, failure taxonomy, trace propagation — is being ratified before implementation begins. The v0.1.0 Hello World release follows once the architecture is locked and the engineering scaffold is in place.

Phase Focus Status
Phase 0 — Foundation Product identity, knowledge architecture, design workshops, ADRs In progress
Phase 1 — Architecture & Design Runtime kernel, data model, orchestrator design, all design decisions In progress
Phase 2 — Engineering Scaffold Tooling, CI, test infrastructure, architecture fitness Planned
Hello World (v0.1.0) First end-to-end runtime proof Planned
Phase 3+ Replay, sandboxing, MCP transport, semantic indexing Deferred

Not in scope for V1: distributed execution, multi-user collaboration, cloud-native scaling, filesystem persistence, complex scheduling.

RelatedEcosystem & links

specorator-runtime — this repository
agentic-workflow — workflow definitions consumed by the runtime
agentonomous — agent implementations invoked by the runtime
Specorator — the Obsidian plugin that drives the runtime
Roadmap — issue #37 — full phase-by-phase delivery plan
PRD — issue #1 — product requirements document