fix(agents): add parallel subagent dispatch and structured JSON contracts to code-review-full by erikschlegel · Pull Request #1304 · microsoft/hve-core

erikschlegel · 2026-04-06T22:05:00Z

Pull Request

Related Issue(s)

Description

Refactors the code-review-full orchestrator from a sequential single-agent prompt into a parallel two-subagent architecture with structured JSON contracts, deterministic merge heuristics, and consolidated read discipline.

Architecture

The orchestrator classifies diffs by T-shirt size (S/M/L/XL) and dispatches two parallel subagents — Code Review Functional and Code Review Standards — with lane boundary directives that prevent finding overlap. Each subagent writes structured JSON findings to disk; the orchestrator merges results using symbol-name-first deduplication.

Key changes

Parallel subagent dispatch: orchestrator computes the diff, writes diff-state.json, and launches functional + standards subagents concurrently with structured JSON output contracts
T-shirt size classification: S/M diffs reviewed inline; L/XL diffs use batched subagent strategies with corrected non-overlapping tier boundaries
Lane directives: functional agent owns logic/correctness findings; standards agent owns skill-backed convention findings — each agent includes an explicit lane boundary section
Read discipline: all three agents enforce single full-range read_file per external file with parallel batching — eliminates 5+ redundant reads per execution
Skill discovery ownership: removed pre-discovery from orchestrator; standards agent owns its own discovery using extensions from diff-state.json
Template extraction: extracted Subagent Findings JSON Schema, Report Skeleton, and persistence rules into docs/templates/full-review-output-format.md to reduce orchestrator token overhead
Writing style compliance: replaced all em dashes with colons and commas per repository writing-style conventions
Documentation rewrite: updated docs/agents/code-review/README.md for parallel architecture and updated language-skills.md with orchestrated mode flow

Files changed (6)

File	Change
`.github/agents/coding-standards/code-review-full.agent.md`	Parallel dispatch, T-shirt sizing, JSON contracts, lane directives, read discipline
`.github/agents/coding-standards/code-review-functional.agent.md`	Orchestrated input gate, lane boundary, read discipline
`.github/agents/coding-standards/code-review-standards.agent.md`	Orchestrated input gate, lane boundary, consolidated skill discovery, read discipline
`docs/agents/code-review/README.md`	Full rewrite for parallel subagent architecture
`docs/agents/code-review/language-skills.md`	Updated orchestrated mode flow and reference table
`docs/templates/full-review-output-format.md`	New template extracted from orchestrator

Type of Change

Select all that apply:

Code & Documentation:

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature causing existing functionality to change)
Documentation update

Infrastructure & Configuration:

AI Artifacts:

Reviewed contribution with prompt-builder agent and addressed all feedback
Copilot instructions (.github/instructions/*.instructions.md)
Copilot prompt (.github/prompts/*.prompt.md)
Copilot agent (.github/agents/*.agent.md)
Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.

Skills: Must include both bash and PowerShell scripts. See Skills.

Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.

See Agents Not Accepted and Model Version Requirements.

Other:

Script/automation (.ps1, .sh, .py)
Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Invoke the full code review via the code-review-full agent on a feature branch, or run one of the subagents standalone:

@Code Review Full — runs the parallel orchestrator on the current branch diff
@Code Review Standards — runs skill-backed standards review standalone
@Code Review Functional — runs functional correctness review standalone

Execution Flow:

Orchestrator detects branch, computes diff, classifies T-shirt size
Writes diff-state.json with branch metadata, file list, extensions, and diff path
Dispatches functional and standards subagents in parallel via runSubagent
Each subagent reads diff once, applies its review lens, writes JSON findings to findingsFolder
Orchestrator reads both findings files, merges using symbol-name deduplication (Rule 3), assembles final report

Output Artifacts:

.copilot-tracking/reviews/code-reviews/<branch>/diff-state.json — diff metadata
.copilot-tracking/reviews/code-reviews/<branch>/functional-findings.json — functional subagent output
.copilot-tracking/reviews/code-reviews/<branch>/standards-findings.json — standards subagent output
.copilot-tracking/reviews/code-reviews/<branch>/review.md — merged final report
.copilot-tracking/reviews/code-reviews/<branch>/metadata.json — review run metadata

Success Indicators:

Both subagent JSON files exist and contain valid findings arrays
Merged report contains findings from both lanes without duplicates
Verdict follows severity escalation rules (Critical/High → request changes)

For detailed contribution requirements, see:

Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Ran full orchestrated review (Run 10) on review-test-sample.py with intentional code smells — 19 merged findings across both subagents, verdict: request_changes
Verified lane boundary enforcement: functional agent did not produce skill-backed findings; standards agent did not flag logic errors
Verified finding deduplication: no duplicate findings in merged report
Manual file verification: all 7 changed files confirmed present and correct

Checklist

Required Checks

Documentation is updated (if applicable)
Files follow existing naming conventions
Changes are backwards compatible (if applicable)
Tests added for new functionality (if applicable)

AI Artifact Contributions

Used /prompt-analyze to review contribution
Addressed all feedback from prompt-builder review
Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

Markdown linting: npm run lint:md
Spell checking: npm run spell-check
Frontmatter validation: npm run lint:frontmatter
Skill structure validation: npm run validate:skills
Link validation: npm run lint:md-links
PowerShell analysis: npm run lint:ps
Plugin freshness: npm run plugin:generate
Docusaurus tests: npm run docs:test

Security Considerations

This PR does not contain any sensitive or NDA information
Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
Security-related scripts follow the principle of least privilege (N/A — no security script changes)

Additional Notes

None

codecov-commenter · 2026-04-06T22:06:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.62%. Comparing base (812569b) to head (c887419).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1304      +/-   ##
==========================================
- Coverage   87.63%   87.62%   -0.02%     
==========================================
  Files          61       61              
  Lines        9328     9328              
==========================================
- Hits         8175     8174       -1     
- Misses       1153     1154       +1

Flag	Coverage Δ
pester	`85.18% <ø> (-0.02%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

Refactors the code-review-full agent from a sequential orchestrator into a parallel two-subagent architecture, using structured JSON output contracts to enable deterministic merging and updated documentation/templates to match the new flow.

Changes:

Updates code-review-full to compute a single pr-reference diff, write diff-state.json, dispatch Functional + Standards subagents in parallel, and merge their JSON findings into a single report.
Adds orchestrated-mode “input gate” + lane-boundary + read-discipline rules to both subagents, with JSON output written to disk for the orchestrator to merge.
Updates docs and introduces a shared template defining the merged report skeleton and the subagent findings JSON schema.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.github/agents/coding-standards/code-review-full.agent.md	Parallel dispatch orchestration, diff-state contract, merge rules, and progress announcements
.github/agents/coding-standards/code-review-functional.agent.md	Orchestrated input gate + lane boundary + JSON output contract
.github/agents/coding-standards/code-review-standards.agent.md	Orchestrated input gate + lane boundary + skill discovery changes + JSON output contract
collections/coding-standards.collection.yml	Adds `pr-reference` skill to collection dependencies
docs/agents/code-review/README.md	Documentation updated for the parallel orchestrator architecture and artifact flow
docs/agents/code-review/language-skills.md	Updates skill-loading flow documentation for orchestrated vs standalone modes
docs/templates/full-review-output-format.md	New authoritative schema + report skeleton + persist-and-present rules for full review output

katriendg

Thanks @erikschlegel for these new improvements after your testing.

One note I wanted to share, I was at first confused by subagent terminology, as until now we have always used it when we hide away the agents from invocation, in this case we are allowing both usages as subagents and as standalone agents.

I think we can do this, since both options make sense (as standalone agents, and invoked as subagents), but we need to add some updated wording to ensure folks still follow and understand the working.
Or, should we reflect in only allowing the subagents to no longer be available as standalone?

Here's some reflections and suggestions:

The docs consistently refer to the functional and standards agents as "subagents" (e.g., "dispatches both subagents in parallel", "Functional subagent", "Standards subagent"). Since these are dual-mode agents — usable both standalone and as subagents under the orchestrator — the subagent-only terminology could confuse users who see them listed as full agents in the Copilot Chat panel.

Precedent comparison

Every other orchestrator in the repo uses distinct files for main agents vs subagents:

Orchestrator	Main Agent (user-facing)	Subagent (`user-invocable: false`, in `subagents/`)
RPI Agent	`Task Researcher`	`Researcher Subagent`
RPI Agent	`Task Implementor`	`Phase Implementor`
Security Reviewer	(none)	`Codebase Profiler`, `Skill Assessor`, etc.

The code-review-full orchestrator introduces a new pattern where the same agent file serves both roles, with conditional sections (Orchestrated Input gates, Lane Boundary toggles) that switch behavior based on whether diff-state.json is provided. This is not prohibited by prompt-builder instructions (user-invocable: false is optional, subagents/ is "typical"), but it has no precedent. The docs should acknowledge this distinction so users and contributors understand the dual-mode design.

Suggested Change

Add a brief note near the top of the "Three Agents" section or the architecture overview clarifying the dual-mode nature:

The Functional and Standards agents operate independently when invoked from the Chat panel. When the orchestrator invokes them, they run as subagents with lane boundaries that partition their review scope.

Alternatively, use "agents" when discussing them as standalone and "subagents" only when specifically describing orchestrated dispatch.

Consider a follow-up PR to update prompt-builder.instructions.md to document dual-mode agents as an accepted alternative to the separate-file subagent pattern.

erikschlegel · 2026-04-07T12:57:21Z

Add a brief note near the top of the "Three Agents" section or the architecture overview clarifying the dual-mode nature:

Updated the docs to provide the dual-mode context

I also addressed all your other comments @katriendg, thanks for the review

…review Add parallel dispatch of Functional and Standards agents with structured JSON contracts and merged report output. Changes: - Add lane directives preventing overlapping findings between agents - Add read discipline consolidating file reads into parallel batches - Extract output format template to docs/templates/ - Move skill discovery ownership entirely to Standards agent - Add T-shirt size classification and diff single-read guard - Simplify merge heuristic with dedup and severity sorting - Add dual-mode note clarifying standalone vs orchestrated usage - Skip standalone templates in orchestrated mode to reduce context - Add cross-platform pre-clean commands (Bash + PowerShell) - Escape angle brackets in MDX documentation for Docusaurus - Simplify skill discovery instruction (match by language/framework/extension)

katriendg

Thank you @erikschlegel for the quick response back and updates.
From what I could see going through it a second time, looks good now.

## Pre-Release 3.3.101 ### ✨ Features - add removed maturity tier and retire owasp-docker (#1444) - add evaluation dataset creator (#1279) - align RAI planner with guide, remove scoring, improve UX (#1287) - add PSGallery staleness check and BOM cleanup (#1379) - ISA-95 network planner agent (#1177) - auto-generate collection.md with maturity filtering (#1316) - add folder-consistency check and standardize WARN outp… (#1350) - add synth-data-generate prompt to data-science collection (#1419) - add canonical deck workflow and customer-card rendering for design thinking (#1413) - add Figma MCP integration for DT artifact export (#1222) - introduce `owasp-docker` (#1245) - replace hve-core-specific references with portable discovery-based language (#1335) - introduce `owasp-cicd` (#1246) - add secure-by-design knowledge skill (#1223) - introduce `owasp-infrastructure` (#1244) - introduce `owasp-mcp` (#1207) - add OutputPath parameter to Invoke-LinkLanguageCheck.ps1 (#1229) - add -OutputPath parameter to Validate-SkillStructure.ps1 (#1225) - add maintainer-only skip-review label guard (#1293) - add extension collections overview and integrate into getting started flow (#950) - add agentic workflows for automated issue triage, implementation, PR review, dependency review, and doc-staleness detection (#1219) - consolidate package-lock.json version sync into Update-VersionFiles.ps1 (#1240) - add standards code review agent and full review orchestrator (#1174) - standardize pytest-mock as Python mocking framework (#1170) - add Jira backlog workflows and Jira/GitLab skills (#978) - add centralized version bump script and supply-chain attestation (#1183) ### 🐛 Bug Fixes - pin PowerShell-Yaml to 0.4.7 across all install sites (#1378) - close fork-PR/workflow-file-PR secret-strip gap and normalize upload-artifact version (#1421) - replace stream-based lookahead with array indexing in list-changed-files.sh (#1376) - centralize ISO 8601 timestamp regex in CIHelpers (#1343) - update stale documentation date in release-process.md (#1363) - pin basic-ftp to 5.3.0 to resolve GHSA-rp42-5vxx-qpwr (#1374) - add bot filter to dependency PR review workflow (#1362) - resolve pip-audit findings in powerpoint, gitlab, and jira skill lock files (#1360) - standardize Timestamp JSON key casing across all lint result files (#1314) - add synchronize trigger to PR Review workflow (#1323) - standardize timestamp in Validate-SkillStructure.ps1 to use Get-StandardTimestamp (#1280) - add parallel subagent dispatch and structured JSON contracts to code-review-full (#1304) - standardize timestamp in SecurityHelpers.psm1 to use Get-StandardTimestamp (#1284) - standardize timestamps in Test-DependencyPinning.ps1 and SecurityClasses.psm1 (#1282) - derive collection artifact counts from YAML at build time (#1275) - standardize timestamp in FrontmatterValidation.psm1 to use Get-StandardTimestamp (#1285) - standardize timestamp in Markdown-Link-Check.ps1 to use Get-StandardTimestamp (#1283) - escape hyphens in Mermaid diagram on Collections page (#1262) - add summary timestamp to PSScriptAnalyzer output (#1211) - fix plugin compatibility and robustness for coding-standards code review agents (#1289) - standardize timestamp in Test-CopyrightHeaders.ps1 to use Get-StandardTimestamp (#1278) - standardize timestamp in Invoke-YamlLint.ps1 to use Get-StandardTimestamp (#1270) - standardize timestamp in Invoke-LinkLanguageCheck.ps1 to use Get-StandardTimestamp (#1264) - fix dependency-review path filters and sparse-checkout cone mode (#1259) - replace invalid bare tool names with official tool identifiers (#1198) - fix broken links and remove orphaned reference in code review docs (#1257) - exclude Python env dirs from skill validation warnings (#1255) - pin happy-dom and serialize-javascript to resolve Dependabot vulnerabilities (#1253) - remove Mermaid diagram and add missing collection cards (#1247) - disable MCP servers by default to prevent token limit errors (#1144) - sync package-lock.json after pre-release version bump (#1236) - separate mermaid node declarations and add dynamic diagram generation with tests (#1215) - replace anchor links in meeting-analyst with bold text references (#1201) - remove recursive symlinks in jira and gitlab skill directories (#1233) - validate-installation scripts now check .github/skills directory (#1010) (#1206) - resolve npm audit vulnerabilities via dependency overrides (#1200) - add post-release triggers to scorecard workflow (#1186) - add missing .md extensions to relative links in agent documentation (#1180) ### 📚 Documentation - broaden Security Review description beyond OWASP (#1385) - document maintainer advisory mode and skip-review label guard (#1386) - document ExcludePaths/OutputPath for Invoke-LinkLanguageCheck (#1383) - CLI getting-started: clarify plugin install commands as alternatives (-all vs base) (#1251) ### ♻️ Refactoring - align agent and prompt folder names to collection identifier (#1210) ### 🔧 Maintenance - pin PSScriptAnalyzer to 1.25.0 and sync stale workflow version comments (#1389) - bump lxml from 6.0.2 to 6.1.0 in /.github/skills/experimental/powerpoint (#1424) - bump @vscode/vsce from 3.7.1 to 3.9.1 in the npm-dependencies group (#1390) - bump the github-actions group across 1 directory with 7 updates (#1391) - bump follow-redirects from 1.15.11 to 1.16.0 in /docs/docusaurus (#1356) - upgrade Node.js from 20 to 24 and bump cspell to v10 (#1353) - bump basic-ftp from 5.2.0 to 5.2.1 (#1324) - update github/gh-aw-actions requirement to 536ea1bad8c6715d098a9dc1afea8d403733acfe in the github-actions group across 1 directory (#1298) - update security instruction attributions and compliance (#1294) - bump the npm-dependencies group with 2 updates (#1297) - pre-release 3.3.41 (#1252) - streamline RAI Planner phase structure and documentation (#1273) - bump happy-dom from 20.8.8 to 20.8.9 in /docs/docusaurus (#1237) - pre-release 3.3.27 (#1191) - bump pygments from 2.19.2 to 2.20.0 in /.github/skills/gitlab/gitlab (#1234) - bump path-to-regexp from 0.1.12 to 0.1.13 in /docs/docusaurus (#1226) - bump the github-actions group with 4 updates (#1231) - add missing folders and alphabetize location lists (#1193) - bump brace-expansion (#1224) - bump handlebars from 4.7.8 to 4.7.9 in /docs/docusaurus (#1217) - bump brace-expansion from 5.0.3 to 5.0.5 in /docs/docusaurus (#1213) - pre-release 3.3.10 (#1187) - bump markdownlint-cli2 from 0.21.0 to 0.22.0 in the npm-dependencies group (#1175) - bump the github-actions group with 3 updates (#1176) - pre-release 3.3.1 (#1165) --- *Managed automatically by pre-release workflow.* Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

erikschlegel self-assigned this Apr 6, 2026

erikschlegel changed the title ~~Feat/code review full parallel subagents~~ fix(agents): add parallel subagent dispatch and structured JSON contracts to code-review-full Apr 6, 2026

erikschlegel requested a review from Copilot April 6, 2026 23:23

Copilot started reviewing on behalf of erikschlegel April 6, 2026 23:24 View session

Copilot AI reviewed Apr 6, 2026

View reviewed changes

Comment thread .github/agents/coding-standards/code-review-full.agent.md Outdated

Comment thread docs/agents/code-review/README.md Outdated

Comment thread docs/agents/code-review/language-skills.md Outdated

Comment thread .github/agents/coding-standards/code-review-standards.agent.md Outdated

erikschlegel force-pushed the feat/code-review-full-parallel-subagents branch from aa8c9d5 to bcaa972 Compare April 7, 2026 00:25

erikschlegel marked this pull request as ready for review April 7, 2026 01:06

erikschlegel requested a review from a team as a code owner April 7, 2026 01:06

katriendg reviewed Apr 7, 2026

View reviewed changes

Comment thread .github/agents/coding-standards/code-review-standards.agent.md

Comment thread .github/agents/coding-standards/code-review-full.agent.md

Comment thread .github/agents/coding-standards/code-review-full.agent.md Outdated

erikschlegel force-pushed the feat/code-review-full-parallel-subagents branch from e0eb71c to db5e754 Compare April 7, 2026 12:55

erikschlegel force-pushed the feat/code-review-full-parallel-subagents branch from db5e754 to c887419 Compare April 7, 2026 12:59

katriendg approved these changes Apr 7, 2026

View reviewed changes

Comment thread docs/agents/code-review/README.md

WilliamBerryiii approved these changes Apr 7, 2026

View reviewed changes

WilliamBerryiii merged commit 06df9d2 into microsoft:main Apr 7, 2026
40 checks passed

This was referenced Apr 7, 2026

chore(main): pre-release 3.3.101 #1274

Merged

chore(main): release hve-core 3.4.0 #1184

Open

WilliamBerryiii mentioned this pull request Apr 7, 2026

feat: evaluate dual-mode agent pattern for other orchestrator systems #1310

Open

This was referenced Apr 7, 2026

[aw] No-Op Runs #1265

Open

docs: document dual-mode agent pattern in prompt-builder.instructions.md #1311

Open

feat: audit orchestrator systems for dual-mode agent candidates #1312

Open

hve-core-release-please Bot mentioned this pull request Apr 27, 2026

chore(main): pre-release 3.3.111 #1476

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(agents): add parallel subagent dispatch and structured JSON contracts to code-review-full#1304

fix(agents): add parallel subagent dispatch and structured JSON contracts to code-review-full#1304
WilliamBerryiii merged 1 commit intomicrosoft:mainfrom
erikschlegel:feat/code-review-full-parallel-subagents

erikschlegel commented Apr 6, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Apr 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

katriendg left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

erikschlegel commented Apr 7, 2026

Uh oh!

katriendg left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

erikschlegel commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Related Issue(s)

Description

Architecture

Key changes

Files changed (6)

Type of Change

Sample Prompts (for AI Artifact Contributions)

Testing

Checklist

Required Checks

AI Artifact Contributions

Required Automated Checks

Security Considerations

Additional Notes

Uh oh!

codecov-commenter commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

katriendg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

erikschlegel commented Apr 7, 2026

Uh oh!

katriendg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

erikschlegel commented Apr 6, 2026 •

edited

Loading

codecov-commenter commented Apr 6, 2026 •

edited

Loading