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