feat(extension): implement collection-based plugin distribution system

[katriendg]

Description

Replaces the originally planned persona-based distribution model with a simpler, domain-focused collection architecture. The initial approach used a centralized JSON registry (ai-artifacts-registry.json) with role-based persona tags (developer, tpm, devops, architect, technical-writer) to filter artifacts at build and install time. During implementation, this was rearchitected to a collection-based system where YAML manifests directly define artifact groupings by domain, eliminating the need for a central registry and its associated indirection.

Ten domain-focused collections now replace the five role-based personas, offering more composable and intuitive groupings. Each collection is a self-contained YAML manifest listing its items by path and kind, with optional per-item maturity tracking. A fully automated plugin generation pipeline produces Copilot CLI-compatible plugin directories from these manifests, and the extension packaging scripts were updated for collection-aware builds with maturity gating.

• Created 10 collection manifests in collections/*.collection.yml with companion .collection.md description files covering Azure DevOps, Coding Standards, Data Science, Git, GitHub, HVE Core All, Project Planning, Prompt Engineering, RPI, and Security Planning domains
• Added scripts/plugins/Generate-Plugins.ps1 for automated plugin generation from collection manifests using symlinks, plugin.json manifests, and auto-generated READMEs
• Added scripts/plugins/Modules/PluginHelpers.psm1 with shared pure functions for manifest parsing, frontmatter extraction, and shared resource directory resolution
• Added scripts/plugins/Validate-Collections.ps1 for CI validation of all collection manifests including structure, required fields, artifact path existence, kind-suffix consistency, and duplicate ID detection
• Created scripts/linting/schemas/collection-manifest.schema.json defining the collection format with required fields (id, name, description, items) and optional fields (tags, display, maturity per item)
• Created .github/plugin/marketplace.json as a centralized registry of all generated plugins with name, version, source path, and description
• Removed maturity frontmatter field from all 61+ artifact files (agents, prompts, instructions, skills) to resolve Copilot CLI incompatibility (fix(agents): maturity, etc. are not supported frontmatter for agents in copilot CLI #360), with maturity now tracked as optional per-item field in collection manifests
• Updated frontmatter schemas (agent-frontmatter.schema.json, prompt-frontmatter.schema.json, instruction-frontmatter.schema.json, chatmode-frontmatter.schema.json) to remove the maturity property
• Expanded scripts/extension/Prepare-Extension.ps1 with collection filtering, BFS handoff dependency resolution (Resolve-HandoffDependencies), registry-based maturity migration, Get-DiscoveredSkills and chatSkills support, and -Collection parameter for filtered builds
• Expanded scripts/extension/Package-Extension.ps1 with -Collection parameter, Copy-CollectionArtifacts function, collection-specific README swapping via Set-CollectionReadme, and template-based package.json generation from extension/templates/
• Replaced static extension/package.json and extension/README.md with build-time generated versions from extension/templates/package.template.json and extension/templates/README.template.md
• Added collection-level maturity gating so experimental collections build only for PreRelease channel and deprecated collections are excluded entirely
• Created scripts/tests/plugins/Generate-Plugins.Tests.ps1 (21 tests), scripts/tests/plugins/PluginHelpers.Tests.ps1 (167 lines), and scripts/tests/plugins/Validate-Collections.Tests.ps1 (199 lines) for plugin infrastructure coverage
• Added 30+ tests to scripts/tests/extension/Prepare-Extension.Tests.ps1 and expanded scripts/tests/extension/Package-Extension.Tests.ps1 for collection-aware packaging coverage
• Removed legacy registry infrastructure: Validate-ArtifactRegistry.ps1, ai-artifacts-registry.schema.json, registry test fixtures, and artifact-registry-validation.yml workflow
• Added plugin-package.yml workflow for plugin packaging and updated main.yml, extension-package.yml, extension-publish-prerelease.yml, and extension-publish.yml for collection matrix strategy
• Updated hve-core-installer.agent.md to use collection-based selection instead of persona-based filtering, with references to collection manifests rather than a central registry
• Marked github-issue-manager.agent.md as deprecated
• Updated architecture documentation (docs/architecture/ai-artifacts.md, docs/architecture/workflows.md), contributing guides (ai-artifacts-common.md, custom-agents.md, instructions.md, prompts.md, skills.md), release process, and extension/PACKAGING.md to reflect the collection model
• Updated docs/getting-started/install.md with collection-based installation guidance
• Integrated npm run plugin:validate and npm run lint:collections-metadata into the CI pipeline, replacing npm run lint:registry

Related Issue(s)

Closes #519

Related to #431 (Epic: Persona-Based Extension Distribution, now superseded by collection approach)
Related to #360 (Custom maturity frontmatter breaks Copilot CLI)
Related to #251 (Update extension packaging to distribute skills)

Superseded Issues

This implementation supersedes the following issues from the persona distribution epic:

Issue	Title	Disposition
#432	AI Artifacts Registry Design and Schema	Superseded — registry removed, replaced by collection manifests
#438	Migrate Maturity Metadata to Registry	Completed — goal achieved via collections
#433	Multi-Package Extension Build System	Superseded — replaced by plugin generation
#434	Installer Agent Persona Selection	Superseded — refactored to collection-based
#437	Persona-to-Artifact Mapping	Superseded — collections define items directly
#467	Collection Maturity Gating	Completed — carried forward
#468	PR Registry Drift Validation	Superseded — replaced by collection validation

Remaining Work

Work Item	Original Issue	Description
Per-collection Marketplace content	#435	Descriptions for all 10 collections suitable for Marketplace
End-to-end publishing validation	#436	Marketplace publishing test for collection-based plugins
Release process documentation	#436	Document collection-based release workflow

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:

• 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.
• 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)

N/A — GHCP artifact changes in this PR are limited to maturity field removal and collection terminology updates, not new artifacts.

Testing

• Executed npm run plugin:validate to validate all 10 collection manifests for structure, required fields, artifact path existence, kind-suffix consistency, and duplicate ID detection
• Executed npm run plugin:generate to verify plugin generation produces correct symlink-based plugins under plugins/
• Validated hve-core-all auto-discovery includes all non-deprecated artifacts
• Verified collection-level maturity gating: experimental collections build only for PreRelease, deprecated are excluded
• Created Generate-Plugins.Tests.ps1 with 21 Pester tests covering channel filtering and plugin orchestration
• Extended Prepare-Extension.Tests.ps1 with 30+ tests for collection filtering, BFS handoff resolution, maturity-based filtering, and error paths
• Extended Package-Extension.Tests.ps1 with tests for template-copy, backup/restore, collection artifact copying, and README swapping
• Created Validate-Collections.Tests.ps1 with 199 lines of tests covering validation scenarios
• Created PluginHelpers.Tests.ps1 with 167 lines of tests for manifest parsing and frontmatter extraction
• Verified maturity removal from all artifact frontmatter files does not affect artifact discovery
• Confirmed npm run lint:all passes (includes lint:collections-metadata)

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
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

Security Considerations

• 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

Architectural Evolution

Development began with Phase 1 of the persona distribution epic (#431), building the centralized AI Artifacts Registry, validation scripts, and Pester tests. As subsequent phases progressed, the architecture was simplified from a centralized registry with persona-based filtering to a decentralized collection manifest system where each collection directly declares its items. The registry and its validation infrastructure were removed once the collection approach proved simpler and more maintainable.

Key architectural decisions that drove the pivot:

Decision	Rationale
YAML collection manifests over JSON registry	Simpler authoring, no indirection layer, human-readable
Domain-focused over role-based groupings	Users pick domains (ado, rpi, git) not personas; more composable
Symlink-based plugins over .vsix per collection	Disk-efficient, single source of truth for artifacts
Auto-discovery for hve-core-all	Removes manual maintenance burden for the full bundle
Maturity per-item in collections	Eliminates need for a central maturity registry

Breaking Changes

• maturity frontmatter field removed from all 61+ artifact files
• Frontmatter schemas updated to remove maturity property
• extension/package.json contributes section generated at build time (no longer static)
• Extension packaging scripts accept new parameters (-Collection, collection-aware filtering)
• ai-artifacts-registry.json removed (previously proposed in Phase 1)
• Validate-ArtifactRegistry.ps1 removed (replaced by Validate-Collections.ps1)
• npm run lint:registry removed (replaced by npm run plugin:validate)

Collections Summary

Collection ID	Name	Maturity
ado	Azure DevOps Integration	stable
coding-standards	Coding Standards	stable
data-science	Data Science	stable
git	Git Operations	stable
github	GitHub Backlog Management	experimental
hve-core-all	HVE Core All	stable
project-planning	Project Planning	stable
prompt-engineering	Prompt Engineering	stable
rpi	RPI Workflow	stable
security-planning	Security Planning	stable

NPM Scripts

Script	Purpose
npm run plugin:generate	Generate plugins from collection manifests
npm run plugin:validate	Validate all collection manifests
npm run lint:collections-metadata	CI validation alias
npm run extension:prepare	Prepare extension (stable channel)
npm run extension:prepare:prerelease	Prepare extension (prerelease channel)
npm run extension:package	Package .vsix

🔧 - Generated by Copilot

[github-actions]

Dependency Review

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

Scanned Files

• .github/workflows/extension-publish-prerelease.yml

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.15385% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.34%. Comparing base (7927db2) to head (a82dfb5).

Files with missing lines	Patch %	Lines
scripts/plugins/Validate-Collections.ps1	66.66%	13 Missing ⚠️
scripts/extension/Prepare-Extension.ps1	98.38%	7 Missing ⚠️
scripts/extension/Package-Extension.ps1	96.07%	4 Missing ⚠️
scripts/plugins/Modules/PluginHelpers.psm1	97.53%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #439      +/-   ##
==========================================
+ Coverage   83.41%   85.34%   +1.92%     
==========================================
  Files          20       23       +3     
  Lines        3510     4476     +966     
==========================================
+ Hits         2928     3820     +892     
- Misses        582      656      +74     

Flag	Coverage Δ
pester	85.34% <96.15%> (+1.92%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/linting/Validate-MarkdownFrontmatter.ps1	65.31% <ø> (ø)
scripts/plugins/Generate-Plugins.ps1	77.77% <100.00%> (ø)
scripts/plugins/Modules/PluginHelpers.psm1	96.61% <97.53%> (ø)
scripts/extension/Package-Extension.ps1	94.80% <96.07%> (+1.55%)	⬆️
scripts/extension/Prepare-Extension.ps1	93.26% <98.38%> (+9.53%)	⬆️
scripts/plugins/Validate-Collections.ps1	69.16% <66.66%> (ø)

... and 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

This draft PR implements Phase 1 of the persona-based distribution epic (#431), introducing the AI Artifacts Registry as a centralized metadata store for all HVE-Core artifacts. The registry replaces in-frontmatter metadata (resolving Copilot CLI incompatibility issues from #360) and establishes the foundation for persona-filtered extension packages and installer enhancements in subsequent phases.

Changes:

• Introduced AI Artifacts Registry JSON file with persona definitions (hve-core-all, developer, tpm, devops, architect, technical-writer) and complete metadata for 62 artifacts (21 agents, 22 prompts, 18 instructions, 1 skill) including maturity levels, persona assignments, and dependency mappings
• Created comprehensive PowerShell validation script with structure validation, persona reference checking, file existence verification, dependency validation, circular dependency detection, and orphan file detection capabilities
• Added JSON Schema defining registry format with maturity enum, persona arrays, tags, and agent dependency mappings
• Implemented Pester test suite with 64 tests covering all validation functions, edge cases, and CI integration scenarios (97.27% code coverage)
• Integrated validation into CI/CD pipeline via npm run lint:registry and lint:all

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.github/ai-artifacts-registry.json	Centralized registry with all 62 artifacts, personas, maturity levels, and dependency mappings
scripts/linting/Validate-ArtifactRegistry.ps1	PowerShell validation script with comprehensive checks for structure, personas, files, and dependencies
scripts/linting/schemas/ai-artifacts-registry.schema.json	JSON Schema defining registry format with enums, patterns, and required fields
scripts/tests/linting/Validate-ArtifactRegistry.Tests.ps1	Complete Pester test suite with 64 tests achieving 97.27% coverage
scripts/tests/Fixtures/ArtifactRegistry/*.json	11 test fixture files for validation scenarios (valid, invalid JSON, missing fields, circular deps, etc.)
package.json	Added lint:registry script and integrated into lint:all pipeline

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 89 out of 90 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 97 out of 98 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 174 out of 175 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

extension/PACKAGING.md:1

• The date "2026-02-10" is in the future. Documentation dates should reflect when the content was last updated, not a future date.
  scripts/tests/extension/Package-Extension.Tests.ps1:1
• The new .github/skills directory creation is added to support skills packaging, but there are no corresponding tests that verify skills are correctly copied during collection-based packaging. Add test coverage for skills copying in the collection mode tests.
  scripts/extension/Package-Extension.ps1:1
• The function lacks a .NOTES section explaining that it returns null for both the hve-core-all collection AND when no matching README file exists. This dual null-return behavior should be documented to clarify the function's contract.
  plugins/hve-core-all/agents/github-issue-manager.md:1
• This symlink points to a deprecated agent. Consider adding a comment in the symlink target file or a README explaining why this deprecated agent is still included in the hve-core-all collection rather than being removed entirely.

[Copilot]

Pull request overview

Copilot reviewed 175 out of 176 changed files in this pull request and generated no new comments.