microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/contributing/ai-artifacts-common.md
757lines · modecode
| 1 | --- |
| 2 | title: 'AI Artifacts Common Standards' |
| 3 | description: 'Common standards and quality gates for all AI artifact contributions to hve-core' |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-11-26 |
| 6 | ms.topic: reference |
| 7 | --- |
| 8 | |
| 9 | This document defines shared standards, conventions, and quality gates that apply to **all** AI artifact contributions to hve-core (agents, prompts, and instructions files). |
| 10 | |
| 11 | ## Agents Not Accepted |
| 12 | |
| 13 | The following agent types will likely be **rejected or closed automatically** because **equivalent agents already exist in hve-core**: |
| 14 | |
| 15 | ### Duplicate Agent Categories |
| 16 | |
| 17 | * **Research or Discovery Agents**: Agents that search for, gather, or discover information |
| 18 | * ❌ Reason: Existing agents already handle research and discovery workflows |
| 19 | * ✅ Alternative: Use existing research-focused agents in `.github/agents/` |
| 20 | |
| 21 | * **Indexing or Referencing Agents**: Agents that catalog, index, or create references to existing projects |
| 22 | * ❌ Reason: Existing agents already provide indexing and referencing capabilities |
| 23 | * ❌ 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 |
| 24 | * ✅ Alternative: Use existing reference management agents that leverage standard VS Code GitHub Copilot tools and widely-adopted MCP tools |
| 25 | |
| 26 | * **Planning Agents**: Agents that plan work, break down tasks, or organize backlog items |
| 27 | * ❌ Reason: Existing agents already handle work planning and task organization |
| 28 | * ✅ Alternative: Use existing planning-focused agents in `.github/agents/` |
| 29 | |
| 30 | * **Implementation Agents**: General-purpose coding agents that implement features |
| 31 | * ❌ Reason: Existing agents already provide implementation guidance |
| 32 | * ✅ Alternative: Use existing implementation-focused agents |
| 33 | |
| 34 | ### Rationale for Rejection |
| 35 | |
| 36 | These agent types are rejected because: |
| 37 | |
| 38 | 1. **Existing agents are hardened and heavily utilized**: The hve-core library already contains production-tested agents in these categories |
| 39 | 2. **Consistency and maintenance**: Coalescing around existing agents reduces fragmentation and maintenance burden |
| 40 | 3. **Avoid duplication**: Multiple agents serving the same purpose create confusion and divergent behavior |
| 41 | 4. **Standard tooling already integrated**: VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already leveraged by existing agents |
| 42 | |
| 43 | ### Before Submitting |
| 44 | |
| 45 | When planning to submit an agent that falls into these categories: |
| 46 | |
| 47 | 1. **Question necessity**: Does your use case truly require a new agent, or can existing agents meet your needs? |
| 48 | 2. **Review existing agents**: Examine `.github/agents/` to identify agents that already serve your purpose |
| 49 | 3. **Check tool integration**: Verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents |
| 50 | 4. **Consider enhancement over creation**: If existing agents don't fully meet your requirements, evaluate whether your changes are: |
| 51 | * **Generic enough** to benefit all users |
| 52 | * **Valuable enough** to justify modifying the existing agent |
| 53 | 5. **Propose enhancements**: Submit a PR to enhance an existing agent rather than creating a duplicate |
| 54 | |
| 55 | ### What Makes a Good New Agent |
| 56 | |
| 57 | Focus on agents that: |
| 58 | |
| 59 | * **Fill gaps**: Address use cases not covered by existing agents |
| 60 | * **Provide unique value**: Offer specialized domain expertise or workflow patterns not present in the library |
| 61 | * **Are non-overlapping**: Have clearly distinct purposes from existing agents |
| 62 | * **Cannot be merged**: Represent functionality too specialized or divergent to integrate into existing agents |
| 63 | * **Use standard tooling**: Leverage widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations |
| 64 | |
| 65 | ## Model Version Requirements |
| 66 | |
| 67 | All AI artifacts (agents, instructions, prompts) **MUST** target the **latest available models** from Anthropic and OpenAI only. |
| 68 | |
| 69 | ### Accepted Models |
| 70 | |
| 71 | * **Anthropic**: Latest Claude models (e.g., Claude Sonnet 4, Claude Opus 4) |
| 72 | * **OpenAI**: Latest GPT models (e.g., GPT-5, 5.1-COdEX) |
| 73 | |
| 74 | ### Not Accepted |
| 75 | |
| 76 | * ❌ Older model versions (e.g., GPT-4o, Claude 4) |
| 77 | * ❌ Models from other providers |
| 78 | * ❌ Custom or fine-tuned models |
| 79 | * ❌ Deprecated model versions |
| 80 | |
| 81 | ### Rationale |
| 82 | |
| 83 | 1. **Feature parity**: Latest models support the most advanced features and capabilities |
| 84 | 2. **Maintenance burden**: Supporting multiple model versions creates testing and compatibility overhead |
| 85 | 3. **Performance**: Latest models provide superior reasoning, accuracy, and efficiency |
| 86 | 4. **Future-proofing**: Older models will be deprecated and removed from service |
| 87 | |
| 88 | ## Collection Manifests |
| 89 | |
| 90 | Collection manifests in `collections/*.collection.yml` are the source of truth for artifact selection and maturity. |
| 91 | |
| 92 | ### Collection Purpose |
| 93 | |
| 94 | Collection manifests serve three primary functions: |
| 95 | |
| 96 | 1. **Selection**: Determine which artifacts are included in each collection via `items[]` |
| 97 | 2. **Maturity filtering**: Control channel inclusion with `items[].maturity` (defaults to `stable`) |
| 98 | 3. **Packaging inputs**: Provide canonical manifest data used by build and distribution flows |
| 99 | |
| 100 | ### Collection Structure |
| 101 | |
| 102 | Each manifest contains top-level collection metadata and an `items` array: |
| 103 | |
| 104 | ```yaml |
| 105 | id: coding-standards |
| 106 | name: Coding Standards |
| 107 | description: Language-specific coding instructions |
| 108 | tags: |
| 109 | - coding-standards |
| 110 | - bash |
| 111 | - python |
| 112 | items: |
| 113 | - path: .github/instructions/python-script.instructions.md |
| 114 | kind: instruction |
| 115 | maturity: stable |
| 116 | - path: .github/prompts/task-plan.prompt.md |
| 117 | kind: prompt |
| 118 | maturity: preview |
| 119 | ``` |
| 120 | |
| 121 | ### Collection Tags |
| 122 | |
| 123 | Each collection manifest declares a top-level `tags` array for categorization and discoverability. Tags exist **only at the collection level**, not on individual items. |
| 124 | |
| 125 | | Collection | Tags | |
| 126 | |----------------------|-------------------------------------------------------------------------------| |
| 127 | | `hve-core-all` | `hve`, `complete`, `bundle` | |
| 128 | | `ado` | `azure-devops`, `ado`, `work-items`, `builds`, `pull-requests` | |
| 129 | | `coding-standards` | `coding-standards`, `bash`, `bicep`, `csharp`, `python`, `terraform`, `uv` | |
| 130 | | `data-science` | `data`, `jupyter`, `streamlit`, `dashboards`, `visualization`, `data-science` | |
| 131 | | `git` | `git`, `commits`, `merge`, `pull-request` | |
| 132 | | `github` | `github`, `issues`, `backlog`, `triage`, `sprint` | |
| 133 | | `project-planning` | `documentation`, `architecture`, `adr`, `brd`, `prd`, `diagrams`, `planning` | |
| 134 | | `prompt-engineering` | `prompts`, `agents`, `authoring`, `refactoring` | |
| 135 | | `rpi` | `workflow`, `rpi`, `planning`, `research`, `implementation`, `review` | |
| 136 | | `security-planning` | `security`, `incident-response`, `risk`, `planning` | |
| 137 | |
| 138 | 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. |
| 139 | |
| 140 | ### Collection Item Format |
| 141 | |
| 142 | Each `items[]` entry follows this structure: |
| 143 | |
| 144 | ```yaml |
| 145 | - path: .github/agents/rpi-agent.agent.md |
| 146 | kind: agent |
| 147 | maturity: stable |
| 148 | ``` |
| 149 | |
| 150 | | Field | Required | Description | |
| 151 | |------------|----------|--------------------------------------------------------------------------------| |
| 152 | | `path` | Yes | Repository-relative path to the artifact source | |
| 153 | | `kind` | Yes | Artifact type (`agent`, `prompt`, `instruction`, `skill`, or `hook`) | |
| 154 | | `maturity` | No | Release readiness level; when omitted, effective maturity defaults to `stable` | |
| 155 | |
| 156 | ### Adding Artifacts to a Collection |
| 157 | |
| 158 | When contributing a new artifact: |
| 159 | |
| 160 | 1. Create the artifact file in the appropriate directory |
| 161 | 2. Add a matching `items[]` entry in one or more `collections/*.collection.yml` files |
| 162 | 3. Set `maturity` when the artifact should be `preview`, `experimental`, or `deprecated` |
| 163 | 4. Update the collection's `tags` array if your artifact introduces a new technology or domain not yet represented |
| 164 | 5. Run `npm run lint:yaml` to validate manifest syntax and schema compliance |
| 165 | |
| 166 | ### Repo-Specific Instructions Exclusion |
| 167 | |
| 168 | Instructions placed in `.github/instructions/hve-core/` are repo-specific and MUST NOT be added to collection manifests. These files govern internal hve-core repository concerns (CI/CD workflows, repo-specific conventions) that do not apply outside this repository. They are excluded from: |
| 169 | |
| 170 | * Collection manifests |
| 171 | * Extension packaging and distribution |
| 172 | * Collection builds |
| 173 | * Artifact selection for published bundles |
| 174 | |
| 175 | If your instructions apply only to the hve-core repository and are not intended for distribution to consumers, place them in `.github/instructions/hve-core/`. Otherwise, place them in `.github/instructions/` or a technology-specific subdirectory (e.g., `csharp/`, `bash/`). |
| 176 | |
| 177 | ## Collection Taxonomy |
| 178 | |
| 179 | Collections represent role-targeted artifact packages for HVE-Core artifacts. The collection system enables role-specific artifact distribution without fragmenting the codebase. |
| 180 | |
| 181 | ### Defined Collections |
| 182 | |
| 183 | | Collection | Identifier | Description | |
| 184 | |------------------------|----------------------|----------------------------------------------------------------------------------| |
| 185 | | **All** | `hve-core-all` | Full bundle of all stable HVE Core agents, prompts, instructions, and skills | |
| 186 | | **Azure DevOps** | `ado` | Azure DevOps work item management, build monitoring, and pull request creation | |
| 187 | | **Coding Standards** | `coding-standards` | Language-specific coding instructions for bash, Bicep, C#, Python, and Terraform | |
| 188 | | **Data Science** | `data-science` | Data specification generation, Jupyter notebooks, and Streamlit dashboards | |
| 189 | | **Git Workflow** | `git` | Git commit messages, merges, setup, and pull request prompts | |
| 190 | | **GitHub Backlog** | `github` | GitHub issue discovery, triage, sprint planning, and backlog execution | |
| 191 | | **Project Planning** | `project-planning` | PRDs, BRDs, ADRs, architecture diagrams, and documentation operations | |
| 192 | | **Prompt Engineering** | `prompt-engineering` | Tools for analyzing, building, and refactoring prompts, agents, and instructions | |
| 193 | | **RPI Workflow** | `rpi` | Research, Plan, Implement, Review workflow agents and prompts | |
| 194 | | **Security Planning** | `security-planning` | Security plan creation, incident response, and risk assessment | |
| 195 | |
| 196 | ### Collection Assignment Guidelines |
| 197 | |
| 198 | When assigning collections to artifacts: |
| 199 | |
| 200 | * **Universal artifacts** should include `hve-core-all` plus any role-specific collections that particularly benefit |
| 201 | * **Role-specific artifacts** should include only the relevant collections (omit `hve-core-all` for highly specialized artifacts) |
| 202 | * **Cross-cutting tools** like RPI workflow artifacts (`task-researcher`, `task-planner`) should include multiple relevant collections |
| 203 | |
| 204 | **Example collection assignments:** |
| 205 | |
| 206 | Adding an artifact to multiple collections means adding its `items[]` entry in each relevant `collections/*.collection.yml`: |
| 207 | |
| 208 | ```yaml |
| 209 | # In collections/hve-core-all.collection.yml - Universal |
| 210 | - path: .github/instructions/markdown.instructions.md |
| 211 | kind: instruction |
| 212 | |
| 213 | # In collections/coding-standards.collection.yml - Coding standards |
| 214 | - path: .github/instructions/markdown.instructions.md |
| 215 | kind: instruction |
| 216 | |
| 217 | # In collections/rpi.collection.yml - Core workflow |
| 218 | - path: .github/agents/rpi-agent.agent.md |
| 219 | kind: agent |
| 220 | ``` |
| 221 | |
| 222 | ### Selecting Collections for New Artifacts |
| 223 | |
| 224 | Answer these questions when determining collection assignments: |
| 225 | |
| 226 | 1. **Who is the primary user?** Identify the main role that benefits from this artifact |
| 227 | 2. **Who else benefits?** Consider secondary roles that may find value |
| 228 | 3. **Is it foundational?** Core workflow artifacts should include multiple collections |
| 229 | 4. **Is it specialized?** Domain-specific artifacts may target fewer collections |
| 230 | |
| 231 | When in doubt, include `hve-core-all` to ensure the artifact appears in the full collection while still enabling targeted distribution. |
| 232 | |
| 233 | ## Dependency Declarations |
| 234 | |
| 235 | Some artifacts require other artifacts to function correctly. Dependency behavior is resolved during packaging. |
| 236 | |
| 237 | ### Dependency Types |
| 238 | |
| 239 | | Type | Purpose | |
| 240 | |----------------|----------------------------------------------------------------------------------| |
| 241 | | `agents` | Agents this artifact dispatches at runtime via `runSubagent` (excludes handoffs) | |
| 242 | | `prompts` | Prompts this artifact invokes or references | |
| 243 | | `instructions` | Instructions this artifact relies on for code generation | |
| 244 | | `skills` | Skills this artifact executes for specialized tasks | |
| 245 | |
| 246 | > **Note**: Frontmatter `handoffs` (UI buttons that suggest next agents) are resolved dynamically during packaging and MUST NOT be listed in `requires.agents`. Only agents invoked programmatically through `runSubagent` belong here. |
| 247 | |
| 248 | ### Handoff vs Requires Maturity Filtering |
| 249 | |
| 250 | Handoff targets and `requires` dependencies follow different maturity rules during extension packaging: |
| 251 | |
| 252 | | Mechanism | Maturity Filtered | Reason | |
| 253 | |------------|-------------------|---------------------------------------------------------------------------| |
| 254 | | `requires` | Yes | Runtime dependencies are excluded when their maturity exceeds the channel | |
| 255 | | `handoffs` | No | UI buttons must resolve to a valid agent or the button is broken | |
| 256 | |
| 257 | During extension packaging (`scripts/extension/Prepare-Extension.ps1`), the `Resolve-HandoffDependencies` function encounters a handoff target whose maturity falls outside the allowed set and still includes that agent in the package. The maturity check only gates whether the target's own handoffs are traversed further. This ensures that a stable agent handing off to a preview agent produces a functional UI button in both stable and pre-release channels. |
| 258 | |
| 259 | The companion function `Resolve-RequiresDependencies` in the same script applies strict maturity filtering: dependencies whose maturity level is outside the allowed set are excluded entirely. |
| 260 | |
| 261 | ### Declaring Dependencies |
| 262 | |
| 263 | Add the `requires` field to collection items in `collections/*.collection.yml`: |
| 264 | |
| 265 | ```yaml |
| 266 | - path: .github/agents/rpi-agent.agent.md |
| 267 | kind: agent |
| 268 | maturity: stable |
| 269 | requires: |
| 270 | agents: |
| 271 | - task-researcher |
| 272 | - task-planner |
| 273 | - task-implementor |
| 274 | - task-reviewer |
| 275 | prompts: |
| 276 | - task-research |
| 277 | - task-plan |
| 278 | - task-implement |
| 279 | - task-review |
| 280 | ``` |
| 281 | |
| 282 | ### Dependency Resolution |
| 283 | |
| 284 | Dependency resolution currently operates at **build time** during extension packaging. The `Resolve-RequiresDependencies` function in `Prepare-Extension.ps1` walks `requires` blocks to compute the transitive closure of all dependent artifacts across types (agents, prompts, instructions, skills). Similarly, `Resolve-HandoffDependencies` performs BFS traversal of agent handoff declarations to ensure all reachable agents are included in the package. |
| 285 | |
| 286 | For clone-based installations, the installer agent supports **agent-only collection filtering** in Phase 7. Full installer-side dependency resolution (automatically including required prompts, instructions, and skills based on the dependency graph) is planned for a future release. |
| 287 | |
| 288 | ### Dependency Best Practices |
| 289 | |
| 290 | * **Declare all runtime dependencies**: List every artifact your artifact references |
| 291 | * **Prefer explicit over implicit**: Document dependencies even if currently co-located |
| 292 | * **Keep dependencies minimal**: Avoid unnecessary coupling between artifacts |
| 293 | * **Test with minimal installs**: Verify your artifact works with only declared dependencies |
| 294 | |
| 295 | ## Maturity Field Requirements |
| 296 | |
| 297 | Maturity is defined in `collections/*.collection.yml` under `items[].maturity` and MUST NOT appear in artifact frontmatter. |
| 298 | |
| 299 | ### Purpose |
| 300 | |
| 301 | The maturity field controls which extension channel includes the artifact: |
| 302 | |
| 303 | * **Stable channel**: Only artifacts with `maturity: stable` |
| 304 | * **Pre-release channel**: Artifacts with `stable`, `preview`, or `experimental` maturity |
| 305 | |
| 306 | ### Valid Values |
| 307 | |
| 308 | | Value | Description | Stable Channel | Pre-release Channel | |
| 309 | |----------------|---------------------------------------------|----------------|---------------------| |
| 310 | | `stable` | Production-ready, fully tested | ✅ Included | ✅ Included | |
| 311 | | `preview` | Feature-complete, may have rough edges | ❌ Excluded | ✅ Included | |
| 312 | | `experimental` | Early development, may change significantly | ❌ Excluded | ✅ Included | |
| 313 | | `deprecated` | Scheduled for removal | ❌ Excluded | ❌ Excluded | |
| 314 | |
| 315 | When `items[].maturity` is omitted, the effective maturity defaults to `stable`. |
| 316 | |
| 317 | ### Default for New Contributions |
| 318 | |
| 319 | New collection items **SHOULD** use `maturity: stable` unless: |
| 320 | |
| 321 | * The artifact is a proof-of-concept or experimental feature |
| 322 | * The artifact requires additional testing or feedback before wide release |
| 323 | * The contributor explicitly intends to target early adopters |
| 324 | |
| 325 | ### Setting Maturity |
| 326 | |
| 327 | Add or update the maturity value on each collection item in `collections/*.collection.yml`: |
| 328 | |
| 329 | ```yaml |
| 330 | items: |
| 331 | - path: .github/agents/example.agent.md |
| 332 | kind: agent |
| 333 | maturity: stable |
| 334 | ``` |
| 335 | |
| 336 | For detailed channel and lifecycle information, see [Release Process - Extension Channels](release-process.md#extension-channels-and-maturity). |
| 337 | |
| 338 | **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. |
| 339 | |
| 340 | ## XML-Style Block Standards |
| 341 | |
| 342 | 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. |
| 343 | |
| 344 | ### Requirements |
| 345 | |
| 346 | * **Tag naming**: Use kebab-case (e.g., `<!-- <example-valid-frontmatter> -->`) |
| 347 | * **Matching pairs**: Opening and closing tags MUST match exactly |
| 348 | * **Unique names**: Each tag name MUST be unique within the file (no duplicates) |
| 349 | * **Code fence placement**: Place code fences **inside** blocks, never outside |
| 350 | * **Nested blocks**: Use 4-backtick outer fence when demonstrating blocks with code fences |
| 351 | * **Single lines**: Opening and closing tags on their own lines |
| 352 | |
| 353 | ### Valid XML-Style Block Structure |
| 354 | |
| 355 | ````markdown |
| 356 | <!-- <example-configuration> --> |
| 357 | ```json |
| 358 | { |
| 359 | "enabled": true, |
| 360 | "timeout": 30 |
| 361 | } |
| 362 | ``` |
| 363 | <!-- </example-configuration> --> |
| 364 | ```` |
| 365 | |
| 366 | ### Demonstrating Blocks with Nested Fences |
| 367 | |
| 368 | When showing examples that contain XML blocks with code fences, use 4-backtick outer fence: |
| 369 | |
| 370 | `````markdown |
| 371 | ````markdown |
| 372 | <!-- <example-bash-script> --> |
| 373 | ```bash |
| 374 | #!/bin/bash |
| 375 | echo "Hello World" |
| 376 | ``` |
| 377 | <!-- </example-bash-script> --> |
| 378 | ```` |
| 379 | ````` |
| 380 | |
| 381 | ### Common Tag Patterns |
| 382 | |
| 383 | * `<!-- <example-*> -->` - Code examples |
| 384 | * `<!-- <schema-*> -->` - Schema definitions |
| 385 | * `<!-- <pattern-*> -->` - Coding patterns |
| 386 | * `<!-- <convention-*> -->` - Convention blocks |
| 387 | * `<!-- <anti-pattern-*> -->` - Things to avoid |
| 388 | * `<!-- <reference-sources> -->` - External documentation links |
| 389 | * `<!-- <validation-checklist> -->` - Validation steps |
| 390 | * `<!-- <file-structure> -->` - File organization |
| 391 | |
| 392 | ### Common XML Block Issues |
| 393 | |
| 394 | #### Missing Closing Tag |
| 395 | |
| 396 | * **Problem**: XML-style comment blocks opened but never closed |
| 397 | * **Solution**: Always include matching closing tags `<!-- </block-name> -->` for all opened blocks |
| 398 | |
| 399 | #### Duplicate Tag Names |
| 400 | |
| 401 | * **Problem**: Using the same XML block tag name multiple times in a file |
| 402 | * **Solution**: Make each tag name unique (e.g., `<example-python-function>` and `<example-bash-script>` instead of multiple `<example-code>` blocks) |
| 403 | |
| 404 | ## Markdown Quality Standards |
| 405 | |
| 406 | All AI artifacts MUST follow these markdown quality requirements: |
| 407 | |
| 408 | ### Heading Hierarchy |
| 409 | |
| 410 | * Start with H1 title |
| 411 | * No skipped levels (H1 → H2 → H3, not H1 → H3) |
| 412 | * Use H1 for document title only |
| 413 | * Use H2 for major sections, H3 for subsections |
| 414 | |
| 415 | ### Code Blocks |
| 416 | |
| 417 | * All code blocks MUST have language tags |
| 418 | * Use proper language identifiers: `bash`, `python`, `json`, `yaml`, `markdown`, `text`, `plaintext` |
| 419 | * No naked code blocks without language specification |
| 420 | |
| 421 | ❌ **Bad**: |
| 422 | |
| 423 | ````markdown |
| 424 | ``` |
| 425 | code without language tag |
| 426 | ``` |
| 427 | ```` |
| 428 | |
| 429 | ✅ **Good**: |
| 430 | |
| 431 | ````markdown |
| 432 | ```python |
| 433 | def example(): pass |
| 434 | ``` |
| 435 | ```` |
| 436 | |
| 437 | ### URL Formatting |
| 438 | |
| 439 | * No bare URLs in prose |
| 440 | * Wrap in angle brackets: `<https://example.com>` |
| 441 | * Use markdown links: `[text](https://example.com)` |
| 442 | |
| 443 | ❌ **Bad**: |
| 444 | |
| 445 | ```markdown |
| 446 | See https://example.com for details. |
| 447 | ``` |
| 448 | |
| 449 | ✅ **Good**: |
| 450 | |
| 451 | ```markdown |
| 452 | See <https://example.com> for details. |
| 453 | # OR |
| 454 | See [official documentation](https://example.com) for details. |
| 455 | ``` |
| 456 | |
| 457 | ### List Formatting |
| 458 | |
| 459 | * Use consistent list markers (prefer `*` for bullets) |
| 460 | * Use `-` for nested lists or alternatives |
| 461 | * Numbered lists use `1.`, `2.`, `3.` etc. |
| 462 | |
| 463 | ### Line Length |
| 464 | |
| 465 | * Target ~500 characters per line |
| 466 | * Exceptions: code blocks, tables, URLs, long technical terms |
| 467 | * Not a hard limit, but improves readability |
| 468 | |
| 469 | ### Whitespace |
| 470 | |
| 471 | * No hard tabs (use spaces) |
| 472 | * No trailing whitespace (except 2 spaces for intentional line breaks) |
| 473 | * File ends with single newline character |
| 474 | |
| 475 | ### File Structure |
| 476 | |
| 477 | * Starts with frontmatter (YAML between `---` delimiters) |
| 478 | * Followed by markdown content |
| 479 | * Ends with attribution footer |
| 480 | * Single newline at EOF |
| 481 | |
| 482 | ## RFC 2119 Directive Language |
| 483 | |
| 484 | Use standardized keywords for clarity and enforceability: |
| 485 | |
| 486 | ### Required Behavior |
| 487 | |
| 488 | * **MUST** / **WILL** / **MANDATORY** / **REQUIRED** / **CRITICAL** |
| 489 | * Indicates absolute requirement |
| 490 | * Non-compliance is a defect |
| 491 | |
| 492 | **Example**: |
| 493 | |
| 494 | ```markdown |
| 495 | All functions MUST include type hints for parameters and return values. |
| 496 | You WILL validate frontmatter before proceeding (MANDATORY). |
| 497 | ``` |
| 498 | |
| 499 | ### Strong Recommendations |
| 500 | |
| 501 | * **SHOULD** / **RECOMMENDED** |
| 502 | * Indicates best practice |
| 503 | * Valid reasons may exist for exceptions |
| 504 | * Non-compliance requires justification |
| 505 | |
| 506 | **Example**: |
| 507 | |
| 508 | ```markdown |
| 509 | Examples SHOULD be wrapped in XML-style blocks for reusability. |
| 510 | Functions SHOULD include docstrings with parameter descriptions. |
| 511 | ``` |
| 512 | |
| 513 | ### Optional/Permitted |
| 514 | |
| 515 | * **MAY** / **OPTIONAL** / **CAN** |
| 516 | * Indicates permitted but not required |
| 517 | * Implementer choice |
| 518 | |
| 519 | **Example**: |
| 520 | |
| 521 | ```markdown |
| 522 | You MAY include version fields in frontmatter. |
| 523 | Contributors CAN organize examples by complexity level. |
| 524 | ``` |
| 525 | |
| 526 | ### Avoid Ambiguous Language |
| 527 | |
| 528 | ❌ **Ambiguous (Never Use)**: |
| 529 | |
| 530 | ```markdown |
| 531 | You might want to validate the input... |
| 532 | It could be helpful to add docstrings... |
| 533 | Perhaps consider wrapping examples... |
| 534 | Try to follow the pattern... |
| 535 | Maybe include tests... |
| 536 | ``` |
| 537 | |
| 538 | ✅ **Clear (Always Use)**: |
| 539 | |
| 540 | ```markdown |
| 541 | You MUST validate all input before processing. |
| 542 | Functions SHOULD include docstrings. |
| 543 | Examples SHOULD be wrapped in XML-style blocks. |
| 544 | You MAY include additional examples. |
| 545 | ``` |
| 546 | |
| 547 | ## Common Validation Standards |
| 548 | |
| 549 | All AI artifacts are validated using these automated tools: |
| 550 | |
| 551 | ### Validation Commands |
| 552 | |
| 553 | Run these commands before submitting: |
| 554 | |
| 555 | ```bash |
| 556 | # Validate frontmatter against schemas |
| 557 | npm run lint:frontmatter |
| 558 | |
| 559 | # Check markdown quality |
| 560 | npm run lint:md |
| 561 | |
| 562 | # Spell check |
| 563 | npm run spell-check |
| 564 | |
| 565 | # Validate all links |
| 566 | npm run lint:md-links |
| 567 | |
| 568 | # PowerShell analysis (if applicable) |
| 569 | npm run lint:ps |
| 570 | ``` |
| 571 | |
| 572 | ### Quality Gates |
| 573 | |
| 574 | All submissions MUST pass: |
| 575 | |
| 576 | * **Frontmatter Schema**: Valid YAML with required fields |
| 577 | * **Markdown Linting**: No markdown rule violations |
| 578 | * **Spell Check**: No spelling errors (or added to dictionary) |
| 579 | * **Link Validation**: All links accessible and valid |
| 580 | * **File Format**: Correct fences and structure |
| 581 | |
| 582 | ### Validation Checklist Template |
| 583 | |
| 584 | Use this checklist structure in type-specific guides: |
| 585 | |
| 586 | ```markdown |
| 587 | ### Validation Checklist |
| 588 | |
| 589 | #### Frontmatter |
| 590 | - [ ] Valid YAML between `---` delimiters |
| 591 | - [ ] All required fields present and valid |
| 592 | - [ ] No trailing whitespace |
| 593 | - [ ] Single newline at EOF |
| 594 | |
| 595 | #### Markdown Quality |
| 596 | - [ ] Heading hierarchy correct |
| 597 | - [ ] Code blocks have language tags |
| 598 | - [ ] No bare URLs |
| 599 | - [ ] Consistent list markers |
| 600 | |
| 601 | #### XML-Style Blocks |
| 602 | - [ ] All blocks closed properly |
| 603 | - [ ] Unique tag names |
| 604 | - [ ] Code fences inside blocks |
| 605 | |
| 606 | #### Technical |
| 607 | - [ ] File references valid |
| 608 | - [ ] External links accessible |
| 609 | - [ ] No conflicts with existing files |
| 610 | ``` |
| 611 | |
| 612 | ## Common Testing Practices |
| 613 | |
| 614 | Before submitting any AI artifact: |
| 615 | |
| 616 | ### 1. Manual Testing |
| 617 | |
| 618 | * Execute the artifact manually with realistic scenarios |
| 619 | * Verify outputs match expectations |
| 620 | * Check edge cases (missing data, invalid inputs, errors) |
| 621 | |
| 622 | ### 2. Example Verification |
| 623 | |
| 624 | * All code examples are syntactically correct |
| 625 | * Examples run without errors |
| 626 | * Examples demonstrate intended patterns |
| 627 | |
| 628 | ### 3. Tool Validation |
| 629 | |
| 630 | * Specified tools/commands exist and work |
| 631 | * Tool outputs match documentation |
| 632 | * Error messages are clear |
| 633 | |
| 634 | ### 4. Documentation Review |
| 635 | |
| 636 | * All sections complete and coherent |
| 637 | * Cross-references valid |
| 638 | * No contradictory guidance |
| 639 | |
| 640 | ## Common Issues and Fixes |
| 641 | |
| 642 | ### Ambiguous Directives |
| 643 | |
| 644 | * **Problem**: Using vague, non-committal language that doesn't clearly indicate requirements |
| 645 | * **Solution**: Use RFC 2119 keywords (MUST, SHOULD, MAY) to specify clear requirements |
| 646 | |
| 647 | ### Missing XML Block Closures |
| 648 | |
| 649 | * **Problem**: XML-style comment blocks opened but never closed |
| 650 | * **Solution**: Always include matching closing tags for all XML-style comment blocks |
| 651 | |
| 652 | ### Code Blocks Without Language Tags |
| 653 | |
| 654 | * **Problem**: Code blocks missing language identifiers for syntax highlighting |
| 655 | * **Solution**: Always specify the language for code blocks (python, bash, json, yaml, markdown, text, plaintext) |
| 656 | |
| 657 | ### Bare URLs |
| 658 | |
| 659 | * **Problem**: URLs placed directly in text without proper markdown formatting |
| 660 | * **Solution**: Wrap URLs in angle brackets `<https://example.com>` or use proper markdown link syntax `[text](url)` |
| 661 | |
| 662 | ### Inconsistent List Markers |
| 663 | |
| 664 | * **Problem**: Mixing different bullet point markers (* and -) in the same list |
| 665 | * **Solution**: Use consistent markers throughout (prefer * for bullets, - for nested or alternatives) |
| 666 | |
| 667 | ### Trailing Whitespace |
| 668 | |
| 669 | * **Problem**: Extra spaces at the end of lines (except intentional 2-space line breaks) |
| 670 | * **Solution**: Remove all trailing whitespace from lines |
| 671 | |
| 672 | ### Skipped Heading Levels |
| 673 | |
| 674 | * **Problem**: Jumping from H1 to H3 without an H2, breaking document hierarchy |
| 675 | * **Solution**: Follow proper heading sequence (H1 → H2 → H3) without skipping levels |
| 676 | |
| 677 | ## Attribution Requirements |
| 678 | |
| 679 | All AI artifacts MUST include attribution footer at the end: |
| 680 | |
| 681 | ```markdown |
| 682 | --- |
| 683 | |
| 684 | Brought to you by microsoft/hve-core |
| 685 | ``` |
| 686 | |
| 687 | **Placement**: After all content, before final closing fence. |
| 688 | |
| 689 | **Format**: |
| 690 | |
| 691 | * Horizontal rule (`---`) |
| 692 | * Blank line |
| 693 | * Exact text: "Brought to you by microsoft/hve-core" |
| 694 | * Or team-specific: "Brought to you by microsoft/edge-ai" |
| 695 | |
| 696 | ## GitHub Issue Title Conventions |
| 697 | |
| 698 | When filing issues against hve-core, use Conventional Commit-style title prefixes that match the repository's commit message format. |
| 699 | |
| 700 | ### Issue Title Format |
| 701 | |
| 702 | | Issue Type | Title Prefix | Example | |
| 703 | |----------------------|-----------------------|-------------------------------------------------| |
| 704 | | Bug reports | `fix:` | `fix: validation script fails on Windows paths` | |
| 705 | | Agent requests | `feat(agents):` | `feat(agents): add Azure cost analysis agent` | |
| 706 | | Prompt requests | `feat(prompts):` | `feat(prompts): add PR description generator` | |
| 707 | | Instruction requests | `feat(instructions):` | `feat(instructions): add Go language standards` | |
| 708 | | Skill requests | `feat(skills):` | `feat(skills): add diagram generation skill` | |
| 709 | | General features | `feat:` | `feat: support multi-root workspaces` | |
| 710 | | Documentation | `docs:` | `docs: clarify installation steps` | |
| 711 | |
| 712 | ### Benefits |
| 713 | |
| 714 | * Issue titles align with commit and PR title conventions |
| 715 | * Automated changelog generation works correctly |
| 716 | * Scopes clearly identify affected artifact categories |
| 717 | * Consistent formatting across all project tracking |
| 718 | |
| 719 | ### Reference |
| 720 | |
| 721 | See [commit-message.instructions.md](../../.github/instructions/commit-message.instructions.md) for the complete list of types and scopes. |
| 722 | |
| 723 | ## Getting Help |
| 724 | |
| 725 | When contributing AI artifacts: |
| 726 | |
| 727 | ### Review Examples |
| 728 | |
| 729 | * **Agents**: Examine files in `.github/agents/` |
| 730 | * **Prompts**: Examine files in `.github/prompts/` |
| 731 | * **Instructions**: Examine files in `.github/instructions/` |
| 732 | |
| 733 | ### Check Repository Standards |
| 734 | |
| 735 | * Read `.github/copilot-instructions.md` for repository-wide conventions |
| 736 | * Review existing files in same category for patterns |
| 737 | * Use `prompt-builder.agent.md` agent for guided assistance |
| 738 | |
| 739 | ### Ask Questions |
| 740 | |
| 741 | * Open draft PR and ask in comments |
| 742 | * Reference specific validation errors |
| 743 | * Provide context about your use case |
| 744 | |
| 745 | ### Common Resources |
| 746 | |
| 747 | * [Contributing Custom Agents](custom-agents.md) - Agent configurations |
| 748 | * [Contributing Prompts](prompts.md) - Workflow guidance |
| 749 | * [Contributing Instructions](instructions.md) - Technology standards |
| 750 | * [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist |
| 751 | |
| 752 | --- |
| 753 | |
| 754 | <!-- markdownlint-disable MD036 --> |
| 755 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 756 | then carefully refined by our team of discerning human reviewers.* |
| 757 | <!-- markdownlint-enable MD036 --> |
| 758 | |