reqvire-syseng

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 Y
• X has property Z
• X 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:

1. concept gets the pure name: Payment, Invoice, Traceability, Verification Coverage.
2. 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.
3. requirement gets obligation wording, usually with Requirement: Payment Settlement Requirement, Invoice Export Requirement, Traceability Link Resolution Requirement.
4. 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.
5. Verification elements get validation wording: Payment Settlement Validation Test, Invoice Export Contract Verification, Traceability Rollup Analysis, API Compatibility Inspection.
6. 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:

1. Inspect capability-root subgraphs with submodels and inspect the ontology plane with search --filter-type=ontology.
2. Decide whether work belongs to an existing capability root, a child capability, a new independent capability root, or the shared ontology hierarchy.
3. 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.
4. 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.
5. Keep hierarchy inside capability, requirement, ontology, concept, or verification families; cross-root contract reuse must be explicit requirement-owned contract_bindings.
6. Move stable reusable structural meaning to ontology, curated terminology to native concepts, obligations to requirements, and exact implementation/interface behavior to requirement-owned contracts.
7. 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.
8. Update verifications and e2e fixtures in the same slice when requirements, report shape, names, or output expectations change.
9. 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
# Export generated SKOS plus ontology-to-concept bridges when needed:
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 coverage
• priority does not change requirement hierarchy or traceability
• risk describes requirement-level delivery/safety/compliance/integration/validation risk; it is not a test result
• owner 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

1. Always run commands from the intended effective workspace root, or pass that root with --workspace
2. Use full paths starting with system-model/ (if other content root, ask user)
3. Never guess — read files before making changes
4. Validate after each significant change
5. When reading requirements, always check for contract_bindings
6. 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
7. Use the Reqvire submodels command to inspect independent subgraphs before refactors
   • submodels --from "<ROOT>": scoped view (root excluded from reported submodels)
8. Implementation coverage (coverage) applies to requirement elements only
9. Hierarchy integrity: mutations must preserve single-root hierarchy ownership
   • Violations should output Single-root hierarchy ownership violation
   • If unclear, verify with validate after mutation
10. 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.

# Explore
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"]

# Manipulate
add <file.md> <<'EOF'
### Element Name
Content here.
#### Metadata
  * 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"

# Quality
validate [--json]
lint [--fix] [--fixable] [--auditable]
coverage [--json]
format [--fix]
migrate [--fix] [--json]

# Analysis
change-impact --git-commit=<hash> [--json]
traces [--json] [--filter-name=".*Pattern.*"]
resources
containment [--short] [--json]

# Assets
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          # Structure and relations
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" lint [--fix]      # Model hygiene
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" coverage          # Verification + implementation gaps
npx -y "${REQVIRE_NPX_PACKAGE:-@reqvire-org/reqvire@latest}" --workspace "$PWD" format [--fix]    # Markdown consistency

After major refactoring, also run the same prefix with resources, traces, model, and containment.