Skip to content

Commit 3156d98

Browse files
katriendgCopilotagreaves-ms
authored
feat(extension): implement collection-based plugin distribution system (#439)
## 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 (#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) - [x] New feature (non-breaking change adding functionality) - [x] Breaking change (fix or feature causing existing functionality to change) - [x] Documentation update **Infrastructure & Configuration:** - [x] GitHub Actions workflow - [x] Linting configuration (markdown, PowerShell, etc.) - [ ] Security configuration - [ ] DevContainer configuration - [ ] Dependency update **AI Artifacts:** - [x] Reviewed contribution with `prompt-builder` agent and addressed all feedback - [x] Copilot instructions (`.github/instructions/*.instructions.md`) - [x] Copilot prompt (`.github/prompts/*.prompt.md`) - [x] 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) 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 - [x] Documentation is updated (if applicable) - [x] Files follow existing naming conventions - [ ] Changes are backwards compatible (if applicable) - [x] Tests added for new functionality (if applicable) ### AI Artifact Contributions - [ ] Used `/prompt-analyze` to review contribution - [x] 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` - [ ] Link validation: `npm run lint:md-links` - [x] PowerShell analysis: `npm run lint:ps` ## Security Considerations - [x] This PR does not contain any sensitive or NDA information - [ ] Any new dependencies have been reviewed for security issues - [x] 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 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: katriendg <[email protected]> Co-authored-by: Allen Greaves <[email protected]>
1 parent 7927db2 commit 3156d98

176 files changed

Lines changed: 6597 additions & 1256 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cspell.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@
7979
"Streamlit",
8080
"vscodeignore",
8181
"\u02c8pr\u00e6ks\u026as",
82-
"\u03c0\u03c1\u1fb6\u03be\u03b9\u03c2"
82+
"\u03c0\u03c1\u1fb6\u03be\u03b9\u03c2",
83+
"TMPVER"
8384
]
84-
}
85+
}

‎.github/agents/ado-prd-to-wit.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: 'Product Manager expert for analyzing PRDs and planning Azure DevOps work item hierarchies'
3-
maturity: stable
43
tools: ['execute/getTerminalOutput', 'execute/runInTerminal', 'read/problems', 'read/readFile', 'read/terminalSelection', 'read/terminalLastCommand', 'edit/createDirectory', 'edit/createFile', 'edit/editFiles', 'search', 'web', 'agent', 'ado/search_workitem', 'ado/wit_get_work_item', 'ado/wit_get_work_items_for_iteration', 'ado/wit_list_backlog_work_items', 'ado/wit_list_backlogs', 'ado/wit_list_work_item_comments', 'ado/work_list_team_iterations', 'microsoft-docs/*']
54
---
65

‎.github/agents/adr-creation.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: 'Interactive AI coaching for collaborative architectural decision record creation with guided discovery, research integration, and progressive documentation building - Brought to you by microsoft/edge-ai'
3-
maturity: stable
43
---
54

65
# ADR Creation Coach

‎.github/agents/arch-diagram-builder.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: Architecture diagram builder agent that builds high quality ASCII-art diagrams - Brought to you by microsoft/hve-core
3-
maturity: stable
43
---
54

65
# Architecture Diagram Builder Agent

‎.github/agents/brd-builder.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: "Business Requirements Document builder with guided Q&A and reference integration"
3-
maturity: stable
43
---
54

65
# BRD Builder Instructions

‎.github/agents/doc-ops.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: 'Autonomous documentation operations agent for pattern compliance, accuracy verification, and gap detection - Brought to you by microsoft/hve-core'
3-
maturity: stable
43
---
54

65
# Documentation Operations Agent

‎.github/agents/gen-data-spec.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: "Generate comprehensive data dictionaries, machine-readable data profiles, and objective summaries for downstream analysis (EDA notebooks, dashboards) through guided discovery"
3-
maturity: stable
43
tools: ['runCommands', 'edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'think', 'todos']
54
---
65

‎.github/agents/gen-jupyter-notebook.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: 'Create structured exploratory data analysis Jupyter notebooks from available data sources and generated data dictionaries'
3-
maturity: stable
43
---
54

65
# Jupyter Notebook Generator

‎.github/agents/gen-streamlit-dashboard.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: 'Develop a multi-page Streamlit dashboard'
3-
maturity: stable
43
---
54

65
# Streamlit Dashboard Generator

‎.github/agents/github-backlog-manager.agent.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
description: "Orchestrator agent for GitHub backlog management workflows including triage, discovery, sprint planning, and execution - Brought to you by microsoft/hve-core"
3-
maturity: experimental
43
tools:
54
- github/*
65
- search

0 commit comments

Comments
 (0)