Enhance agent consistency and add planning agent documentation#18
Merged
Conversation
- Add planning.agent.md: standalone planning agent extracted from implementation's inline explore call, with 7-step workflow, full audit report, and lean structured response to caller - Update implementation.agent.md: call planning custom agent instead of explore built-in; handle SUCCEEDED/INCOMPLETE/FAILED results; pass planning companion artifact table to quality; add Unknowns section for INCOMPLETE path; add Report field; rename Final State to Last Active State - Update developer.agent.md: add verification docs, README.md, and user guides to companion artifact pre-flight list; add Report field - Update quality.agent.md: add verification docs and README/user guide to scope analysis; fix review-set trigger to software item hierarchy changes only; separate Documentation from structural change enforcement; add Verification Documentation Compliance section; rename Review Management to Review Sets; fix traceability wording; fix Skipped example; add Report field; cross-reference planning companion artifact table - Update formal-review.agent.md: add Report field - Update lint-fix.agent.md: add Report field - Update template-sync.agent.md: add root-file work group for docs/design, docs/verification, docs/reqstream; name sub-agent types; clarify no-template vs unfetchable-mapped semantics; define per-group response schema; add INCOMPLETE result with Unknowns section; add Report field - Update AGENTS.md: behavior-based agent routing; planning agent in delegation matrix; reporting convention updated to include INCOMPLETE; SUCCEEDED scoped to agent scope; template-url renamed to kebab-case; INCOMPLETE extended to planning and template-sync - Update README.md and docs/user_guide/introduction.md: add planning agent documentation; update implementation description; add template-sync to Other Agents table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the agent workflow documentation/specs to introduce a new standalone planning agent, wire it into the implementation orchestrator, and tighten traceability expectations around companion artifacts (requirements/design/verification/docs/review-sets).
Changes:
- Added
planningagent spec and documented it in the README and user guide. - Updated
implementationorchestration to callplanningfirst and pass planning artifact expectations intoquality. - Refined multiple standards/agent prompts to clarify artifact requirements, reporting paths, and verification/design documentation rules.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/AGENTS.md | Updates delegation guidance and standardizes template URL key + reporting semantics. |
| src/.github/standards/verification-documentation.md | Adjusts verification doc structure/requirements and removes in-doc requirements coverage mapping. |
| src/.github/standards/testing-principles.md | Streamlines introductory text; keeps core testing boundary rules. |
| src/.github/standards/technical-documentation.md | Streamlines documentation standards wording and formatting guidance. |
| src/.github/standards/software-items.md | Tightens wording around artifact locations and integration design phrasing. |
| src/.github/standards/reviewmark-usage.md | Streamlines review-set guidance/checklist verbosity. |
| src/.github/standards/design-documentation.md | Clarifies mandatory sections, classification rules, and OTS/shared design structure. |
| src/.github/standards/csharp-testing.md | Streamlines quality checks section header text. |
| src/.github/standards/csharp-language.md | Streamlines intro text before example. |
| src/.github/standards/cpp-testing.md | Streamlines quality checks section header text. |
| src/.github/standards/cpp-language.md | Simplifies Doxygen guidance intro text. |
| src/.github/standards/coding-principles.md | Streamlines and clarifies literate coding / anti-pattern wording. |
| src/.github/agents/template-sync.agent.md | Expands orchestration rules, result semantics, and per-file reporting format. |
| src/.github/agents/quality.agent.md | Adds planning-table cross-checking and introduces verification-doc compliance section. |
| src/.github/agents/planning.agent.md | New planning agent spec with report templates and critique/risks/feasibility steps. |
| src/.github/agents/lint-fix.agent.md | Adds report path metadata field to lint-fix report template. |
| src/.github/agents/implementation.agent.md | Switches PLANNING state from built-in explore to custom planning; passes artifact table to quality. |
| src/.github/agents/formal-review.agent.md | Adds report path metadata field to formal-review report template. |
| src/.github/agents/developer.agent.md | Expands companion artifact categories and adds report path metadata field. |
| README.md | Documents the new planning agent and adds template-sync to the agent list. |
| docs/user_guide/introduction.md | Documents planning agent and updates implementation + agent listings accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Replace per-requirement traceability checks with checks that match the verification-documentation standard: validate mandatory section completeness in verification docs, and confirm requirements-to-test coverage is tracked via ReqStream trace matrix (not embedded in verification documents). Co-authored-by: Copilot <223556219+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 a new standalone planning agent, updates the orchestration and quality processes to integrate this agent, and clarifies the reporting and artifact requirements throughout the documentation and agent specs. The most significant changes are the addition of the
planningagent, improved traceability and artifact requirements, and enhancements to report formatting and content.Agent Architecture and Workflow Updates:
planningagent (planning.agent.md) that investigates the codebase, produces a verified implementation plan, and identifies all required companion artifacts. The agent includes a critique-and-strengthen cycle, risk and feasibility assessment, and a structured reporting template.planningagent (instead of the oldexploreagent) as the first step in the orchestration state machine. The orchestration now passes the planning companion artifact table to the quality agent for enhanced traceability. [1] [2] [3] [4] [5] [6] [7]Documentation and Reporting Enhancements:
Agent Catalog and User Guide Updates:
planningandtemplate-syncagents to the agent catalog tables in the documentation, and updated usage guidance for when to use the new planning agent. [1] [2] [3]These changes collectively strengthen the planning and quality assurance process, ensure better artifact traceability, and improve clarity for both users and agent implementers.