fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(work): decompose platform-retrofit and walking-skeleton epics

Browse Source 
platform-retrofit: 8 stories / 18 tasks (spec bundle into docs/product,
single-version release-please before deletions, demo feature removal,
web-next auth shell, optional cores, work-tree archive, library traces,
agent-doc rewrite). walking-skeleton: 11 stories / 28 tasks across
workspaces, discovery, core-runner-protocol, runner app, editor, and
the flagship connect-to-selection e2e; builds on platform-retrofit
(prose dependency note — cross-epic frontmatter unsupported).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
This commit is contained in:
Danijel Martinek
2026-07-12 12:28:51 +02:00
parent 442b70476c
commit 99180887f3
22 changed files with 1286 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/work/epics/walking-skeleton/02-core-runner-protocol/_story.md Normal file
View File

@@ -0,0 +1,44 @@
---
id: 02-core-runner-protocol
epic: walking-skeleton
title: core-runner-protocol package — versioned, zod-validated message schemas
type: technical-story
status: todo
feature: core-runner-protocol
depends-on: []
blocks: [04-runner-app-protocol-clone-install, 09-editor-package]
created: 2026-07-12T10:24:14Z
---
## Goal
Ship `@repo/core-runner-protocol`: versioned, zod-validated message schemas for the runner protocol (hello/ready, clone, install, scan, adapter-start, render-frame, status/error events) shared by features, editor, and runner, so the three sides cannot drift apart silently (PRD user story 7).
## Why
The runner protocol is plain WS/JSON, not tRPC (ADR-027) — which means nothing type-checks the wire unless every message is zod-parsed against one shared schema package. Every other story in this epic (runner app, provisioner, lifecycle events, editor frame) consumes these schemas; they must exist first.
## Done when
- `@repo/core-runner-protocol` exists as a green optional core package.
- Message envelope carries `protocolVersion: "0"` and a workspace-scoped auth token (PRD Implementation decisions).
- Zod-validated schemas exist for: hello/ready, clone, install, scan, adapter-start, render-frame, and status/error events — status events carry stage + elapsed (ui-gap §5 staged-progress), error events carry named causes.
- Unit tests cover accept/reject round-trips for every message type (`.strict()` schemas reject unknown fields).
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass after each task.
## In scope
- `pnpm turbo gen core-package runner-protocol` scaffold.
- Versioned envelope + the message schema set listed above.
- Schema unit tests.
## Out of scope
- The WS server/client implementations (stories 04 and 07) — this package is schemas only.
- Protocol version negotiation beyond the pinned `"0"` (later PRDs).
- Watch/HMR messages (`discovery-and-library`).
## Tasks
- [ ] Run `pnpm turbo gen core-package runner-protocol` → green `@repo/core-runner-protocol` package shell.
- [ ] Add the versioned protocol surface: message envelope (`protocolVersion: "0"`, workspace-scoped auth token) + zod-validated `.strict()` schemas for hello/ready, clone, install, scan, adapter-start, render-frame, and status/error events (staged progress carries stage + elapsed; errors carry named causes), with unit tests covering accept/reject round-trips for every message type.