Milestone: Hello World — first end-to-end runtime proof (v0.1.0)

[Luis85]

Prerequisites

• Milestone: Project Ready — pre-flight checklist before Phase 1 #7 — Milestone: Project Ready must be closed before this issue is actioned
• SOLUTION-PROPOSAL.md committed and approved in Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4
• npm package name confirmed available on the registry (ADR from Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4)
• NPM_TOKEN secret configured in repository settings (Phase 0 · Project environment — repo setup, agentic-workflow conventions, and workshops #3)
• PR spec(hello-world): GitHub Pages hosting for product page and product demo #9 merged to develop — SPEC-HW-001 (specs/hello-world/github-pages.md) must exist before the GitHub Pages deliverables are implemented

---

What this issue is

This is the Hello World milestone — the first proof that Specorator Runtime actually runs.

It is not a feature release. It is the minimum working demonstration of the full system operating end-to-end within the constraints defined in the PRD. Every architectural decision made in #4 is validated here for the first time against real code.

When this issue closes, v0.1.0 is tagged. That is the first release that contains working software.

Constraint reminder (from PRD NFR-02, NFR-05, NFR-06): Node.js context, TypeScript, Vitest for testing, compatible with Obsidian environment, in-memory state only, published to npm with TypeScript types — module format per ADR from #4.

---

The Hello World Scenario

The minimum scenario that proves the system:

Given: a workflow with a single task assigned to a stub agent
When:  a runtime session is started
Then:  the following events fire in order:
         workflow.started
         → task.created
           → task.ready
             → agent.invoked
               → agent.completed
                 → artifact.created
                   → task.completed
                     → workflow.completed
       And: session state is queryable at any point
       And: the stub agent receives context and returns structured output
       And: the artifact produced by the agent is captured in the session

This scenario must be covered end-to-end by a Vitest test suite. It must pass with npm run verify.

---

Phase 1 — Core Skeleton

These are the implementation prerequisites. Each item produces a tested, committed module.

Runtime Kernel

• RuntimeKernel class or module created
• Session creation: kernel.startSession(workflow) returns a Session
• Session stop: kernel.stopSession(sessionId) halts execution
• Session query: kernel.getSession(sessionId) returns current state
• Unit tests covering session lifecycle

Event Bus

• EventBus class or module created
• emit(event) publishes a typed event
• subscribe(eventType, handler) registers a listener
• Event ordering guaranteed within a session (sequential, synchronous in V1)
• Unit tests: emit → subscriber receives, multiple subscribers, ordering

Session Model

• Session type defined with: id, workflowRef, state, taskGraph, eventLog, artifacts
• TaskState type: created | ready | running | completed | failed
• RuntimeEvent type: discriminated union of all V1 events with typed payloads
• Artifact type defined
• All types exported from a single entry point

---

Phase 2 — Execution (Hello World scope only)

Implement only what is needed for the Hello World scenario. Full interpreter and executor are scoped to the next milestone.

Stub Workflow Interpreter

• Accepts a minimal workflow definition (one task, one dependency graph)
• Resolves the single task as ready on session start
• Emits workflow.started and task.created, task.ready in sequence

Stub Agent Executor

• Accepts a task and context
• Emits agent.invoked
• Calls a configurable stub agent function
• Captures the return value as an Artifact
• Emits agent.completed, artifact.created, task.completed
• Emits workflow.completed when all tasks are done

---

Phase 3 — Observability (Hello World scope only)

In-Memory State Store

• Stores session state updated by event handlers
• getSession(id) returns current snapshot
• getEventLog(id) returns ordered list of events for the session

Logging

• Each event emission produces a structured log entry (console or logger)
• Log format: [timestamp] [sessionId] event.type payload

---

Hello World App

• examples/hello-world/ directory created
• index.ts — runnable script demonstrating the full scenario end-to-end
• workflow.ts — minimal workflow definition used by the demo
• stub-agent.ts — stub agent that returns a fixed structured output
• Running the example script (using the TypeScript runner confirmed in SOLUTION-PROPOSAL.md, e.g. tsx or ts-node) prints the full event log to stdout
• The printed output is human-readable and shows every event in sequence

---

GitHub Pages — product page and product demo

The Hello World release ships two public-facing static HTML files hosted on GitHub Pages. Full content requirements and acceptance criteria are defined in SPEC-HW-001 (specs/hello-world/github-pages.md — see PR #9, which must be merged to develop before this work begins).

• docs/index.html — static product page committed (hero, problem/solution, capabilities, integration map, links)
• docs/demo.html — static rendering of the full Hello World execution trace with all 8 events, the stub agent artifact, and a session state snapshot
• Both files render correctly when opened directly in a browser via file:// — no build step, no server required
• GitHub Pages configured to serve from docs/ on main
• .github/workflows/pages.yml created — verifies docs/index.html and docs/demo.html exist on every push to docs/**
• https://luis85.github.io/specorator-runtime/ resolves to the product page after merge to main
• https://luis85.github.io/specorator-runtime/demo.html resolves to the product demo

---

npm Package

The Hello World release must be the first publicly installable version of the library (NFR-06).

• package.json configured for publishing: name, version, main, types, exports, and files fields set correctly per the ADR from Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4
• Build output is clean, typed, and importable: import { RuntimeKernel } from 'specorator-runtime' (or scoped equivalent) works after install
• NPM_TOKEN secret configured in GitHub repository settings (prerequisite — see Phase 0 · Project environment — repo setup, agentic-workflow conventions, and workshops #3)
• release.yml workflow publishes to npm on semver tag from main HEAD
• Package published to npm at v0.1.0 under the name confirmed in the ADR from Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4
• npm install specorator-runtime installs the package and its TypeScript type declarations

---

Test Suite

• All unit tests pass under npm run verify via Vitest
• Integration test: the Hello World scenario runs end-to-end and all 8 events fire in the correct order
• Test coverage includes: session creation, event ordering, agent invocation, artifact capture, state query
• No test relies on external I/O or real agents

---

Documentation Updates

• README.md updated: "Getting started" section shows npm install specorator-runtime and a link to the Hello World example
• CHANGELOG.md entry for v0.1.0 written
• DELIVERABLES-MAP.md updated to reflect Phase 1 complete, Phase 2 in progress
• FOLLOW-UP-REGISTER.md reviewed: close resolved risks, add any new ones surfaced during implementation

---

Release — v0.1.0

• All tests green on main
• All CI workflows passing: ci.yml, gitleaks.yml, typos.yml, pages.yml
• CHANGELOG.md entry for v0.1.0 finalised
• Package published to npm at v0.1.0 — npm install specorator-runtime installs successfully
• GitHub Pages live at https://luis85.github.io/specorator-runtime/ — product page and demo both accessible
• GitHub Release created:
  • Tag: v0.1.0
  • Title: Hello World — first working runtime release
  • Release notes: what the Hello World scenario demonstrates, which modules are implemented, what is explicitly deferred to the next milestone, link to the example script, link to the GitHub Pages demo, link to the npm package

---

Acceptance Criteria

• npm run verify passes with zero failures
• The Hello World scenario produces all 8 events in the correct order, verified by the integration test
• Session state is queryable after execution completes
• The stub agent receives typed context and returns a typed artifact
• The example script runs without errors and produces readable output
• npm install specorator-runtime installs the package and its TypeScript types
• docs/index.html and docs/demo.html are committed, valid static HTML, and pass the cold-reader test
• GitHub Pages is live and both URLs resolve correctly
• GitHub Release v0.1.0 exists with links to the npm package and the live demo

---

What this milestone does NOT include

• Real workflow definitions from agentic-workflow (deferred to next milestone)
• Real agents from agentonomous (deferred)
• Parallel task execution (deferred)
• UI integration with Specorator (deferred)
• Persistence to filesystem (deferred — open question from PRD §15)
• Retry or failure handling (deferred)

---

Related

• Phase 0 · PRD — Specorator Runtime #1 — PRD: Specorator Runtime (NFR-06 defines the npm distribution requirement; NFR-05 drives module format decision)
• Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4 — Design consolidation (SOLUTION-PROPOSAL.md drives implementation; module format and package name ADRs are prerequisites)
• Phase 0 · Formal initiation — p3.express Group A + v0.0.2 baseline #6 — Formal initiation (DELIVERABLES-MAP.md is updated here)
• Milestone: Project Ready — pre-flight checklist before Phase 1 #7 — Milestone: Project Ready (must be closed before this issue is actioned)
• spec(hello-world): GitHub Pages hosting for product page and product demo #9 — PR: spec(hello-world): GitHub Pages hosting for product page and product demo (must be merged before GitHub Pages deliverables are implemented)
• SPEC-HW-001: specs/hello-world/github-pages.md — full spec for docs/index.html, docs/demo.html, and GitHub Pages configuration
• workflow-adoption-guide — Step 8 defines the pattern for this first-increment milestone

[Luis85]

Predecessor

This milestone opens only after #7 (Milestone: Project Ready) is closed.

The inputs that drive implementation here are:

• SOLUTION-PROPOSAL.md — produced in Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4; defines the architecture and TypeScript interfaces
• DELIVERABLES-MAP.md — produced in Phase 0 · Formal initiation — p3.express Group A + v0.0.2 baseline #6; defines what Phase 1 must deliver
• Event Catalog v1 — produced in Workshop B (Phase 0 · Project environment — repo setup, agentic-workflow conventions, and workshops #3) and finalised in Phase 0 · Design consolidation — stock-taking, enrichment, and solution proposal #4; defines all event names and payload contracts

Do not begin implementation without these three documents in hand and committed to main.

---

Generated by Claude Code