From 2509a942ae7eda1189cd7e5f19dd48740bc98bab Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 3 May 2026 17:02:49 +0000 Subject: [PATCH 1/2] spec(hello-world): define GitHub Pages hosting for product page and product demo Adds SPEC-HW-001 which formalises the requirement that docs/index.html (product page) and docs/demo.html (product demo) are delivered as static HTML files and served via GitHub Pages from the docs/ directory on main. Covers deliverable content, GitHub Pages configuration, a pages.yml CI workflow, and acceptance criteria aligned with issue #8. https://claude.ai/code/session_01AtN6bdu7Gk1Cb13SxZ4RaJ --- specs/hello-world/github-pages.md | 126 ++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 specs/hello-world/github-pages.md diff --git a/specs/hello-world/github-pages.md b/specs/hello-world/github-pages.md new file mode 100644 index 0000000..1282d47 --- /dev/null +++ b/specs/hello-world/github-pages.md @@ -0,0 +1,126 @@ +# Spec: GitHub Pages — product page and product demo + +```yaml +id: SPEC-HW-001 +feature: hello-world +issue: "#8" +stage: specification +status: draft +created: 2026-05-03 +``` + +--- + +## Context + +The Hello World milestone (issue #8) includes a runnable example that demonstrates the full end-to-end execution scenario. Two public-facing artefacts must accompany that example: + +- a **product page** — the human-readable introduction to Specorator Runtime +- a **product demo** — a static, self-contained rendering of a Hello World run + +Both files are static HTML. They require no build step, no server, and no JavaScript framework. They are hosted on **GitHub Pages** served from the `docs/` directory of the `main` branch. + +--- + +## Deliverables + +### 1. `docs/index.html` — product page + +A single static HTML file. No external dependencies that require a build step. Inline styles are acceptable; a single linked stylesheet (`docs/style.css`) is also acceptable. + +Must include: + +- Hero statement — one sentence, jargon-free, that explains what Specorator Runtime is +- Problem → Solution narrative — 3–5 sentences +- Key capabilities — outcome-oriented bullet list (not feature names) +- Integration map — how the runtime connects to Specorator UI, `agentic-workflow`, and `agentonomous` +- Current status — clearly states this is `v0.1.0`, the Hello World release +- Link to the GitHub repository +- Link to the product demo (`demo.html`) + +Must NOT include: + +- API documentation +- Marketing language disconnected from the PRD +- Anything that requires a server, CMS, or build pipeline to render + +--- + +### 2. `docs/demo.html` — product demo + +A single static HTML file that presents a rendered execution trace of the Hello World scenario. + +Must include: + +- A brief intro (2–3 sentences) explaining what the viewer is looking at +- The full ordered event log from a Hello World run, rendered as a visual timeline or structured list: + 1. `workflow.started` + 2. `task.created` + 3. `task.ready` + 4. `agent.invoked` + 5. `agent.completed` + 6. `artifact.created` + 7. `task.completed` + 8. `workflow.completed` +- For each event: event name, a one-sentence description of what it means, and the key payload fields +- The artifact produced by the stub agent, displayed inline +- Session state snapshot after completion (id, state: `completed`, task count, artifact count) +- Link back to the product page (`index.html`) + +Must NOT include: + +- A live runtime — this is a static snapshot, not an interactive executor +- External API calls +- Any dependency that prevents the file from opening directly in a browser via `file://` + +--- + +### 3. GitHub Pages configuration + +- Source: `docs/` directory on the `main` branch +- No custom domain required for `v0.1.0` +- Expected URL: `https://luis85.github.io/specorator-runtime/` +- The repository's **GitHub Pages** setting must be configured to serve from `docs/` on `main` +- A CI workflow `pages.yml` must be added under `.github/workflows/` that validates the pages are reachable after every push to `main` + +#### `pages.yml` requirements + +Trigger: `push` to `main` (paths: `docs/**`) + +Steps: +1. Checkout +2. Verify `docs/index.html` exists +3. Verify `docs/demo.html` exists +4. (Optional) Run an HTML validator (e.g. `html-validate` or `tidy`) if one is available in the CI environment + +--- + +## Acceptance Criteria + +- [ ] `docs/index.html` committed and renders correctly in a browser opened via `file://` +- [ ] `docs/demo.html` committed and renders correctly in a browser opened via `file://` +- [ ] All 8 Hello World events are present and correctly ordered in `docs/demo.html` +- [ ] The stub agent artifact is visible in `docs/demo.html` +- [ ] GitHub Pages is configured to serve from `docs/` on `main` +- [ ] `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 +- [ ] `.github/workflows/pages.yml` exists and passes on `main` +- [ ] Both HTML files pass the cold-reader test: a newcomer can understand the project within 60 seconds + +--- + +## Constraints + +- No build step — both files must be valid HTML as committed; no transpilation or bundling +- No external runtime dependencies — CSS from a CDN (e.g. a single font or reset) is acceptable, but the pages must degrade gracefully if offline +- Terminology must be consistent with the PRD and `docs/product-page.md`: _session_, _event bus_, _task_, _agent_, _artifact_, _workflow_ +- The product demo content must match the actual output of `examples/hello-world/index.ts` — it is not a fictional example + +--- + +## Related + +- Issue #8 — Milestone: Hello World +- Issue #2 — Product presence (`docs/product-page.md` is the source document for `docs/index.html`) +- `examples/hello-world/` — the runnable source that the demo page renders statically +- PRD §11 — UX Entry Points From c4ea45d28cd59ad736627e0e1838795960254478 Mon Sep 17 00:00:00 2001 From: Luis Mendez <3923861+Luis85@users.noreply.github.com> Date: Sun, 10 May 2026 12:56:08 +0200 Subject: [PATCH 2/2] spec(hello-world): align github-pages spec with ratified event taxonomy, CI gate policy, and SAO integration map MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Event names updated to match #15/#21 RuntimeEvent union (session.*, agent.spawned, command.dispatched) - pages.yml redesigned with hard/soft gate split per #29 (existence + HTML validity = hard; reachability = soft with retry) - Demo content pinned to actual hello-world run output — explicit note to verify against #15 before merge - Integration map includes SAO orchestrator engine - Added #14/#15/#21/#29 cross-references for authoritative sources --- specs/hello-world/github-pages.md | 86 +++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 22 deletions(-) diff --git a/specs/hello-world/github-pages.md b/specs/hello-world/github-pages.md index 1282d47..b00ab45 100644 --- a/specs/hello-world/github-pages.md +++ b/specs/hello-world/github-pages.md @@ -7,19 +7,27 @@ issue: "#8" stage: specification status: draft created: 2026-05-03 +updated: 2026-05-10 +inputs: + - "#14 — architecture proposal (public API surface)" + - "#15 — data model (RuntimeEvent union — authoritative event names)" + - "#21 — failure-event taxonomy" + - "#29 — CI workflow (hard vs. soft gate policy)" ``` --- ## Context -The Hello World milestone (issue #8) includes a runnable example that demonstrates the full end-to-end execution scenario. Two public-facing artefacts must accompany that example: +The Hello World milestone (issue #8) includes a runnable example that demonstrates the first end-to-end execution scenario. Two public-facing artefacts must accompany that example: - a **product page** — the human-readable introduction to Specorator Runtime - a **product demo** — a static, self-contained rendering of a Hello World run Both files are static HTML. They require no build step, no server, and no JavaScript framework. They are hosted on **GitHub Pages** served from the `docs/` directory of the `main` branch. +> **Living spec notice:** The event names, payload shapes, and API surface shown in this spec are preliminary. Authoritative definitions are resolved in #14 (architecture), #15 (data model), and #21 (failure-event taxonomy). The demo page content (`docs/demo.html`) must be verified against the actual output of `examples/hello-world/index.ts` before this spec is considered complete. Update the event table below when #15 §7 closes. + --- ## Deliverables @@ -28,12 +36,14 @@ Both files are static HTML. They require no build step, no server, and no JavaSc A single static HTML file. No external dependencies that require a build step. Inline styles are acceptable; a single linked stylesheet (`docs/style.css`) is also acceptable. +Source document: `docs/product-page.md` (issue #2) is the canonical content source for this file. The HTML is a rendered version of that document. + Must include: - Hero statement — one sentence, jargon-free, that explains what Specorator Runtime is - Problem → Solution narrative — 3–5 sentences - Key capabilities — outcome-oriented bullet list (not feature names) -- Integration map — how the runtime connects to Specorator UI, `agentic-workflow`, and `agentonomous` +- Integration map — how the runtime connects to Specorator, `agentic-workflow`, `agentonomous`, and the SAO orchestrator engine - Current status — clearly states this is `v0.1.0`, the Hello World release - Link to the GitHub repository - Link to the product demo (`demo.html`) @@ -48,23 +58,31 @@ Must NOT include: ### 2. `docs/demo.html` — product demo -A single static HTML file that presents a rendered execution trace of the Hello World scenario. +A single static HTML file that presents a rendered execution trace of the Hello World scenario. This is a **static snapshot of a real run** — not a fictional example. The content must match the actual output of `examples/hello-world/index.ts`. Must include: -- A brief intro (2–3 sentences) explaining what the viewer is looking at -- The full ordered event log from a Hello World run, rendered as a visual timeline or structured list: - 1. `workflow.started` - 2. `task.created` - 3. `task.ready` - 4. `agent.invoked` - 5. `agent.completed` - 6. `artifact.created` - 7. `task.completed` - 8. `workflow.completed` -- For each event: event name, a one-sentence description of what it means, and the key payload fields +- A brief intro (2–3 sentences) explaining what the viewer is looking at and that this is a static snapshot +- The full ordered event log from a Hello World run, rendered as a visual timeline or structured list + + **Event names must match the ratified `RuntimeEvent` union from #15 §7 and #21.** Preliminary expected sequence: + + | # | Event | What it means | + |---|---|---| + | 1 | `session.started` | A new runtime session was created and the workflow package loaded | + | 2 | `agent.spawned` | An agentonomous agent was instantiated as an ECS entity in the session | + | 3 | `task.created` | A task was registered in the session task graph | + | 4 | `task.ready` | Task prerequisites met; the agent may claim it | + | 5 | `command.dispatched` | A command was dispatched to the agent for execution | + | 6 | `artifact.created` | The agent produced a typed artifact output | + | 7 | `task.completed` | The task transitioned to `completed` state | + | 8 | `session.stopped` | The session was cleanly stopped and the lifecycle concluded | + + > Verify and update this table against `examples/hello-world/index.ts` output and #15 §7 before merging to `main`. Do not ship fictional event names. + +- For each event: event name, a one-sentence description of what it means, and the key payload fields — at minimum: `eventId`, `traceId`, `seq`, `type` - The artifact produced by the stub agent, displayed inline -- Session state snapshot after completion (id, state: `completed`, task count, artifact count) +- Session state snapshot after completion (`id`, `state: 'stopped'`, task count, artifact count) - Link back to the product page (`index.html`) Must NOT include: @@ -81,17 +99,31 @@ Must NOT include: - No custom domain required for `v0.1.0` - Expected URL: `https://luis85.github.io/specorator-runtime/` - The repository's **GitHub Pages** setting must be configured to serve from `docs/` on `main` -- A CI workflow `pages.yml` must be added under `.github/workflows/` that validates the pages are reachable after every push to `main` +- A CI workflow `pages.yml` must be added under `.github/workflows/` #### `pages.yml` requirements +Per the CI gate philosophy in #29 — hard gates block merge; soft gates retry once and report without blocking: + Trigger: `push` to `main` (paths: `docs/**`) -Steps: +**Hard gates** (fail the job immediately if violated): 1. Checkout 2. Verify `docs/index.html` exists 3. Verify `docs/demo.html` exists -4. (Optional) Run an HTML validator (e.g. `html-validate` or `tidy`) if one is available in the CI environment +4. Run HTML validator (e.g. `html-validate`) on both files — both must be valid HTML5 +5. Verify neither file contains `