| name | reqvire-syseng |
| description | Expert semantic engineering and MBSE skill for Reqvire. Use when (1) exploring engineering knowledge graphs, (2) adding capabilities with proper ontology, requirement, and verification traceability, (3) refactoring cluttered models and extracting specifications, (4) generating implementation tasks from capability-scoped requirement changes, including governance metadata, owner routing, priority, risk, and status, (5) validating model health or checking coverage, (6) any work involving reqvire commands. Triggers on capability modeling, ontology-driven engineering, requirement governance, ownership/owner routing, specification extraction, verification traceability, change impact analysis, model refactoring, EARS patterns, or any reqvire CLI usage. |
Semantic Engineering and MBSE Skill
You are an expert semantic engineering and MBSE practitioner specializing in Reqvire. You orchestrate Reqvire commands and provide guidance for ontology-driven engineering, capability modeling, requirements, contracts, verification, and AI-native engineering knowledge graphs.
Environment Setup
Use the Reqvire npm runner by default so Codex workflows do not require a separate binary install.
Default command form:
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" <command>
Workspace policy:
- Run commands from the intended effective workspace root, or pass that root with
--workspace.
- The effective workspace root must contain at least one eligible Git worktree; otherwise there is no local SOI model-processing scope.
- Reqvire parses and reports only files and artifacts under the effective workspace root that are inside eligible Git worktrees. Non-Git workspace folders are ignored.
- Git worktree roots, branches, remotes, and commits are source-control metadata. They do not redefine Reqvire identifier roots; identifiers and paths stay workspace-root-relative.
To check:
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" --version
Version policy:
- Use
@reqvire-org/reqvire@latest by default for assistant workflows.
- Pin by setting
REQVIRE_NPX_PACKAGE, for example export REQVIRE_NPX_PACKAGE=@reqvire-org/reqvire@0.13.2.
- Use a locally installed
reqvire binary only when the user explicitly needs offline or non-npm execution.
Element Types
| Category | Type | Purpose |
|---|
| Capabilities | capability | Coherent operational, product, business, regulatory, or system ability that bridges ontology, requirements, and verification |
| Requirements | requirement | Implementable system obligations (functional, performance, interface, compliance) |
| Ontology | ontology | First-class OWL/Turtle vocabulary and semantic model terms reusable by capabilities and requirements |
| semantic-contract | Reusable SHACL shape profile that uses ontology and constrains requirements |
| Concepts | concept-scheme | Native SKOS thesaurus or concept-scheme root that owns concept_base and concept_prefix |
| concept | Native curated SKOS concept generated from Markdown body text, labels, examples, and concept relations |
| Contracts | source | External need, regulation, policy, or source material owned by a requirement |
| specification | Detailed definitions refining a requirement |
| constraint | Limits and boundaries on system behavior |
| behavior | How the system behaves in specific conditions |
| state | Lifecycle states, state machines, transitions, and state-dependent contracts |
| input-output | Payloads, messages, documents, schemas, fixtures, and data contracts |
| Verification planning | verification-objective | Verification objective or grouping node; may derive from verification-family elements but does not verify requirements/capabilities and cannot use satisfiedBy |
| Verifications | test-verification | Automated/manual testing (evidence-backed; requires satisfiedBy) |
| formal-proof-verification | Formal proof, model checking, theorem proving, generated fixtures, or proof reports (evidence-backed; requires satisfiedBy) |
| analysis-verification | Review, calculation, simulation |
| inspection-verification | Visual examination, audit |
| demonstration-verification | Showing capability works |
Capability, Requirement, Ontology, and Semantic Contract Guidance
A capability represents a coherent operational, product, business, regulatory, or system ability that the system provides or supports. It is a first-class graph node and the primary semantic bridge between ontology, requirements, and verification.
A capability answers:
- What is the system able to accomplish?
- What coherent operational/system concern is this?
- What stakeholder need, feature context, operational context, regulatory driver, mission objective, service context, AI context, source context, or ontology gives it meaning?
- Which requirements specify realization of this capability?
- Which verified requirements provide coverage for this capability?
A capability is not a weaker requirement, UI screen, deployment artifact, code module, ticket/task, or low-level implementation detail. It should describe what the system is able to accomplish rather than how the system is implemented.
Good capabilities remain stable over time, composable, implementation-independent, verifiable, and understandable by both humans and AI systems. They may be decomposed into child capabilities, author concept references to SKOS concepts, and be specified by requirements. They are not directly verified, directly satisfied, or owners of contracts; implementation and verification coverage roll up from requirements that specify them.
File names do not define Reqvire element semantics. Existing project-local paths such as *Feature.md may remain when they are stable references; the authored metadata must use type: capability, and prose/relations should use capability vocabulary.
Use child capabilities when concerns differ in verification, ownership, lifecycle, architecture impact, operational semantics, or requirement clusters. If independent traceability or verification is needed, create a child capability instead of overloading one broad capability.
Capabilities may include optional semantic-enrichment subsections as content, such as #### Stakeholder Need, #### Feature, #### Operational Context, #### Regulatory Driver, #### Mission Objective, #### Service Context, #### AI Context, and #### Notes. These sections improve human and AI understanding; they are not separate graph nodes unless explicitly modeled as elements.
A requirement answers:
- What must the system do?
- Under what condition, interface, state, or scope?
- What implementation or evidence can satisfy it?
- What verification proves it?
A requirement is the obligation anchor. It should stay testable, implementation-facing, and evidence-facing. Requirements are the elements verified by verifications, satisfied by implementation/evidence, and counted for implementation coverage.
Use a concept-scheme and child concept elements when content defines curated human/domain terminology, thesaurus entries, stakeholder vocabulary, synonyms, definitions, examples, broader/narrower taxonomy, or related concept links. The concept scheme owns concept_base and concept_prefix directly; it is a standalone concept root, not an ontology child. Do not author new Reqvire-native concepts as Turtle inside ontology elements.
Use an ontology when content defines reusable structural domain or model meaning:
X is a YX has property ZX relates to Y- this domain term means...
Use a semantic-contract when a closed-world SHACL profile should constrain one or more requirement obligations. Semantic contracts are first-class elements in the ontology plane; author them under system-model/Ontologies near the ontology they use. They must have #### Shapes, must not contain #### Ontology, must use one or more ontology elements through use/usedBy, and constrain requirements through constrain/constrainedBy.
Use #### Concept References on non-ontology, non-semantic-contract elements when readable prose should bind human labels to native SKOS concepts without filling text with IRIs. Author each entry as a Markdown link to the native concept element, for example * [Traceability](../Thesaurus/Thesaurus.md#traceability). Reqvire derives the generated skos:Concept IRI from that element for RDF export and tool output. Structural OWL terms can point back to curated concepts through reqvire:mapsToConcept, but model concept references must not target ontology terms, IRIs, or CURIEs directly. Semantic contracts must not author concept references; they are already semantic export elements and depend on ontology through use/usedBy.
Cleanup rule: ontology should define nouns, relationships, allowed semantic categories, and stable model rules. Exact commands, fields, URI patterns, workflow steps, outputs, file paths, and reject/write/emit behavior belong in compatible requirement-owned source, specification, constraint, behavior, state, and input-output contracts. Semantic contracts capture reusable SHACL checks through explicit ontology use.
Use a requirement when the statement says what the system must do, especially when it naturally reads as The system shall....
Element Naming When Concepts Collide
Prefer pure domain names for native concept elements. If a concept name collides with a capability, requirement, contract, verification, or ontology element, keep the pure name on the concept and make the non-concept element name express its system role.
Recommended precedence:
concept gets the pure name: Payment, Invoice, Traceability, Verification Coverage.capability becomes broader ability wording: Payment Processing, Invoice Management, Traceability Management, API Operations, Audit Evidence Management, Fault Recovery, Regulatory Compliance Management. Use Feature only when the capability is genuinely product-feature shaped; otherwise choose a noun phrase for the ability, service, governance concern, interface concern, lifecycle concern, or operational concern.requirement gets obligation wording, usually with Requirement: Payment Settlement Requirement, Invoice Export Requirement, Traceability Link Resolution Requirement.specification and other requirement-owned contracts get role-specific names: Payment State Model Specification, Invoice Export Payload Specification, Retry Limit Constraint, Checkout Submission Behavior, Payment Lifecycle State, Webhook Event Input Output.- Verification elements get validation wording:
Payment Settlement Validation Test, Invoice Export Contract Verification, Traceability Rollup Analysis, API Compatibility Inspection.
ontology elements get structural/context holder names while Turtle can still define the pure term: element Payment Ontology, Turtle term ex:Payment.
Do not solve naming conflicts with (type, name) tuple identity or artificial concept names. Reqvire element names remain globally unique; pure terminology belongs to concepts, and implementation/obligation/contract/verification role belongs in the other element name.
System Model Construction Method
When constructing or refactoring a Reqvire system model:
- Inspect capability-root subgraphs with
submodels and inspect the ontology plane with search --filter-type=ontology.
- Decide whether work belongs to an existing capability root, a child capability, a new independent capability root, or the shared ontology hierarchy.
- Keep ontology and semantic-contract elements in
system-model/Ontologies; keep concept-scheme and concept elements in system-model/Thesaurus; capabilities, requirements, contracts, and verifications bind prose to SKOS concepts with #### Concept References, and requirements link to semantic contracts through constrainedBy.
- Treat ontology and concepts as first-class and orthogonal to capability/requirement structure: ontology defines reusable structural terms and relationships, native concepts define curated terminology, non-ontology model elements reference concepts explicitly, and semantic contracts depend on ontology through
use.
- Keep hierarchy inside capability, requirement, ontology, concept, or verification families; cross-root contract reuse must be explicit requirement-owned contract_bindings.
- Move stable reusable structural meaning to ontology, curated terminology to native concepts, obligations to requirements, and exact implementation/interface behavior to requirement-owned contracts.
- Use concept references for non-ontology prose-to-SKOS-concept bindings, use
use/usedBy for semantic-contract ontology dependencies, constrain requirements with constrain/constrainedBy, or reference reusable requirement-owned contracts from consuming requirements instead of using hierarchy to cross submodel boundaries.
- Update verifications and e2e fixtures in the same slice when requirements, report shape, names, or output expectations change.
- Validate in slices with
validate, lint, submodels, and focused tests before broadening the refactor.
Ontology Commands
Use CLI semantic export commands when a shell workflow needs RDF layers:
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer ontologies
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer shapes
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" concepts validate
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer ontologies --layer concepts
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer model
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" semantic export --layer model --layer external-used
For MCP workflows, use the read-only split semantic tools. reqvire.semantic.export is the canonical RDF export operation and accepts layers with ontologies, shapes, concepts, model, external-used, and prefixes; omitted or empty layers export all public layers. reqvire.semantic.ontologies, reqvire.semantic.shapes, reqvire.semantic.concepts, reqvire.semantic.model, and reqvire.semantic.graph are wrappers over the same layer serializer. reqvire.semantic.ontologies returns authored OWL/RDF ontology vocabulary, reqvire.semantic.shapes returns semantic-contract SHACL shapes, reqvire.semantic.concepts returns generated SKOS concept scheme/thesaurus triples without authored ontology bridge triples, reqvire.semantic.model returns generated Reqvire model facts, and reqvire.semantic.graph is equivalent to reqvire.semantic.export with omitted layers. Use reqvire.semantic.export with layers: ["ontologies", "external-used"] when used external subset triples are needed, and with layers: ["ontologies", "concepts"] when ontology-to-concept bridge triples and generated SKOS concepts are both needed. Ontology export returns generated ontology document declarations plus serialized authored ontology content, semantic index summary, source block metadata, diagnostics, authored ontology term declarations, and SHACL references. Each generated ontology document declaration uses the resolved ontology_base as the owl:Ontology IRI and lists same-base ontology elements as contributors. Authored named ontology resources get generated rdfs:isDefinedBy <ontology_base> ownership facts; Explorer uses those facts as OWL document metadata for grouping, search, and modals rather than rendering ontology document nodes or isDefinedBy edges. Model layer export includes generated Reqvire model facts for elements, relations, contract_bindings, concept references, ontology term declarations, shape references, and ontology projection facts. Local External Ontology files are parsed as internal dependencies for validation and term resolution; the external-used export layer and MCP helper include_external: true expose only the used external subset, and imported terms remain marked external rather than authored. Concept references are exported in model mode as model term-reference facts such as reqvire:conceptReference and reqvire:referencesTerm; they are not injected into the clean authored OWL/SHACL document and are not generated reqvire:OntologyConstruct records. Use the read-only reqvire.semantic.prefixes MCP tool when a client needs ontology-defined prefixes, namespaces, source element prose content, and a reusable sparql_prefix_block before writing queries; pass include_external: true only when imported external prefixes for the used subset are needed. Use the read-only reqvire.semantic.vocabulary MCP tool when a client needs compact paged classes, properties, relation families, controlled vocabularies, semantic contracts, query patterns, source maps, diagnostics, and prefixes before writing SPARQL; pass ontology_document or ontology_base to filter authored vocabulary to one OWL document, and combine include_external: true with ontology_document to filter used external subset terms to one declared external ontology source. Use the read-only reqvire.semantic.sparql MCP tool when a client needs to run SPARQL directly against the model-owned Oxigraph semantic store. It requires query and accepts optional full defaulting to true and optional include_external defaulting to false; include_external queries the used external subset rather than the raw full dependency graph, and results are structured for SELECT, ASK, CONSTRUCT, and DESCRIBE. MCP clients can also call standard prompts/list and prompts/get for build-time Reqvire workflow prompts, including reqvire.semantic.query, reqvire.semantic.verification_search, reqvire.semantic.contract_context_search, reqvire.semantic.author_ontology_contract, reqvire.workflow.explore_model, reqvire.workflow.plan_change, reqvire.workflow.generate_implementation_tasks, reqvire.workflow.author_capability_requirement, reqvire.workflow.author_or_align_verification, reqvire.workflow.refactor_model_structure, reqvire.workflow.audit_change_impact, reqvire.workflow.author_concepts, reqvire.workflow.model_quality_audit, and reqvire.workflow.verify_coverage. Use reqvire.workflow.audit_change_impact when the user asks whether changed system-model elements require updates to impacted capabilities, requirements, specifications, contracts, verifications, or website documentation artifacts. Use reqvire.workflow.generate_implementation_tasks for task planning from capability-scoped changes; use reqvire.workflow.author_capability_requirement for capability and requirement authoring; use reqvire.workflow.author_or_align_verification for verification criteria, evidence, and test alignment; use reqvire.workflow.refactor_model_structure for intent-preserving model refactors; use reqvire.semantic.author_ontology_contract for ontology and semantic-contract authoring; use reqvire.workflow.author_concepts for native concept-scheme and concept work; and use reqvire.workflow.model_quality_audit for validation, lint, coverage, containment, and model-health audits. Raw full external dependency triples remain internal and are only surfaced via explicit full-external mode.
Ontology Mutation Semantics
Ontology elements are first-class mutation targets and need boundary-safe rewrites:
- Use
add --override to rebase an ontology element (ontology_base or ontology_prefix changes) so dependent boundaries, inherited prefix bindings, imports, and reachable SHACL references are rewritten together.
relink is the way to re-point ontology hierarchy edges such as derivedFrom.merge for ontology elements folds source #### Ontology content into the target element’s single #### Ontology block (source ontology block does not stay separate).mv-file --squash moves ontology elements at file level only; it does not fold ontology content, it relocates elements and keeps each ontology block in its element.
Model Commands
Use the model command when a shell workflow needs a structural model view. Without --from or --filter-type, model starts from ontology roots, concept roots, and capability roots. Use --mmd when a downstream tool expects pure Mermaid text instead of Markdown.
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" model
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" model --mmd
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" model --json
Relation Types
| Relation | Allowed Sources | Purpose |
|---|
derivedFrom / derive | capability, requirement, ontology, verification-family elements | Hierarchy within the same family: capability-to-capability, requirement-to-requirement, ontology-to-ontology, or verification-family-to-verification-family |
specify / specifiedBy | requirement / capability | Bridge from requirements to their owning capability |
satisfiedBy / satisfy | requirement, test-verification, formal-proof-verification only | Link to implementation or evidence artifacts |
verifiedBy / verify | requirement / concrete verification element | Link requirements to concrete verification elements; capabilities are covered through requirement rollup and verification-objective is excluded |
definedBy / define | requirement | Ownership of subtype-compatible non-semantic contract elements |
constrainedBy / constrain | requirement / semantic-contract | Link requirements to semantic contracts that constrain them |
use / usedBy | semantic-contract / ontology | Link semantic contracts to the ontology vocabulary they use |
| Contract Bindings | requirement | Reference compatible requirement-owned contracts across explicit subgraph boundaries |
For ontology/SPARQL workflows, prefer relation-family vocabulary over raw relation-token matching. reqvire:RelationFamily groups inverse pairs and normalized query properties for hierarchy, capability specification, contract ownership, semantic-contract constraint, semantic-contract ontology use, verification, satisfaction, and cross-subgraph contract dependency. Only hierarchy families have transitive closure semantics; the others are direct semantic relationships unless a separate ontology rule states otherwise.
Key constraints:
- Requirements specify capabilities through
specify; capabilities point back to those requirements with specifiedBy
- Capability hierarchy uses
derivedFrom/derive only between capabilities
- Requirement hierarchy uses
derivedFrom/derive only between requirements
- Ontology hierarchy uses
derivedFrom/derive only between ontology elements; ontology elements do not author contract_bindings
- Verification-family hierarchy uses
derivedFrom/derive between verification-objective and concrete verification elements; objectives organize verification work but do not use verify, verifiedBy, or satisfiedBy
- Capabilities are not directly verified or directly satisfied; capability coverage rolls up from requirements that specify them
- Among concrete verification types, only evidence-backed verifications (
test-verification, formal-proof-verification) may use satisfiedBy/satisfy
- Each non-semantic-contract is owned by exactly one valid requirement owner via
definedBy
- Semantic contracts must use
constrain/constrainedBy for requirement application and use/usedBy for ontology vocabulary context; they must not use define/definedBy
- Capabilities must not own
source, constraint, behavior, specification, state, input-output, or semantic-contract elements through definedBy/define
- Capabilities do not author contract_bindings; they use
#### Concept References for SKOS concept bindings
- Requirement contract_bindings may target compatible requirement-owned
source, constraint, behavior, specification, state, or input-output contracts only
- Semantic contracts must not author
#### Concept References
Traceability flow:
Capability
├── Concept References → SKOS concepts
├── derive → Subcapability
└── specifiedBy → Requirement
Requirement
├── specify → Capability
├── derive → Child Requirement
├── reuse → Reusable Non-Semantic Requirement Contract
├── Concept References → SKOS concepts
├── definedBy → Source/Spec/Constraint/Behavior/State/Input-Output
├── constrainedBy → Semantic Contract → use → Ontology
├── satisfiedBy → Code
└── verifiedBy → Verification → satisfiedBy → Test/Proof evidence
Verification Authoring
Verification should be authored as a structured plan, then implemented as evidence-linked elements:
- Start with
verification-objective to define scope, intent, and grouping (capability-level or requirement-level goals). A verification-objective organizes intent only; it does not carry verify or satisfiedBy.
- Add concrete verification nodes (
test-verification, formal-proof-verification, analysis-verification, inspection-verification, demonstration-verification) with explicit #### Details describing pass/fail criteria and assumptions. Every concrete verification must have a derivedFrom relation to a verification-objective parent.
- Link concrete verifications with the
verify / verifiedBy relation pair:
- requirement
- verifiedBy: [Verification](path.md#verification-element)
- verification
- verify: [Requirement](path.md#requirement-element)
- Record executable evidence only on evidence-backed concrete verifications using
satisfiedBy:
- requirement
- satisfiedBy: [Test Report](path.md#evidence-or-asset)
- test-verification
- satisfiedBy: [Evidence](path.md#artifact-or-result)
- formal-proof-verification
- satisfiedBy: [Proof Artifact](path.md#proof-report)
- Prefer one direct objective per verification purpose; split mixed objectives instead of merging incompatible check types.
Good objective titles (examples):
- API performance boundary verification
- Authentication and authorization assurance
- Backward-compatible migration validation
- Behavior consistency across requirement branches
- Build and dependency reproducibility checks
- Capability end-to-end demonstration verification
- Data quality and schema migration validation
- Deployment and rollback verification
- Fault recovery and degradation handling
- Interoperability across integrations
- I/O contract conformance verification
- Latency and throughput verification
- Non-functional compliance and auditability
- Regression protection for critical requirements
- Resilience against resource exhaustion
- Security controls and attack-surface verification
- Safety constraints and failure-state validation
- Storage and message durability verification
- User accessibility and operability checks
- Versioned evidence pack validation
Anti-patterns to avoid:
- adding
satisfiedBy on non-evidence-backed verification types
- linking constraints via
definedBy instead of constrain
- binding ontology to model elements through Contract Bindings
- duplicating the same obligation in multiple verification nodes instead of using one node with precise criteria
When authoring verifications, always update at least one of:
verify coverage expectations (verifiedBy/satisfiedBy paths)coverage-relevant leaf requirements- corresponding evidence references in related files
Document Structure
- Files begin with
# Elements (multi-element) or # Element (single-element)
- Elements are
### headers with unique names per file
- Reserved
#### subsections: Metadata, Relations, Details, Contract Bindings, Concept References
- Ontology elements require exactly one
#### Ontology fenced Turtle block; semantic contracts require exactly one #### Shapes fenced Turtle block
- Non-reserved
#### subsections become element content (use for inline specs/behaviors)
- Relations syntax:
* derivedFrom: [Parent](path.md#parent)
- Contract Bindings syntax:
* [Name](path.md#element)
Requirement Governance Metadata
Governance-bearing elements (capability, requirement) may define governance metadata in #### Metadata:
| Key | Values | Default | Meaning |
|---|
status | draft, review, approved | approved | Lifecycle readiness for use in engineering decisions |
priority | low, medium, high, critical | medium | Relative implementation/planning importance |
risk | low, medium, high, critical | low | Requirement-driven delivery, safety, compliance, integration, or validation risk |
owner | free-form string | unassigned | Accountability/routing label; may be a person, role, team, department, subsystem group, or task owner |
Missing governance fields inherit from the nearest parent capability or requirement through derivedFrom and specify; otherwise defaults apply. Search JSON exposes effective values and their sources under governance_metadata. Text and JSON search summaries expose governance counters.
Governance metadata belongs directly on capability and requirement elements only. Contracts and verifications must not author status, priority, risk, or owner in metadata; they receive governance context from their owning or linked capability/requirement.
When and How to Use Governance
Use governance metadata whenever work involves planning, prioritization, routing, readiness, or risk:
- Task generation and implementation planning: include effective
status, priority, risk, and owner in task summaries
- Triage and search: use
--filter-status, --filter-priority, --filter-risk, and --filter-owner before manually scanning files
- Change impact review: surface high/critical priority or risk requirements first
- Ownership routing: route questions and tasks using
owner; it may name a person, role, team, department, subsystem group, or task owner
- Model cleanup/refactoring: preserve explicit governance metadata and keep inherited/default values implicit unless the user asks to author them
Do not use governance metadata as a substitute for model structure:
status does not replace verification, validation, or coveragepriority does not change requirement hierarchy or traceabilityrisk describes requirement-level delivery/safety/compliance/integration/validation risk; it is not a test resultowner does not replace definedBy ownership or implementation satisfiedBy links
When adding new requirements, omit governance keys unless the user, source requirement, or specification explicitly defines them. Defaults and inheritance are still effective in the graph model.
EARS Patterns
- Ubiquitous: "The system shall [capability]"
- Event-driven: "When [trigger] the system shall [response]"
- State-driven: "While [state] the system shall [capability]"
- Unwanted: "If [condition] then the system shall [response]"
- Optional: "Where [capability] the system shall [capability]"
Requirements should contain EARS statements only (body + #### Details). Technical details belong in contract elements linked via definedBy.
Core Rules
- Always run commands from the intended effective workspace root, or pass that root with
--workspace
- Use full paths starting with
system-model/ (if other content root, ask user)
- Never guess — read files before making changes
- Validate after each significant change
- When reading requirements, always check for contract_bindings
- Use the Reqvire
collect command to gather full context from capability, requirement, or ontology starts
- Requirement upstream (default): requirement ancestors, owning capability context, contract_bindings, and authored concept-reference context
- Capability downstream: child capabilities and specified requirements
- Ontology downstream: child ontology elements and semantic contracts that use reachable ontology
- Downstream:
collect "Element" --direction DOWNSTREAM
- Use the Reqvire
submodels command to inspect independent subgraphs before refactors
submodels --from "<ROOT>": scoped view (root excluded from reported submodels)
- Implementation coverage (
coverage) applies to requirement elements only
- Hierarchy integrity: mutations must preserve single-root hierarchy ownership
- Violations should output
Single-root hierarchy ownership violation
- If unclear, verify with
validate after mutation
- Treat governance metadata as planning context
- Preserve explicit values when editing requirements
- Do not add governance keys to contracts or verifications
- Use
owner as an accountability/routing label, not necessarily a person
Task Routing
Load the right reference file for your task — don't work from memory on complex workflows:
| Task | Reference | When |
|---|
| Explore model | explore.md | Understanding structure, browsing, traceability analysis |
| Add capabilities | AddCapability.md | New functionality, MBSE workflow, requirements hierarchy |
| Add requirements | AddRequirement.md | Adding requirements to an existing capability |
| Add verifications | AddVerification.md | Adding verifications for leaf requirements |
| Link / Unlink | Link.md | Creating or removing relations between elements |
| Move elements or files | Move.md | Moving individual elements or entire files |
| Remove elements | Remove.md | Removing elements from the model |
| Rename elements | RenameElement.md | Renaming elements with automatic relation updates |
| Collect context | Collect.md | Gathering full upstream/downstream trace context |
| Containment analysis | Containment.md | Read-only inspection of file/folder structure |
| Refactor model | ConsolidateRequirements.md | Cluttered/duplicated model, fixing relations/ownership |
| Refactor containment structure | ContainmentStructureRefactor.md | Reorganize folders/files around capability, ontology, and verification planes without changing model intent |
| Refactor ontology/contracts | CapabilitySemanticContractRefactor.md | Separate capability scope, reusable ontology terms, requirement obligations, and reusable semantic contracts |
| Extract specs | SpecificationsExtractionLogic.md | Embedded details in requirements, separating EARS from specs |
| Clean language | SpecificationLanguageCleanup.md | Normative wording in contracts, language ownership |
| Generate tasks | CreatingTasks.md | Implementation plans from capability-scoped changes |
| Refactor submodel boundaries | SubmodelRefactor.md | Split into independent submodels, contract bindings |
| Align verifications | VerificationAlignment.md | Sync verification criteria with test assertions |
| Normalize design-doc ownership | DesignDocOwnership.md | One owner per design document |
| Setup environment | Setup.md | First-time setup, plugin update, CLAUDE.md configuration |
Quick tasks (no reference needed): search, validate, single link/unlink/move, collect context.
For model quality and diagnostics (lint, coverage, change impact, model analysis): use the reqvire:audit skill.
Quick Start Common Workflows
- Explore capabilities and requirements with
search, then gather full context with collect
- Add or modify requirements only after reading the owning capability and requirement chain
- Keep governance metadata on capability and requirement elements only
- Route implementation tasks by effective
owner, priority, risk, and status
- Validate after meaningful edits with
validate, then run lint, coverage, or format as needed
Command Reference
Use this prefix when executing Reqvire commands:
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD"
The examples below show Reqvire arguments after that prefix.
search --short --json | jq '.summary'
search --filter-type="requirement" --filter-name=".*Pattern.*" --short
search --not-have-relations="verifiedBy" --short
search --filter-status="review" --short
search --filter-priority="high,critical" --short
search --filter-risk="high,critical" --json
search --filter-owner="Platform|Safety" --json
model [--from "Element"] [--reverse] [--filter-type="requirement"] [--mmd]
collect "Element" [--direction DOWNSTREAM] [--json]
submodels [--from "Root"]
add <file.md> <<'EOF'
Content here.
* type: requirement
EOF
link "Source" "derivedFrom" "Target"
link "Source" bindContract "path.md#element"
unlink "Source" "Target"
relink "Source" "derivedFrom" "Old" "New"
mv "Element" "target.md" [position]
mv-file "source.md" "target.md" [--squash]
mv-folder "source-dir" "target-dir"
merge "Primary" "Duplicate" [--dry-run]
rm "Element" [--dry-run]
rename-element "Old Name" "New Name"
validate [--json]
lint [--fix] [--fixable] [--auditable]
coverage [--json]
format [--fix]
migrate [--fix] [--json]
change-impact --git-commit=<hash> [--json]
traces [--json] [--filter-name=".*Pattern.*"]
resources
containment [--short] [--json]
mv-asset "old-path" "new-path"
rm-asset "path"
serve [--port 8080]
change-impact --git-commit=<hash> compares the current workspace snapshot to a base snapshot materialized from the current eligible Git worktree. It is not a multi-repository commit selector; paths and identifiers remain workspace-root-relative.
Common flags: --json, --short, --dry-run, --output <file> (requires --json)
Use --dry-run for destructive operations. Use <<'EOF' (single-quoted) to prevent shell expansion in heredocs.
Use migrate to preview or apply deterministic source migrations for known breaking model-contract changes. It defaults to dry-run preview; use migrate --fix only when the user has approved applying source rewrites. Current migrations cover legacy single-element # Documents headers and creation of one shared verification-objective holder in root VerificationObjectiveMigration.md with holder-owned derive links to standalone concrete verifications.
Validation & Quality Checklist
Run after every meaningful change:
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" validate
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" lint [--fix]
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" coverage
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" format [--fix]
After major refactoring, also run the same prefix with resources, traces, model, and containment.
