diff --git a/specs/hello-world/github-pages.md b/specs/hello-world/github-pages.md new file mode 100644 index 0000000..b00ab45 --- /dev/null +++ b/specs/hello-world/github-pages.md @@ -0,0 +1,168 @@ +# 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 +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 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 + +### 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. + +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, `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`) + +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. 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 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: 'stopped'`, 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/` + +#### `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/**`) + +**Hard gates** (fail the job immediately if violated): +1. Checkout +2. Verify `docs/index.html` exists +3. Verify `docs/demo.html` exists +4. Run HTML validator (e.g. `html-validate`) on both files — both must be valid HTML5 +5. Verify neither file contains `