docs: the a2learn format draft - #74
Draft
adamstankiewicz wants to merge 4 commits into
Draft
Conversation
Three sketch documents defining the agent-to-learning format as data riding existing protocols: surface (a profile of A2UI — flat components, bindTo references, the WidgetResult contract, namespaced learning extensions that plain A2UI renderers safely ignore), manifest (the registry/marketplace listing: verified standards alignment, pedagogy metadata, two-tier content/code trust split, provenance with reviewer attestations), and events (payload shapes with two transport bindings, AG-UI and MCP Apps, plus the normative two-tier interaction rule). Every section is tagged Shipped / Prototype / Planned so the spec formalizes reality rather than aspiration. Prose only — no schemas, no validator, no src/ changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, changelog The precision pass, not a feature pass. conformance.md makes conformance claimable: four classes (Producer, Renderer, Registry, Host) with RFC 2119 requirements distilled from statements previously scattered as narrative, plus versioning/extension rules and a public 1.0 gate (two independent Renderer implementations + fixtures + a two-month stability window). considerations.md gives the security/privacy/a11y sections an education spec owes its adopters first — the catalog trust boundary as invariant, the two-tier threat-model split, both prompt-injection doors, and the WidgetResult-is-an-education-record division of FERPA-shaped responsibility (content and people never in the same artifact). CHANGELOG.md starts the breaking-change ledger. README gains the RFC 2119 conventions note. Still prose only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The docs predate the labels-are-earned rule and said 'spec' throughout while the PR body and landing promise 'a format, not a specification — it earns the second word when a second implementation exists.' Now the README states that rule itself, and every self-reference says format. References to other projects' specifications (A2UI, AG-UI) stay as they are — those earned the word. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
adamstankiewicz
marked this pull request as draft
August 30, 2026 18:41
Owner
Author
|
Converted to draft deliberately: the format docs don't ship until the OSS solution actually uses the format — the README's own "implementation first" lesson, applied to itself. Un-drafts when phase 2 of #79 lands, i.e. when:
At that point every normative statement in these docs has a producer in 🤖 Generated with Claude Code |
…g K-12
`gradeBand: {min, max}` was normative and numeric, so it could only ever
describe K-12 grade levels; an undergraduate year or a new-hire cohort has
no honest value to put in it. `audience` is a list of scheme-scoped label
sets, which is the shape `standards[]` already uses — the naming authority
travels with the value, so `"4"` is unambiguous once `scheme` says which
system named it.
Safe because nothing consumes the field: the reference implementation's
find_activity writes gradeBand into the manifest and never reads it back,
and its ranking scores plannerDescription and assess-anchors, not audience.
No producer outside this repository emits it, so the change is a rename in
an unmerged draft rather than a break for anyone.
Only `k12-us` is registered. Higher-ed and professional schemes are
structurally supported but deliberately unnamed — the format documents what
a producer emits today, and none emits them yet.
`purposes` is stated as an open vocabulary in the same pass, so the enum
that would need a new beat for workplace practice isn't frozen shut.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 30, 2026
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.
What & why
The a2learn document format draft under
docs/a2learn/: the surface (drafted as an A2UI profile) plus the manifest (verified standards, pedagogy, accessibility and language declarations, provenance), with conformance classes and a changelog. Deliberately a format, not a specification — it earns the second word when a second implementation exists.Latest push —
audiencereplacesgradeBand. The manifest's audience field was a{min, max}integer range, which can only describe K-12 grade levels: an undergraduate year or a new-hire cohort has no honest value to put in it. It is now a list of scheme-scoped label sets —[{ "scheme": "k12-us", "values": ["4", "5", "6"] }]— carrying the naming authority with the value the waystandards[]already carriessourcealongsidecode, so"4"is unambiguous instead of meaning grade 4 here and year 4 elsewhere. Onlyk12-usis registered: higher-ed and professional schemes are structurally supported but deliberately unnamed, because the format documents what a producer emits today and none emits them yet.pedagogy.purposesis stated as an open vocabulary in the same pass, so the enum that would need a new beat for workplace practice isn't frozen shut.Type of change
Breaking or contract changes
One breaking change within the draft, recorded in
CHANGELOG.mdwith the migration an implementer needs:manifest.gradeBand→manifest.audience(see above). Done now rather than after v0 precisely because contracts freeze — no producer outside this repo emitsgradeBand, so today it is a rename in an unmerged draft rather than a break for anyone.Not filed as an issue first: the issue-first rule protects third parties depending on a shipped contract, and debating a field name on a pre-v0 format with one implementation is the standards-first failure mode this draft's own README warns against. The reasoning lives here and in the changelog instead. Once the format gains a producer (#79 phase 2), changes fall under the normal rule.
How it was verified
audiencerename cross-checked against the reference implementation:find_activitywrote the old field and never read it back, and ranking scoresplannerDescriptionand the assess anchors, so nothing consumed itAuthorship
package.json/pnpm-lock.yamlchanges🤖 Generated with Claude Code