docs: rewrite course authoring guide as procedural LLM-facing instructions#70
Merged
Conversation
…tions Convert AGENTS.md prose to rules/tables and trim runtime-internal reference (adapter spec citations, xAPI internals) that course authors never write. 1785 -> 1502 lines; all code examples and prop tables kept. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The scaffolded root CLAUDE.md/AGENTS.md aren't immutable pointers — they carry a Project notes section for user-provided standards (#68). Updates don't overwrite them. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The GitHub link resolved to the root monorepo dev guide; point it at packages/tessera-learn/AGENTS.md. Correct the "guide at the workspace root" wording to reflect the pointer model, and add the missing useCompletion hook to the included-hooks list. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The rewrite documented the runtime audit as `pnpm exec tessera a11y`, but the scaffolded workspace exposes a `pnpm a11y <course>` script and the workspace README already uses that form. Switch the guide to `pnpm a11y <course>` and list a11y among the reserved script names so all the authoring docs agree. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
Summary
Rewrites
packages/tessera-learn/AGENTS.md(the course authoring guide) into a procedural instruction set for the LLM agents that actually consume it, rather than human-facing prose. The guiding test for every sentence: does it change what the agent writes? If not, it was cut.1785 → 1502 lines. All code examples and prop/type tables are preserved verbatim — they're the most actionable content.
What changed
LMS Adapter Reference(~100 lines) →LMS behaviour(~30): dropped spec citations (§9.x), interaction encoding, API-discovery, and other pure runtime internals an author never writes; kept an author-relevant differences table + local-testing table.Custom xAPI(~130 → ~75): kept config/call shapes and the per-mode table; replaced the actor-priority pseudocode, retry narrative, and per-mode caveat essays with a tight Gotchas list.#lms-adapter-reference→#lms-behaviour,#data-contract-what-the-lms-sees→#data-contract) and updated all references — verified no dead internal links.Notes
patchchangeset included.prettier --checkpasses.