docs: add maturity field and extension channel documentation

WilliamBerryiii · WilliamBerryiii · commit 241216d227f0 · 2026-01-15T12:18:20.000-08:00
- release-process.md: extension channels and maturity lifecycle
- ai-artifacts-common.md: maturity field requirements section
- prompts.md, instructions.md, chatmodes.md: maturity as required field
- extension/README.md: pre-release channel section

📚 - Generated by Copilot
diff --git a/docs/contributing/README.md b/docs/contributing/README.md
@@ -23,6 +23,7 @@ Guidelines and standards for contributing AI artifacts to hve-core.
 | [Chat Modes](chatmodes.md)                 | How to create and submit new chat mode definitions                              |
 | [Instructions](instructions.md)            | How to create repository-specific coding guidelines                             |
 | [Prompts](prompts.md)                      | How to create reusable prompt templates                                         |
+| [Release Process](release-process.md)      | Extension channels, maturity levels, and publishing workflow                    |
 
 ## Before You Start
 
diff --git a/docs/contributing/ai-artifacts-common.md b/docs/contributing/ai-artifacts-common.md
@@ -83,6 +83,46 @@ All AI artifacts (chatmodes, instructions, prompts) **MUST** target the **latest
 1. **Feature parity**: Latest models support the most advanced features and capabilities
 2. **Maintenance burden**: Supporting multiple model versions creates testing and compatibility overhead
 3. **Performance**: Latest models provide superior reasoning, accuracy, and efficiency
+
+## Maturity Field Requirements
+
+All AI artifacts (chatmodes, instructions, prompts) **MUST** include a `maturity` field in frontmatter.
+
+### Purpose
+
+The maturity field controls which extension channel includes the artifact:
+
+* **Stable channel**: Only artifacts with `maturity: stable`
+* **Pre-release channel**: Artifacts with `stable`, `preview`, or `experimental` maturity
+
+### Valid Values
+
+| Value          | Description                                      | Stable Channel | Pre-release Channel |
+|----------------|--------------------------------------------------|----------------|---------------------|
+| `stable`       | Production-ready, fully tested                   | ✅ Included    | ✅ Included         |
+| `preview`      | Feature-complete, may have rough edges           | ❌ Excluded    | ✅ Included         |
+| `experimental` | Early development, may change significantly      | ❌ Excluded    | ✅ Included         |
+| `deprecated`   | Scheduled for removal                            | ❌ Excluded    | ❌ Excluded         |
+
+### Default for New Contributions
+
+New artifacts **SHOULD** use `maturity: stable` unless:
+
+* The artifact is a proof-of-concept or experimental feature
+* The artifact requires additional testing or feedback before wide release
+* The contributor explicitly intends to target early adopters
+
+### Example
+
+```yaml
+---
+description: 'Specialized chatmode for security analysis'
+maturity: 'stable'
+tools: ['codebase', 'search']
+---
+```
+
+For detailed channel and lifecycle information, see [Release Process - Extension Channels](release-process.md#extension-channels-and-maturity).
 4. **Future-proofing**: Older models will be deprecated and removed from service
 
 **Before submitting**: Verify your artifact targets the current latest model versions from Anthropic or OpenAI. Contributions targeting older or alternative models will be automatically rejected.
diff --git a/docs/contributing/chatmodes.md b/docs/contributing/chatmodes.md
@@ -125,6 +125,17 @@ Chatmode files **MUST**:
 * **Style**: Sentence case with proper punctuation
 * **Example**: `'Validates contributed content for quality and compliance with hve-core standards'`
 
+**`maturity`** (string enum, MANDATORY)
+
+* **Purpose**: Controls which extension channel includes this chatmode
+* **Valid values**:
+  * `stable` - Production-ready, included in Stable and Pre-release channels
+  * `preview` - Feature-complete, included in Pre-release channel only
+  * `experimental` - Early development, included in Pre-release channel only
+  * `deprecated` - Scheduled for removal, excluded from all channels
+* **Default**: New chatmodes should use `stable` unless targeting early adopters
+* **Example**: `stable`
+
 ### Optional Fields
 
 **`tools`** (array of strings)
diff --git a/docs/contributing/instructions.md b/docs/contributing/instructions.md
@@ -84,6 +84,17 @@ Instruction files **MUST**:
   * Directory scope: `**/src/**/*.sh`
   * Specific paths: `**/.copilot-tracking/pr/new/**`
 
+**`maturity`** (string enum, MANDATORY)
+
+* **Purpose**: Controls which extension channel includes this instruction
+* **Valid values**:
+  * `stable` - Production-ready, included in Stable and Pre-release channels
+  * `preview` - Feature-complete, included in Pre-release channel only
+  * `experimental` - Early development, included in Pre-release channel only
+  * `deprecated` - Scheduled for removal, excluded from all channels
+* **Default**: New instructions should use `stable` unless targeting early adopters
+* **Example**: `stable`
+
 ### Optional Fields
 
 **`version`** (string)
@@ -108,6 +119,7 @@ Instruction files **MUST**:
 ---
 description: 'Required instructions for Python script implementation with type hints, docstrings, and error handling'
 applyTo: '**/*.py, **/*.ipynb'
+maturity: 'stable'
 version: '1.0.0'
 author: 'microsoft/hve-core'
 lastUpdated: '2025-11-19'
diff --git a/docs/contributing/prompts.md b/docs/contributing/prompts.md
@@ -72,6 +72,17 @@ Prompt files **MUST**:
   * `workflow` - Automated workflow/pipeline context
 * **Example**: `workflow`
 
+**`maturity`** (string enum, MANDATORY)
+
+* **Purpose**: Controls which extension channel includes this prompt
+* **Valid values**:
+  * `stable` - Production-ready, included in Stable and Pre-release channels
+  * `preview` - Feature-complete, included in Pre-release channel only
+  * `experimental` - Early development, included in Pre-release channel only
+  * `deprecated` - Scheduled for removal, excluded from all channels
+* **Default**: New prompts should use `stable` unless targeting early adopters
+* **Example**: `stable`
+
 ### Optional Fields
 
 **`category`** (string enum)
@@ -105,6 +116,7 @@ Prompt files **MUST**:
 ---
 description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'
 mode: 'workflow'
+maturity: 'stable'
 category: 'ado'
 version: '1.0.0'
 author: 'microsoft/hve-core'
@@ -417,6 +429,7 @@ Before submitting your prompt, verify:
 
 * [ ] Clear H1 title describing workflow
 * [ ] Overview/purpose section
+* [ ] Maturity field set appropriately (see [Common Standards - Maturity](ai-artifacts-common.md#maturity-field-requirements))
 * [ ] Prerequisites or context section
 * [ ] Workflow steps with clear sequence
 * [ ] Success criteria defined
diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md
@@ -124,3 +124,44 @@ Documentation-only releases may not require an extension publish.
 | Merge Release PR         | GitHub Release created, tag applied         |
 | Run publish workflow     | Extension published to marketplace          |
 | Merge docs-only PR       | Changelog updated, no version bump          |
+
+## Extension Channels and Maturity
+
+The VS Code extension is published to two channels with different stability expectations.
+
+### Extension Channels
+
+| Channel    | Stability       | Included Maturity Levels           | Audience          |
+|------------|-----------------|-------------------------------------|-------------------|
+| Stable     | Production-ready | `stable` only                      | All users         |
+| Pre-release | Early access    | `stable`, `preview`, `experimental` | Early adopters    |
+
+### Maturity Levels
+
+Each prompt, instruction, and chatmode declares a `maturity` field in its frontmatter:
+
+| Level          | Description                                      | Included In       |
+|----------------|--------------------------------------------------|-------------------|
+| `stable`       | Production-ready, fully tested                   | Stable, Pre-release |
+| `preview`      | Feature-complete but may have rough edges        | Pre-release only  |
+| `experimental` | Early development, may change significantly      | Pre-release only  |
+| `deprecated`   | Scheduled for removal, excluded from all builds  | Neither           |
+
+### Maturity Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> experimental : New artifact
+    experimental --> preview : Core features complete
+    preview --> stable : Production tested
+    stable --> deprecated : Superseded or obsolete
+    deprecated --> [*] : Removed
+```
+
+### Contributor Guidelines
+
+* **New contributions**: Default to `maturity: stable` unless explicitly targeting early adopters
+* **Experimental work**: Use `maturity: experimental` for proof-of-concept or rapidly evolving artifacts
+* **Preview promotions**: Move to `maturity: preview` when core functionality is complete
+* **Stable promotions**: Move to `maturity: stable` after production validation
+* **Deprecation**: Set `maturity: deprecated` before removal to provide transition time
diff --git a/extension/README.md b/extension/README.md
@@ -80,6 +80,19 @@ adr-creation create an ADR for our new microservice architecture
 
 Prompts are available in the Copilot Chat prompt picker and can be used to generate consistent, high-quality outputs for common tasks.
 
+## Pre-release Channel
+
+HVE Core offers two installation channels:
+
+| Channel     | Description                                              | Maturity Levels                     |
+|-------------|----------------------------------------------------------|-------------------------------------|
+| Stable      | Production-ready artifacts only                          | `stable`                            |
+| Pre-release | Early access to new features and experimental artifacts  | `stable`, `preview`, `experimental` |
+
+To install the pre-release version, select **Install Pre-Release Version** from the extension page in VS Code, or use the Extensions view and switch to the pre-release channel.
+
+For more details on maturity levels and the release process, see the [contributing documentation](https://github.com/microsoft/hve-core/blob/main/docs/contributing/release-process.md#extension-channels-and-maturity).
+
 ## Requirements
 
 - VS Code version 1.106.1 or higher
