Add SysML2 model support and enhance related documentation

[Malcolmnixon]

This pull request introduces several improvements and clarifications to the agent orchestration, planning, and quality processes, as well as updates to documentation and tool configuration. The most significant changes include the addition of a dedicated planning agent with a structured report template, enhanced requirements for companion artifact tracking and verification, and updates to agent report formats for better traceability. There are also improvements to the quality agent’s evaluation logic and clearer instructions for review and template synchronization.

Agent Orchestration and Reporting

• Added a new planning.agent.md that defines a structured, multi-step planning process, including companion artifact identification, assumption/risk analysis, feasibility, and a standardized report template with lean summary for downstream agents.
• Updated the implementation agent to use the new planning agent, clarified state transitions, and revised the implementation report format to reference the planning report and include unknowns when incomplete. [1] [2] [3] [4] [5]

Companion Artifact and Quality Requirements

• Expanded companion artifact requirements to include verification docs, README, and user guides in both developer and quality agent instructions. The quality agent now cross-references the planning agent’s artifact table and fails if required artifacts are missing. [1] [2]
• Improved the quality agent’s compliance sections: added verification documentation compliance, clarified review set requirements, and updated traceability language. [1] [2] [3]

Documentation and Review Process

• Clarified the formal review agent’s process for separating context/reference files from files under review, and updated the review report template to include a report file path.
• Updated report templates for developer, lint-fix, and quality agents to include a Report field referencing the saved log file for traceability. [1] [2] [3]

Template Synchronization and Tooling

• Improved template sync agent grouping to explicitly handle docs/sysml2/, root-level files in docs/design/, docs/verification/, and docs/reqstream/, and clarified template-matching logic and error handling.
• Added demaconsulting.sysml2tools.tool to .config/dotnet-tools.json and updated spelling dictionary entries for new tools and terminology. [1] [2] [3]

These changes collectively strengthen traceability, compliance, and auditability across the agent-driven development workflow, while providing clearer guidance and reporting for each agent’s responsibilities.

[Copilot]

Pull request overview

This PR adds SysML2-based architecture modeling to ReviewMark (model files + lint/render integration) and updates the repo’s compliance workflow and documentation/agent standards to treat the SysML2 model as an authoritative companion artifact.

Changes:

• Integrate demaconsulting.sysml2tools.tool into local/CI linting and the docs build to lint models and render SVG diagrams.
• Introduce a SysML2 model under docs/sysml2/ plus view definitions, and embed rendered diagrams into design docs.
• Update requirements/review sets/standards/agent prompts to incorporate SysML2 artifacts, expanded companion-artifact expectations, and a new planning agent.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
requirements.yaml	Includes SysML2Tools OTS requirements file in the root ReqStream include set.
lint.ps1	Runs sysml2tools lint (when docs/sysml2 exists) as part of compliance linting.
docs/verification/ots/sysml2tools.md	Adds verification evidence description for SysML2Tools as an OTS item.
docs/verification/ots.md	Adds SysML2Tools to the OTS verification narrative and evidence list.
docs/verification/introduction.md	Adds SysML2Tools to the OTS inventory and folder-layout example.
docs/verification/definition.yaml	Includes SysML2Tools verification page in the Verification Pandoc collection.
docs/sysml2/views/design-views.sysml	Defines named views to be rendered as SVG diagrams for design docs.
docs/sysml2/model/review-mark.sysml	Adds top-level ReviewMark system model with subsystem/unit composition and OTS usages.
docs/sysml2/model/ots.sysml	Adds OTS dependency part definitions for use by the system model.
docs/sysml2/model/review-mark/program.sysml	Adds SysML2 unit model for Program with artifact-location comments.
docs/sysml2/model/review-mark/cli.sysml	Adds SysML2 subsystem model for CliSubsystem with artifact-location comments.
docs/sysml2/model/review-mark/cli/context.sysml	Adds SysML2 unit model for Context with artifact-location comments.
docs/sysml2/model/review-mark/configuration.sysml	Adds SysML2 subsystem model for ConfigurationSubsystem with artifact-location comments.
docs/sysml2/model/review-mark/configuration/review-mark-configuration.sysml	Adds SysML2 unit model for ReviewMarkConfiguration with artifact-location comments.
docs/sysml2/model/review-mark/configuration/glob-matcher.sysml	Adds SysML2 unit model for GlobMatcher with artifact-location comments.
docs/sysml2/model/review-mark/indexing.sysml	Adds SysML2 subsystem model for IndexingSubsystem with artifact-location comments.
docs/sysml2/model/review-mark/indexing/review-index.sysml	Adds SysML2 unit model for ReviewIndex with artifact-location comments.
docs/sysml2/model/review-mark/indexing/path-helpers.sysml	Adds SysML2 unit model for PathHelpers with artifact-location comments.
docs/sysml2/model/review-mark/self-test.sysml	Adds SysML2 subsystem model for SelfTestSubsystem with artifact-location comments.
docs/sysml2/model/review-mark/self-test/validation.sysml	Adds SysML2 unit model for Validation with artifact-location comments.
docs/reqstream/ots/sysml2tools.yaml	Adds OTS requirements for SysML2Tools lint/render behavior.
docs/design/review-mark.md	Embeds rendered ReviewMark SVG diagram in the system design page.
docs/design/review-mark/program.md	Embeds rendered ReviewMark SVG diagram in the Program design page.
docs/design/review-mark/cli.md	Embeds rendered Cli SVG diagram in the Cli subsystem design page.
docs/design/review-mark/cli/context.md	Embeds rendered Cli SVG diagram in the Context unit design page.
docs/design/review-mark/configuration.md	Embeds rendered Configuration SVG diagram in the Configuration subsystem design page.
docs/design/review-mark/configuration/review-mark-configuration.md	Embeds rendered Configuration SVG diagram in the ReviewMarkConfiguration unit design page.
docs/design/review-mark/configuration/glob-matcher.md	Embeds rendered Configuration SVG diagram in the GlobMatcher unit design page.
docs/design/review-mark/indexing.md	Embeds rendered Indexing SVG diagram in the Indexing subsystem design page.
docs/design/review-mark/indexing/review-index.md	Embeds rendered Indexing SVG diagram in the ReviewIndex unit design page.
docs/design/review-mark/indexing/path-helpers.md	Embeds rendered Indexing SVG diagram in the PathHelpers unit design page.
docs/design/review-mark/self-test.md	Embeds rendered SelfTest SVG diagram in the SelfTest subsystem design page.
docs/design/review-mark/self-test/validation.md	Embeds rendered SelfTest SVG diagram in the Validation unit design page.
docs/design/ots/sysml2tools.md	Adds OTS integration/usage design for SysML2Tools.
docs/design/introduction.md	Reworks the design intro to reference the SysML2 model and embeds the software structure diagram.
docs/design/definition.yaml	Includes SysML2Tools design page in the Design Pandoc collection.
AGENTS.md	Updates repo navigation guidance to prefer SysML2 model queries; updates agent delegation/reporting notes.
.versionmark.yaml	Adds SysML2Tools to tool version capture definitions.
.reviewmark.yaml	Adds SysML2 model coverage to needs-review and introduces global/per-review context configuration updates (plus OTS SysML2Tools review-set).
.github/workflows/build.yaml	Captures sysml2tools version; runs SysML2Tools self-validation and renders diagrams before building design docs.
.github/standards/verification-documentation.md	Updates verification doc standards (mandatory sections, classification guidance, checklist changes).
.github/standards/testing-principles.md	Trims intro boilerplate; retains substantive testing standards.
.github/standards/technical-documentation.md	Streamlines guidance and clarifies ordering/format requirements.
.github/standards/sysml2-modeling.md	Adds a SysML2 modeling standard defining repository structure, view conventions, and integration expectations.
.github/standards/software-items.md	Updates placeholder conventions and notes SysML2 comment metadata for artifact locations.
.github/standards/reviewmark-usage.md	Updates ReviewMark usage guidance to include SysML2 and context-file concepts.
.github/standards/reqstream-usage.md	Clarifies recursive path patterns and consistent artifact path mapping across collections.
.github/standards/design-documentation.md	Updates design doc standards to use SysML2-rendered diagrams for software structure and refines mandatory sections.
.github/standards/csharp-testing.md	Trims minor boilerplate in the quality checks section.
.github/standards/csharp-language.md	Trims minor boilerplate in the API documentation section.
.github/standards/coding-principles.md	Streamlines prose and clarifies several anti-pattern bullet descriptions.
.github/skills/sysml2tools-query/SKILL.md	Adds a skill doc for querying the SysML2 model via sysml2tools.
.github/agents/template-sync.agent.md	Updates template-sync grouping and reporting template (adds sysml2 group and report path field).
.github/agents/quality.agent.md	Expands quality evaluation rules to cross-check companion artifacts and add verification-doc compliance.
.github/agents/planning.agent.md	Adds a new planning agent with structured plan + companion-artifact deliverables report format.
.github/agents/lint-fix.agent.md	Adds report path field to lint-fix agent report template.
.github/agents/implementation.agent.md	Switches PLANNING state to use the new planning agent; updates report fields/state terminology.
.github/agents/formal-review.agent.md	Clarifies context vs reviewed files flow and adds report path field.
.github/agents/developer.agent.md	Expands companion artifact categories to include verification/docs/user guide and adds report path field.
.cspell.yaml	Adds spell-check dictionary entries for SysML2-related terms and package naming.
.config/dotnet-tools.json	Adds demaconsulting.sysml2tools.tool to local .NET tool manifest.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.