Migrate to SysML2 architecture model and update related documentation

[Malcolmnixon]

This pull request introduces significant improvements to the agent orchestration and reporting process, enhances quality and planning agent standards, and adds a new dedicated planning agent. The changes ensure stricter traceability and artifact coverage, clarify agent responsibilities, and unify reporting formats across agents. Additionally, the .dotnet-tools.json and .cspell.yaml files are updated to support the new sysml2tools tool.

Agent Orchestration and Reporting Enhancements:

• Refactored the implementation agent to use a dedicated planning agent instead of the generic explore agent, updating state transitions and clarifying the flow for SUCCEEDED, FAILED, and INCOMPLETE results. The planning agent now produces a structured report file referenced throughout the orchestration process. [1] [2] [3] [4] [5]
• Unified report file naming and referencing conventions across developer, formal review, lint-fix, planning, and quality agents for consistency and traceability. [1] [2] [3] [4] [5]

Planning and Quality Agent Improvements:

• Added .github/agents/planning.agent.md, defining a comprehensive planning process: loading standards, identifying companion artifacts, critiquing assumptions, assessing risks and feasibility, and producing a structured, auditable report and summary.
• Updated the quality agent to cross-reference the planning agent’s companion artifact table, enforce stricter artifact coverage (requirements, design, verification, README, user guides, review sets), and expand the compliance checklist, including repository structure and traceability. [1] [2]

Process and Standards Clarifications:

• Improved developer agent instructions to ensure companion artifacts (requirements, design docs, verification docs, tests, review-sets, README, user guides) are always considered and updated as part of the work plan.
• Clarified formal review agent instructions for distinguishing context/reference files from files under review and updated reporting requirements.

Tooling and Spellcheck Updates:

• Added demaconsulting.sysml2tools.tool to .config/dotnet-tools.json and corresponding terms to .cspell.yaml for improved toolchain support and spellchecking. [1] [2]

---

Most Important Changes:

Agent Orchestration and Reporting

• Refactored the implementation agent to use a dedicated planning agent, clarifying state transitions and report file handling for SUCCEEDED, FAILED, and INCOMPLETE outcomes. [1] [2] [3] [4] [5]
• Standardized report file naming and referencing across all agents for improved traceability. [1] [2] [3] [4] [5]

Planning and Quality Process

• Added a new planning.agent.md defining a structured planning workflow, including standards loading, artifact identification, assumption analysis, risk and feasibility assessment, and reporting.
• Enhanced the quality agent to enforce stricter artifact coverage, cross-reference planning outputs, and expand the compliance checklist (requirements, design, verification, documentation, review sets, repository structure). [1] [2]

Process and Standards

• Updated developer and formal review agent instructions to ensure all companion artifacts are considered and that review context is handled correctly. [1] [2]

Tooling

• Added the sysml2tools tool to .dotnet-tools.json and updated .cspell.yaml for new terminology. [1] [2]

[Copilot]

Pull request overview

This PR migrates the repository’s “software structure” source of truth from hand-maintained prose to a SysML2 model under docs/sysml2/, integrates SysML2Tools into the CI/lint toolchain, and updates agent/standards documentation to reflect the new architecture-model-first workflow.

Changes:

• Added a SysML2 architecture model (docs/sysml2/**) plus a SysML2Tools query skill and modeling standard, and embedded rendered diagrams into the design docs.
• Integrated SysML2Tools into compliance tooling: dotnet tool manifest + VersionMark capture + lint.ps1 + CI render/self-validation steps.
• Refined Continuous Compliance standards and agent orchestration/reporting guidance (planning agent, quality agent, ReviewMark context/review-set structure, etc.).

Reviewed changes

Copilot reviewed 50 out of 51 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 ReqStream root include list.
lint.ps1	Adds SysML2Tools model linting to the compliance tools lint pass.
docs/verification/ots/sysml2tools.md	Adds OTS verification evidence narrative for SysML2Tools.
docs/verification/introduction.md	Updates OTS list to include SysML2Tools; removes the old structure tree section.
docs/verification/definition.yaml	Adds additional NuGetCaching verification docs and SysML2Tools verification to the compiled verification collection.
docs/sysml2/views/design-views.sysml	Declares rendered views used by the design documentation.
docs/sysml2/model/ots.sysml	Models OTS dependencies (NuGet SDK, Polyfill) as SysML2 parts with artifact references.
docs/sysml2/model/nuget-caching/path-helpers.sysml	Models PathHelpers unit and links companion artifacts via comments.
docs/sysml2/model/nuget-caching/package-source-resolver.sysml	Models PackageSourceResolver unit and links companion artifacts via comments.
docs/sysml2/model/nuget-caching/package-downloader.sysml	Models PackageDownloader unit and links companion artifacts via comments.
docs/sysml2/model/nuget-caching/nuget-cache.sysml	Models NuGetCache unit and links companion artifacts via comments.
docs/sysml2/model/nuget-caching/credential-service-registrar.sysml	Models CredentialServiceRegistrar unit and links companion artifacts (with test omission note).
docs/sysml2/model/nuget-caching/auth-failure-classifier.sysml	Models AuthFailureClassifier unit and links companion artifacts via comments.
docs/sysml2/model/nuget-caching.sysml	Models the system root (NuGetCachingSystem) and composes units + OTS dependencies.
docs/reqstream/ots/sysml2tools.yaml	Defines OTS requirements for SysML2Tools lint/render behaviors.
docs/design/nuget-caching/path-helpers.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching/package-source-resolver.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching/package-downloader.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching/nuget-cache.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching/credential-service-registrar.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching/auth-failure-classifier.md	Embeds SysML2-rendered structure diagram in the unit design doc.
docs/design/nuget-caching.md	Embeds SysML2-rendered system structure diagram in the system design doc.
docs/design/introduction.md	Replaces the prose structure tree with SysML2-derived diagram guidance and embed.
docs/design/definition.yaml	Adds more design docs to the compiled design collection.
AGENTS.md	Updates repo overview/navigation guidance to prefer SysML2 model querying; adds agent/process clarifications.
.versionmark.yaml	Adds SysML2Tools to VersionMark tool-version capture patterns.
.reviewmark.yaml	Adds SysML2 files to review scope and refines review-set structure/context.
.gitignore	Ignores docs/design/generated/ output folder (rendered diagrams).
.github/workflows/build.yaml	Adds SysML2Tools to tool capture and runs SysML2Tools self-validation + render in the design-docs pipeline.
.github/standards/verification-documentation.md	Updates verification doc structure/requirements and adds shared package sections.
.github/standards/testing-principles.md	Trims/reformats introductory text; keeps testing principle rules.
.github/standards/technical-documentation.md	Clarifies generated folder policy and tightens documentation formatting guidance.
.github/standards/sysml2-modeling.md	Adds SysML2 modeling conventions, view conventions, and build/lint integration rules.
.github/standards/software-items.md	Expands software item taxonomy to include “Shared Package” and refines naming/path conventions.
.github/standards/reviewmark-usage.md	Updates ReviewMark configuration guidance (context, decomposition review, shared/OTS patterns).
.github/standards/reqstream-usage.md	Updates ReqStream structure guidance (adds shared folder, clarifies section nesting patterns).
.github/standards/design-documentation.md	Updates design doc structure rules; ties software structure to SysML2-derived diagrams.
.github/standards/csharp-testing.md	Minor formatting cleanup in testing standard.
.github/standards/csharp-language.md	Minor formatting cleanup in language standard.
.github/standards/coding-principles.md	Minor formatting cleanup and wording refinement.
.github/skills/sysml2tools-query/SKILL.md	Adds an agent skill for querying the SysML2 model via SysML2Tools CLI.
.github/agents/template-sync.agent.md	Adds a new template-sync orchestrator agent spec.
.github/agents/software-architect.agent.md	Updates taxonomy reference to include Shared Package.
.github/agents/quality.agent.md	Strengthens quality checks (companion artifact coverage, verification docs, review sets, repository structure).
.github/agents/planning.agent.md	Adds a dedicated planning agent spec and report template.
.github/agents/lint-fix.agent.md	Unifies lint-fix report metadata format.
.github/agents/implementation.agent.md	Switches orchestration to use the planning agent; updates state/report metadata.
.github/agents/formal-review.agent.md	Clarifies review workflow and unifies report metadata.
.github/agents/developer.agent.md	Strengthens pre-flight artifact planning and unifies report metadata.
.cspell.yaml	Adds SysML-related terms to spellchecker allow-list.
.config/dotnet-tools.json	Adds SysML2Tools as a pinned local dotnet tool.

---

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

[Copilot]

Pull request overview

Copilot reviewed 50 out of 51 changed files in this pull request and generated 1 comment.