Add SysML2 modeling standard and update related documentation#21
Merged
Conversation
- Add .github/standards/sysml2-modeling.md defining the docs/sysml2/ model
layout (one .sysml file per system, optional ots.sysml/shared.sysml, and
views/design-views.sysml), the correct `expose`-based view usage syntax
(not `view def`/`render`-for-scoping), the View naming convention
(SoftwareStructureView / {SystemName}View / {SubsystemName}View), diagram
embedding rules, and build/lint integration guidance. No stable
"system.sysml" alias file is used since a repository may contain more
than one system.
- Add .github/skills/sysml2tools-query/SKILL.md documenting the agent query
workflow (discover systems via `query list`, then describe/hierarchy/
used-by/impact/requirements/find), generalized from the DictionaryMark
pilot to not assume a single fixed system name.
- Update AGENTS.md: Codebase Navigation now queries the SysML2 model first;
add docs/sysml2/ to Key Configuration Files; add a Standards Application
matrix row for software structure changes; mention sysml2tools in the CI
Quality Tools summary.
- Update design-documentation.md: Software Structure section is now sourced
from the SysML2 model/diagrams, not a hand-maintained text tree.
- Update reviewmark-usage.md: include docs/sysml2/**/*.sysml in needs-review
and in the Decomposition review's file patterns, since the model is now
the authoritative structural source.
- Update template-sync.agent.md: add docs/sysml2/ as its own work group.
- Add "sysml" to .cspell.yaml.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request adds SysML2 modeling as a first-class documentation artifact in this repository’s distributable agent/standards content, positioning docs/sysml2/ as the authoritative source for software structure and updating related standards, review processes, and agent workflows accordingly.
Changes:
- Added a new SysML2 modeling standard (
sysml2-modeling.md) describing model layout, view conventions, rendering, and embedding guidance. - Added a new agent skill (
sysml2tools-query) and updated agent onboarding (AGENTS.md) to prioritize querying the SysML2 model for structure/navigation. - Updated documentation/review standards to reference SysML2 model artifacts, and extended spellcheck vocabulary.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
src/AGENTS.md |
Updates navigation guidance to query docs/sysml2/ first; adds SysML2 to standards matrix and CI tool list. |
src/.github/standards/sysml2-modeling.md |
Introduces the SysML2 modeling standard covering structure, views, rendering, embedding, and quality checks. |
src/.github/standards/reviewmark-usage.md |
Expands ReviewMark patterns/scope to include docs/sysml2/**/*.sysml in decomposition review context. |
src/.github/standards/design-documentation.md |
Requires Software Structure diagrams rendered from the SysML2 model instead of hand-maintained text trees. |
src/.github/skills/sysml2tools-query/SKILL.md |
Adds a skill documenting how to query the SysML2 model using sysml2tools. |
src/.github/agents/template-sync.agent.md |
Adds docs/sysml2/ as a dedicated work group for delegation. |
.cspell.yaml |
Adds SysML-related terms to the spellcheck allowlist. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
25
to
33
| - reqstream | ||
| - reviewmark | ||
| - Sarif | ||
| - SARIF | ||
| - sarifmark | ||
| - sonarmark | ||
| - sysml | ||
| - versionmark | ||
| - Weasy |
Comment on lines
+14
to
+16
| The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`. | ||
| Restore it once per session if not already available: | ||
|
|
Comment on lines
145
to
+148
| ## CI Quality Tools | ||
|
|
||
| CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format, | ||
| reqstream, versionmark, and reviewmark. | ||
| reqstream, versionmark, reviewmark, and sysml2tools. |
Comment on lines
+125
to
+126
| Place the image directly under the file's top-level heading, before its first prose | ||
| subsection, e.g. ``. |
Comment on lines
+24
to
+25
| - **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder, | ||
| not a Pandoc collection) |
Comment on lines
+107
to
+109
| dotnet sysml2tools render ` | ||
| docs/sysml2/{system-name}.sysml docs/sysml2/ots.sysml docs/sysml2/shared.sysml ` | ||
| docs/sysml2/views/design-views.sysml --output docs/design/generated --format svg |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces first-class support for SysML2 architecture modeling in the repository. The changes establish the SysML2 model under
docs/sysml2/as the authoritative source for software structure, update documentation standards and review processes to reference the model, and provide comprehensive guidance for both humans and AI agents on querying, maintaining, and embedding SysML2-based diagrams. The update also adds new skills and standards for working with the model and integrates SysML2 tools into the CI and linting workflows.SysML2 Model Integration and Standards
sysml2-modeling.md, detailing repository structure, modeling conventions, view/diagram embedding, and quality checks for SysML2 models indocs/sysml2/.design-documentation.mdto require that the Software Structure section uses diagrams rendered from the SysML2 model, replacing hand-maintained text trees.AI Agent and Developer Workflow
sysml2tools-queryskill, providing detailed instructions for querying the SysML2 model to understand system structure, dependencies, and requirements, and specifying fallback procedures when the model is incomplete.AGENTS.md) to instruct agents to query the SysML2 model first when navigating or understanding the codebase, and to treat it as the authoritative source for software structure. [1] [2]docs/sysml2/folder to the repository structure documentation.CI, Linting, and Review Integration
sysml2toolsinto CI linting (lint.ps1) and documented this in the quality tools section..sysmlfiles and thesysml2term. [1] [2]Work Group and Agent Delegation
docs/sysml2/files in agent task delegation, clarifying that these are not part of a Pandoc collection but a flat folder for model files and rendered views.