microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/contributing/ai-artifacts-common.md
928lines · modecode
| 1 | --- |
| 2 | title: 'AI Artifacts Common Standards' |
| 3 | description: 'Common standards and quality gates for all AI artifact contributions to hve-core' |
| 4 | sidebar_position: 2 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-03-12 |
| 7 | ms.topic: reference |
| 8 | --- |
| 9 | |
| 10 | This document defines shared standards, conventions, and quality gates that apply to **all** AI artifact contributions to hve-core (agents, prompts, and instructions files). |
| 11 | |
| 12 | ## Agents Not Accepted |
| 13 | |
| 14 | The following agent types will likely be **rejected or closed automatically** because equivalent agents already exist in hve-core: |
| 15 | |
| 16 | ### Duplicate Agent Categories |
| 17 | |
| 18 | #### Research or Discovery Agents |
| 19 | |
| 20 | Agents that search for, gather, or discover information. |
| 21 | |
| 22 | * ❌ Reason: Existing agents already handle research and discovery workflows |
| 23 | * ✅ Alternative: Use existing research-focused agents in `.github/agents/` |
| 24 | |
| 25 | #### Indexing or Referencing Agents |
| 26 | |
| 27 | Agents that catalog, index, or create references to existing projects. |
| 28 | |
| 29 | * ❌ Reason: Existing agents already provide indexing and referencing capabilities |
| 30 | * ❌ Tool integration: Widely supported tools built into VS Code GitHub Copilot and MCP tools with extremely wide adoption are already supported by existing hve-core agents |
| 31 | * ✅ Alternative: Use existing reference management agents that use standard VS Code GitHub Copilot tools and widely-adopted MCP tools |
| 32 | |
| 33 | #### Planning Agents |
| 34 | |
| 35 | Agents that plan work, break down tasks, or organize backlog items. |
| 36 | |
| 37 | * ❌ Reason: Existing agents already handle work planning and task organization |
| 38 | * ✅ Alternative: Use existing planning-focused agents in `.github/agents/` |
| 39 | |
| 40 | #### Implementation Agents |
| 41 | |
| 42 | General-purpose coding agents that implement features. |
| 43 | |
| 44 | * ❌ Reason: Existing agents already provide implementation guidance |
| 45 | * ✅ Alternative: Use existing implementation-focused agents |
| 46 | |
| 47 | ### Rationale for Rejection |
| 48 | |
| 49 | These agent types are rejected because: |
| 50 | |
| 51 | 1. Existing agents are hardened and heavily used: the hve-core library already contains production-tested agents in these categories |
| 52 | 2. Consistency and maintenance: coalescing around existing agents reduces fragmentation and maintenance burden |
| 53 | 3. Avoid duplication: multiple agents serving the same purpose create confusion and divergent behavior |
| 54 | 4. Standard tooling already integrated: VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already used by existing agents |
| 55 | |
| 56 | ### Before Submitting |
| 57 | |
| 58 | When planning to submit an agent that falls into these categories: |
| 59 | |
| 60 | 1. Question necessity: does your use case truly require a new agent, or can existing agents meet your needs? |
| 61 | 2. Review existing agents: examine `.github/agents/` to identify agents that already serve your purpose |
| 62 | 3. Check tool integration: verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents |
| 63 | 4. Consider enhancement over creation: if existing agents don't fully meet your requirements, evaluate whether your changes are generic enough to benefit all users and valuable enough to justify modifying the existing agent |
| 64 | 5. Propose enhancements: submit a PR to enhance an existing agent rather than creating a duplicate |
| 65 | |
| 66 | ### What Makes a Good New Agent |
| 67 | |
| 68 | Focus on agents that: |
| 69 | |
| 70 | | Criterion | Description | |
| 71 | |----------------------|-------------------------------------------------------------------------------------------------| |
| 72 | | Fill gaps | Address use cases not covered by existing agents | |
| 73 | | Provide unique value | Offer specialized domain expertise or workflow patterns not present in the library | |
| 74 | | Are non-overlapping | Have clearly distinct purposes from existing agents | |
| 75 | | Cannot be merged | Represent functionality too specialized or divergent to integrate into existing agents | |
| 76 | | Use standard tooling | Use widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations | |
| 77 | |
| 78 | ## Model Version Requirements |
| 79 | |
| 80 | All AI artifacts (agents, instructions, prompts) **MUST** target the **latest available models** from Anthropic and OpenAI only. |
| 81 | |
| 82 | The model catalog (`scripts/linting/model-catalog.json`) contains the full list of models available in GitHub Copilot for validation purposes, but not all cataloged models are accepted for use in hve-core artifacts, per above. |
| 83 | |
| 84 | ### Accepted Models |
| 85 | |
| 86 | | Provider | Models | |
| 87 | |-----------|-----------------------------------------------------------------| |
| 88 | | Anthropic | Latest Claude models (e.g., Claude Sonnet 4.6, Claude Opus 4.6) | |
| 89 | | OpenAI | Latest GPT models (e.g., GPT-5.4, GPT-5.3-Codex) | |
| 90 | |
| 91 | ### Not Accepted |
| 92 | |
| 93 | * ❌ Models from other providers |
| 94 | * ❌ Older model versions not in the catalog (e.g., GPT-4o, Claude 3.5) |
| 95 | * ❌ Custom or fine-tuned models |
| 96 | * ❌ Deprecated or retired model versions |
| 97 | |
| 98 | ### Model Name Format |
| 99 | |
| 100 | Model references in frontmatter use the VS Code display name with vendor suffix: |
| 101 | |
| 102 | ```yaml |
| 103 | # Single model |
| 104 | model: Claude Haiku 4.5 (copilot) |
| 105 | |
| 106 | # Prioritized fallback array (system tries each in order) |
| 107 | model: |
| 108 | - Claude Haiku 4.5 (copilot) |
| 109 | - GPT-5.4 mini (copilot) |
| 110 | ``` |
| 111 | |
| 112 | The `(copilot)` suffix is required. Run `npm run lint:models` to validate all model references against the catalog. |
| 113 | |
| 114 | ### Model Selection (Optional) |
| 115 | |
| 116 | The `model` frontmatter property is **optional**. When omitted, the agent or prompt inherits the user's session model (whatever is selected in the VS Code model picker). |
| 117 | |
| 118 | Use explicit model selection for cost optimization: |
| 119 | |
| 120 | | Tier | Multiplier | Use When | Example Models | |
| 121 | |----------|-------------|---------------------------------------------------------|--------------------------------| |
| 122 | | Fast | 0.25x–0.33x | Read-only research, mechanical file ops, classification | Claude Haiku 4.5, GPT-5.4 mini | |
| 123 | | Standard | 1x | Code generation, architecture, complex synthesis | Claude Sonnet 4.6, GPT-5.4 | |
| 124 | | Premium | 3x–15x | Vision-capable tasks, complex architectural decisions | Claude Opus 4.6, GPT-5.5 | |
| 125 | |
| 126 | ### Cost Tier Constraint |
| 127 | |
| 128 | The `model` property is a **preference hint**, not a hard constraint. VS Code never fails a prompt or agent invocation due to model unavailability. When a specified model is unavailable or exceeds the cost tier of the parent model, VS Code falls back through the array entries in order, then to the session model (model picker selection). |
| 129 | |
| 130 | VS Code enforces that subagent models cannot exceed the cost tier of the parent model. If the user selects Sonnet (standard) in the model picker, subagents can use Haiku (fast) but not Opus (premium). Fallback arrays provide resilience when the preferred model is unavailable or exceeds the cost tier. A single-model string is equally safe: it falls back to the session model when the specified model cannot be used. |
| 131 | |
| 132 | ### Model Catalog Validation |
| 133 | |
| 134 | Model references are validated against `scripts/linting/model-catalog.json` by the `lint:models` script. A scheduled GitHub Actions workflow (`model-validation.yml`) runs weekly to detect catalog drift and retiring models. |
| 135 | |
| 136 | To refresh the catalog from upstream documentation: |
| 137 | |
| 138 | ```bash |
| 139 | npm run lint:models:refresh |
| 140 | ``` |
| 141 | |
| 142 | ### Rationale |
| 143 | |
| 144 | 1. Feature parity: latest models support the most advanced features and capabilities |
| 145 | 2. Maintenance burden: supporting multiple model versions creates testing and compatibility overhead |
| 146 | 3. Performance: latest models provide superior reasoning, accuracy, and efficiency |
| 147 | 4. Future-proofing: older models will be deprecated and removed from service |
| 148 | 5. Cost optimization: fast-tier models reduce consumption for tasks that do not require premium reasoning |
| 149 | |
| 150 | ## Collections |
| 151 | |
| 152 | Collection manifests in `collections/*.collection.yml` are the source of truth for artifact selection and distribution. |
| 153 | |
| 154 | ### Collection Purpose |
| 155 | |
| 156 | Collection manifests serve three primary functions: |
| 157 | |
| 158 | 1. Selection \u2014 determine which artifacts are included in each collection via `items[]` |
| 159 | 2. Maturity filtering \u2014 control channel inclusion with `items[].maturity` (defaults to `stable`) |
| 160 | 3. Packaging inputs \u2014 provide canonical manifest data used by build and distribution flows |
| 161 | |
| 162 | ### Collection Structure |
| 163 | |
| 164 | Each manifest contains top-level collection metadata and an `items` array: |
| 165 | |
| 166 | ```yaml |
| 167 | id: coding-standards |
| 168 | name: Coding Standards |
| 169 | description: Language-specific coding instructions |
| 170 | tags: |
| 171 | - coding-standards |
| 172 | - bash |
| 173 | - python |
| 174 | items: |
| 175 | - path: .github/instructions/coding-standards/python-script.instructions.md |
| 176 | kind: instruction |
| 177 | maturity: stable |
| 178 | - path: .github/prompts/hve-core/task-plan.prompt.md |
| 179 | kind: prompt |
| 180 | maturity: preview |
| 181 | ``` |
| 182 | |
| 183 | ### Collection Tags |
| 184 | |
| 185 | Each collection manifest declares a top-level `tags` array for categorization and discoverability. Tags exist **only at the collection level**, not on individual items. |
| 186 | |
| 187 | | Collection | Tags | |
| 188 | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------| |
| 189 | | `hve-core-all` | `hve`, `complete`, `bundle` | |
| 190 | | `ado` | `azure-devops`, `ado`, `work-items`, `builds`, `pull-requests` | |
| 191 | | `coding-standards` | `coding-standards`, `code-review`, `pull-request`, `quality`, `bash`, `bicep`, `csharp`, `powershell`, `python`, `rust`, `terraform`, `uv` | |
| 192 | | `data-science` | `data`, `jupyter`, `streamlit`, `dashboards`, `visualization`, `data-science` | |
| 193 | | `design-thinking` | `design-thinking`, `coaching`, `methodology`, `ux` | |
| 194 | | `experimental` | `experimental`, `media`, `utilities` | |
| 195 | | `github` | `github`, `issues`, `backlog`, `triage`, `sprint` | |
| 196 | | `installer` | `installer`, `setup`, `onboarding` | |
| 197 | | `project-planning` | `documentation`, `architecture`, `adr`, `brd`, `prd`, `diagrams`, `planning` | |
| 198 | | `hve-core` | `workflow`, `rpi`, `planning`, `research`, `implementation`, `review` | |
| 199 | | `security` | `security`, `incident-response`, `risk`, `planning`, `review`, `vulnerability`, `threat-modeling` | |
| 200 | |
| 201 | When creating a new collection, choose tags that describe the domain, technologies, and workflows covered. Use lowercase kebab-case and prefer existing tags before introducing new ones. |
| 202 | |
| 203 | ### Collection Item Format |
| 204 | |
| 205 | Each `items[]` entry follows this structure: |
| 206 | |
| 207 | ```yaml |
| 208 | - path: .github/agents/hve-core/rpi-agent.agent.md |
| 209 | kind: agent |
| 210 | maturity: stable |
| 211 | ``` |
| 212 | |
| 213 | | Field | Required | Description | |
| 214 | |------------|----------|--------------------------------------------------------------------------------| |
| 215 | | `path` | Yes | Repository-relative path to the artifact source | |
| 216 | | `kind` | Yes | Artifact type (`agent`, `prompt`, `instruction`, `skill`, or `hook`) | |
| 217 | | `maturity` | No | Release readiness level; when omitted, effective maturity defaults to `stable` | |
| 218 | |
| 219 | ### Adding Artifacts to a Collection |
| 220 | |
| 221 | When contributing a new artifact: |
| 222 | |
| 223 | 1. Create the artifact file in the appropriate directory |
| 224 | 2. Add a matching `items[]` entry in one or more `collections/*.collection.yml` files |
| 225 | 3. Set `maturity` when the artifact should be `preview`, `experimental`, `deprecated`, or `removed`. Use `removed` to exclude an artifact from all generated plugins and extension distributions while leaving the source file in place; this is the preferred way to retire a single artifact when the file should remain in the repository (see [AI Artifacts Architecture - Removed Artifacts](../architecture/ai-artifacts.md#removed-artifacts)) |
| 226 | 4. Update the collection's `tags` array if your artifact introduces a new technology or domain not yet represented |
| 227 | 5. Run `npm run lint:yaml` to validate manifest syntax and schema compliance |
| 228 | 6. Run `npm run plugin:validate` to validate collection manifests |
| 229 | 7. Run `npm run plugin:generate` to regenerate plugin directories |
| 230 | 8. Run `npm run docs:test` to verify the Docusaurus site reflects the updated collection counts |
| 231 | |
| 232 | ### Repo-Specific Artifact Exclusion |
| 233 | |
| 234 | Artifacts placed at the root of `.github/agents/`, `.github/instructions/`, `.github/prompts/`, or `.github/skills/` (without a subdirectory) are repo-specific and MUST NOT be added to collection manifests. These files govern internal repository concerns (CI/CD workflows, repo-specific conventions) that do not apply outside this repository. |
| 235 | |
| 236 | ### Deprecated Artifact Placement |
| 237 | |
| 238 | Artifacts that have been superseded or are scheduled for removal MUST be moved to `.github/deprecated/{type}/` (e.g., `.github/deprecated/agents/`, `.github/deprecated/prompts/`). The build system automatically excludes this subtree from collection manifests, plugin generation, and extension packaging. |
| 239 | |
| 240 | #### When to Move an Artifact to Deprecated |
| 241 | |
| 242 | * A newer artifact fully replaces the existing one |
| 243 | * The artifact is no longer maintained or tested |
| 244 | * The artifact targets a retired platform or workflow |
| 245 | |
| 246 | #### How to Deprecate an Artifact |
| 247 | |
| 248 | 1. Move the file with `git mv` to preserve history: `git mv .github/agents/{collection}/old.agent.md .github/deprecated/agents/old.agent.md` |
| 249 | 2. Add a note in the deprecated file's frontmatter or body identifying its replacement |
| 250 | 3. Remove the artifact's entry from all `collections/*.collection.yml` files |
| 251 | 4. Run `npm run plugin:generate` to regenerate plugin outputs |
| 252 | 5. Update any documentation that references the old artifact path |
| 253 | |
| 254 | #### Exclusion Scope |
| 255 | |
| 256 | Artifacts at the root of `.github/agents/`, `.github/instructions/`, `.github/prompts/`, or `.github/skills/` are excluded from: |
| 257 | |
| 258 | * Collection manifests (`collections/*.collection.yml` items) |
| 259 | * Plugin generation (`plugins/` directory contents) |
| 260 | * Extension packaging and distribution |
| 261 | * Collection builds and bundles |
| 262 | * Artifact selection for published releases |
| 263 | |
| 264 | #### Validation Enforcement |
| 265 | |
| 266 | The plugin generation and validation tooling actively enforces this exclusion: |
| 267 | |
| 268 | * Collection validation fails if root-level repo-specific paths appear in `items[]` |
| 269 | * Plugin generation skips root-level artifacts |
| 270 | * Extension packaging filters out these files during build |
| 271 | |
| 272 | #### Placement Guidelines |
| 273 | |
| 274 | | Scope | Location | Included in Plugins | |
| 275 | |-----------------------------|---------------------------------------------------------|---------------------| |
| 276 | | **Repository-specific** | `.github/instructions/` (root, no subdirectory) | ❌ No | |
| 277 | | **Collection-scoped** | `.github/instructions/{collection-id}/` (by convention) | ✅ Yes | |
| 278 | | **Language/tech-specific** | `.github/instructions/coding-standards/{language}/` | ✅ Yes | |
| 279 | | **Shared cross-collection** | `.github/instructions/shared/` | ✅ Yes | |
| 280 | |
| 281 | If your instructions apply only to this repository and are not intended for distribution to consumers, place them at the root of `.github/instructions/`. Otherwise, by convention, place them in `.github/instructions/{collection-id}/` or a language-specific subdirectory under `coding-standards/` (e.g., `coding-standards/csharp/`, `coding-standards/bash/`). Shared cross-collection artifacts go in `.github/instructions/shared/`. |
| 282 | |
| 283 | ## Collection Taxonomy |
| 284 | |
| 285 | Collections represent role-targeted artifact packages for HVE Core artifacts. The collection system enables role-specific artifact distribution without fragmenting the codebase. |
| 286 | |
| 287 | ### Defined Collections |
| 288 | |
| 289 | | Collection | Identifier | Description | |
| 290 | |-----------------------|--------------------|--------------------------------------------------------------------------------------| |
| 291 | | **All** | `hve-core-all` | Full bundle of all stable HVE Core agents, prompts, instructions, and skills | |
| 292 | | **Azure DevOps** | `ado` | Azure DevOps work item management, build monitoring, and pull request creation | |
| 293 | | **Coding Standards** | `coding-standards` | Language-specific coding instructions for bash, Bicep, C#, Python, and Terraform | |
| 294 | | **Data Science** | `data-science` | Data specification generation, Jupyter notebooks, and Streamlit dashboards | |
| 295 | | **Design Thinking** | `design-thinking` | Design Thinking coaching identity, quality constraints, and methodology instructions | |
| 296 | | **Experimental** | `experimental` | Experimental skills and utilities in early development | |
| 297 | | **GitHub Backlog** | `github` | GitHub issue discovery, triage, sprint planning, and backlog execution | |
| 298 | | **Installer** | `installer` | HVE Core installation skill (installer) and environment setup | |
| 299 | | **Project Planning** | `project-planning` | PRDs, BRDs, ADRs, architecture diagrams, and documentation operations | |
| 300 | | **HVE Core Workflow** | `hve-core` | Research, Plan, Implement, Review workflow agents and prompts | |
| 301 | | **Security** | `security` | Security review, planning, incident response, and risk assessment | |
| 302 | |
| 303 | ### Collection Assignment Guidelines |
| 304 | |
| 305 | When assigning collections to artifacts: |
| 306 | |
| 307 | * Include `hve-core-all` plus any role-specific collections that particularly benefit for universal artifacts |
| 308 | * Include only the relevant collections for role-specific artifacts (omit `hve-core-all` for highly specialized artifacts) |
| 309 | * Assign cross-cutting tools like RPI workflow artifacts (`task-researcher`, `task-planner`) to multiple relevant collections |
| 310 | |
| 311 | #### Example Collection Assignments |
| 312 | |
| 313 | Adding an artifact to multiple collections means adding its `items[]` entry in each relevant `collections/*.collection.yml`: |
| 314 | |
| 315 | ```yaml |
| 316 | # In collections/hve-core-all.collection.yml - Universal |
| 317 | - path: .github/instructions/hve-core/markdown.instructions.md |
| 318 | kind: instruction |
| 319 | |
| 320 | # In collections/coding-standards.collection.yml - Coding standards |
| 321 | - path: .github/instructions/hve-core/markdown.instructions.md |
| 322 | kind: instruction |
| 323 | |
| 324 | # In collections/hve-core.collection.yml - Core workflow |
| 325 | - path: .github/agents/hve-core/rpi-agent.agent.md |
| 326 | kind: agent |
| 327 | ``` |
| 328 | |
| 329 | ### Selecting Collections for New Artifacts |
| 330 | |
| 331 | Answer these questions when determining collection assignments: |
| 332 | |
| 333 | 1. **Who is the primary user?** Identify the main role that benefits from this artifact |
| 334 | 2. **Who else benefits?** Consider secondary roles that may find value |
| 335 | 3. **Is it foundational?** Core workflow artifacts should include multiple collections |
| 336 | 4. **Is it specialized?** Domain-specific artifacts may target fewer collections |
| 337 | |
| 338 | When in doubt, include `hve-core-all` to ensure the artifact appears in the full collection while still enabling targeted distribution. |
| 339 | |
| 340 | ## Extension Packaging |
| 341 | |
| 342 | Collections are consumed during VS Code Extension packaging to determine which artifacts are included in stable and pre-release extension channels. |
| 343 | |
| 344 | ### Agent Handoff Dependencies |
| 345 | |
| 346 | During VS Code Extension packaging, agent handoff dependencies are automatically resolved to ensure UI navigation buttons work correctly. |
| 347 | |
| 348 | #### How Handoff Resolution Works |
| 349 | |
| 350 | The extension packaging process (`scripts/extension/Prepare-Extension.ps1`) includes the `Resolve-HandoffDependencies` function: |
| 351 | |
| 352 | 1. Seed agents: Starts with agents listed in the collection manifest |
| 353 | 2. Parse frontmatter: Reads the `handoffs` field from each agent's frontmatter |
| 354 | 3. BFS traversal: Performs breadth-first search to find all reachable agents through handoff chains |
| 355 | 4. Include all: Adds all discovered agents to the extension package |
| 356 | |
| 357 | #### Collection Manifests and Dependencies |
| 358 | |
| 359 | **Collection manifests do NOT declare dependencies.** They only specify: |
| 360 | |
| 361 | * `path`: Repository-relative path to the artifact |
| 362 | * `kind`: Artifact type (agent, prompt, instruction, skill, hook) |
| 363 | * `maturity`: Release readiness level (optional, defaults to stable) |
| 364 | |
| 365 | Dependencies are resolved through agent frontmatter `handoffs` declarations during extension packaging, not through collection manifest fields. |
| 366 | |
| 367 | #### Creating Artifacts with Dependencies |
| 368 | |
| 369 | When creating artifacts that reference other artifacts: |
| 370 | |
| 371 | | Guideline | Description | |
| 372 | |------------------------|---------------------------------------------------------------------------------| |
| 373 | | Agent handoffs | Use the `handoffs` frontmatter field in agents to declare UI navigation buttons | |
| 374 | | Document relationships | Clearly describe dependencies in artifact documentation | |
| 375 | | Test in isolation | Verify your artifact works when only its collection is installed | |
| 376 | | Keep coupling minimal | Avoid unnecessary dependencies between artifacts | |
| 377 | |
| 378 | For agent handoff configuration details, see [Contributing Custom Agents - Frontmatter Requirements](custom-agents.md#frontmatter-requirements). |
| 379 | |
| 380 | ### Maturity Field Requirements |
| 381 | |
| 382 | Maturity is defined in `collections/*.collection.yml` under `items[].maturity` and MUST NOT appear in artifact frontmatter. |
| 383 | |
| 384 | #### Purpose |
| 385 | |
| 386 | The maturity field controls which extension channel includes the artifact: |
| 387 | |
| 388 | | Channel | Description | |
| 389 | |---------------------|----------------------------------------------------------------| |
| 390 | | Stable channel | Only artifacts with `maturity: stable` | |
| 391 | | Pre-release channel | Artifacts with `stable`, `preview`, or `experimental` maturity | |
| 392 | |
| 393 | #### Valid Values |
| 394 | |
| 395 | | Value | Description | Stable Channel | Pre-release Channel | |
| 396 | |----------------|---------------------------------------------|----------------|---------------------| |
| 397 | | `stable` | Production-ready, fully tested | ✅ Included | ✅ Included | |
| 398 | | `preview` | Feature-complete, may have rough edges | ❌ Excluded | ✅ Included | |
| 399 | | `experimental` | Early development, may change significantly | ❌ Excluded | ✅ Included | |
| 400 | | `deprecated` | Scheduled for removal | ❌ Excluded | ❌ Excluded | |
| 401 | |
| 402 | When `items[].maturity` is omitted, the effective maturity defaults to `stable`. |
| 403 | |
| 404 | #### Default for New Contributions |
| 405 | |
| 406 | New collection items **SHOULD** use `maturity: stable` unless: |
| 407 | |
| 408 | * The artifact is a proof-of-concept or experimental feature |
| 409 | * The artifact requires additional testing or feedback before wide release |
| 410 | * The contributor explicitly intends to target early adopters |
| 411 | |
| 412 | #### Setting Maturity |
| 413 | |
| 414 | Add or update the maturity value on each collection item in `collections/*.collection.yml`: |
| 415 | |
| 416 | ```yaml |
| 417 | items: |
| 418 | # path can reference artifacts from any subfolder |
| 419 | - path: .github/agents/{collection-id}/example.agent.md |
| 420 | kind: agent |
| 421 | maturity: stable |
| 422 | ``` |
| 423 | |
| 424 | For detailed channel and lifecycle information, see [Release Process - Extension Channels](release-process.md#extension-channels-and-maturity). |
| 425 | |
| 426 | 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. |
| 427 | |
| 428 | ## Plugin Generation |
| 429 | |
| 430 | The `plugins/` directory contains **auto-generated plugin bundles** created from collection manifests for use with GitHub Copilot CLI. These plugin directories are outputs of the build process and **MUST NOT be edited directly**. |
| 431 | |
| 432 | ### Generation Workflow |
| 433 | |
| 434 | When you add an artifact to a collection manifest: |
| 435 | |
| 436 | 1. Author artifact: Create your agent, prompt, instruction, or skill in `.github/` |
| 437 | 2. Update collection: Add an `items[]` entry to one or more `collections/*.collection.yml` files |
| 438 | 3. Validate collections: Run `npm run plugin:validate` to check manifest correctness |
| 439 | 4. Generate plugins: Run `npm run plugin:generate` to regenerate all plugin directories |
| 440 | 5. Commit both: Commit the source artifact, collection manifest updates, AND generated plugin outputs together |
| 441 | |
| 442 | ### Plugin Directory Structure |
| 443 | |
| 444 | Each generated plugin directory contains: |
| 445 | |
| 446 | | Content | Description | |
| 447 | |----------------------|----------------------------------------------------------------------------------| |
| 448 | | Symlinked artifacts | Direct symlinks to source files in `.github/` (preserves single source of truth) | |
| 449 | | Generated README | Auto-generated documentation listing all included artifacts | |
| 450 | | Plugin manifest | `plugin.json` file for GitHub Copilot CLI plugin system | |
| 451 | | Marketplace metadata | Aggregated data for extension distribution | |
| 452 | |
| 453 | ### Critical Rules for Plugin Files |
| 454 | |
| 455 | > [!WARNING] |
| 456 | > Files under `plugins/` are generated outputs and MUST NOT be edited directly. |
| 457 | |
| 458 | | Rule | Description | |
| 459 | |--------------------------|----------------------------------------------------------------------------------------| |
| 460 | | Regenerate after changes | Always run `npm run plugin:generate` after modifying collection manifests or artifacts | |
| 461 | | Symlinked files | Markdown artifacts are symlinked, so edits to plugin files modify source artifacts | |
| 462 | | Generated files | README and JSON files are generated fresh on each run | |
| 463 | | Durable edits | Direct edits to plugin files will be overwritten or cause conflicts | |
| 464 | | Source of truth | Always edit the source artifact in `.github/`, not the plugin copy | |
| 465 | |
| 466 | ### When to Regenerate Plugins |
| 467 | |
| 468 | Run `npm run plugin:generate` whenever you: |
| 469 | |
| 470 | * Add a new artifact to a collection manifest |
| 471 | * Remove an artifact from a collection manifest |
| 472 | * Modify artifact frontmatter (description, dependencies, handoffs) |
| 473 | * Update artifact file content that affects generated README documentation |
| 474 | * Change collection manifest metadata (tags, description, name) |
| 475 | * Update the `hve-core-all` collection (auto-updated during generation) |
| 476 | |
| 477 | ### Validating Collection Manifests |
| 478 | |
| 479 | Before generating plugins, validate collection YAML files to catch errors early: |
| 480 | |
| 481 | ```bash |
| 482 | npm run plugin:validate |
| 483 | ``` |
| 484 | |
| 485 | This command checks: |
| 486 | |
| 487 | | Check | Description | |
| 488 | |-----------------------|-------------------------------------------------------------------| |
| 489 | | YAML syntax | Valid YAML structure and formatting | |
| 490 | | Required fields | Presence of `id`, `name`, `description`, `items` | |
| 491 | | Path references | All artifact paths exist and are accessible | |
| 492 | | Kind values | Valid artifact kinds (agent, prompt, instruction, skill, hook) | |
| 493 | | Maturity values | Valid maturity levels (stable, preview, experimental, deprecated) | |
| 494 | | Duplicate paths | No duplicate artifact entries within a collection | |
| 495 | | Root-level exclusions | No repo-specific artifacts from `.github/{type}/` root | |
| 496 | |
| 497 | Always validate before generating plugins: |
| 498 | |
| 499 | ```bash |
| 500 | # Recommended workflow |
| 501 | npm run plugin:validate # Validate collections first |
| 502 | npm run plugin:generate # Then regenerate plugins |
| 503 | ``` |
| 504 | |
| 505 | Validation errors will prevent successful plugin generation, so fixing validation issues first saves time and prevents incomplete plugin outputs. |
| 506 | |
| 507 | ### Plugin Generation Reference |
| 508 | |
| 509 | For detailed documentation on the plugin generation system, including: |
| 510 | |
| 511 | * Generation script implementation details |
| 512 | * Collection validation rules |
| 513 | * Plugin directory structure specifications |
| 514 | * Troubleshooting generation errors |
| 515 | |
| 516 | See the [Plugin Scripts README](https://github.com/microsoft/hve-core/blob/main/scripts/plugins/README.md). |
| 517 | |
| 518 | ## XML-Style Block Standards |
| 519 | |
| 520 | All AI artifacts use XML-style HTML comment blocks to wrap examples, schemas, templates, and critical instructions. This enables automated extraction, better navigation, and consistency. |
| 521 | |
| 522 | ### Requirements |
| 523 | |
| 524 | | Rule | Description | |
| 525 | |----------------------|-----------------------------------------------------------------------| |
| 526 | | Tag naming | Use kebab-case (e.g., `<!-- <example-valid-frontmatter> -->`) | |
| 527 | | Matching pairs | Opening and closing tags MUST match exactly | |
| 528 | | Unique names | Each tag name MUST be unique within the file (no duplicates) | |
| 529 | | Code fence placement | Place code fences inside blocks, never outside | |
| 530 | | Nested blocks | Use 4-backtick outer fence when demonstrating blocks with code fences | |
| 531 | | Single lines | Opening and closing tags on their own lines | |
| 532 | |
| 533 | ### Valid XML-Style Block Structure |
| 534 | |
| 535 | ````markdown |
| 536 | <!-- <example-configuration> --> |
| 537 | ```json |
| 538 | { |
| 539 | "enabled": true, |
| 540 | "timeout": 30 |
| 541 | } |
| 542 | ``` |
| 543 | <!-- </example-configuration> --> |
| 544 | ```` |
| 545 | |
| 546 | ### Demonstrating Blocks with Nested Fences |
| 547 | |
| 548 | When showing examples that contain XML blocks with code fences, use 4-backtick outer fence: |
| 549 | |
| 550 | `````markdown |
| 551 | ````markdown |
| 552 | <!-- <example-bash-script> --> |
| 553 | ```bash |
| 554 | #!/bin/bash |
| 555 | echo "Hello World" |
| 556 | ``` |
| 557 | <!-- </example-bash-script> --> |
| 558 | ```` |
| 559 | ````` |
| 560 | |
| 561 | ### Common Tag Patterns |
| 562 | |
| 563 | * `<!-- <example-*> -->` - Code examples |
| 564 | * `<!-- <schema-*> -->` - Schema definitions |
| 565 | * `<!-- <pattern-*> -->` - Coding patterns |
| 566 | * `<!-- <convention-*> -->` - Convention blocks |
| 567 | * `<!-- <anti-pattern-*> -->` - Things to avoid |
| 568 | * `<!-- <reference-sources> -->` - External documentation links |
| 569 | * `<!-- <validation-checklist> -->` - Validation steps |
| 570 | * `<!-- <file-structure> -->` - File organization |
| 571 | |
| 572 | ### Common XML Block Issues |
| 573 | |
| 574 | #### Missing Closing Tag |
| 575 | |
| 576 | XML-style comment blocks opened but never closed. Always include matching closing tags `<!-- </block-name> -->` for all opened blocks. |
| 577 | |
| 578 | #### Duplicate Tag Names |
| 579 | |
| 580 | Using the same XML block tag name multiple times in a file. Make each tag name unique (e.g., `<example-python-function>` and `<example-bash-script>` instead of multiple `<example-code>` blocks). |
| 581 | |
| 582 | ## Markdown Quality Standards |
| 583 | |
| 584 | All AI artifacts MUST follow these markdown quality requirements: |
| 585 | |
| 586 | ### Heading Hierarchy |
| 587 | |
| 588 | * Start with H1 title |
| 589 | * No skipped levels (H1 → H2 → H3, not H1 → H3) |
| 590 | * Use H1 for document title only |
| 591 | * Use H2 for major sections, H3 for subsections |
| 592 | |
| 593 | ### Code Blocks |
| 594 | |
| 595 | * All code blocks MUST have language tags |
| 596 | * Use proper language identifiers: `bash`, `python`, `json`, `yaml`, `markdown`, `text`, `plaintext` |
| 597 | * No naked code blocks without language specification |
| 598 | |
| 599 | ❌ Bad: |
| 600 | |
| 601 | ````markdown |
| 602 | ``` |
| 603 | code without language tag |
| 604 | ``` |
| 605 | ```` |
| 606 | |
| 607 | ✅ Good: |
| 608 | |
| 609 | ````markdown |
| 610 | ```python |
| 611 | def example(): pass |
| 612 | ``` |
| 613 | ```` |
| 614 | |
| 615 | ### URL Formatting |
| 616 | |
| 617 | * No bare URLs in prose |
| 618 | * Wrap in angle brackets: `<https://example.com>` |
| 619 | * Use markdown links: `[text](https://example.com)` |
| 620 | |
| 621 | ❌ Bad: |
| 622 | |
| 623 | ```markdown |
| 624 | See https://example.com for details. |
| 625 | ``` |
| 626 | |
| 627 | ✅ Good: |
| 628 | |
| 629 | ```markdown |
| 630 | See <https://example.com> for details. |
| 631 | # OR |
| 632 | See [official documentation](https://example.com) for details. |
| 633 | ``` |
| 634 | |
| 635 | ### List Formatting |
| 636 | |
| 637 | * Use consistent list markers (prefer `*` for bullets) |
| 638 | * Use `-` for nested lists or alternatives |
| 639 | * Numbered lists use `1.`, `2.`, `3.` etc. |
| 640 | |
| 641 | ### Line Length |
| 642 | |
| 643 | * Target ~500 characters per line |
| 644 | * Exceptions: code blocks, tables, URLs, long technical terms |
| 645 | * Not a hard limit, but improves readability |
| 646 | |
| 647 | ### Whitespace |
| 648 | |
| 649 | * No hard tabs (use spaces) |
| 650 | * No trailing whitespace (except 2 spaces for intentional line breaks) |
| 651 | * File ends with single newline character |
| 652 | |
| 653 | ### File Structure |
| 654 | |
| 655 | * Starts with frontmatter (YAML between `---` delimiters) |
| 656 | * Followed by markdown content |
| 657 | * Includes attribution in frontmatter `description` field |
| 658 | * Single newline at EOF |
| 659 | |
| 660 | ## RFC 2119 Directive Language |
| 661 | |
| 662 | Use standardized keywords for clarity and enforceability: |
| 663 | |
| 664 | ### Required Behavior |
| 665 | |
| 666 | MUST, WILL, MANDATORY, REQUIRED, and CRITICAL indicate absolute requirements. Non-compliance is a defect. |
| 667 | |
| 668 | #### Example: Required Behavior |
| 669 | |
| 670 | ```markdown |
| 671 | All functions MUST include type hints for parameters and return values. |
| 672 | You WILL validate frontmatter before proceeding (MANDATORY). |
| 673 | ``` |
| 674 | |
| 675 | ### Strong Recommendations |
| 676 | |
| 677 | SHOULD and RECOMMENDED indicate best practices. Valid reasons may exist for exceptions, but non-compliance requires justification. |
| 678 | |
| 679 | #### Example: Strong Recommendations |
| 680 | |
| 681 | ```markdown |
| 682 | Examples SHOULD be wrapped in XML-style blocks for reusability. |
| 683 | Functions SHOULD include docstrings with parameter descriptions. |
| 684 | ``` |
| 685 | |
| 686 | ### Optional/Permitted |
| 687 | |
| 688 | MAY, OPTIONAL, and CAN indicate permitted but not required behavior. The choice is left to the implementer. |
| 689 | |
| 690 | #### Example: Optional Behavior |
| 691 | |
| 692 | ```markdown |
| 693 | You MAY include version fields in frontmatter. |
| 694 | Contributors CAN organize examples by complexity level. |
| 695 | ``` |
| 696 | |
| 697 | ### Avoid Ambiguous Language |
| 698 | |
| 699 | ❌ Ambiguous (Never Use): |
| 700 | |
| 701 | ```markdown |
| 702 | You might want to validate the input... |
| 703 | It could be helpful to add docstrings... |
| 704 | Perhaps consider wrapping examples... |
| 705 | Try to follow the pattern... |
| 706 | Maybe include tests... |
| 707 | ``` |
| 708 | |
| 709 | ✅ Clear (Always Use): |
| 710 | |
| 711 | ```markdown |
| 712 | You MUST validate all input before processing. |
| 713 | Functions SHOULD include docstrings. |
| 714 | Examples SHOULD be wrapped in XML-style blocks. |
| 715 | You MAY include additional examples. |
| 716 | ``` |
| 717 | |
| 718 | ## Common Validation Standards |
| 719 | |
| 720 | All AI artifacts are validated using these automated tools: |
| 721 | |
| 722 | ### Validation Commands |
| 723 | |
| 724 | Run these commands before submitting: |
| 725 | |
| 726 | ```bash |
| 727 | # Validate frontmatter against schemas |
| 728 | npm run lint:frontmatter |
| 729 | |
| 730 | # Check markdown quality |
| 731 | npm run lint:md |
| 732 | |
| 733 | # Spell check |
| 734 | npm run spell-check |
| 735 | |
| 736 | # Validate all links |
| 737 | npm run lint:md-links |
| 738 | |
| 739 | # Validate model references in agent/prompt frontmatter |
| 740 | npm run lint:models |
| 741 | |
| 742 | # PowerShell analysis (if applicable) |
| 743 | npm run lint:ps |
| 744 | |
| 745 | # Validate skill structure (if applicable) |
| 746 | npm run validate:skills |
| 747 | ``` |
| 748 | |
| 749 | ### Quality Gates |
| 750 | |
| 751 | All submissions MUST pass: |
| 752 | |
| 753 | | Gate | Description | |
| 754 | |--------------------|---------------------------------------------| |
| 755 | | Frontmatter Schema | Valid YAML with required fields | |
| 756 | | Markdown Linting | No markdown rule violations | |
| 757 | | Spell Check | No spelling errors (or added to dictionary) | |
| 758 | | Link Validation | All links accessible and valid | |
| 759 | | File Format | Correct fences and structure | |
| 760 | |
| 761 | ### Validation Checklist Template |
| 762 | |
| 763 | Use this checklist structure in type-specific guides: |
| 764 | |
| 765 | ```markdown |
| 766 | ### Validation Checklist |
| 767 | |
| 768 | #### Frontmatter |
| 769 | - [ ] Valid YAML between `---` delimiters |
| 770 | - [ ] All required fields present and valid |
| 771 | - [ ] No trailing whitespace |
| 772 | - [ ] Single newline at EOF |
| 773 | |
| 774 | #### Markdown Quality |
| 775 | - [ ] Heading hierarchy correct |
| 776 | - [ ] Code blocks have language tags |
| 777 | - [ ] No bare URLs |
| 778 | - [ ] Consistent list markers |
| 779 | |
| 780 | #### XML-Style Blocks |
| 781 | - [ ] All blocks closed properly |
| 782 | - [ ] Unique tag names |
| 783 | - [ ] Code fences inside blocks |
| 784 | |
| 785 | #### Technical |
| 786 | - [ ] File references valid |
| 787 | - [ ] External links accessible |
| 788 | - [ ] No conflicts with existing files |
| 789 | ``` |
| 790 | |
| 791 | ## Common Testing Practices |
| 792 | |
| 793 | Before submitting any AI artifact: |
| 794 | |
| 795 | ### 1. Manual Testing |
| 796 | |
| 797 | * Execute the artifact manually with realistic scenarios |
| 798 | * Verify outputs match expectations |
| 799 | * Check edge cases (missing data, invalid inputs, errors) |
| 800 | |
| 801 | ### 2. Example Verification |
| 802 | |
| 803 | * All code examples are syntactically correct |
| 804 | * Examples run without errors |
| 805 | * Examples demonstrate intended patterns |
| 806 | |
| 807 | ### 3. Tool Validation |
| 808 | |
| 809 | * Specified tools/commands exist and work |
| 810 | * Tool outputs match documentation |
| 811 | * Error messages are clear |
| 812 | |
| 813 | ### 4. Documentation Review |
| 814 | |
| 815 | * All sections complete and coherent |
| 816 | * Cross-references valid |
| 817 | * No contradictory guidance |
| 818 | |
| 819 | ## Common Issues and Fixes |
| 820 | |
| 821 | ### Ambiguous Directives |
| 822 | |
| 823 | Using vague, non-committal language that doesn't clearly indicate requirements. Use RFC 2119 keywords (MUST, SHOULD, MAY) to specify clear requirements. |
| 824 | |
| 825 | ### Missing XML Block Closures |
| 826 | |
| 827 | XML-style comment blocks opened but never closed. Always include matching closing tags for all XML-style comment blocks. |
| 828 | |
| 829 | ### Code Blocks Without Language Tags |
| 830 | |
| 831 | Code blocks missing language identifiers for syntax highlighting. Always specify the language for code blocks (python, bash, json, yaml, markdown, text, plaintext). |
| 832 | |
| 833 | ### Bare URLs |
| 834 | |
| 835 | URLs placed directly in text without proper markdown formatting. Wrap URLs in angle brackets `<https://example.com>` or use proper markdown link syntax `[text](url.md)`. |
| 836 | |
| 837 | ### Inconsistent List Markers |
| 838 | |
| 839 | Mixing different bullet point markers (\* and -) in the same list. Use consistent markers throughout (prefer \* for bullets, - for nested or alternatives). |
| 840 | |
| 841 | ### Trailing Whitespace |
| 842 | |
| 843 | Extra spaces at the end of lines (except intentional 2-space line breaks). Remove all trailing whitespace from lines. |
| 844 | |
| 845 | ### Skipped Heading Levels |
| 846 | |
| 847 | Jumping from H1 to H3 without an H2, breaking document hierarchy. Follow proper heading sequence (H1 → H2 → H3) without skipping levels. |
| 848 | |
| 849 | ## Attribution Requirements |
| 850 | |
| 851 | All AI artifacts MUST include attribution as a suffix in the frontmatter `description` field: |
| 852 | |
| 853 | ```yaml |
| 854 | description: 'Tests prompt files in a sandbox environment - Brought to you by microsoft/hve-core' |
| 855 | ``` |
| 856 | |
| 857 | Format: `- Brought to you by organization/repository-name` appended to the description value. |
| 858 | |
| 859 | Skill files (`SKILL.md`) additionally include a blockquote attribution footer as the last line of body content: |
| 860 | |
| 861 | ```markdown |
| 862 | > Brought to you by microsoft/hve-core |
| 863 | ``` |
| 864 | |
| 865 | ## GitHub Issue Title Conventions |
| 866 | |
| 867 | When filing issues against hve-core, use Conventional Commit-style title prefixes that match the repository's commit message format. |
| 868 | |
| 869 | ### Issue Title Format |
| 870 | |
| 871 | | Issue Type | Title Prefix | Example | |
| 872 | |----------------------|-----------------------|-------------------------------------------------| |
| 873 | | Bug reports | `fix:` | `fix: validation script fails on Windows paths` | |
| 874 | | Agent requests | `feat(agents):` | `feat(agents): add Azure cost analysis agent` | |
| 875 | | Prompt requests | `feat(prompts):` | `feat(prompts): add PR description generator` | |
| 876 | | Instruction requests | `feat(instructions):` | `feat(instructions): add Go language standards` | |
| 877 | | Skill requests | `feat(skills):` | `feat(skills): add diagram generation skill` | |
| 878 | | General features | `feat:` | `feat: support multi-root workspaces` | |
| 879 | | Documentation | `docs:` | `docs: clarify installation steps` | |
| 880 | |
| 881 | ### Benefits |
| 882 | |
| 883 | * Issue titles align with commit and PR title conventions |
| 884 | * Automated changelog generation works correctly |
| 885 | * Scopes clearly identify affected artifact categories |
| 886 | * Consistent formatting across all project tracking |
| 887 | |
| 888 | ### Reference |
| 889 | |
| 890 | See [commit-message.instructions.md](https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/commit-message.instructions.md) for the complete list of types and scopes. |
| 891 | |
| 892 | ## Getting Help |
| 893 | |
| 894 | When contributing AI artifacts: |
| 895 | |
| 896 | ### Review Examples |
| 897 | |
| 898 | | Artifact Type | Location | |
| 899 | |---------------|------------------------------------------------------------------------------| |
| 900 | | Agents | Files in `.github/agents/{collection-id}/` (the conventional location) | |
| 901 | | Prompts | Files in `.github/prompts/{collection-id}/` (the conventional location) | |
| 902 | | Instructions | Files in `.github/instructions/{collection-id}/` (the conventional location) | |
| 903 | |
| 904 | ### Check Repository Standards |
| 905 | |
| 906 | * Read `.github/copilot-instructions.md` for repository-wide conventions |
| 907 | * Review existing files in same category for patterns |
| 908 | * Use `prompt-builder.agent.md` agent for guided assistance |
| 909 | |
| 910 | ### Ask Questions |
| 911 | |
| 912 | * Open draft PR and ask in comments |
| 913 | * Reference specific validation errors |
| 914 | * Provide context about your use case |
| 915 | |
| 916 | ### Common Resources |
| 917 | |
| 918 | * [Contributing Custom Agents](custom-agents.md) - Agent configurations |
| 919 | * [Contributing Prompts](prompts.md) - Workflow guidance |
| 920 | * [Contributing Instructions](instructions.md) - Technology standards |
| 921 | * [Pull Request Template](https://github.com/microsoft/hve-core/blob/main/.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist |
| 922 | |
| 923 | --- |
| 924 | |
| 925 | <!-- markdownlint-disable MD036 --> |
| 926 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 927 | then carefully refined by our team of discerning human reviewers.* |
| 928 | <!-- markdownlint-enable MD036 --> |
| 929 | |