docs(spec): record the Markdown Agents product vision#106
Merged
Conversation
Non-normative product direction for agent authoring: the agentic control flow is the document. Deterministic orchestration around nondeterministic model calls — named agents, explicit instructions and context as workflow data, bounded visible control flow, execution records that describe the real run, and a design test for future work.
PR #106: docs(spec): record the Markdown Agents product vision1 files, +223 / -0 Scope🟡 Large PR with no linked issue. Structural✅ No structural bloat detected. Slop✅ Slop indicators look low. Static Analysis✅ Oxlint found no issues. CorrectnessNo extraneous code patterns detected. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The repo specifies how the runtime behaves (executable-mdx-spec) and how
releases ship (release-process-spec), but not where the product is going. The
design conversations keep re-deriving the same principles — explicit
instructions, visible control flow, observable execution — without a recorded
direction to test against.
Approach
Add
specs/markdown-agents-vision.md: a non-normative product-directiondocument for agent authoring. North star — Executable.md is the easiest way to
write reliable, well-behaved, observable, and composable agents whose source
code is Markdown; the agentic control flow is the document. It records the
product qualities, the intended authoring model (named agents, structured
samples, bounded loops), context-as-workflow-data, the foundation/agent-layer
split, the relationship to Agent Skills, and an eight-question design test.
It explicitly defers to the executable MDX specification for implemented
behavior.
Scope confirmation
New abstractions (if any)
None — documentation only.
New dependencies (if any)
None.
New tests (if any)
None.