From 151585444869f690a9700210b12dd5a5130f486d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 4 May 2026 16:26:15 +0000 Subject: [PATCH 1/2] docs(product-presence): add product page, VISION.md, and README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Delivers all three issue #2 artifacts: - docs/product-page.md — hero, problem/solution, capabilities, integration map, roadmap - VISION.md — why/who/success/non-goals/north star decision filter - README.md — cold-reader front door with core concepts and delivery plan These are the source documents for docs/index.html (SPEC-HW-001) and feed directly into the design consolidation in #4 and the v0.0.1 baseline in #5. https://claude.ai/code/session_01WzYmom16ifVgSrBRqFwSNE --- README.md | 58 ++++++++++++++++++++++++++- VISION.md | 50 +++++++++++++++++++++++ docs/product-page.md | 94 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 201 insertions(+), 1 deletion(-) create mode 100644 VISION.md create mode 100644 docs/product-page.md diff --git a/README.md b/README.md index 2b64724..fd1de8a 100644 --- a/README.md +++ b/README.md @@ -1 +1,57 @@ -# specorator-runtime \ No newline at end of file +# specorator-runtime + +The execution layer for the Specorator ecosystem — runs agentic workflows, orchestrates agents, and exposes session state and events to the rest of the system. + +[![Phase 1 — Core Skeleton](https://img.shields.io/badge/phase-1%20core%20skeleton-blue)](https://github.com/Luis85/specorator-runtime/issues/8) + +--- + +## Where it fits + +``` +Specorator UI ──► specorator-runtime ◄── agentic-workflow (definitions) + │ + └──────────────◄── agentonomous (agents) +``` + +The runtime sits between workflow definitions and agent implementations. It is the piece that makes the system execute. + +--- + +## Core concepts + +**Session** — one execution instance of a workflow. Contains the workflow reference, execution state, task graph, agent interactions, produced artifacts, and the full event log. Query it at any point during or after a run. + +**Event bus** — the coordination spine. Every lifecycle change emits a typed event (`workflow.started`, `task.ready`, `agent.invoked`, `artifact.created`, …). Components subscribe; the runtime guarantees event ordering within a session. + +**Task lifecycle** — each task in a workflow progresses through states: `created → ready → running → completed | failed`. The runtime resolves dependencies and advances tasks when their prerequisites are met. + +--- + +## Getting started + +> Not yet available — see the delivery plan below. +> +> The first installable release is `v0.1.0` (Hello World milestone, issue [#8](https://github.com/Luis85/specorator-runtime/issues/8)). +> Once published: `npm install specorator-runtime` + +--- + +## Delivery plan + +| Phase | Focus | Status | +|---|---|---| +| Phase 1 — Core Skeleton | Runtime kernel, event bus, session model | In progress → v0.1.0 | +| Phase 2 — Execution | Full workflow interpreter, agent executor | Planned | +| Phase 3 — Observability | Runtime API, logging, state store | Planned | +| Phase 4 — Integration | Connect to Specorator UI | Planned | + +--- + +## Related + +- [PRD — Specorator Runtime](https://github.com/Luis85/specorator-runtime/issues/1) +- [VISION.md](./VISION.md) — the decision filter for this project +- [`agentic-workflow`](https://github.com/Luis85/agentic-workflow) — workflow definitions consumed by the runtime +- [`agentonomous`](https://github.com/Luis85/agentonomous) — agent implementations invoked by the runtime +- [Specorator](https://github.com/Luis85/specorator) — the UI that subscribes to runtime events diff --git a/VISION.md b/VISION.md new file mode 100644 index 0000000..b5d50cb --- /dev/null +++ b/VISION.md @@ -0,0 +1,50 @@ +# Vision — Specorator Runtime + +```yaml +document: VISION.md +issue: "#2" +stage: draft +created: 2026-05-04 +``` + +--- + +## Why does this exist? + +Workflows and agents exist throughout the Specorator ecosystem, but nothing orchestrates them. A workflow definition describes what should happen. An agent implementation knows how to do a task. Without a runtime, neither runs automatically, and no shared state connects them. The gap is an execution layer — something that reads a workflow, invokes the right agents in the right order, captures what they produce, and makes the whole thing observable. That is the only job of this library. + +--- + +## Who benefits? + +The human in the loop: a practitioner who designs knowledge work as a workflow and needs to see it execute, inspect what each agent produced, and intervene when something goes wrong. Not a developer wiring up plumbing — someone doing actual work, watching it run, and trusting the output. + +--- + +## What does success look like in 12 months? + +- A practitioner can define a multi-task workflow in `agentic-workflow`, install `specorator-runtime` from npm, start a session with three lines of TypeScript, and watch every task progress through the lifecycle without writing orchestration logic +- Specorator UI renders live session state — task graph, agent outputs, event log — directly from the runtime's event stream, with no polling +- `agentonomous` agents are invoked by the runtime with typed context and return typed artifacts; no manual wiring needed between workflow steps +- Breaking changes to the public API are rare because the session model, event catalog, and agent interface are stable enough that ecosystem consumers trust them across minor releases + +--- + +## What is this explicitly NOT? + +- Not a general-purpose workflow engine — it executes knowledge-work workflows, not arbitrary automation pipelines +- Not a distributed system — V1 is single-process, in-memory, single-user; no cloud, no multi-tenancy, no persistence layer +- Not a UI — it has no frontend; it emits events that a UI subscribes to +- Not an agent framework — it invokes agents from `agentonomous`; it does not define what agents are or how they reason +- Not a scheduler — sequential task execution in V1; complex scheduling strategies are explicitly deferred +- Not a replacement for `agentic-workflow` or `agentonomous` — it depends on both and does not absorb their responsibilities + +When a decision would push the runtime toward any of the above, that is the signal to stop and record it in the Follow-Up Register. + +--- + +## North Star + +> Does this help humans understand, control, and evolve knowledge work? + +Every architectural decision, API shape, and scoping choice is tested against this question. If the answer is not clearly yes, the decision is deferred or rejected. diff --git a/docs/product-page.md b/docs/product-page.md new file mode 100644 index 0000000..980faa3 --- /dev/null +++ b/docs/product-page.md @@ -0,0 +1,94 @@ +# Specorator Runtime — Product Page + +```yaml +source: docs/product-page.md +feeds: docs/index.html (SPEC-HW-001) +issue: "#2" +stage: draft +created: 2026-05-04 +terminology: session, event bus, task, agent, artifact, workflow +``` + +--- + +## Hero Statement + +Specorator Runtime is the execution layer that turns defined agentic workflows into running, observable, in-memory sessions — bridging workflow definitions and agent implementations into a single coordinated system. + +--- + +## Problem → Solution + +Knowledge work teams using the Specorator ecosystem can define workflows and configure agents, but nothing runs them. Workflows sit as static definitions. Agents exist but are invoked manually, without shared context or structured output capture. 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 workflow definitions from `agentic-workflow`, invokes agents from `agentonomous`, and coordinates execution through a typed event bus. Every step in a workflow — from session start to artifact capture — emits a lifecycle event. The result is a stateful, observable session that any part of the ecosystem can subscribe to and query. + +--- + +## Key Capabilities + +- **Start and stop workflow sessions** — create a runtime session from any workflow definition; query its state at any point during or after execution +- **Coordinate task execution** — resolve task dependencies, advance tasks from `created` through `ready` to `completed` or `failed`, and emit lifecycle events at each transition +- **Invoke agents in context** — pass typed context to each agent, capture its structured output as an artifact, and log the interaction in the session event log +- **Stream execution events** — subscribe to any event type (`workflow.started`, `agent.invoked`, `artifact.created`, etc.) from any part of the system, in guaranteed order within a session +- **Query runtime state** — inspect sessions, task graphs, event logs, and produced artifacts via a clean TypeScript API, without filesystem or network I/O + +--- + +## Integration Map + +``` +Specorator UI ──────────── subscribes to events, visualises sessions, triggers execution + │ + ▼ +Specorator Runtime ◄──── interprets workflows from: agentic-workflow + (this package) ◄──── invokes agents from: agentonomous + │ + ▼ + npm registry ─────────── install with: npm install specorator-runtime +``` + +**Consuming the runtime:** + +```ts +import { RuntimeKernel, EventBus } from 'specorator-runtime'; +import type { Session, RuntimeEvent, Artifact } from 'specorator-runtime'; +``` + +All public types are re-exported from a single entry point. No deep or path-based imports required. + +--- + +## Current Status + +**Phase 1 — Core Skeleton** *(in progress toward v0.1.0 — Hello World)* + +The v0.1.0 release is the first proof that the system runs end-to-end. It delivers: + +- `RuntimeKernel` — session lifecycle management +- `EventBus` — typed pub/sub, ordered within a session +- Session, Task, Artifact, and RuntimeEvent types +- A stub workflow interpreter and agent executor +- A runnable Hello World example (`examples/hello-world/`) +- This product page and a static demo at `docs/demo.html`, hosted on GitHub Pages + +**Roadmap:** + +| Phase | Focus | Status | +|---|---|---| +| Phase 1 — Core Skeleton | Runtime kernel, event bus, session model | In progress | +| Phase 2 — Execution | Full workflow interpreter, agent executor | Planned | +| Phase 3 — Observability | Runtime API, logging, state store | Planned | +| Phase 4 — Integration | Connect to Specorator UI | Planned | + +Non-Goals (V1): distributed execution, multi-user collaboration, cloud-native scaling, filesystem persistence, complex scheduling. + +--- + +## Related + +- [GitHub repository](https://github.com/Luis85/specorator-runtime) +- PRD — issue #1 in this repository +- [`agentic-workflow`](https://github.com/Luis85/agentic-workflow) — workflow definitions consumed by the runtime +- [`agentonomous`](https://github.com/Luis85/agentonomous) — agent implementations invoked by the runtime +- [Specorator UI](https://github.com/Luis85/specorator) — the interface that subscribes to runtime events From 1c4bd8d26f6f207729ed952d76a40a73101a3cae Mon Sep 17 00:00:00 2001 From: Luis Mendez <3923861+Luis85@users.noreply.github.com> Date: Sun, 10 May 2026 12:55:11 +0200 Subject: [PATCH 2/2] docs: align product presence with architecture proposal, SAO, and actual roadmap phases - README: four-project system map (per #14), orchestrator engine concept, correct phases - VISION: add SAO non-goal distinction; 12-month success includes automated dispatch; harness framing - product-page: updated integration map with SAO, ratified API verbs, correct phase table --- README.md | 60 ++++++++++++++++++++++++--------- VISION.md | 16 ++++++--- docs/product-page.md | 79 ++++++++++++++++++++++++-------------------- 3 files changed, 101 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index fd1de8a..c370fcd 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,54 @@ # specorator-runtime -The execution layer for the Specorator ecosystem — runs agentic workflows, orchestrates agents, and exposes session state and events to the rest of the system. +The execution layer for the Specorator ecosystem — provides an agent habitat, loads typed workflow packages, and exposes a small request/response API that Specorator uses to start sessions, run commands, submit tasks, and stream events. -[![Phase 1 — Core Skeleton](https://img.shields.io/badge/phase-1%20core%20skeleton-blue)](https://github.com/Luis85/specorator-runtime/issues/8) +[![Phase 1 — Architecture & Design](https://img.shields.io/badge/phase-1%20architecture%20%26%20design-blue)](https://github.com/Luis85/specorator-runtime/issues/14) --- ## Where it fits ``` -Specorator UI ──► specorator-runtime ◄── agentic-workflow (definitions) - │ - └──────────────◄── agentonomous (agents) +┌─────────────────────────────────────────────────────────────────┐ +│ agentic-workflow — workflow package source │ +│ Agent/skill/command definitions, TS scripts, templates, docs │ +└──────────────────────────────┬──────────────────────────────────┘ + │ assembled into WorkflowPackage + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ specorator-runtime (this package) │ +│ Agent habitat · capability provider · event bus │ +│ Public API: startSession / stopSession / getSession │ +│ submitTask / runCommand / runScript │ +│ spawnAgent / stopAgent / bus.subscribe │ +│ Orchestrator engine (SAO): automated agent dispatch │ +└──────┬──────────────────────────────────────────────────────────┘ + │ submits tasks/commands; subscribes to events + ▼ +┌──────────────────────────┐ ┌────────────────────────────────┐ +│ Specorator │ │ agentonomous │ +│ Obsidian plugin │ │ Autonomous agent library │ +│ Cockpit UI · vault I/O │ │ Lives inside the runtime │ +│ HITL · WorkflowPackage │ │ as ECS entities │ +│ assembly │ │ instantiated from definitions │ +└──────────────────────────┘ └────────────────────────────────┘ ``` -The runtime sits between workflow definitions and agent implementations. It is the piece that makes the system execute. +The runtime sits between workflow definitions and UI/agent consumers. It exposes a small, stable surface so consumers never see internal ECS, definition-parsing, permission enforcement, or orchestration complexity. --- ## Core concepts -**Session** — one execution instance of a workflow. Contains the workflow reference, execution state, task graph, agent interactions, produced artifacts, and the full event log. Query it at any point during or after a run. +**Session** — one isolated execution context for a workflow package. Created via `startSession(workflowPackage, capabilities)`. Query its state at any point via `getSession(id)`. -**Event bus** — the coordination spine. Every lifecycle change emits a typed event (`workflow.started`, `task.ready`, `agent.invoked`, `artifact.created`, …). Components subscribe; the runtime guarantees event ordering within a session. +**Event bus** — the coordination spine. Every lifecycle change emits a typed `RuntimeEvent` with a monotonic `seq`, `traceId`, and `parentId`. Subscribe via `bus.subscribe`. Events are ordered and trace-correlated across the three buses (plugin, runtime, agent-internal). -**Task lifecycle** — each task in a workflow progresses through states: `created → ready → running → completed | failed`. The runtime resolves dependencies and advances tasks when their prerequisites are met. +**Task lifecycle** — tasks progress through `created → ready → running → completed | failed`. The runtime resolves dependencies and advances tasks when prerequisites are met. + +**Agent habitat** — the runtime hosts `agentonomous` agents as ECS entities. It provisions capabilities (LLM, vault-read, workflow-reference), enforces per-agent permissions declared in the workflow package, and ticks the agent loop each simulation step. + +**Orchestrator engine (SAO)** — the automated dispatch layer built into the runtime. Polls the vault for eligible features, dispatches Claude CLI agent processes into isolated git worktrees, evaluates artifact quality via a sensor hierarchy, and advances workflow stages upon confirmed success. Configurable via the `agentOrchestrator` settings namespace with human review gates. --- @@ -41,17 +65,23 @@ The runtime sits between workflow definitions and agent implementations. It is t | Phase | Focus | Status | |---|---|---| -| Phase 1 — Core Skeleton | Runtime kernel, event bus, session model | In progress → v0.1.0 | -| Phase 2 — Execution | Full workflow interpreter, agent executor | Planned | -| Phase 3 — Observability | Runtime API, logging, state store | Planned | -| Phase 4 — Integration | Connect to Specorator UI | Planned | +| Phase 0 — Foundation | Product identity, knowledge architecture, design workshops, ADRs, solution proposal | 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, entropy management | Planned | +| Hello World (v0.1.0) | First end-to-end runtime proof | Planned | +| Phase 3+ | Replay, sandboxing, MCP transport, semantic indexing | Deferred | + +See the full roadmap in [issue #37](https://github.com/Luis85/specorator-runtime/issues/37). --- ## Related -- [PRD — Specorator Runtime](https://github.com/Luis85/specorator-runtime/issues/1) +- [ROADMAP — issue #37](https://github.com/Luis85/specorator-runtime/issues/37) — full phase-by-phase delivery plan +- [PRD — issue #1](https://github.com/Luis85/specorator-runtime/issues/1) - [VISION.md](./VISION.md) — the decision filter for this project +- [Architecture proposal — issue #14](https://github.com/Luis85/specorator-runtime/issues/14) +- [Orchestrator engine — issue #43](https://github.com/Luis85/specorator-runtime/issues/43) - [`agentic-workflow`](https://github.com/Luis85/agentic-workflow) — workflow definitions consumed by the runtime - [`agentonomous`](https://github.com/Luis85/agentonomous) — agent implementations invoked by the runtime -- [Specorator](https://github.com/Luis85/specorator) — the UI that subscribes to runtime events +- [Specorator](https://github.com/Luis85/specorator) — the Obsidian plugin that drives the runtime diff --git a/VISION.md b/VISION.md index b5d50cb..60687c3 100644 --- a/VISION.md +++ b/VISION.md @@ -5,13 +5,16 @@ document: VISION.md issue: "#2" stage: draft created: 2026-05-04 +updated: 2026-05-10 ``` --- ## Why does this exist? -Workflows and agents exist throughout the Specorator ecosystem, but nothing orchestrates them. A workflow definition describes what should happen. An agent implementation knows how to do a task. Without a runtime, neither runs automatically, and no shared state connects them. The gap is an execution layer — something that reads a workflow, invokes the right agents in the right order, captures what they produce, and makes the whole thing observable. That is the only job of this library. +Workflows and agents exist throughout the Specorator ecosystem, but nothing orchestrates them reliably. A workflow definition describes what should happen. An agent implementation knows how to do a task. Without a runtime, neither runs automatically, no shared state connects them, and no harness keeps quality consistent across automated runs. + +The gap is an execution layer — something that reads a typed workflow package, instantiates the right agents in a controlled habitat, dispatches the right commands, captures what they produce, and makes the whole thing observable. It must also provide the harness that lets automated agent dispatch (the SAO) produce reliable, auditable output without requiring human attention at every step. That is the only job of this library. --- @@ -19,13 +22,16 @@ Workflows and agents exist throughout the Specorator ecosystem, but nothing orch The human in the loop: a practitioner who designs knowledge work as a workflow and needs to see it execute, inspect what each agent produced, and intervene when something goes wrong. Not a developer wiring up plumbing — someone doing actual work, watching it run, and trusting the output. +Teams running the Specorator Agent Orchestrator also benefit: the runtime's harness — prompt templates, structured feedback sensors, trace-correlated event bus, permission enforcement — ensures automated agent runs produce consistent, auditable output without requiring manual review at every stage. + --- ## What does success look like in 12 months? -- A practitioner can define a multi-task workflow in `agentic-workflow`, install `specorator-runtime` from npm, start a session with three lines of TypeScript, and watch every task progress through the lifecycle without writing orchestration logic -- Specorator UI renders live session state — task graph, agent outputs, event log — directly from the runtime's event stream, with no polling -- `agentonomous` agents are invoked by the runtime with typed context and return typed artifacts; no manual wiring needed between workflow steps +- A practitioner can define a multi-stage workflow in `agentic-workflow`, install `specorator-runtime` from npm, start a session with three lines of TypeScript, and watch every stage progress through the lifecycle without writing orchestration logic +- Specorator renders live session state — agent activity, produced artifacts, event log — directly from the runtime's event stream, with no polling +- `agentonomous` agents are invoked by the runtime with typed context and return typed artifacts; no manual wiring needed between workflow stages +- The Specorator Agent Orchestrator (SAO) advances features through workflow stages automatically — dispatching isolated Claude CLI processes into per-feature worktrees, evaluating artifact quality, and merging confirmed output — with human review gates at configurable stages - Breaking changes to the public API are rare because the session model, event catalog, and agent interface are stable enough that ecosystem consumers trust them across minor releases --- @@ -36,8 +42,10 @@ The human in the loop: a practitioner who designs knowledge work as a workflow a - Not a distributed system — V1 is single-process, in-memory, single-user; no cloud, no multi-tenancy, no persistence layer - Not a UI — it has no frontend; it emits events that a UI subscribes to - Not an agent framework — it invokes agents from `agentonomous`; it does not define what agents are or how they reason +- Not a standalone orchestrator — automated agent dispatch belongs to the Specorator Agent Orchestrator (SAO), a separate layer built on the runtime's public API. The runtime provides the habitat, harness, and event bus; the SAO provides the dispatch loop, worktree isolation, prompt template system, and quality sensors - Not a scheduler — sequential task execution in V1; complex scheduling strategies are explicitly deferred - Not a replacement for `agentic-workflow` or `agentonomous` — it depends on both and does not absorb their responsibilities +- Not a methodology owner — the runtime loads and enforces definitions; it never authors them, writes to the vault, or models the 11-stage methodology in runtime types When a decision would push the runtime toward any of the above, that is the signal to stop and record it in the Follow-Up Register. diff --git a/docs/product-page.md b/docs/product-page.md index 980faa3..c4c555e 100644 --- a/docs/product-page.md +++ b/docs/product-page.md @@ -6,80 +6,88 @@ feeds: docs/index.html (SPEC-HW-001) issue: "#2" stage: draft created: 2026-05-04 -terminology: session, event bus, task, agent, artifact, workflow +updated: 2026-05-10 +terminology: session, event bus, task, agent, artifact, workflow, orchestrator ``` --- ## Hero Statement -Specorator Runtime is the execution layer that turns defined agentic workflows into running, observable, in-memory sessions — bridging workflow definitions and agent implementations into a single coordinated system. +Specorator Runtime is the execution layer that turns typed agentic workflow packages into running, observable, in-memory sessions — and provides the harness that lets the Specorator Agent Orchestrator dispatch automated agents reliably. --- ## Problem → Solution -Knowledge work teams using the Specorator ecosystem can define workflows and configure agents, but nothing runs them. Workflows sit as static definitions. Agents exist but are invoked manually, without shared context or structured output capture. There is no unified lifecycle, no session state to query, and no event stream for a UI to follow in real time. +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 workflow definitions from `agentic-workflow`, invokes agents from `agentonomous`, and coordinates execution through a typed event bus. Every step in a workflow — from session start to artifact capture — emits a lifecycle event. The result is a stateful, observable session that any part of the ecosystem can subscribe to and query. +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. The Specorator Agent Orchestrator (SAO) — built on the runtime's public API — dispatches isolated Claude CLI agents into per-feature git worktrees and advances stages upon confirmed artifact production. Every step emits a lifecycle event. The result is a stateful, observable session that any part of the ecosystem can subscribe to and query. --- ## Key Capabilities -- **Start and stop workflow sessions** — create a runtime session from any workflow definition; query its state at any point during or after execution -- **Coordinate task execution** — resolve task dependencies, advance tasks from `created` through `ready` to `completed` or `failed`, and emit lifecycle events at each transition -- **Invoke agents in context** — pass typed context to each agent, capture its structured output as an artifact, and log the interaction in the session event log -- **Stream execution events** — subscribe to any event type (`workflow.started`, `agent.invoked`, `artifact.created`, etc.) from any part of the system, in guaranteed order within a session -- **Query runtime state** — inspect sessions, task graphs, event logs, and produced artifacts via a clean TypeScript API, without filesystem or network I/O +- **Start and stop workflow sessions** — create a runtime session from a typed `WorkflowPackage`; query its state at any point via `getSession` +- **Dispatch commands and scripts** — `runCommand` orchestrates the full agent dispatch chain with permission enforcement; `runScript` invokes typed TS 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 cockpit visibility +- **Stream trace-correlated events** — subscribe to any `RuntimeEvent` from any part of the system; events carry `traceId`/`parentId` correlated across the three buses (plugin, runtime, agent-internal) +- **Automated stage dispatch (SAO)** — the orchestrator engine polls the vault, dispatches Claude CLI agents into isolated worktrees, evaluates output via a feedforward/feedback sensor hierarchy, and advances stages — with human review gates configurable per stage --- ## Integration Map ``` -Specorator UI ──────────── subscribes to events, visualises sessions, triggers execution - │ +agentic-workflow + (definitions source) + │ WorkflowPackage assembled by Specorator ▼ -Specorator Runtime ◄──── interprets workflows from: agentic-workflow - (this package) ◄──── invokes agents from: agentonomous - │ - ▼ - npm registry ─────────── install with: npm install specorator-runtime +Specorator (Obsidian plugin) + │ startSession(workflowPackage, capabilities) + │ runCommand / submitTask / runScript + │ subscribes to RuntimeEvents + ▼ +specorator-runtime (this package) + │ hosts agents (agentonomous) + │ enforces permissions + │ emits RuntimeEvents + │ SAO: dispatches Claude CLI → worktrees → artifacts + │ + └─► agentonomous (agent library — lives inside runtime as ECS entities) ``` **Consuming the runtime:** ```ts -import { RuntimeKernel, EventBus } from 'specorator-runtime'; -import type { Session, RuntimeEvent, Artifact } from 'specorator-runtime'; +import { RuntimeKernel } from 'specorator-runtime'; +import type { Session, RuntimeEvent, 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 entry point. No deep or path-based imports required. +All public types are re-exported from a single barrel entry point. No deep or path-based imports required. --- ## Current Status -**Phase 1 — Core Skeleton** *(in progress toward v0.1.0 — Hello World)* - -The v0.1.0 release is the first proof that the system runs end-to-end. It delivers: +**Phase 1 — Architecture & Design** *(in progress)* -- `RuntimeKernel` — session lifecycle management -- `EventBus` — typed pub/sub, ordered within a session -- Session, Task, Artifact, and RuntimeEvent types -- A stub workflow interpreter and agent executor -- A runnable Hello World example (`examples/hello-world/`) -- This product page and a static demo at `docs/demo.html`, hosted on GitHub Pages +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. -**Roadmap:** +**Delivery plan:** | Phase | Focus | Status | |---|---|---| -| Phase 1 — Core Skeleton | Runtime kernel, event bus, session model | In progress | -| Phase 2 — Execution | Full workflow interpreter, agent executor | Planned | -| Phase 3 — Observability | Runtime API, logging, state store | Planned | -| Phase 4 — Integration | Connect to Specorator UI | Planned | +| Phase 0 — Foundation | Product identity, knowledge architecture, design workshops, ADRs, solution proposal | 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, entropy management | Planned | +| Hello World (v0.1.0) | First end-to-end runtime proof | Planned | +| Phase 3+ | Replay, sandboxing, MCP transport, semantic indexing | Deferred | Non-Goals (V1): distributed execution, multi-user collaboration, cloud-native scaling, filesystem persistence, complex scheduling. @@ -88,7 +96,8 @@ Non-Goals (V1): distributed execution, multi-user collaboration, cloud-native sc ## Related - [GitHub repository](https://github.com/Luis85/specorator-runtime) -- PRD — issue #1 in this repository +- [ROADMAP — issue #37](https://github.com/Luis85/specorator-runtime/issues/37) +- [PRD — issue #1](https://github.com/Luis85/specorator-runtime/issues/1) - [`agentic-workflow`](https://github.com/Luis85/agentic-workflow) — workflow definitions consumed by the runtime - [`agentonomous`](https://github.com/Luis85/agentonomous) — agent implementations invoked by the runtime -- [Specorator UI](https://github.com/Luis85/specorator) — the interface that subscribes to runtime events +- [Specorator](https://github.com/Luis85/specorator) — the Obsidian plugin that drives the runtime