docs(docs): add Project Planning agent documentation#936
Merged
WilliamBerryiii merged 11 commits intomainfrom Mar 12, 2026
Merged
docs(docs): add Project Planning agent documentation#936WilliamBerryiii merged 11 commits intomainfrom
WilliamBerryiii merged 11 commits intomainfrom
Conversation
- add hub page, category config, and four agent detail pages - cover ADR Creation, Architecture Diagram Builder, BRD/PRD Builders, and Security Plan Creator - include RPI-quality sample prompts with execution flows and output artifacts - update agents README with Project Planning section and navigation row 📝 - Generated by Copilot
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
agreaves-ms
approved these changes
Mar 10, 2026
katriendg
approved these changes
Mar 10, 2026
Contributor
katriendg
left a comment
There was a problem hiding this comment.
Just a few notes on the agent picker and the cross references to security. Nice examples in the docs to make it real for users.
…ntation (#965) Corrected documentation across 28 files to clearly differentiate three products with overlapping names: the **HVE Core Extension** (flagship AI artifact library, zero config), the **HVE Core Installer** (guided setup companion with MCP auto-config and agent bundle copying), and **clone-based methods** (full artifact customization via direct file access). Removed inaccurate claims about Installer capabilities, added a customization capability matrix, and updated site navigation to help users choose the right installation method. > Documentation conflated the Extension with the Installer and made inaccurate claims about what the Installer provides (e.g., "select specific collections," "install collections independently"). The Installer copies agents by bundle and auto-configures MCP servers; it does not filter prompts, instructions, or skills. The updated language establishes consistent three-tier messaging: Extension (recommended) → Installer (guided setup + MCP) → Clone (full customization). ### Terminology and Positioning Updated language across all installation guides and 9 role-specific pages to replace "all stable artifacts" and "Full collection" with "flagship RPI workflow and core artifacts." The `hve-core` extension now consistently describes the flagship collection, while `hve-core-all` is referenced wherever the complete artifact library is relevant. - Renamed **"Full Collection"** heading to **"Flagship Collection"** and **"Collection Filtering"** to **"Agent Bundle Selection"** in *install.md* - Updated TIP boxes in all 9 role guides (*business-program-manager*, *data-scientist*, *engineer*, *new-contributor*, *security-architect*, *sre-operations*, *tech-lead*, *tpm*, *ux-designer*) with flagship language - Updated *ai-artifacts.md* extension packaging table from "Full / All stable artifacts" to "Flagship / RPI workflow and core artifacts" - Removed the "What HVE Core Does for You" heading in *engineer.md* (content preserved, integrated under Recommended Collections) ### Installer Skill Cross-References Added consistent references to the HVE Core Installer skill across getting-started, customization, and lifecycle documentation, establishing the installer as the recommended path for guided setup. - Added installer callout to *README.md* linking to the HVE Core Installer extension for guided setup and agent bundle selection - Added TIP box to *docs/README.md* distinguishing flagship and complete extension options - Updated all 6 clone method Quick Start sections (*peer-clone*, *submodule*, *git-ignored*, *multi-root*, *mounted*, *codespaces*) with a consistent three-tier pattern: extension first, then installer skill, then manual steps - Added new **"Need MCP Configuration or Guided Setup?"** section to *extension.md* with a capabilities comparison table - Rewritten *extension.md* Scenario 4 ("Want to Customize Later") to show progressive layering instead of uninstall-and-clone - Added TIP box to *mcp-configuration.md* referencing installer skill for auto MCP configuration - Updated *cli-plugins.md* installer plugin description with broader scope and extension link - Added "Not sure which method fits?" entry to *install.md* decision criteria - Updated new contributor guide step 3 to acknowledge both extension-only and clone-based installer paths ### Customization Documentation Introduced a capability matrix and starting-point guidance to help users understand what each installation type enables. - Added **"Before You Customize"** capability matrix to *customization/README.md* showing 8 customization levels across Extension Only, Installer Skill (Clone), and Direct Clone - Added **"Recommended Starting Point"** section to *team-adoption.md* guiding teams from flagship extension to installer to direct clone - Added IMPORTANT callout to *collections.md* clarifying that agent bundle selection copies agents only (prompts, instructions, and skills are not filtered by collection) ### Site Navigation - Added **Customization** links to both Docusaurus navbar and footer in *docusaurus.config.js* - Created *customization/_category_.json* at position 5 for Docusaurus navigation hierarchy ### Bug Fix - Fixed broken extension ID `hve-hve-core-installer` → `hve-installer` in *lifecycle/setup.md* ## Related Issue(s) Closes #964 ## 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) * [x] Documentation update **Infrastructure & Configuration:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **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`) **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) <!-- Not applicable — no AI artifact changes in this PR --> ## Testing Automated validation commands run by the agent: * `npm run lint:md` — Passed (0 errors across 148 files) * `npm run spell-check` — Passed (0 issues across 239 files) * `npm run lint:frontmatter` — Passed (308 files validated, 0 errors) * `npm run validate:skills` — Passed (5 skills, 0 errors) * `npm run lint:md-links` — Passed (all links resolved) * `npm run lint:ps` — Passed (all PowerShell files clean) * `npm run plugin:generate` — Passed (11 plugins generated, no formatting changes) * `npm run lint:links` — Passed (no URLs with language paths) Security analysis: no sensitive data, credentials, dependency changes, or privilege modifications detected. All changes are documentation-only. Diff-based assessment: verified all 28 changed files exist, confirmed broken extension ID fix (`hve-hve-core-installer` → `hve-installer`), confirmed consistent terminology across role guides and clone method pages. Manual testing was not performed. ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) (N/A — documentation-only changes) * [ ] Tests added for new functionality (if applicable) (N/A — no testable functionality added) ### AI Artifact Contributions <!-- Not applicable — no AI artifact changes in this PR --> * [ ] 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: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [x] Link validation: `npm run lint:md-links` * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations <!--⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> * [x] 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 scripts modified) ## Additional Notes - All changes are documentation-only (markdown files and one Docusaurus JS config file). No code, workflow, or AI artifact changes. - Agent bundle selection remains scoped to agents only; collection-based filtering of prompts, instructions, and skills is noted as future work in multiple locations.
- Replace silent `find -execdir uv sync` in the Install uv package manager step with an error propagating while loop. - Adds -type f flag for parity with on-create.sh, uses -print0/read -d '' for safe path handling, emits ::error:: annotations per failing directory, processes all skills before aborting, and exits non-zero if any sync fails. ## Related Issue(s) Closes #946 ## Type of Change Select all that apply: **Code & Documentation:** * [x] 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:** * [x] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Testing Ran workflow in forked repository in `main` -- producing the following output for the relevant step: ``` Syncing Python environments for skills... Installing dependencies in .github/skills/experimental/powerpoint Using CPython 3.11.14 interpreter at: /opt/hostedtoolcache/Python/3.11.14/x64/bin/python3 Creating virtual environment at: .venv Resolved 33 packages in 0.61ms Downloading pygments (1.2MiB) Downloading pymupdf (23.8MiB) Downloading lxml (5.0MiB) Downloading pillow (6.7MiB) Downloading ruff (10.7MiB) Downloading github-copilot-sdk (56.5MiB) Downloading pydantic-core (2.0MiB) Downloaded pydantic-core Downloaded ruff Downloaded pillow Downloaded lxml Downloaded pygments Downloaded pymupdf Downloaded github-copilot-sdk Prepared 30 packages in 1.73s Installed 30 packages in 24ms + annotated-types==0.7.0 + cairocffi==1.7.1 + cairosvg==2.8.2 + cffi==2.0.0 + coverage==7.13.4 + cssselect2==0.9.0 + defusedxml==0.7.1 + github-copilot-sdk==0.1.30 + iniconfig==2.3.0 + lxml==6.0.2 + packaging==26.0 + pillow==12.1.1 + pluggy==1.6.0 + pycparser==3.0 + pydantic==2.12.5 + pydantic-core==2.41.5 + pygments==2.19.2 + pymupdf==1.27.1 + pytest==9.0.2 + pytest-cov==7.0.0 + python-dateutil==2.9.0.post0 + python-pptx==1.0.2 + pyyaml==6.0.3 + ruff==0.15.4 + six==1.17.0 + tinycss2==1.5.1 + typing-extensions==4.15.0 + typing-inspection==0.4.2 + webencodings==0.5.1 + xlsxwriter==3.2.9 ``` ## Checklist ### Required Checks * [ ] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [ ] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [x] Link validation: `npm run lint:md-links` * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` * [ ] YAML linting: `npm run lint:yaml` ## Security Considerations <!--⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> * [x] This PR does not contain any sensitive or NDA information * [ ] Any new dependencies have been reviewed for security issues * [ ] Security-related scripts follow the principle of least privilege ## Additional Notes The same `-type f` parity and error-propagation improvements could be applied here in a follow-on task.
- Bold suggestion titles in numbered list for visual prominence - Add blockquote mapping each button (1️⃣ 2️⃣ 3️⃣) to its suggestion title ## Related Issue(s) Closes #495 ## Type of Change Select all that apply: **Code & Documentation:** * [x] 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:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **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](../docs/contributing/skills.md). > * 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](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) <!-- If you checked any boxes under "AI Artifacts" above, provide a sample prompt showing how to use your contribution --> <!-- Delete this section if not applicable --> **User Request:** <!-- What natural language request would trigger this agent/prompt/instruction? --> **Execution Flow:** <!-- Step-by-step: what happens when invoked? Include tool usage, decision points --> **Output Artifacts:** <!-- What files/content are created? Show first 10-20 lines as preview --> **Success Indicators:** <!-- How does user know it worked correctly? What validation should they perform? --> For detailed contribution requirements, see: * Common Standards: [docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing * Agents: [docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md) - Agent configurations with tools and behavior patterns * Prompts: [docs/contributing/prompts.md](../docs/contributing/prompts.md) - Workflow-specific guidance with template variables * Instructions: [docs/contributing/instructions.md](../docs/contributing/instructions.md) - Technology-specific standards with glob patterns * Skills: [docs/contributing/skills.md](../docs/contributing/skills.md) - Task execution utilities with cross-platform scripts ## Testing <!-- Describe how you tested these changes --> ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [ ] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions <!-- If contributing an agent, prompt, instruction, or skill, complete these checks --> * [ ] 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` ## Security Considerations <!--⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> * [ ] This PR does not contain any sensitive or NDA information * [ ] Any new dependencies have been reviewed for security issues * [ ] Security-related scripts follow the principle of least privilege ## Additional Notes <!-- Any additional information that reviewers should know --> --------- Co-authored-by: Katrien De Graeve <katriendg@users.noreply.github.com>
Added declarative GitHub label management to the repository. *`.github/labels.yml`* defines all 62 live repository labels as code — 60 canonical entries organized into five comment-annotated groups (Type, Area, Priority, Status/Process, and Release Management), with aliases on the `instructions` and `prompts` labels consolidating the legacy `instruction-file` and `prompt` labels respectively. *`.github/workflows/label-sync.yml`* syncs labels additively using **EndBug/label-sync v2.3.3**, triggered on push to `main` when either file changes and on `workflow_dispatch`. > Labels are synced in additive mode (`delete-other-labels: false`), which means no existing label is deleted until the file is the authoritative source. The alias entries migrate existing issue and PR assignments from the legacy labels to their canonical counterparts on first sync run. Both action references are SHA-pinned to full 40-character commit SHAs per repository convention. ## Related Issue(s) Closes #518 ## Type of Change Select all that apply: **Code & Documentation:** * [ ] Bug fix (non-breaking change fixing an issue) * [x] New feature (non-breaking change adding functionality) * [ ] Breaking change (fix or feature causing existing functionality to change) * [ ] Documentation update **Infrastructure & Configuration:** * [x] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Testing Ran the workflow on the forked repository after merging to main ### Workflow output: ``` Run EndBug/label-sync@5207415 Checking inputs... 🛈 Current config mode: local ✓ Inputs are valid .github/labels.yml Reading config file... 🛈 Reading file... 🛈 Parsing YAML file... ✓ File parsed successfully. 🛈 Parsed config: [ { "name": "bug", "color": "d73a4a", "description": "Something isn't working" }, { "name": "breaking-change", "color": "B60205", "description": "Breaking change requiring major version bump" }, ... (Remaining labels) ] Syncing labels... ✓ Sync successful Label diff feature [missing] ☀️ → feature ☀️ → #1D76DB ☀️ → New feature triggering minor version bump maintenance [missing] ☀️ → maintenance ☀️ → #FBCA04 ☀️ → Maintenance work, no version bump refactor [missing] ☀️ → refactor ☀️ → #ededed ☀️ → Code refactoring without functional changes performance [missing] ☀️ → performance ☀️ → #0E8A16 ☀️ → Performance improvement security [missing] ☀️ → security ☀️ → #D93F0B ☀️ → Security improvement or fix ``` ## Checklist ### Required Checks * [ ] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions <!-- If contributing an agent, prompt, instruction, or skill, complete these checks --> * [ ] 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: * [x] Markdown linting: `npm run lint:md` * [ ] Spell checking: `npm run spell-check` (N/A — no prose markdown files changed) * [ ] Frontmatter validation: `npm run lint:frontmatter` (N/A — no instruction, prompt, or agent files changed) * [ ] Skill structure validation: `npm run validate:skills` (N/A — no skill files changed) * [ ] Link validation: `npm run lint:md-links` (N/A — no markdown files changed) * [ ] PowerShell analysis: `npm run lint:ps` (N/A — no PowerShell files changed) * [ ] Plugin freshness: `npm run plugin:generate` (N/A — no collection files changed) ## Security Considerations <!--⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege ## Additional Notes The workflow uses `GITHUB_TOKEN` — no new secrets are required. The token is already available in all Actions runs. Two additional workflow-level validations were confirmed: * **SHA pinning**: Both `actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2` and `EndBug/label-sync@52074158190acb45f3077f9099fea818aa43f97a # v2.3.3` are pinned to full 40-character commit SHAs with version comments. * **Permissions**: `contents: read` declared at workflow level; `issues: write` granted only at job level, following the principle of least privilege.
# feat(workflows): add ms.date documentation freshness checking ## Description This PR ports the automated `ms.date` documentation freshness checking system from [`Azure-Samples/azure-nvidia-robotics-reference-architecture`](https://github.com/Azure-Samples/azure-nvidia-robotics-reference-architecture) PR #448 into hve-core. The system tracks the `ms.date` frontmatter field across all markdown files, surfaces stale content through CI annotations during pull requests, and automates GitHub issue creation for stale files on a weekly schedule. ### PowerShell Script and Tests The core of the feature is *Invoke-MsDateFreshnessCheck.ps1*, a PowerShell 7 script that discovers markdown files, parses `ms.date` from YAML frontmatter, computes staleness against a configurable day threshold, and generates both a JSON report (`logs/msdate-freshness-results.json`) and a markdown summary (`logs/msdate-summary.md`). Stale files emit CI annotations via the existing `Write-CIAnnotation` helper. - Added `scripts/linting/Invoke-MsDateFreshnessCheck.ps1` — file discovery with configurable exclusions (`node_modules`, `.git`, `logs`, `.copilot-tracking`, `CHANGELOG.md`), YAML frontmatter parsing via `powershell-yaml`, and `changed-files-only` mode backed by `git diff` - Fixed a bug present in the source repo: `$isExplicitFilePath` now uses `Test-Path -PathType Leaf` rather than `$path -ne '.'`, ensuring absolute directory paths correctly receive exclusion filtering - Added `scripts/tests/linting/Invoke-MsDateFreshnessCheck.Tests.ps1` — Pester 5 test suite (~530 lines) with `Unit` and `Integration` tags, covering file discovery (6 contexts), frontmatter parsing (5 contexts including YAML errors and file-not-found), report generation (4 contexts), and an integration loop exercising `Write-CIAnnotation` via a verifiable mock - Added `msdate` to `.cspell/general-technical.txt` ### GitHub Actions Workflows Three new reusable workflows implement the dual-context checking pattern: - Added `.github/workflows/msdate-freshness-check.yml` — reusable `workflow_call` with `staleness-threshold-days` (default: 90) and `changed-files-only` inputs; uploads `msdate-freshness-results.json` as a workflow artifact and writes the markdown summary to the Actions job summary - Added `.github/workflows/weekly-validation.yml` — scheduled orchestrator running Monday at 09:00 UTC; calls `msdate-freshness-check.yml` for a full-repository scan, then calls `create-stale-docs-issues.yml` - Added `.github/workflows/create-stale-docs-issues.yml` — idempotent issue automation; uses a hidden `<!-- automation:stale-docs:{file-path} -->` marker to locate existing open issues before creating new ones, avoiding duplicates across weekly runs Modified `.github/workflows/pr-validation.yml` to add the `msdate-freshness` job between `frontmatter-validation` and `plugin-validation`, running with `changed-files-only: true` against files changed in the PR. ### Documentation Added `docs/contributing/documentation-maintenance.md` explaining the dual-context freshness pattern, how to fix stale documentation, how to configure thresholds, how the issue automation deduplicates, and common troubleshooting steps. Stale `soft-fail` references were also removed from the guide during review — the implementation is a hard-fail; there is no `soft-fail` mode. ## Related Issue(s) Closes #968 ## Type of Change Select all that apply: **Code & Documentation:** * [ ] Bug fix (non-breaking change fixing an issue) * [x] New feature (non-breaking change adding functionality) * [ ] Breaking change (fix or feature causing existing functionality to change) * [x] Documentation update **Infrastructure & Configuration:** * [x] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **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](../docs/contributing/skills.md). > * 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](../docs/contributing/custom-agents.md#agents-not-accepted) and [Model Version Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements). **Other:** * [x] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) <!-- If you checked any boxes under "AI Artifacts" above, provide a sample prompt showing how to use your contribution --> <!-- Delete this section if not applicable --> ## Testing Validated using the Pester 5 test suite added as part of this PR: - `npm run test:ps` — 1691 tests passed (0 failures); includes all existing tests plus the new `Invoke-MsDateFreshnessCheck.Tests.ps1` suite covering `Get-MarkdownFiles`, `Get-MsDateFromFrontmatter`, `New-MsDateReport`, and integration contexts - `npm run lint:ps` — PSScriptAnalyzer reported no issues against `Invoke-MsDateFreshnessCheck.ps1` - `npm run lint:frontmatter` — 0 errors, 0 warnings across all markdown files including the new `documentation-maintenance.md` - `npm run validate:skills` — 5 skills validated, 0 errors - `npm run plugin:generate` — 11 plugins generated successfully Manual verification: Reviewed all workflow files for SHA-pinned actions, least-privilege permissions, and consistent `shell: pwsh` per-step (no workflow-level `defaults`). ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) * [x] Tests added for new functionality (if applicable) ### AI Artifact Contributions <!-- If contributing an agent, prompt, instruction, or skill, complete these checks --> * [ ] Used `/prompt-analyze` to review contribution (N/A — no AI artifact changes) * [ ] Addressed all feedback from `prompt-builder` review (N/A — no AI artifact changes) * [ ] Verified contribution follows common standards and type-specific requirements (N/A — no AI artifact changes) ### Required Automated Checks The following validation commands must pass before merging: * [ ] Markdown linting: `npm run lint:md` (not available in local environment; runs in CI) * [ ] Spell checking: `npm run spell-check` (not available in local environment; runs in CI) * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [ ] Link validation: `npm run lint:md-links` (not available in local environment; runs in CI) * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations <!--⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data --> * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [ ] Security-related scripts follow the principle of least privilege (N/A — no security scripts modified) ## Additional Notes - GitHub labels `stale-docs` and `automated` must be created in the repository before `create-stale-docs-issues.yml` runs in production. No automated pre-flight check exists — this is an operational prerequisite. - `create-stale-docs-issues.yml` rewrites the full issue body on each weekly run. Human edits to the issue body will be discarded; comments are preserved. - `PowerShell-Yaml` is installed on each run without a version pin or module cache. Pinning the version is a follow-up improvement. - The artifact name `msdate-freshness-results` is hardcoded in the producer workflow and referenced by name in the consumer. This loose coupling is intentional but worth noting for future maintainers.
…980) Rename the `security-planning` collection to `security` to broaden scope from planning-only to the full security domain (review, planning, incident response, risk assessment, vulnerability analysis). **Changes:** - Rename collection ID from `security-planning` to `security` - Broaden scope from planning-only to full security domain - Set collection maturity to `experimental` - Move `.github/agents/security-planning/` to `.github/agents/security/` - Move `.github/prompts/security-planning/` to `.github/prompts/security/` - Update `hve-core-all.collection.yml`, `.vscode/settings.json`, installer skill, prompts README, and 14 documentation files - Regenerate `plugins/security/` via `plugin:generate` **BREAKING CHANGE:** collection ID changed from `security-planning` to `security` ## Related Issue(s) Closes #792 ## Type of Change Select all that apply: **Code & Documentation:** * [ ] Bug fix (non-breaking change fixing an issue) * [ ] New feature (non-breaking change adding functionality) * [x] Breaking change (fix or feature causing existing functionality to change) * [x] Documentation update **Infrastructure & Configuration:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **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`) **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [ ] Other (please describe): ## Testing - `npm run plugin:generate` — produces `plugins/security/` with 4 items - `npm run plugin:validate` — 11 collections validated, 0 errors - `npm run lint:all` — passes (only pre-existing `VersionMismatch` in `codeql-analysis.yml`, confirmed on baseline `main`) - `grep -rl "security-planning"` across source directories — zero matches ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [ ] Changes are backwards compatible (if applicable) — **intentional breaking change per #792** * [ ] Tests added for new functionality (if applicable) — rename only, no new functionality ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [x] Skill structure validation: `npm run validate:skills` * [ ] Link validation: `npm run lint:md-links` * [x] PowerShell analysis: `npm run lint:ps` * [x] Plugin freshness: `npm run plugin:generate` ## Security Considerations * [x] This PR does not contain any sensitive or NDA information * [x] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege ## Additional Notes - `extension/package.security-planning.json` and `extension/README.security-planning.md` referenced in the issue do not exist in the repo — those acceptance criteria are N/A. - This is a pre-condition for #793, #794, #795, #796, #797, #798, #799 (MVP security reviewer work). - The `lint:version-consistency` failure in `lint:all` is a pre-existing issue on `main` (confirmed by running against baseline) and is unrelated to this change. 🤖 Generated by Copilot
- replace @agent-name references with agent picker prose in all docs - add agent picker TIP callout to How to Use sections - fix security-plan-creator collection path from security-planning to security - update README prerequisites, getting started table, and sequencing 📝 - Generated by Copilot
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #936 +/- ##
=======================================
Coverage 86.01% 86.01%
=======================================
Files 28 28
Lines 5270 5270
=======================================
Hits 4533 4533
Misses 737 737
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
This was referenced Mar 12, 2026
This was referenced Mar 15, 2026
WilliamBerryiii
added a commit
that referenced
this pull request
Mar 20, 2026
🤖 I have created a release *beep* *boop* --- ## [3.2.0](hve-core-v3.1.46...hve-core-v3.2.0) (2026-03-20) ### ✨ Features * add -OutputPath parameter to Validate-MarkdownFrontmatter.ps1 ([#1134](#1134)) ([fdf1bcf](fdf1bcf)), closes [#1006](#1006) * add action version consistency scan workflow ([#1127](#1127)) ([4229df1](4229df1)) * **agent:** MVE Experiment Designer ([#976](#976)) ([70f86ca](70f86ca)) * **agents:** add ADO Backlog Manager orchestrator agent ([#800](#800)) ([fae3987](fae3987)) * **agents:** add meeting analyst agent for transcript analysis using work-iq ([#502](#502)) ([5345b5b](5345b5b)) * **agents:** add quick-reference line to RPI Phase 5 suggestions ([#897](#897)) ([9a90f39](9a90f39)) * **agents:** add RAI Planner, enhance SSSC Planner, and redesign Security Planner ([#979](#979)) ([06f826c](06f826c)) * **agents:** add symmetric cross-system handoff to GitHub Backlog Manager ([#952](#952)) ([ba34a35](ba34a35)) * **agents:** Functional Code Review Agent — pre-PR functional correctness reviewer ([#733](#733)) ([9cf63b7](9cf63b7)) * **build:** add Python extensions and uv 0.10.8 to devcontainer ([#920](#920)) ([9ca0579](9ca0579)) * **build:** add uv ecosystem to Dependabot configuration ([#913](#913)) ([2a4bd39](2a4bd39)) * **build:** enable npm pinning enforcement in dependency scan ([#838](#838)) ([4e9e31f](4e9e31f)) * **build:** migrate attestation actions to v4.1.0 and add SBOM verification docs ([#841](#841)) ([ca1e65b](ca1e65b)) * **collections:** add four new validator checks (orphan, duplicate, companion, coverage) ([#869](#869)) ([1a96b73](1a96b73)) * **devcontainer,security:** add enterprise artifact hub configuration ([#1032](#1032)) ([1d56d25](1d56d25)) * **docs:** add Rust coding standards and guidelines ([#809](#809)) ([d4c4899](d4c4899)) * **extension:** add Microsoft logo icon to VS Code Marketplace listings ([#906](#906)) ([82aca41](82aca41)) * **github:** add declarative label management ([#953](#953)) ([a1a6845](a1a6845)) * **instructions:** add ADO backlog shared infrastructure ([#786](#786)) ([1914078](1914078)) * **instructions:** add ADO backlog sprint planning and capacity tracking ([#788](#788)) ([d6fb77d](d6fb77d)) * **instructions:** add ADO triage workflow and prompt ([#787](#787)) ([cde0190](cde0190)) * **instructions:** add shared story quality conventions and sprint planning ([#803](#803)) ([a2f18e3](a2f18e3)) * **prompts:** add ADO discovery and work item prompts with agent routing ([#790](#790)) ([7e74523](7e74523)) * **prompts:** add security review prompts ([#1118](#1118)) ([ad30967](ad30967)) * **scripts:** add dynamic Python skill discovery for lint/test ([#957](#957)) ([0a90f57](0a90f57)) * **scripts:** add Get-StandardTimestamp utility to CIHelpers module ([#1126](#1126)) ([b273a4b](b273a4b)) * **scripts:** add Python copyright header validation ([#905](#905)) ([67df902](67df902)) * **scripts:** add Python skill support to Validate-SkillStructure ([#903](#903)) ([68479d9](68479d9)) * **scripts:** add workflow npm command scanning to dependency pinning ([#837](#837)) ([6b5ae06](6b5ae06)) * **security:** add basic security reviewer agent with owasp skills ([#1008](#1008)) ([cb1fd05](cb1fd05)) * **security:** add sigstore attestation bundles and fix component-detection action ([#1148](#1148)) ([f79c272](f79c272)) * **skills:** add Atheris fuzz harness with CI workflow integration ([#1102](#1102)) ([d337e1d](d337e1d)) * **skills:** add PowerPoint automation skill with YAML-driven deck generation ([#868](#868)) ([00465cd](00465cd)) * **skills:** convert hve-core-installer agent to self-contained skill ([#846](#846)) ([1d821fb](1d821fb)) * **skills:** enhance pr-reference skill with flexible filtering and base branch detection ([#1095](#1095)) ([26a32ea](26a32ea)) * **workflows:** add devcontainer infrastructure change log workflow ([#899](#899)) ([8aca446](8aca446)) * **workflows:** add milestone auto-close on stable and pre-release publishes ([#834](#834)) ([79362b1](79362b1)) * **workflows:** add ms.date documentation freshness checking ([#969](#969)) ([3ed441c](3ed441c)) * **workflows:** add Python linting CI workflow with Ruff ([#951](#951)) ([f89f0eb](f89f0eb)) * **workflows:** add Python testing CI workflow with pytest and Codecov ([#934](#934)) ([5e8306f](5e8306f)) * **workflows:** add uv and Python package sync to copilot-setup-steps ([#921](#921)) ([45d517d](45d517d)) ### 🐛 Bug Fixes * **build:** override Linguist vendored flag for Python skill files ([#1155](#1155)) ([0eee5b6](0eee5b6)) * **build:** override serialize-javascript to >=7.0.3 for RCE fix ([#876](#876)) ([e49039a](e49039a)) * **build:** resolve Pinned-Dependencies alerts for vsce npm commands in extension workflows ([#782](#782)) ([89dad9d](89dad9d)) * **build:** update undici and yauzl overrides for security audit ([#1030](#1030)) ([2c2f92f](2c2f92f)) * **docs:** add CLI Plugins to install.md navigation surfaces ([#902](#902)) ([79d6595](79d6595)) * **docs:** add sidebar ordering for Design Thinking documentation ([#832](#832)) ([551fddc](551fddc)), closes [#830](#830) * **docs:** graduate design-thinking to preview and correct stale collection references ([#831](#831)) ([5110e35](5110e35)) * **docs:** include project-planning in UX Designer install guidance ([#908](#908)) ([e7aa9bc](e7aa9bc)) * **docs:** remediate writing-style convention violations ([#865](#865)) ([68b04bc](68b04bc)) * **docs:** remove draft content announcement banner ([#825](#825)) ([b45de80](b45de80)) * **docs:** remove unbounded path-to-regexp override breaking SSG ([#1153](#1153)) ([d810018](d810018)) * **docs:** use actual clone paths instead of folder display names in multi-root workspace settings ([#984](#984)) ([5dbab82](5dbab82)) * **instructions:** replace black with ruff in uv-projects ([#898](#898)) ([b0c06d9](b0c06d9)) * **scripts:** cover .github/ skill files in copyright header validation ([#1055](#1055)) ([#1098](#1098)) ([27fbd33](27fbd33)) * **scripts:** eliminate phantom git changes from plugin generation ([#1035](#1035)) ([e49a1b5](e49a1b5)) * **scripts:** enable JSON log output for lint:version-consistency ([#1033](#1033)) ([52b0885](52b0885)) * **security:** calculate compliance score from total scanned dependencies ([#930](#930)) ([c112c3d](c112c3d)) * **skills:** add AST validation and namespace restriction for content-extra.py ([#1027](#1027)) ([c50c7a3](c50c7a3)) * **skills:** add depth limits to recursive PowerPoint processing functions ([#1028](#1028)) ([bf08994](bf08994)) * **skills:** harden XML parsing and blob writes in powerpoint extract ([#1053](#1053)) ([89d24b1](89d24b1)) * **skills:** resolve ruff lint and format violations in powerpoint skill ([#1048](#1048)) ([17bbe7a](17bbe7a)) * **workflows:** add uv.lock dependencies submission have fork-skip condition ([#1109](#1109)) ([dec56ac](dec56ac)) * **workflows:** automate weekly SHA staleness check with issue creation ([#975](#975)) ([1ea4caa](1ea4caa)) * **workflows:** close Codecov integration gaps for Pester and pytest flags ([#1106](#1106)) ([cca29b7](cca29b7)) * **workflows:** propagate uv sync errors in copilot-setup-steps ([#961](#961)) ([df88d7c](df88d7c)) * **workflows:** resolve release-please skip cascade and Python project discovery ([#1043](#1043)) ([79993e2](79993e2)) * **workflows:** scan only commit subjects for breaking change detection ([#1157](#1157)) ([a38a657](a38a657)) ### 📚 Documentation * clarify HVE Core Extension vs Installer messaging across documentation ([#965](#965)) ([0fceb8f](0fceb8f)) * **docs:** add ADO integration user documentation ([#935](#935)) ([ec89302](ec89302)) * **docs:** add Project Planning agent documentation ([#936](#936)) ([3a3a0fd](3a3a0fd)) * **onboarding:** overhaul marketplace onboarding and documentation site ([#982](#982)) ([4309e10](4309e10)) ### ♻️ Refactoring * **build:** merge code-review collection into coding-standards ([#863](#863)) ([8027e7b](8027e7b)) * **workflows:** rename release pipeline workflows and add marketplace automation triggers ([#829](#829)) ([b6397f4](b6397f4)) ### 🔧 Maintenance * **build:** add clean:logs npm script ([#1122](#1122)) ([f85fe02](f85fe02)), closes [#988](#988) * **build:** add JSON reporter for cspell ([#1123](#1123)) ([6d59f67](6d59f67)) * **ci:** add multi-arch support to copilot-setup-steps binary downloads ([#955](#955)) ([8d0c706](8d0c706)) * **deps-dev:** bump cspell from 9.6.4 to 9.7.0 in the npm-dependencies group ([#839](#839)) ([3fa16ff](3fa16ff)) * **deps:** bump actions/dependency-review-action from 4.8.3 to 4.9.0 in the github-actions group across 1 directory ([#942](#942)) ([1a9b858](1a9b858)) * **deps:** bump cairosvg from 2.8.2 to 2.9.0 in /.github/skills/experimental/powerpoint ([#1025](#1025)) ([f4deda7](f4deda7)) * **deps:** bump dompurify from 3.3.1 to 3.3.2 in /docs/docusaurus ([#924](#924)) ([d2060d6](d2060d6)) * **deps:** bump svgo from 3.3.2 to 3.3.3 in /docs/docusaurus ([#880](#880)) ([6dc2406](6dc2406)) * **deps:** bump the github-actions group across 1 directory with 4 updates ([#1100](#1100)) ([2290dc0](2290dc0)) * **deps:** bump the github-actions group with 6 updates ([#840](#840)) ([f57bc01](f57bc01)) * **docs:** correct New-MsDateReport table rendering and refresh stale docs ([#1114](#1114)) ([c2b806f](c2b806f)) * **settings:** remove orphaned Checkov config and stale gitignore entries ([#870](#870)) ([98fcd74](98fcd74)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com> Co-authored-by: Bill Berry <wberry@microsoft.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.
Description
Added a new Project Planning documentation section to the Docusaurus agents site, covering five agent pages across hub infrastructure and individual agent guides. The section follows the established pattern from the ado-backlog and github-backlog agent documentation areas.
Hub Infrastructure
Created the docs/agents/project-planning/ directory with a
_category_.jsonsidebar configuration (label "Project Planning", position 3) and a hub README.md that links to all four agent detail pages. Sidebar positions are sequential across the section: README(1), BRD/PRD(2), ADR(3), Architecture Diagram(4), Security Plan(5).Agent Detail Pages
Added four agent documentation pages, each including capabilities, sample prompts with execution flows, and output artifact descriptions:
.github/agents/security-planning/Parent README Update
Updated docs/agents/README.md to rename the "Document Builders" label to "Project Planning", adjusted the agent count from 4 to 5, and added a navigation row linking to the new section.
Related Issue(s)
Closes #508
Type of Change
Select all that apply:
Code & Documentation:
Infrastructure & Configuration:
AI Artifacts:
prompt-builderagent and addressed all feedback.github/instructions/*.instructions.md).github/prompts/*.prompt.md).github/agents/*.agent.md).github/skills/*/SKILL.md)Other:
.ps1,.sh,.py)Sample Prompts (for AI Artifact Contributions)
User Request:
Execution Flow:
Output Artifacts:
Success Indicators:
For detailed contribution requirements, see:
Testing
All required automated checks pass:
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run validate:skillsnpm run lint:md-linksnpm run lint:psnpm run plugin:generateCSpell dictionary additions: "MSAL" added to
.cspell/azure-services.txt, "workstreams" added to.cspell/general-technical.txt.Checklist
Required Checks
AI Artifact Contributions
/prompt-analyzeto review contributionprompt-builderreviewRequired Automated Checks
The following validation commands must pass before merging:
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run validate:skillsnpm run lint:md-linksnpm run lint:psnpm run plugin:generateSecurity Considerations
Additional Notes
Follow-up: Frontmatter consistency — All 5 new files under docs/agents/project-planning/ are missing optional
keywordsandestimated_reading_timefrontmatter fields that all 16 existing agent docs include. CI passes because onlytitleanddescriptionare required, but adding these fields would align with the established pattern. Suitable as a separate follow-up task.