Luis85 · Luis85 · May 4, 2026 · May 10, 2026
diff --git a/README.md b/README.md
@@ -1 +1,87 @@
-# specorator-runtime
+# specorator-runtime
+
+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 — 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
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  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 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 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 `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** — 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.
+
+---
+
+## 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 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
+
+- [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 Obsidian plugin that drives the runtime
diff --git a/VISION.md b/VISION.md
@@ -0,0 +1,58 @@
+# Vision — Specorator Runtime
+
+```yaml
+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 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.
+
+---
+
+## 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.
+
+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-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
+
+---
+
+## 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 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.
+
+---
+
+## 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
@@ -0,0 +1,103 @@
+# 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
+updated: 2026-05-10
+terminology: session, event bus, task, agent, artifact, workflow, orchestrator
+```
+
+---
+
+## Hero Statement
+
+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 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. 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 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
+
+```
+agentic-workflow
+  (definitions source)
+       │ WorkflowPackage assembled by Specorator
+       ▼
+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 } 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 barrel entry point. No deep or path-based imports required.
+
+---
+
+## Current Status
+
+**Phase 1 — Architecture & Design** *(in progress)*
+
+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.
+
+**Delivery plan:**
+
+| Phase | Focus | Status |
+|---|---|---|
+| 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.
+
+---
+
+## Related
+
+- [GitHub repository](https://github.com/Luis85/specorator-runtime)
+- [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](https://github.com/Luis85/specorator) — the Obsidian plugin that drives the runtime