From 1b826144cb2c03945e09d412d7af634058ce60aa Mon Sep 17 00:00:00 2001 From: Taras Mankovski <74687+taras@users.noreply.github.com> Date: Fri, 28 Aug 2026 21:24:29 -0400 Subject: [PATCH] Document the portable playground vision --- specs/markdown-agents-vision.md | 77 +++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/specs/markdown-agents-vision.md b/specs/markdown-agents-vision.md index 12f63d0e..aa206938 100644 --- a/specs/markdown-agents-vision.md +++ b/specs/markdown-agents-vision.md @@ -11,7 +11,12 @@ the authority for implemented behavior. ## North star Executable.md is the easiest way to write reliable, well-behaved, observable, -and composable agents whose source code is Markdown. +composable, and portable agents whose source code is Markdown. + +The playground is the primary authoring surface for that experience. A person +can develop and understand the same Markdown project locally or entirely in the +browser, without moving the workflow into a host-specific format or depending +on a mandatory cloud service. An agent document makes its orchestration readable. A reader can determine which instructions an agent receives, which model acts, what context crosses an agent @@ -22,6 +27,11 @@ The central product idea is: > The agentic control flow is the document. +The corresponding portability promise is: + +> Write once, understand everywhere, and run wherever the required capabilities +> are available. + Executable.md provides deterministic orchestration around nondeterministic model calls. It does not claim that model responses are deterministic. It makes the construction, ordering, boundaries, and provenance of those calls explicit. @@ -84,6 +94,61 @@ Observability describes the real execution rather than an agent's self-report. - Instructions, skills, tools, context transformations, and complete agents can be composed explicitly. +### Portable + +- The Markdown project and its components remain the canonical workflow source + in every authoring and execution host. +- The same project version identifies the same immutable workflow definition + locally and in the browser. +- Local and browser hosts preserve the same control-flow, journaling, + checkpoint, replay, cancellation, and failure semantics. +- A workflow declares the capabilities it requires. A host either supplies + those capabilities through explicit adapters or refuses before work begins + with an actionable explanation. +- Portability does not imply identical authority. Local filesystem access, + browser storage, credentials, providers, and external services remain + explicit host capabilities. +- Execution evidence can be exported and inspected across hosts. Continuing + from exported evidence creates a new, linked history rather than reviving or + mutating the original execution. + +## Playground experience + +The playground brings authoring, execution, and revision into one inspectable +workspace. It is not inherently a hosted service: the same experience can be +provided by a local host or by an entirely client-side browser host. A remote +host may be selected explicitly when a workflow requires capabilities that +neither one can provide, but it is never a silent fallback. + +The intended authoring loop is: + +1. A person states the outcome and constraints. +2. An agent proposes or edits the executable Markdown project. +3. The person inspects the source, changes, and required capabilities. +4. A specific immutable version runs as a constrained trial. +5. Structured execution evidence guides the next revision. +6. A separately authorized version may run with real capabilities. + +The source project is the durable expression of intent and behavior. +Conversation, approvals, revisions, executions, and evidence are linked records; +they do not become hidden workflow state. Each accepted edit produces a new +immutable workflow definition, so evidence always identifies the exact behavior +that produced it. + +A trial is described by its actual capability boundary. The playground does not +call an execution a simulation when it can still cause unmodelled external +effects. Promotion to real capabilities is an explicit authorization of a +specific workflow version, not an ambient mode switch. + +The browser host runs the execution engine in a worker and owns browser-local +durable storage. The local host runs the same semantic layer with local storage +and local capability adapters. Shared production modules do not detect which +runtime is active; host entrypoints install the contextual implementations. + +Text is the canonical editing surface. Diagrams, graphs, forms, and other +semantic views may project the Markdown project and propose source changes, but +they do not introduce a second hidden workflow representation. + ## Authoring model The following examples express the intended experience. They are not a frozen @@ -228,7 +293,13 @@ its declared props: 6. What happens when it fails or returns invalid output? 7. Why did the workflow take a branch or stop? 8. What evidence in the execution record supports those answers? +9. Does this project version retain the same workflow meaning locally and in + the browser? +10. Which required capabilities does each host provide or refuse before work + begins? +11. Can another host inspect the source and evidence without a proprietary + project representation? If those answers depend on hidden host behavior, implicit transcript sharing, or -an agent's own account of what it did, the design does not satisfy the product -goal. +an agent's own account of what it did, or an undocumented host-specific project +format, the design does not satisfy the product goal.