Refactor documentation and apply formal review findings

[Malcolmnixon]

This pull request introduces significant improvements and clarifications to the agent definitions and quality processes for software development orchestration. The changes focus on enhancing traceability, artifact coverage, and compliance verification by refining agent workflows, updating report templates, and adding a dedicated planning agent specification. The updates also clarify companion artifact requirements and improve the rigor of quality and planning assessments.

Key changes include:

New Agent Definition and Planning Process:

• Added a new planning.agent.md file, specifying a detailed, standards-driven process for developing implementation plans, identifying companion artifacts, critiquing assumptions, and reporting unknowns or risks. This includes a structured report and response template for downstream agent coordination.

Improvements to Implementation and Planning Workflows:

• Updated implementation.agent.md to invoke a dedicated planning agent, clarify state transitions (including explicit SUCCEEDED/FAILED/INCOMPLETE outcomes), and reference the planning agent's report for full details. Report templates now include report file paths and explicit sections for unknowns when the result is INCOMPLETE. [1] [2] [3] [4] [5]
• Enhanced developer workflow in developer.agent.md to require fetching templates for new files, explicitly list all relevant companion artifacts (including verification docs, README, user guides), and update reporting instructions. [1] [2]

Quality Assessment and Artifact Coverage:

• Expanded quality.agent.md to enforce stricter coverage of requirements, design, verification docs, README/user guides, and review sets, cross-referencing the planning agent's companion artifact table. Updated the compliance checklist to better reflect artifact and process requirements, including new sections for verification documentation, review sets, repository structure, and process compliance. [1] [2] [3]

Reporting and Review Process Enhancements:

• Updated report templates across agents (lint-fix.agent.md, formal-review.agent.md, etc.) to standardize the inclusion of report file paths and clarify evaluation steps and file organization. [1] [2]

Standards and Vocabulary Updates:

• Clarified the use of terms such as "Shared Package" and "Postconditions" in standards and spell-check configuration files. [1] [2]

These changes collectively improve the rigor, traceability, and clarity of the agent-driven development and review process, ensuring that all required artifacts are properly planned, produced, and validated.

---

Most Important Changes:

1. Planning Agent Introduction and Workflow Overhaul

• Added a new planning.agent.md file, formalizing a step-by-step planning process, companion artifact identification, and structured reporting for downstream agent integration.
• Updated implementation.agent.md to use the planning agent, clarify state transitions, and reference planning reports for full context and unknowns. [1] [2] [3] [4] [5]

2. Quality and Artifact Coverage Improvements

• Enhanced quality.agent.md to require all relevant artifacts (requirements, design, verification, review sets, documentation) are created or updated, cross-referencing the planning agent's companion artifact table, and expanded the compliance checklist. [1] [2] [3]

3. Developer and Review Workflow Clarifications

• Improved developer.agent.md to require template-based file creation, explicitly list all companion artifacts, and update reporting procedures. [1] [2]
• Updated formal-review.agent.md to clarify review context, reporting, and file organization.

4. Reporting Template Standardization

• Standardized report templates across agents to include explicit report file paths and improve clarity. [1] [2]

5. Standards and Vocabulary Updates

• Added "Postconditions" and clarified "Shared Package" in standards and spell-check configuration files. [1] [2]

[Copilot]

Pull request overview

This PR updates the repository’s Continuous Compliance artifacts (agent specs, standards, review configuration, and companion docs) to incorporate formal review findings—especially around planning rigor, artifact traceability, and OTS documentation coverage.

Changes:

• Adds new orchestration capabilities via a dedicated planning agent and a template-sync agent, and updates existing agent report templates/requirements.
• Refactors standards and supporting docs to clarify terminology (OTS/Shared Package), documentation structure rules, and quality/review workflows.
• Updates TemplateDotNetTool design/verification narratives and requirements entries; adds an OTS verification overview and a README contributing pointer.

Reviewed changes

Copilot reviewed 69 out of 69 changed files in this pull request and generated 37 comments.

Show a summary per file

File	Description
README.md	Adds a Contributing section pointing to CONTRIBUTING.md.
AGENTS.md	Expands canonical project metadata placeholders; clarifies standards selection and delegation rules.
.reviewmark.yaml	Updates review-set structure and adds context configuration for hierarchical reviews.
.cspell.yaml	Adds “Postconditions” to the project dictionary.
.github/agents/developer.agent.md	Updates developer workflow to require template-based scaffolding and expanded companion artifact handling.
.github/agents/formal-review.agent.md	Clarifies formal review workflow steps and report location metadata.
.github/agents/implementation.agent.md	Switches planning stage to the new planning agent; clarifies reporting/state transitions.
.github/agents/lint-fix.agent.md	Standardizes report template to include report path metadata.
.github/agents/planning.agent.md	Introduces a dedicated planning agent spec and report template.
.github/agents/quality.agent.md	Expands quality assessment scope and checklist, emphasizing companion artifacts and verification docs.
.github/agents/software-architect.agent.md	Updates vocabulary to include Shared Package category.
.github/agents/template-sync.agent.md	Adds a template-sync orchestrator agent for auditing/syncing against a canonical template.
.github/standards/coding-principles.md	Streamlines wording; clarifies literate coding expectations.
.github/standards/cpp-language.md	Adds new C++ language standards document.
.github/standards/cpp-testing.md	Adds new C++ testing standards document.
.github/standards/csharp-language.md	Trims preamble text in C# language standards.
.github/standards/csharp-testing.md	Trims preamble text in C# testing standards.
.github/standards/design-documentation.md	Refactors design doc structural requirements and introduces OTS/shared design guidance.
.github/standards/reqstream-usage.md	Updates requirements folder structure guidance and adds Shared Package requirements model.
.github/standards/reviewmark-usage.md	Updates ReviewMark configuration guidance and adds context-file expectations.
.github/standards/software-items.md	Adds Shared Package category and expands artifact model guidance.
.github/standards/technical-documentation.md	Adds/clarifies heading-depth rule and generated-folder expectations.
.github/standards/testing-principles.md	Removes redundant header preamble.
.github/standards/verification-documentation.md	Refactors verification doc structural requirements and adds OTS/shared verification guidance.
docs/design/introduction.md	Updates scope/structure narrative and adds explicit OTS design coverage.
docs/design/ots/buildmark.md	Adds OTS integration/usage design doc for BuildMark.
docs/design/ots/fileassert.md	Adds OTS integration/usage design doc for FileAssert.
docs/design/ots/pandoc.md	Adds OTS integration/usage design doc for Pandoc.
docs/design/ots/reqstream.md	Adds OTS integration/usage design doc for ReqStream.
docs/design/ots/reviewmark.md	Adds OTS integration/usage design doc for ReviewMark.
docs/design/ots/sarifmark.md	Adds OTS integration/usage design doc for SarifMark.
docs/design/ots/sonarmark.md	Adds OTS integration/usage design doc for SonarMark.
docs/design/ots/versionmark.md	Adds OTS integration/usage design doc for VersionMark.
docs/design/ots/weasyprint.md	Adds OTS integration/usage design doc for WeasyPrint.
docs/design/ots/xunit.md	Adds OTS integration/usage design doc for xUnit.
docs/design/template-dot-net-tool/cli/cli.md	Refactors CLI subsystem design narrative and interface contracts.
docs/design/template-dot-net-tool/cli/context.md	Refactors Context unit design into structured sections.
docs/design/template-dot-net-tool/program.md	Refactors Program unit design into structured sections.
docs/design/template-dot-net-tool/self-test/self-test.md	Refactors SelfTest subsystem design into structured sections.
docs/design/template-dot-net-tool/self-test/validation.md	Refactors Validation unit design into structured sections.
docs/design/template-dot-net-tool/template-dot-net-tool.md	Refactors system design into architecture/interfaces/dependencies constraints format.
docs/design/template-dot-net-tool/utilities/path-helpers.md	Refactors PathHelpers design into structured “purpose/data model/methods” format.
docs/design/template-dot-net-tool/utilities/utilities.md	Refactors Utilities subsystem design into structured overview/interfaces/design.
docs/reqstream/ots/reviewmark.yaml	Splits ReviewMark operational requirements into finer-grained requirements (lint/elaborate/enforce).
docs/reqstream/template-dot-net-tool/platform-requirements.yaml	Updates platform requirement wording from build/run to execution success.
docs/reqstream/template-dot-net-tool/self-test/self-test.yaml	Adds a SelfTest requirement covering unsupported results extension behavior.
docs/reqstream/template-dot-net-tool/self-test/validation.yaml	Adds a Validation requirement covering unsupported results extension behavior.
docs/reqstream/template-dot-net-tool/template-dot-net-tool.yaml	Updates system-level requirements wording (results failure behavior; banner wording).
docs/user_guide/introduction.md	Adds a References section.
docs/verification/introduction.md	Updates verification scope to include OTS items and clarifies exclusions and artifact layout.
docs/verification/ots.md	Adds an OTS verification overview page.
docs/verification/ots/buildmark.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/fileassert.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/pandoc.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/reqstream.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/reviewmark.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/sarifmark.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/sonarmark.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/versionmark.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/weasyprint.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/ots/xunit.md	Adjusts headings/structure and removes trailing requirements-coverage section.
docs/verification/template-dot-net-tool/cli/cli.md	Refactors CLI subsystem verification doc structure.
docs/verification/template-dot-net-tool/cli/context.md	Refactors Context unit verification doc structure.
docs/verification/template-dot-net-tool/program.md	Refactors Program unit verification doc structure.
docs/verification/template-dot-net-tool/self-test/self-test.md	Refactors SelfTest subsystem verification doc structure.
docs/verification/template-dot-net-tool/self-test/validation.md	Refactors Validation unit verification doc structure.
docs/verification/template-dot-net-tool/template-dot-net-tool.md	Refactors system verification doc into approach/environment/criteria/scenarios.
docs/verification/template-dot-net-tool/utilities/path-helpers.md	Refactors PathHelpers unit verification doc structure.
docs/verification/template-dot-net-tool/utilities/utilities.md	Refactors Utilities subsystem verification doc structure.

---

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

[Copilot]

Pull request overview

Copilot reviewed 79 out of 81 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 79 out of 81 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

docs/reqstream/template-dot-net-tool.yaml:97

• The requirement ID Template-System-ValidateFailure no longer matches the requirement's meaning (it now describes results-file write failure, not a validation test failure). Since IDs appear verbatim in reports/trace matrices, the ID should stay semantically aligned with the title/justification.