This repository defines the formats of the documents people write for Musher, and the rules for interpreting them: normative prose, the JSON Schemas built from it, example documents, and language-neutral conformance corpora. The platform API and Musher's internal data models are specified elsewhere. An implementation that disagrees with what is published here is defective.
Status: stable. Every family has released 1.0.0, and
published.json lists every release. What makes a version
released: Draft or released.
| Family | Specification | Front page | Rendered prose |
|---|---|---|---|
| core | core/v1/spec.md |
README | core v1 |
| component | component/v1/spec.md |
README | component v1 |
| blueprint | blueprint/v1/spec.md |
README | blueprint v1 |
| listing | listing/v1/spec.md |
README | listing v1 |
The rendered prose is generated and informative. What each family describes and how they depend on one another is set out in specifications/README.md, and which of its parts are normative in What is normative.
| I want to… | Start at |
|---|---|
| validate a document, or bind a schema in my editor | Using the schemas |
| implement a parser or validator | Implementing a family, then the fixture format |
| look up a rule by its requirement ID | Requirement traceability |
| know whether a version is released | Draft or released |
| know what counts as a breaking change | Compatibility review |
| change a specification | Contributing |
| understand why something was decided | Architecture decision records |
| report a vulnerability | Security policy |
| see every guide, by audience | Documentation index |
specifications/ one directory per family; each major version, v<N>/, releases on its own tag line
docs/ guides, governance, the fixture format, traceability, and decisions
tools/ non-normative build and check scripts (Bun and TypeScript)
taskfiles/ the tasks behind `task check`
.claude/ the agent brief, CLAUDE.md, for Claude Code
.config/ every linter, formatter, and hook configuration
.github/ contributing, security, rulesets, and workflows
published.json append-only ledger of every release (docs/publication.md#the-ledger)
task setup # install tooling and git hooks
task check # run every check CI runs, except the CI-only stepsRead CONTRIBUTING.md before opening a pull request, docs/conventions.md for how repository artifacts are named, and docs/governance.md for how decisions are made.
Apache-2.0. See also NOTICE.