docs: hoist mx::api doctrine into a skill - #335
Merged
Conversation
Move docs/ai/design/api-design-principles.md into a new mx-api-doctrine skill whose description tells agents they MUST read it before touching mx::api. Add the missing doctrine: no UB reachable from the interface, no exceptions (never for failed preconditions), Result quarantined to the DocumentManager boundary, the choice-type pattern (TimeChoice / MarkDataChoice), and comment rules (write for users authoring notation, never from the round-trip harness's perspective). Replace the AGENTS.md digest with a pointer (net -8 lines), repoint the add-feature skill and Copilot review instructions, and delete the mx-architecture skill.
webern
commented
Jul 12, 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.
Human Summary
I asked Fable, while I still have access to it, to improve Agent performance with better instructions putting them in places more likely to be read and incorporating some of my latest pet-peeves.
Summary
Agents were not reading docs/ai/design/api-design-principles.md, and several recurring review
themes were written down nowhere. This PR moves the doctrine to where agents actually look and
captures the missing rules, without growing AGENTS.md (it shrinks by 8 lines).
anything in the api layer. It contains the seven design principles (moved verbatim from the
deleted doc) plus the previously unwritten doctrine:
MusicXML files. Round-tripping is how we develop the api, not what it is for. Header comments
explain notation semantics and how MusicXML encodes them; "source"/"preserved" framing is
allowed only on true fidelity knobs. No documenting what is not modeled, no banner comments
(from review feedback on fix: preserve staff-scoped
staff-layout number="N"#326, feat: add score-part groups, measure-numbering multi-rest/system attrs, and swing to mx::api #333, feat(api): support the full time-signature model #321).unreachable from the public interface, nothing throws across the api boundary (never for a
failed precondition), and Result stays quarantined at the DocumentManager I/O boundary.
accessors, default-constructed wrong-kind fallback, auto-collapse, common case kept prominent
in its own header), from the feat(api): support the full time-signature model #321 redesign and the feat: support multi-note tremolos in mx::api #330 review.
api-headers review instructions repointed and extended with the same rules.
mx-specific facts live elsewhere (gen design in gen/DESIGN.md; the error-handling stance is now
concrete doctrine in the new skill).
Net -33 lines repo-wide.
Testing
References
staff-layout number="N"#326, feat: support multi-note tremolos in mx::api #330, feat: add score-part groups, measure-numbering multi-rest/system attrs, and swing to mx::api #333