SpecMgr

biz.dfch.SpecMgr

An artifact manager for system specifications.

This project is an MCP server that you can use to manage different specification artifacts — see Concepts for the full list of artifact types and how they relate, and MCP Server / docs/MCP.md for the tool/resource/prompt reference.

The MCP server (and the management CLI) are optional. You install them as "extras" (see Installation).

Table of Contents

• Concepts
• Installation
• CLI Usage
• UC → PlantUML Diagrams
• Reference Graph Diagrams
• MCP Server
• Installing the specmgr Harness Files
• Usage
• Referencing Artifacts
• Multi-Language Artifacts
• Development
• Testing
• Make a Release
• License

Concepts

Every artifact is a plain markdown file with a YAML frontmatter block on disk — git-friendly, diffable, and readable/editable by hand. The filesystem is always the source of truth; the MCP server wraps it with structured, validated read/write/list/status tools (see Usage).

A typical spec effort starts with a QA elicitation interview, which surfaces GOLs (goals) and PRBs (problems). Those inform REQs and UCs, which get risk-assessed (RSK) and backed by DECisions, verified via one VCR per REQ/UC (each collecting its acceptance criteria), and tracked via TSK task lists. A SYSRS ties all of it together into one ISO/IEC/IEEE 29148-structured specification. SOP and FEAT support the process itself rather than sitting in this chain, and TXT is the free-form catch-all that likewise sits outside it (any markdown that does not warrant a dedicated artifact type).

QA -> GOL / PRB -> REQ / UC -> RSK / DEC -> TSK, VCR -> SYSRS (aggregates all)

Installation

As a library only (no CLI, no MCP server):

pip install biz-dfch-specmgr

With the CLI:

pip install "biz-dfch-specmgr[cli]"

With the MCP server:

pip install "biz-dfch-specmgr[mcp]"

With semantic-similarity search (find_related/find_similar_text, see Semantic Similarity Search below), add the similarity extra on top of mcp:

pip install "biz-dfch-specmgr[mcp,similarity]"

Or with uv:

uv add "biz-dfch-specmgr[cli,mcp,similarity]"

CLI Usage

With the CLI you can generate schema and documentation. We use these commands in pre-commit hooks and ci.yml.

_No domain document-management commands (create/update/status/etc.) exist in the CLI yet — those are currently MCP-only, see MCP Server. The CLI covers version, mcp (below), a handful of cross-cutting/doc-generation commands, and the diagram commands — UC → PlantUML (see UC → PlantUML Diagrams) and reference-graph (see Reference Graph Diagrams) (specmgr --help for the full list)._

specmgr version

specmgr lint [paths]... [--type T [--dir D]] [--all] [--skip-unrecognized] # in-tree spec artifact parseability gate: full model-level parse of the paths (type inferred from the layout, --type overrides) or a --type/--all sweep (exit 0 parsed / 1 parse failure or missing mcp extra / 2 usage-or-resolution)

specmgr lint requires the mcp extra, like specmgr diagram (the decoupling is tracked as issue #238).

UC → PlantUML Diagrams

Specmgr can turn UC artifacts into PlantUML diagrams — deterministic use-case and package diagrams, plus sequence diagrams attributed by the agent flow.

Sequence diagrams (agent path). The generate_uc_sequence_diagram MCP prompt (in OpenCode: the self-triggering uc-diagram skill or the /uc-diagram command) runs the frozen rulebook flow: the agent attributes every UNATTRIBUTED message (asking via the question tool when not confident), validates with validate_plantuml, and writes diagrams/uc/ .sequence.puml host-natively — no specmgr tool writes .puml files.

**Deterministic diagrams + tooling (CLI, deterministic-only — the CLI never creates, overwrites, or diffs the agent-owned *.sequence.puml files):**

specmgr diagram uc <id>|all --out <dir> [--check]  # per-UC <id>.usecase.puml + package.puml; --check byte-diffs without writing (exit 0 ok / 1 diff / 2 usage-or-render error)

specmgr plantuml-check # validates any .puml through the chain (exit 0 valid / 1 invalid / 2 source misconfigured-or-unavailable / 3 inconclusive) specmgr plantuml-encode # offline classic SoWkI… encoding

Validation source. Exactly three env vars, the first one set is the only source used (no fall-through, no PATH discovery, no public default): SPECMGR_PLANTUML_JAR (a plantuml.jar path), SPECMGR_PLANTUML_BIN (an executable speaking the PlantUML CLI contract), SPECMGR_PLANTUML_URL (a PlantUML server base URL). All unset ⇒ offline structure-only validation. Diagram content is never sent to plantuml.com unless you set that URL.

The normative rulebook ships as the specmgr://uc/plantuml resource; the full MCP surface is in docs/MCP.md.

Reference Graph Diagrams

Specmgr can render the deterministic cross-reference network between its artifacts (the tag vocabulary behind the list_references tool) as a PlantUML component diagram — one node per artifact (label = the document title, truncated to the SPECMGR_DIAGRAM_MAX_TITLE limit, default 40), a stereotype + colour per artifact type (a frozen 15-entry palette), nodes grouped into per-domain curly component "TYPE" { … } domain groups, one label-free edge per unique reference ({src} --> {dst}), every edge that lies on a cycle (self-loops and same-SCC ≥ 2) drawn with a red label-free -[#red]-> arrow, and every reference whose target cannot be resolved on disk drawn as a top-level < > node. Fully deterministic: the same registry and the same arguments always emit byte-identical source.

MCP tools. get_reference_diagram(type, id, depth=1, reverse=False, include_feat=True, title=None) renders one source document's reference neighbourhood (the forward walk to depth, 1..5; reverse=True adds the direct incoming references, additive and direct-only); get_reference_diagram_all(include_feat=True, title=None) renders the registry-wide graph. Both return the PlantUML source directly (no file writes); the scoped tool accepts all 14 domains (adr included) and returns the non-raising ParseFailureResult for an existing-but-broken source; the registry-wide tool never raises for content.

CLI (writes the artifact, deterministic-only):

specmgr diagram refs <type> <id> [--depth N] [--reverse] [--no-feat] [--title T] [--out diagrams/refs] [--check]  # scoped → <id>.refs.puml

specmgr diagram refs all [--no-feat] [--title T] [--out diagrams/refs] [--check] # registry-wide → reference-graph.puml

--no-feat drops every FEAT node except the explicitly requested source (then every edge touching a dropped node). Exit codes: 0 written / no diff, 1 a --check diff (a missing file counts as differing) or the missing mcp extra, 2 a usage-or-resolution error (wrong-format type/id/depth — a bare feat-NNN is rejected, use list_feat to discover the exact id — a missing source, an existing-but-broken source, all combined with a source). Written artifacts carry no structure-only header (checker-clean by construction).

Validation. specmgr plantuml-check (or the validate_plantuml MCP tool over the source) validates the diagram through the same strict chain as the UC diagrams (the three SPECMGR_PLANTUML_* source env vars, see UC → PlantUML Diagrams; all unset is the offline structure-only floor).

Label limit. SPECMGR_DIAGRAM_MAX_TITLE (an int, default 40) bounds the resolved-node H1 labels (word-boundary cut + …; a set-but-invalid value falls back to 40); the @startuml diagram title is sanitized but never truncated. Its set/valid/default/resolved status is reported by the diagram section of the specmgr://config resource (the raw value is never disclosed).

The normative rulebook ships as the specmgr://reference-graph resource; the full MCP surface is in [docs/MCP.md](doc