Integrate SysML2 architecture and tooling into design documentation#196
Merged
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds docs/sysml2/model/**/*.sysml covering the BuildMark system, all
subsystems (including nested GitHub/AzureDevOps/Mock repo-connector
sub-subsystems), and all units, plus docs/sysml2/model/ots.sysml for
the YamlDotNet OTS dependency and docs/sysml2/views/design-views.sysml
with SoftwareStructureView, BuildMarkView, and one {SubsystemName}View
per subsystem.
Every part def carries sourceRef/testRef/designRef/verificationRef/
reqRef comments pointing at verified existing companion artifacts,
with documented-exception comments for units that share a subsystem-
level file (Configuration units' reqRef, RuleMatchConfig, IRepoConnector,
ItemControlsInfo, AzureDevOpsApiTypes, GitHubGraphQLTypes) and for the
YamlDotNet OTS gap (no verification/reqstream doc exists).
Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
- .config/dotnet-tools.json: add demaconsulting.sysml2tools.tool 0.1.0-beta.5 - lint.ps1: run 'dotnet sysml2tools lint' over docs/sysml2/**/*.sysml - .github/workflows/build.yaml: render docs/sysml2 views to SVG before Pandoc in the build-docs job, and capture sysml2tools' version - .versionmark.yaml: capture sysml2tools version from 'dotnet tool list' - .cspell.yaml: add 'sysml' word (additive only) Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
Adds  images directly under the top-level
heading of every design doc, per sysml2-modeling.md's Diagram Embedding
rule: SoftwareStructureView in introduction.md, BuildMarkView in
build-mark.md and program.md, and each {SubsystemName}View in its
subsystem doc and every unit doc nested under that subsystem (including
the nested GitHub/AzureDevOps/Mock repo-connector sub-subsystems).
Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
Replace the hand-maintained ASCII Software Structure tree with the SysML2-model pointer paragraph and rendered diagram per sysml2-modeling.md, and condense the Folder Layout section to a folders-only bullet list per the template's directive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove duplicate SoftwareStructureView.svg embed under the top-level Introduction heading (image belongs only in the Software Structure section per the template). - Remove the test/ tree from Folder Layout: the template directive is explicit that this section documents 'your actual source folder layout' only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR integrates a SysML2 architecture model into BuildMark’s design documentation and agent workflow, making software structure machine-queryable and rendering diagrams into the design docs as part of CI/lint.
Changes:
- Added a SysML2 model (
docs/sysml2/) with views rendered intodocs/design/generated/. - Integrated SysML2Tools into linting, version capture, and the design-doc build workflow.
- Updated standards and agent prompts/skills to treat the SysML2 model as the authoritative software-structure source.
Reviewed changes
Copilot reviewed 121 out of 121 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| lint.ps1 | Lints SysML2 model when present |
| docs/sysml2/views/design-views.sysml | Defines rendered design view set |
| docs/sysml2/model/ots.sysml | Adds OTS dependency part defs |
| docs/sysml2/model/build-mark.sysml | Defines BuildMark system structure |
| docs/sysml2/model/build-mark/program.sysml | Models Program unit metadata |
| docs/sysml2/model/build-mark/cli.sysml | Models Cli subsystem metadata |
| docs/sysml2/model/build-mark/cli/context.sysml | Models Context unit metadata |
| docs/sysml2/model/build-mark/build-notes.sysml | Models BuildNotes subsystem metadata |
| docs/sysml2/model/build-mark/build-notes/build-information.sysml | Models BuildInformation unit metadata |
| docs/sysml2/model/build-mark/build-notes/item-info.sysml | Models ItemInfo unit metadata |
| docs/sysml2/model/build-mark/build-notes/web-link.sysml | Models WebLink unit metadata |
| docs/sysml2/model/build-mark/self-test.sysml | Models SelfTest subsystem metadata |
| docs/sysml2/model/build-mark/self-test/validation.sysml | Models Validation unit metadata |
| docs/sysml2/model/build-mark/utilities.sysml | Models Utilities subsystem metadata |
| docs/sysml2/model/build-mark/utilities/path-helpers.sysml | Models PathHelpers unit metadata |
| docs/sysml2/model/build-mark/utilities/process-runner.sysml | Models ProcessRunner unit metadata |
| docs/sysml2/model/build-mark/utilities/temporary-directory.sysml | Models TemporaryDirectory unit metadata |
| docs/sysml2/model/build-mark/version.sysml | Models Version subsystem metadata |
| docs/sysml2/model/build-mark/version/version-tag.sysml | Models VersionTag unit metadata |
| docs/sysml2/model/build-mark/version/version-semantic.sysml | Models VersionSemantic unit metadata |
| docs/sysml2/model/build-mark/version/version-interval.sysml | Models VersionInterval unit metadata |
| docs/sysml2/model/build-mark/version/version-interval-set.sysml | Models VersionIntervalSet unit metadata |
| docs/sysml2/model/build-mark/version/version-comparable.sysml | Models VersionComparable unit metadata |
| docs/sysml2/model/build-mark/version/version-commit-tag.sysml | Models VersionCommitTag unit metadata |
| docs/sysml2/model/build-mark/configuration.sysml | Models Configuration subsystem metadata |
| docs/sysml2/model/build-mark/configuration/section-config.sysml | Models SectionConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/rule-match-config.sysml | Models RuleMatchConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/rule-config.sysml | Models RuleConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/report-config.sysml | Models ReportConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/github-connector-config.sysml | Models GitHubConnectorConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/connector-config.sysml | Models ConnectorConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/configuration-load-result.sysml | Models ConfigurationLoadResult unit metadata |
| docs/sysml2/model/build-mark/configuration/configuration-issue.sysml | Models ConfigurationIssue unit metadata |
| docs/sysml2/model/build-mark/configuration/build-mark-config.sysml | Models BuildMarkConfig unit metadata |
| docs/sysml2/model/build-mark/configuration/build-mark-config-reader.sysml | Models BuildMarkConfigReader unit metadata |
| docs/sysml2/model/build-mark/configuration/azure-devops-connector-config.sysml | Models AzureDevOpsConnectorConfig unit metadata |
| docs/sysml2/model/build-mark/repo-connectors.sysml | Models RepoConnectors subsystem metadata |
| docs/sysml2/model/build-mark/repo-connectors/repo-connector-factory.sysml | Models RepoConnectorFactory unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/repo-connector-base.sysml | Models RepoConnectorBase unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/mock/mock-repo-connector.sysml | Models MockRepoConnector unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/mock.sysml | Models Mock subsystem metadata |
| docs/sysml2/model/build-mark/repo-connectors/item-router.sysml | Models ItemRouter unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/item-controls-parser.sysml | Models ItemControlsParser unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/item-controls-info.sysml | Models ItemControlsInfo unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/i-repo-connector.sysml | Models IRepoConnector unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/github/github-repo-connector.sysml | Models GitHubRepoConnector unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-types.sysml | Models GitHubGraphQLTypes unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-client.sysml | Models GitHubGraphQLClient unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/github.sysml | Models GitHub subsystem metadata |
| docs/sysml2/model/build-mark/repo-connectors/azure-devops/work-item-mapper.sysml | Models WorkItemMapper unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.sysml | Models AzureDevOpsRestClient unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.sysml | Models AzureDevOpsRepoConnector unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-api-types.sysml | Models AzureDevOpsApiTypes unit metadata |
| docs/sysml2/model/build-mark/repo-connectors/azure-devops.sysml | Models AzureDevOps subsystem metadata |
| docs/design/introduction.md | Replaces manual tree with rendered diagram |
| docs/design/build-mark.md | Embeds system-level diagram |
| docs/design/build-mark/program.md | Embeds BuildMark view diagram |
| docs/design/build-mark/cli.md | Embeds Cli view diagram |
| docs/design/build-mark/cli/context.md | Embeds Cli view diagram |
| docs/design/build-mark/build-notes.md | Embeds BuildNotes view diagram |
| docs/design/build-mark/build-notes/build-information.md | Embeds BuildNotes view diagram |
| docs/design/build-mark/build-notes/item-info.md | Embeds BuildNotes view diagram |
| docs/design/build-mark/build-notes/web-link.md | Embeds BuildNotes view diagram |
| docs/design/build-mark/self-test.md | Embeds SelfTest view diagram |
| docs/design/build-mark/self-test/validation.md | Embeds SelfTest view diagram |
| docs/design/build-mark/utilities.md | Embeds Utilities view diagram |
| docs/design/build-mark/utilities/path-helpers.md | Embeds Utilities view diagram |
| docs/design/build-mark/utilities/process-runner.md | Embeds Utilities view diagram |
| docs/design/build-mark/utilities/temporary-directory.md | Embeds Utilities view diagram |
| docs/design/build-mark/version.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-tag.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-semantic.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-interval.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-interval-set.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-comparable.md | Embeds Version view diagram |
| docs/design/build-mark/version/version-commit-tag.md | Embeds Version view diagram |
| docs/design/build-mark/configuration.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/build-mark-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/build-mark-config-reader.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/configuration-load-result.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/configuration-issue.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/connector-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/github-connector-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/azure-devops-connector-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/report-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/rule-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/configuration/section-config.md | Embeds Configuration view diagram |
| docs/design/build-mark/repo-connectors.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/repo-connector-factory.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/repo-connector-base.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/item-router.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/item-controls-parser.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/item-controls-info.md | Embeds RepoConnectors view diagram |
| docs/design/build-mark/repo-connectors/github.md | Embeds GitHub view diagram |
| docs/design/build-mark/repo-connectors/github/github-repo-connector.md | Embeds GitHub view diagram |
| docs/design/build-mark/repo-connectors/github/github-graphql-types.md | Embeds GitHub view diagram |
| docs/design/build-mark/repo-connectors/github/github-graphql-client.md | Embeds GitHub view diagram |
| docs/design/build-mark/repo-connectors/azure-devops.md | Embeds AzureDevOps view diagram |
| docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md | Embeds AzureDevOps view diagram |
| docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md | Embeds AzureDevOps view diagram |
| docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md | Embeds AzureDevOps view diagram |
| docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md | Embeds AzureDevOps view diagram |
| docs/design/build-mark/repo-connectors/mock.md | Embeds Mock view diagram |
| docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md | Embeds Mock view diagram |
| AGENTS.md | Documents SysML2-first navigation + planning agent |
| .versionmark.yaml | Adds sysml2tools version capture regex |
| .github/workflows/build.yaml | Renders SysML2 diagrams during doc build |
| .github/standards/sysml2-modeling.md | Adds SysML2 modeling and rendering standard |
| .github/standards/software-items.md | Notes SysML2 comment metadata linkage |
| .github/standards/reviewmark-usage.md | Adds SysML2 files + context guidance |
| .github/standards/design-documentation.md | Requires SysML2-derived structure diagrams |
| .github/skills/sysml2tools-query/SKILL.md | Adds SysML2Tools query workflow skill |
| .github/agents/template-sync.agent.md | Expands grouping to include SysML2 + roots |
| .github/agents/quality.agent.md | Adds verification/README/user-guide expectations |
| .github/agents/planning.agent.md | Introduces planning agent + report template |
| .github/agents/lint-fix.agent.md | Adds standardized report path metadata |
| .github/agents/implementation.agent.md | Switches planning to planning agent + metadata |
| .github/agents/formal-review.agent.md | Clarifies context vs reviewed files + report path |
| .github/agents/developer.agent.md | Expands companion artifacts + report path |
| .cspell.yaml | Adds “sysml” dictionary term |
| .config/dotnet-tools.json | Adds demaconsulting.sysml2tools.tool |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Pandoc does not rewrite image src paths when merging multiple markdown files (from different source directories) into a single output document — it passes each markdown image reference through literally. Since the compiled docs/design/generated/design.html always sits in the same directory as the rendered SVGs (docs/design/generated/), the only path that resolves correctly for every source file, regardless of its own folder depth, is a bare filename with no directory prefix. The relative paths added when the SysML2 model was introduced (generated/X.svg, ../generated/X.svg, ../../generated/X.svg, etc., computed per source file's folder depth) were wrong: they only coincidentally resolved for source files one level deep, and were broken everywhere else, including the top-level introduction.md and build-mark.md. As a result, no SysML2 diagrams rendered in the CI-built PDF. Verified locally: rebuilt design.html + PDF with WeasyPrint before and after this fix. Before: 51 embedded vector Form XObjects, 657KB PDF. After: 433 Form XObjects, 880KB PDF — confirming the diagrams are now genuinely embedded. pwsh ./lint.ps1 passes clean (0 errors). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Verified the full design-document build.yaml pipeline locally after this change: sysml2tools render (12 views), Pandoc HTML generation, WeasyPrint PDF generation, and FileAssert both passed (Pandoc_DesignHtml, WeasyPrint_DesignPdf). Diagrams remain embedded in the compiled PDF. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
docs/sysml2/**/*.sysml was missing from the top-level needs-review patterns and from every review-set's paths, so the model was never flagged for review despite being the authoritative structural source per sysml2-modeling.md. Add the pattern to needs-review and to BuildMark-Architecture (the closest existing analog to the standard's Decomposition review-set, which this repo's older .reviewmark.yaml predates). Verified: dotnet reviewmark --lint passes; dotnet reviewmark --plan --enforce confirms all 53 docs/sysml2/**/*.sysml files are now captured by BuildMark-Architecture (previously 0). One pre-existing, unrelated uncovered file remains (docs/design/ots/yaml-dot-net.md) - out of scope for this change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…rage
docs/design/ots/yaml-dot-net.md existed but had no review-set at all
(every other OTS item has an OTS-{Name} review-set), leaving it
uncovered and causing 'dotnet reviewmark --plan --enforce' to fail the
CI merge-gate. Add OTS-YamlDotNet covering the existing design doc.
Note: unlike other OTS items, YamlDotNet has no docs/reqstream/ots/
or docs/verification/ots/ file and is not included in requirements.yaml
- a separate, pre-existing ReqStream traceability gap, out of scope for
this change (this fix addresses only ReviewMark file coverage).
Verified: dotnet reviewmark --lint passes; dotnet reviewmark --plan
--enforce now exits 0 with zero uncovered files (previously 1).
Full lint.ps1 passes clean.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add top-level context key and Decomposition review-set - Add 9 OTS-* review-set titles fixed to standard wording; OTS-BuildMark title fixed - Fix Purpose title/scope, BuildMark-Architecture scope (remove sysml2 model) - Fix BuildMark-AllRequirements scope and title - Fix 30 title-wording deviations across system/subsystem/unit review-sets - Add per-review-set context entries per Context Files table - Fix depth-1 subsystem docs/design and docs/reqstream path references from nested to flat form to match actual files on disk and depth-2 convention Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
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 significant enhancements and clarifications to the agent orchestration and reporting workflow, with a strong focus on improving traceability, artifact coverage, and quality compliance in the development process. It adds a dedicated planning agent, revises the expectations and reporting for implementation, quality, and review agents, and updates the handling of companion artifacts across the workflow. The changes also improve documentation and reporting consistency throughout the agent system.
Agent Workflow and Artifact Coverage Improvements:
planning.agent.mdfile defining a custom planning agent that investigates the codebase, develops a verified implementation plan, identifies all required companion artifacts, and produces a structured report and summary.implementation.agent.md) to use the new planning agent, clarify state transitions, report file locations, and include companion artifact tables in context for downstream agents. The reporting template now emphasizes traceability and unknowns. [1] [2] [3] [4] [5]Review and Template Synchronization Enhancements:
Tooling and Documentation Consistency:
demaconsulting.sysml2tools.toolto.config/dotnet-tools.jsonfor SysML2 model support.These changes collectively strengthen the agent-based workflow by ensuring all required artifacts are planned, produced, and validated, improving traceability, and making agent outputs more actionable and auditable.