@driftsys/markspec
v0.13.0
Published
Markdown flavor and toolchain for traceable industrial documentation
Maintainers
Readme
MarkSpec
A Markdown flavor for traceable industrial documentation, and a CLI toolchain that processes it.
Pre-1.0. The toolchain is functional end-to-end for authoring, validation, traceability, rendering, and editor / agent integration. The language specification and wire formats (compile-output JSON, lockfile) may still change without backward-compatibility shims until 1.0.
Tools
Authoring and validation
markspec fmt # stamp ULIDs, normalize attributes
markspec check # check broken refs, missing Ids, duplicates
markspec lint # prose analysis (modal verbs, EARS, passive, …)
markspec insert <type> # append a scaffolded entry to a file
markspec create <type> # scaffold a new entry block (stdout)
markspec next-id <type> # next available display ID for a typeTraceability and querying
markspec compile <paths> # build traceability graph → JSON
markspec show <id> # show one entry by display ID or ULID
markspec context <id> # walk the Satisfies chain upward
markspec dependents <id> # list entries that depend on an entry
markspec report <kind> # traceability matrix or coverage report
markspec export <format> # compile-graph → json, yaml, csvLockfile and external sync
markspec lock # generate or refresh markspec.lock
markspec sync status # group bound entries by remote_state
markspec sync log # tail per-system sync log (NDJSON)
markspec sync show <id> # full sync state for one bound entryProfiles and diagnostics
markspec profile show # show active profile chain
markspec doctor # project health checkRendering
markspec doc build # single document → PDF (Typst WASM)
markspec book build # multi-chapter → static HTML siteEditor and agent integration
markspec lsp # LSP server (stdio JSON-RPC)
markspec lsp install # print LSP config for vscode, neovim, zed
markspec mcp # MCP server (stdio JSON-RPC)
markspec mcp install # write/print MCP config for claude,
# copilot, cursor, opencode, vscodeNot yet implemented (registered but exit with an error):
markspec export reqif # ReqIF XML export
markspec book dev # live preview with hot reload
markspec deck build # slides → PDF via Touying/Typst
markspec deck dev # live slide previewModules
core/ ← parser, validator, compiler, reporter, formatter
render/ ← Typst WASM, entry block rendering, Mustache substitution, captions
book/ ← multi-file PDF + HTML book builder
deck/ ← Touying-based slide deck builder
cli/ ← subcommand handlers
lsp/ ← LSP server
mcp/ ← MCP serverOne binary. One install. Three rendering targets (document, book, deck).
Markdown extensions
MarkSpec extends CommonMark with constructs that render as plain Markdown on GitHub and GitLab — no tooling required to read.
Entry blocks — a list item with a display ID and an indented body:
- [SRS_BRK_0001] Sensor input debouncing
The sensor driver shall debounce raw inputs to eliminate electrical noise
before processing.
Id: 01HGW2Q8MNP3RSTVWXYZABCDEF\
Satisfies: SYS_BRK_0042\
Labels: ASIL-BEvery entry carries a single Id: attribute. A ULID value identifies an
identified entry (content the project authors); a URI value (urn:, doi:,
pkg:, https:, …) identifies a referenced entry (citation of an external
artifact). The entry's type (requirement, test, unit, standard, dependency, …)
is inferred by the active profile from the display-ID prefix (SRS_ →
type: software-requirement); compliance vocabulary comes from the active
profile.
In PDF output, entry blocks render as admonition-style blocks with
profile-driven color-coding by type, label pills on the title line, and italic
metadata with dashed-underline cross-references. See
docs/examples/entry-rendering.md for a
full showcase.
Table captions — emphasized paragraph above a pipe table:
_Table: Sensor thresholds_
| Sensor | Min | Max |
| -------- | --- | ---- |
| Pressure | 0 | 1023 |Figure captions — emphasized paragraph below an image:

_Figure: High-level architecture of the braking system_In-code entries — entries in doc comments, same format:
/// [SRS_BRK_0001] Sensor input debouncing
///
/// The sensor driver shall reject transient noise shorter
/// than the configured debounce window.
///
/// Id: 01HGW2Q8MNP3RSTVWXYZABCDEF \
/// Satisfies: SYS_BRK_0042 \
/// Labels: ASIL-B
#[test]
fn swt_brk_0001_debounce_filters_noise() {
// test implementation
}Mustache variables — {{project.name}} substitution from project.yaml,
resolved at build time.
MarkDesk
MarkDesk is a desktop authoring app for MarkSpec products. It lives in
apps/markdesk: a React and Vite UI in a Tauri v2
shell. The app starts markspec desk --serve as a sidecar and reads the product
through that local API. It writes an entry body only after the author accepts an
assistant's proposal. MarkDesk is in development and is not yet released. The
design is recorded in ADR-035.
Install
See docs/guide/installation.md for the VS Code
extension, the macOS / Linux install script, the
Windows PowerShell install script,
manual binary downloads, and the Deno install path.
License
Part of the DriftSys ecosystem.
Post-clone setup
Run ./bootstrap after git clone or git worktree add.
