chore(rai-planning): streamline RAI Planner phase structure and documentation by WilliamBerryiii · Pull Request #1273 · microsoft/hve-core

WilliamBerryiii · 2026-04-02T02:42:22Z

Description

Reduced the RAI Planner workflow from 6 phases to 5 phases by removing the second phase and renumbering all subsequent phases. This consolidation touched agent definitions, instruction files, collection manifests, plugin metadata, documentation, and plan templates.

Changes by Area

Agent and Instruction Files — Updated rai-planner.agent.md with the new 5-phase workflow description. Modified rai-identity.instructions.md to adjust phase boundaries, terminal state values, and the state machine transitions. Updated rai-backlog-handoff.instructions.md and rai-standards.instructions.md to align phase references throughout. Deleted the removed phase's dedicated instruction file and all plugin symlinks pointing to it.

Collection Manifests and Plugin Metadata — Removed the deleted instruction entry from rai-planning.collection.yml, data-science.collection.yml, hve-core-all.collection.yml, project-planning.collection.yml, and security.collection.yml. Updated collection markdown descriptions to reflect the new phase count. Regenerated plugin outputs including plugin.json and README files across all affected plugin directories.

Documentation — Rewrote phase-reference.md with the consolidated 5-phase sequence. Updated agent-overview.md, docs/agents/README.md, and rai-plan-template.md to remove the deleted phase's sections and renumber remaining phases. Updated CUSTOM-AGENTS.md agent table descriptions.

Other — Deleted .vscode/mcp.json.sample (stale configuration file). Updated dependency-pr-review.md terminology.

Related Issue(s)

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 RAI Planner agent to conduct a responsible AI assessment: @rai-planner Assess my project for responsible AI considerations.

Execution Flow:

The agent reads rai-identity.instructions.md and initializes the 5-phase state machine.
Phase 1 — System Definition: Gathers system context, stakeholders, and AI components.
Phase 2 — RAI Standards Mapping: Maps the system against embedded RAI standards from rai-standards.instructions.md.
Phase 3 — RAI Security Model Analysis: Performs AI-specific STRIDE-based threat modeling.
Phase 4 — RAI Impact Assessment: Evaluates impacts and generates control surfaces.
Phase 5 — Review and Handoff: Produces the final assessment with dual-format backlog handoff per rai-backlog-handoff.instructions.md.

Output Artifacts:

A RAI plan document in .copilot-tracking/rai-plans/ following the template in docs/templates/rai-plan-template.md, plus optional ADO or GitHub work items generated during handoff.

Success Indicators:

The agent completes all 5 phases, produces a plan file with populated sections for each phase, and the plan template aligns with the updated rai-plan-template.md structure.

Note

Human review is recommended for agent-populated Sample Prompts content.

Testing

Automated validation: 4 of 7 required checks passed (lint:md, spell-check, lint:frontmatter, validate:skills). Link validation and PowerShell analysis were skipped at author request. Plugin freshness was validated during implementation.
Diff-based assessment: Verified phase renumbering consistency across all 23 changed files. Confirmed instruction file references, collection manifest entries, plugin metadata, and documentation all reflect the updated 5-phase structure.
Security analysis: No new permissions, secrets, dependencies, or external references introduced. Changes are limited to documentation, instruction content, and plugin metadata.
Manual testing was not performed.

Checklist

Required Checks

Documentation is updated (if applicable)
Files follow existing naming conventions
Changes are backwards compatible (if applicable) (N/A — experimental-maturity artifacts; no stable API contract)
Tests added for new functionality (if applicable) (N/A — documentation and instruction changes only)

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 (skipped)
PowerShell analysis: npm run lint:ps (skipped)
Plugin freshness: npm run plugin:generate

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)

Warning

This PR includes experimental GHCP artifacts that may have breaking changes.

.github/agents/rai-planning/rai-planner.agent.md
.github/instructions/rai-planning/rai-backlog-handoff.instructions.md
.github/instructions/rai-planning/rai-identity.instructions.md
.github/instructions/rai-planning/rai-standards.instructions.md

GHCP Artifact Maturity

File	Type	Maturity	Notes
`.github/agents/rai-planning/rai-planner.agent.md`	Agent	⚠️ experimental	Pre-release only
`.github/instructions/rai-planning/rai-backlog-handoff.instructions.md`	Instructions	⚠️ experimental	Pre-release only
`.github/instructions/rai-planning/rai-identity.instructions.md`	Instructions	⚠️ experimental	Pre-release only
`.github/instructions/rai-planning/rai-standards.instructions.md`	Instructions	⚠️ experimental	Pre-release only

GHCP Maturity Acknowledgment

I acknowledge this PR includes non-stable GHCP artifacts
Non-stable artifacts are intentional for this change

Additional Notes

All changed AI artifacts carry experimental maturity across every collection they appear in. The phase renumbering is a clean cut with no backward-compatibility layer — existing RAI plan documents referencing the old 6-phase structure will need manual alignment with the new 5-phase template.

github-actions · 2026-04-02T02:42:58Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/github/gh-aw-actions/setup	934698b44320d87a7a9196339f90293f10bd2247	Unknown	Unknown

Scanned Files

.github/workflows/dependency-pr-review.lock.yml

codecov-commenter · 2026-04-02T02:44:45Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.71%. Comparing base (ccf30b2) to head (3f41e5e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1273      +/-   ##
==========================================
- Coverage   87.72%   87.71%   -0.02%     
==========================================
  Files          61       61              
  Lines        9320     9320              
==========================================
- Hits         8176     8175       -1     
- Misses       1144     1145       +1

Flag	Coverage Δ
pester	`85.31% <ø> (-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.

github-actions

test

…pendency-review - update package.json path filter from root-only to **/package.json - update package-lock.json path filter from root-only to **/package-lock.json 🔧 - Generated by Copilot

- replace **/requirements.txt and **/pyproject.toml with .github/skills/ - gh-aw hardcodes sparse-checkout-cone-mode which rejects glob patterns - recompile lock file to pick up the directory-based checkout 🔧 - Generated by Copilot

- fix ../../instructions/ to ../instructions/ for github-backlog-triage - fix ../../instructions/ to ../instructions/ for community-interaction 🔗 - Generated by Copilot

- update agents, instructions, collections, docs, and templates - regenerate plugin outputs 🗑️ - Generated by Copilot

- reformat table column widths in handoff-pipeline and phase-reference - update artifact counts in collectionCards.ts to match YAML manifests 🔧 - Generated by Copilot

🔧 - Generated by Copilot

no need

raymond-nassar · 2026-04-02T03:09:08Z

Minor Issues Found During Local Review

Two small inconsistencies noticed while reviewing the branch locally:

1. Frontmatter description still says "6-phase"

File: .github/instructions/rai-planning/rai-identity.instructions.md (line 2)

The YAML frontmatter description field still reads:

RAI Planner identity, 6-phase orchestration, state management, and session recovery

All body content has been correctly updated to 5 phases. Suggest changing 6-phase → 5-phase in the description.

2. `handoffGenerated` schema mismatch between agent and instructions

Agent file (.github/agents/rai-planning/rai-planner.agent.md, line 114):

"handoffGenerated": false

Identity instructions (.github/instructions/rai-planning/rai-identity.instructions.md, line 93):

"handoffGenerated": { "ado": false, "github": false }

The identity instructions version with platform-specific flags is the correct schema (consistent with "platform-specific flags" language in the phase transitions and Phase 5 description). The agent file's state.json example should match.

Neither issue blocks functionality, but both are worth cleaning up for consistency before merge.

raymond-nassar

Minor feedback in the comments.

- update frontmatter description from 6-phase to 5-phase - align handoffGenerated in agent state.json to platform-specific schema 🔧 - Generated by Copilot

## Pre-Release 3.3.41 ### ✨ Features - 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 - 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 - 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 - 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>

## 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>

WilliamBerryiii requested a review from a team as a code owner April 2, 2026 02:42

github-actions Bot mentioned this pull request Apr 2, 2026

[aw] No-Op Runs #1265

Open

github-actions Bot added the needs-revision label Apr 2, 2026

github-actions Bot previously requested changes Apr 2, 2026

View reviewed changes

Bill Berry added 5 commits April 1, 2026 19:52

fix(workflows): add recursive glob prefixes to npm path filters in de…

87f90f1

…pendency-review - update package.json path filter from root-only to **/package.json - update package-lock.json path filter from root-only to **/package-lock.json 🔧 - Generated by Copilot

fix(agents): correct relative link paths in issue-triage agent

df44b91

- fix ../../instructions/ to ../instructions/ for github-backlog-triage - fix ../../instructions/ to ../instructions/ for community-interaction 🔗 - Generated by Copilot

chore(instructions): remove some RAI docs and references

ac0bfe8

- update agents, instructions, collections, docs, and templates - regenerate plugin outputs 🗑️ - Generated by Copilot

fix(docs): align table formatting and collection artifact counts

a43114f

- reformat table column widths in handoff-pipeline and phase-reference - update artifact counts in collectionCards.ts to match YAML manifests 🔧 - Generated by Copilot

WilliamBerryiii force-pushed the chore/streamline-rai-planner-phases branch from 5fdabd1 to a43114f Compare April 2, 2026 02:53

fix(settings): restore mcp.json.sample deleted in error

6cf991b

🔧 - Generated by Copilot

WilliamBerryiii removed the needs-revision label Apr 2, 2026

ChrisRisner approved these changes Apr 2, 2026

View reviewed changes

raymond-nassar approved these changes Apr 2, 2026

View reviewed changes

fix(rai-planning): correct phase count and handoff schema consistency

3f41e5e

- update frontmatter description from 6-phase to 5-phase - align handoffGenerated in agent state.json to platform-specific schema 🔧 - Generated by Copilot

raymond-nassar approved these changes Apr 2, 2026

View reviewed changes

WilliamBerryiii merged commit fb7cd64 into main Apr 2, 2026
46 checks passed

This was referenced Apr 2, 2026

chore(main): pre-release 3.3.41 #1252

Merged

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

Open

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

chore(main): pre-release 3.3.101 #1274

Merged

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

chore(rai-planning): streamline RAI Planner phase structure and documentation#1273

chore(rai-planning): streamline RAI Planner phase structure and documentation#1273
WilliamBerryiii merged 7 commits intomainfrom
chore/streamline-rai-planner-phases

WilliamBerryiii commented Apr 2, 2026

Uh oh!

github-actions Bot commented Apr 2, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Apr 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment •

edited by WilliamBerryiii

Loading

Uh oh!

raymond-nassar commented Apr 2, 2026

Uh oh!

raymond-nassar left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

WilliamBerryiii commented Apr 2, 2026

Description

Changes by Area

Related Issue(s)

Type of Change

Sample Prompts (for AI Artifact Contributions)

Testing

Checklist

Required Checks

AI Artifact Contributions

Required Automated Checks

Security Considerations

GHCP Artifact Maturity

GHCP Maturity Acknowledgment

Additional Notes

Uh oh!

github-actions Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

OpenSSF Scorecard

Scanned Files

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

github-actions Bot left a comment • edited by WilliamBerryiii Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raymond-nassar commented Apr 2, 2026

Minor Issues Found During Local Review

1. Frontmatter description still says "6-phase"

2. handoffGenerated schema mismatch between agent and instructions

Uh oh!

raymond-nassar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Apr 2, 2026 •

edited

Loading

codecov-commenter commented Apr 2, 2026 •

edited

Loading

github-actions Bot left a comment •

edited by WilliamBerryiii

Loading

2. `handoffGenerated` schema mismatch between agent and instructions