---
title: 'AI Artifacts Common Standards'
description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
author: Microsoft
ms.date: 2025-11-26
ms.topic: reference
---

This document defines shared standards, conventions, and quality gates that apply to **all** AI artifact contributions to hve-core (agents, prompts, and instructions files).

## Agents Not Accepted

The following agent types will likely be **rejected or closed automatically** because **equivalent agents already exist in hve-core**:

### Duplicate Agent Categories

* **Research or Discovery Agents**: Agents that search for, gather, or discover information
  * ❌ Reason: Existing agents already handle research and discovery workflows
  * ✅ Alternative: Use existing research-focused agents in `.github/agents/`

* **Indexing or Referencing Agents**: Agents that catalog, index, or create references to existing projects
  * ❌ Reason: Existing agents already provide indexing and referencing capabilities
  * ❌ 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
  * ✅ Alternative: Use existing reference management agents that leverage standard VS Code GitHub Copilot tools and widely-adopted MCP tools

* **Planning Agents**: Agents that plan work, break down tasks, or organize backlog items
  * ❌ Reason: Existing agents already handle work planning and task organization
  * ✅ Alternative: Use existing planning-focused agents in `.github/agents/`

* **Implementation Agents**: General-purpose coding agents that implement features
  * ❌ Reason: Existing agents already provide implementation guidance
  * ✅ Alternative: Use existing implementation-focused agents

### Rationale for Rejection

These agent types are rejected because:

1. **Existing agents are hardened and heavily utilized**: The hve-core library already contains production-tested agents in these categories
2. **Consistency and maintenance**: Coalescing around existing agents reduces fragmentation and maintenance burden
3. **Avoid duplication**: Multiple agents serving the same purpose create confusion and divergent behavior
4. **Standard tooling already integrated**: VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already leveraged by existing agents

### Before Submitting

When planning to submit an agent that falls into these categories:

1. **Question necessity**: Does your use case truly require a new agent, or can existing agents meet your needs?
2. **Review existing agents**: Examine `.github/agents/` to identify agents that already serve your purpose
3. **Check tool integration**: Verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents
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
   * **Valuable enough** to justify modifying the existing agent
5. **Propose enhancements**: Submit a PR to enhance an existing agent rather than creating a duplicate

### What Makes a Good New Agent

Focus on agents that:

* **Fill gaps**: Address use cases not covered by existing agents
* **Provide unique value**: Offer specialized domain expertise or workflow patterns not present in the library
* **Are non-overlapping**: Have clearly distinct purposes from existing agents
* **Cannot be merged**: Represent functionality too specialized or divergent to integrate into existing agents
* **Use standard tooling**: Leverage widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations

## Model Version Requirements

All AI artifacts (agents, instructions, prompts) **MUST** target the **latest available models** from Anthropic and OpenAI only.

### Accepted Models

* **Anthropic**: Latest Claude models (e.g., Claude Sonnet 4, Claude Opus 4)
* **OpenAI**: Latest GPT models (e.g., GPT-5, 5.1-COdEX)

### Not Accepted

* ❌ Older model versions (e.g., GPT-4o, Claude 4)
* ❌ Models from other providers
* ❌ Custom or fine-tuned models
* ❌ Deprecated model versions

### Rationale

1. **Feature parity**: Latest models support the most advanced features and capabilities
2. **Maintenance burden**: Supporting multiple model versions creates testing and compatibility overhead
3. **Performance**: Latest models provide superior reasoning, accuracy, and efficiency
4. **Future-proofing**: Older models will be deprecated and removed from service

## Collections

Collection manifests in `collections/*.collection.yml` are the source of truth for artifact selection and distribution.

### Collection Purpose

Collection manifests serve three primary functions:

1. **Selection**: Determine which artifacts are included in each collection via `items[]`
2. **Maturity filtering**: Control channel inclusion with `items[].maturity` (defaults to `stable`)
3. **Packaging inputs**: Provide canonical manifest data used by build and distribution flows

### Collection Structure

Each manifest contains top-level collection metadata and an `items` array:

```yaml
id: coding-standards
name: Coding Standards
description: Language-specific coding instructions
tags:
  - coding-standards
  - bash
  - python
items:
  - path: .github/instructions/coding-standards/python-script.instructions.md
    kind: instruction
    maturity: stable
  - path: .github/prompts/hve-core/task-plan.prompt.md
    kind: prompt
    maturity: preview
```

### Collection Tags

Each collection manifest declares a top-level `tags` array for categorization and discoverability. Tags exist **only at the collection level**, not on individual items.

| Collection          | Tags                                                                                 |
|---------------------|--------------------------------------------------------------------------------------|
| `hve-core-all`      | `hve`, `complete`, `bundle`                                                          |
| `ado`               | `azure-devops`, `ado`, `work-items`, `builds`, `pull-requests`                       |
| `coding-standards`  | `coding-standards`, `bash`, `bicep`, `csharp`, `python`, `terraform`, `uv`           |
| `data-science`      | `data`, `jupyter`, `streamlit`, `dashboards`, `visualization`, `data-science`        |
| `design-thinking`   | `design-thinking`, `coaching`, `methodology`, `ux`                                   |
| `experimental`      | `experimental`, `media`, `utilities`                                                 |
| `github`            | `github`, `issues`, `backlog`, `triage`, `sprint`                                    |
| `installer`         | `installer`, `setup`, `onboarding`                                                   |
| `project-planning`  | `documentation`, `architecture`, `adr`, `brd`, `prd`, `diagrams`, `planning`         |
| `hve-core`          | `workflow`, `rpi`, `planning`, `research`, `implementation`, `review`, `code-review` |
| `security-planning` | `security`, `incident-response`, `risk`, `planning`                                  |

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.

### Collection Item Format

Each `items[]` entry follows this structure:

```yaml
- path: .github/agents/hve-core/rpi-agent.agent.md
  kind: agent
  maturity: stable
```

| Field      | Required | Description                                                                    |
|------------|----------|--------------------------------------------------------------------------------|
| `path`     | Yes      | Repository-relative path to the artifact source                                |
| `kind`     | Yes      | Artifact type (`agent`, `prompt`, `instruction`, `skill`, or `hook`)           |
| `maturity` | No       | Release readiness level; when omitted, effective maturity defaults to `stable` |

### Adding Artifacts to a Collection

When contributing a new artifact:

1. Create the artifact file in the appropriate directory
2. Add a matching `items[]` entry in one or more `collections/*.collection.yml` files
3. Set `maturity` when the artifact should be `preview`, `experimental`, or `deprecated`
4. Update the collection's `tags` array if your artifact introduces a new technology or domain not yet represented
5. Run `npm run lint:yaml` to validate manifest syntax and schema compliance
6. Run `npm run plugin:validate` to validate collection manifests
7. Run `npm run plugin:generate` to regenerate plugin directories

### Repo-Specific Artifact Exclusion

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.

### Deprecated Artifact Placement

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.

#### When to Move an Artifact to Deprecated

* A newer artifact fully replaces the existing one
* The artifact is no longer maintained or tested
* The artifact targets a retired platform or workflow

#### How to Deprecate an Artifact

1. Move the file with `git mv` to preserve history: `git mv .github/agents/{collection}/old.agent.md .github/deprecated/agents/old.agent.md`
2. Add a note in the deprecated file's frontmatter or body identifying its replacement
3. Remove the artifact's entry from all `collections/*.collection.yml` files
4. Run `npm run plugin:generate` to regenerate plugin outputs
5. Update any documentation that references the old artifact path

#### Exclusion Scope

Artifacts at the root of `.github/agents/`, `.github/instructions/`, `.github/prompts/`, or `.github/skills/` are excluded from:

* Collection manifests (`collections/*.collection.yml` items)
* Plugin generation (`plugins/` directory contents)
* Extension packaging and distribution
* Collection builds and bundles
* Artifact selection for published releases

#### Validation Enforcement

The plugin generation and validation tooling actively enforces this exclusion:

* Collection validation fails if root-level repo-specific paths appear in `items[]`
* Plugin generation skips root-level artifacts
* Extension packaging filters out these files during build

#### Placement Guidelines

| Scope                       | Location                                                | Included in Plugins |
|-----------------------------|---------------------------------------------------------|---------------------|
| **Repository-specific**     | `.github/instructions/` (root, no subdirectory)         | ❌ No                |
| **Collection-scoped**       | `.github/instructions/{collection-id}/` (by convention) | ✅ Yes               |
| **Language/tech-specific**  | `.github/instructions/coding-standards/{language}/`     | ✅ Yes               |
| **Shared cross-collection** | `.github/instructions/shared/`                          | ✅ Yes               |

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/`.

## Collection Taxonomy

Collections represent role-targeted artifact packages for HVE-Core artifacts. The collection system enables role-specific artifact distribution without fragmenting the codebase.

### Defined Collections

| Collection            | Identifier          | Description                                                                          |
|-----------------------|---------------------|--------------------------------------------------------------------------------------|
| **All**               | `hve-core-all`      | Full bundle of all stable HVE Core agents, prompts, instructions, and skills         |
| **Azure DevOps**      | `ado`               | Azure DevOps work item management, build monitoring, and pull request creation       |
| **Coding Standards**  | `coding-standards`  | Language-specific coding instructions for bash, Bicep, C#, Python, and Terraform     |
| **Data Science**      | `data-science`      | Data specification generation, Jupyter notebooks, and Streamlit dashboards           |
| **Design Thinking**   | `design-thinking`   | Design Thinking coaching identity, quality constraints, and methodology instructions |
| **Experimental**      | `experimental`      | Experimental skills and utilities in early development                               |
| **GitHub Backlog**    | `github`            | GitHub issue discovery, triage, sprint planning, and backlog execution               |
| **Installer**         | `installer`         | HVE Core installation and environment setup                                          |
| **Project Planning**  | `project-planning`  | PRDs, BRDs, ADRs, architecture diagrams, and documentation operations                |
| **HVE Core Workflow** | `hve-core`          | Research, Plan, Implement, Review workflow agents and prompts                        |
| **Security Planning** | `security-planning` | Security plan creation, incident response, and risk assessment                       |

### Collection Assignment Guidelines

When assigning collections to artifacts:

* **Universal artifacts** should include `hve-core-all` plus any role-specific collections that particularly benefit
* **Role-specific artifacts** should include only the relevant collections (omit `hve-core-all` for highly specialized artifacts)
* **Cross-cutting tools** like RPI workflow artifacts (`task-researcher`, `task-planner`) should include multiple relevant collections

**Example collection assignments:**

Adding an artifact to multiple collections means adding its `items[]` entry in each relevant `collections/*.collection.yml`:

```yaml
# In collections/hve-core-all.collection.yml - Universal
- path: .github/instructions/hve-core/markdown.instructions.md
  kind: instruction

# In collections/coding-standards.collection.yml - Coding standards
- path: .github/instructions/hve-core/markdown.instructions.md
  kind: instruction

# In collections/hve-core.collection.yml - Core workflow
- path: .github/agents/hve-core/rpi-agent.agent.md
  kind: agent
```

### Selecting Collections for New Artifacts

Answer these questions when determining collection assignments:

1. **Who is the primary user?** Identify the main role that benefits from this artifact
2. **Who else benefits?** Consider secondary roles that may find value
3. **Is it foundational?** Core workflow artifacts should include multiple collections
4. **Is it specialized?** Domain-specific artifacts may target fewer collections

When in doubt, include `hve-core-all` to ensure the artifact appears in the full collection while still enabling targeted distribution.

## Extension Packaging

Collections are consumed during VS Code Extension packaging to determine which artifacts are included in stable and pre-release extension channels.

### Agent Handoff Dependencies

During VS Code Extension packaging, agent handoff dependencies are automatically resolved to ensure UI navigation buttons work correctly.

#### How Handoff Resolution Works

The extension packaging process (`scripts/extension/Prepare-Extension.ps1`) includes the `Resolve-HandoffDependencies` function:

1. **Seed agents**: Starts with agents listed in the collection manifest
2. **Parse frontmatter**: Reads the `handoffs` field from each agent's frontmatter
3. **BFS traversal**: Performs breadth-first search to find all reachable agents through handoff chains
4. **Include all**: Adds all discovered agents to the extension package

#### Collection Manifests and Dependencies

**Collection manifests do NOT declare dependencies.** They only specify:

* `path`: Repository-relative path to the artifact
* `kind`: Artifact type (agent, prompt, instruction, skill, hook)
* `maturity`: Release readiness level (optional, defaults to stable)

Dependencies are resolved through agent frontmatter `handoffs` declarations during extension packaging, not through collection manifest fields.

#### Creating Artifacts with Dependencies

When creating artifacts that reference other artifacts:

* **Agent handoffs**: Use the `handoffs` frontmatter field in agents to declare UI navigation buttons
* **Document relationships**: Clearly describe dependencies in artifact documentation
* **Test in isolation**: Verify your artifact works when only its collection is installed
* **Keep coupling minimal**: Avoid unnecessary dependencies between artifacts

For agent handoff configuration details, see [Contributing Custom Agents - Frontmatter Requirements](custom-agents.md#frontmatter-requirements).

### Maturity Field Requirements

Maturity is defined in `collections/*.collection.yml` under `items[].maturity` and MUST NOT appear in artifact frontmatter.

#### Purpose

The maturity field controls which extension channel includes the artifact:

* **Stable channel**: Only artifacts with `maturity: stable`
* **Pre-release channel**: Artifacts with `stable`, `preview`, or `experimental` maturity

#### Valid Values

| Value          | Description                                 | Stable Channel | Pre-release Channel |
|----------------|---------------------------------------------|----------------|---------------------|
| `stable`       | Production-ready, fully tested              | ✅ Included     | ✅ Included          |
| `preview`      | Feature-complete, may have rough edges      | ❌ Excluded     | ✅ Included          |
| `experimental` | Early development, may change significantly | ❌ Excluded     | ✅ Included          |
| `deprecated`   | Scheduled for removal                       | ❌ Excluded     | ❌ Excluded          |

When `items[].maturity` is omitted, the effective maturity defaults to `stable`.

#### Default for New Contributions

New collection items **SHOULD** use `maturity: stable` unless:

* The artifact is a proof-of-concept or experimental feature
* The artifact requires additional testing or feedback before wide release
* The contributor explicitly intends to target early adopters

#### Setting Maturity

Add or update the maturity value on each collection item in `collections/*.collection.yml`:

```yaml
items:
  # path can reference artifacts from any subfolder
  - path: .github/agents/{collection-id}/example.agent.md
    kind: agent
    maturity: stable
```

For detailed channel and lifecycle information, see [Release Process - Extension Channels](release-process.md#extension-channels-and-maturity).

**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.

## Plugin Generation

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**.

### Generation Workflow

When you add an artifact to a collection manifest:

1. **Author artifact**: Create your agent, prompt, instruction, or skill in `.github/`
2. **Update collection**: Add an `items[]` entry to one or more `collections/*.collection.yml` files
3. **Validate collections**: Run `npm run plugin:validate` to check manifest correctness
4. **Generate plugins**: Run `npm run plugin:generate` to regenerate all plugin directories
5. **Commit both**: Commit the source artifact, collection manifest updates, AND generated plugin outputs together

### Plugin Directory Structure

Each generated plugin directory contains:

* **Symlinked artifacts**: Direct symlinks to source files in `.github/` (preserves single source of truth)
* **Generated README**: Auto-generated documentation listing all included artifacts
* **Plugin manifest**: `plugin.json` file for GitHub Copilot CLI plugin system
* **Marketplace metadata**: Aggregated data for extension distribution

### Critical Rules for Plugin Files

> [!WARNING]
> Files under `plugins/` are generated outputs and MUST NOT be edited directly.

* **Regenerate after changes**: Always run `npm run plugin:generate` after modifying collection manifests or artifacts
* **Symlinked files**: Markdown artifacts are symlinked, so edits to plugin files modify source artifacts
* **Generated files**: README and JSON files are generated fresh on each run
* **Durable edits**: Direct edits to plugin files will be overwritten or cause conflicts
* **Source of truth**: Always edit the source artifact in `.github/`, not the plugin copy

### When to Regenerate Plugins

Run `npm run plugin:generate` whenever you:

* Add a new artifact to a collection manifest
* Remove an artifact from a collection manifest
* Modify artifact frontmatter (description, dependencies, handoffs)
* Update artifact file content that affects generated README documentation
* Change collection manifest metadata (tags, description, name)
* Update the `hve-core-all` collection (auto-updated during generation)

### Validating Collection Manifests

Before generating plugins, validate collection YAML files to catch errors early:

```bash
npm run plugin:validate
```

This command checks:

* **YAML syntax**: Valid YAML structure and formatting
* **Required fields**: Presence of `id`, `name`, `description`, `items`
* **Path references**: All artifact paths exist and are accessible
* **Kind values**: Valid artifact kinds (agent, prompt, instruction, skill, hook)
* **Maturity values**: Valid maturity levels (stable, preview, experimental, deprecated)
* **Duplicate paths**: No duplicate artifact entries within a collection
* **Root-level exclusions**: No repo-specific artifacts from `.github/{type}/` root

Always validate before generating plugins:

```bash
# Recommended workflow
npm run plugin:validate  # Validate collections first
npm run plugin:generate  # Then regenerate plugins
```

Validation errors will prevent successful plugin generation, so fixing validation issues first saves time and prevents incomplete plugin outputs.

### Plugin Generation Reference

For detailed documentation on the plugin generation system, including:

* Generation script implementation details
* Collection validation rules
* Plugin directory structure specifications
* Troubleshooting generation errors

See the [Plugin Scripts README](../../scripts/plugins/README.md).

## XML-Style Block Standards

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.

### Requirements

* **Tag naming**: Use kebab-case (e.g., `<!-- <example-valid-frontmatter> -->`)
* **Matching pairs**: Opening and closing tags MUST match exactly
* **Unique names**: Each tag name MUST be unique within the file (no duplicates)
* **Code fence placement**: Place code fences **inside** blocks, never outside
* **Nested blocks**: Use 4-backtick outer fence when demonstrating blocks with code fences
* **Single lines**: Opening and closing tags on their own lines

### Valid XML-Style Block Structure

````markdown
<!-- <example-configuration> -->
```json
{
  "enabled": true,
  "timeout": 30
}
```
<!-- </example-configuration> -->
````

### Demonstrating Blocks with Nested Fences

When showing examples that contain XML blocks with code fences, use 4-backtick outer fence:

`````markdown
````markdown
<!-- <example-bash-script> -->
```bash
#!/bin/bash
echo "Hello World"
```
<!-- </example-bash-script> -->
````
`````

### Common Tag Patterns

* `<!-- <example-*> -->` - Code examples
* `<!-- <schema-*> -->` - Schema definitions
* `<!-- <pattern-*> -->` - Coding patterns
* `<!-- <convention-*> -->` - Convention blocks
* `<!-- <anti-pattern-*> -->` - Things to avoid
* `<!-- <reference-sources> -->` - External documentation links
* `<!-- <validation-checklist> -->` - Validation steps
* `<!-- <file-structure> -->` - File organization

### Common XML Block Issues

#### Missing Closing Tag

* **Problem**: XML-style comment blocks opened but never closed
* **Solution**: Always include matching closing tags `<!-- </block-name> -->` for all opened blocks

#### Duplicate Tag Names

* **Problem**: Using the same XML block tag name multiple times in a file
* **Solution**: Make each tag name unique (e.g., `<example-python-function>` and `<example-bash-script>` instead of multiple `<example-code>` blocks)

## Markdown Quality Standards

All AI artifacts MUST follow these markdown quality requirements:

### Heading Hierarchy

* Start with H1 title
* No skipped levels (H1 → H2 → H3, not H1 → H3)
* Use H1 for document title only
* Use H2 for major sections, H3 for subsections

### Code Blocks

* All code blocks MUST have language tags
* Use proper language identifiers: `bash`, `python`, `json`, `yaml`, `markdown`, `text`, `plaintext`
* No naked code blocks without language specification

❌ **Bad**:

````markdown
```
code without language tag
```
````

✅ **Good**:

````markdown
```python
def example(): pass
```
````

### URL Formatting

* No bare URLs in prose
* Wrap in angle brackets: `<https://example.com>`
* Use markdown links: `[text](https://example.com)`

❌ **Bad**:

```markdown
See https://example.com for details.
```

✅ **Good**:

```markdown
See <https://example.com> for details.
# OR
See [official documentation](https://example.com) for details.
```

### List Formatting

* Use consistent list markers (prefer `*` for bullets)
* Use `-` for nested lists or alternatives
* Numbered lists use `1.`, `2.`, `3.` etc.

### Line Length

* Target ~500 characters per line
* Exceptions: code blocks, tables, URLs, long technical terms
* Not a hard limit, but improves readability

### Whitespace

* No hard tabs (use spaces)
* No trailing whitespace (except 2 spaces for intentional line breaks)
* File ends with single newline character

### File Structure

* Starts with frontmatter (YAML between `---` delimiters)
* Followed by markdown content
* Ends with attribution footer
* Single newline at EOF

## RFC 2119 Directive Language

Use standardized keywords for clarity and enforceability:

### Required Behavior

* **MUST** / **WILL** / **MANDATORY** / **REQUIRED** / **CRITICAL**
* Indicates absolute requirement
* Non-compliance is a defect

**Example**:

```markdown
All functions MUST include type hints for parameters and return values.
You WILL validate frontmatter before proceeding (MANDATORY).
```

### Strong Recommendations

* **SHOULD** / **RECOMMENDED**
* Indicates best practice
* Valid reasons may exist for exceptions
* Non-compliance requires justification

**Example**:

```markdown
Examples SHOULD be wrapped in XML-style blocks for reusability.
Functions SHOULD include docstrings with parameter descriptions.
```

### Optional/Permitted

* **MAY** / **OPTIONAL** / **CAN**
* Indicates permitted but not required
* Implementer choice

**Example**:

```markdown
You MAY include version fields in frontmatter.
Contributors CAN organize examples by complexity level.
```

### Avoid Ambiguous Language

❌ **Ambiguous (Never Use)**:

```markdown
You might want to validate the input...
It could be helpful to add docstrings...
Perhaps consider wrapping examples...
Try to follow the pattern...
Maybe include tests...
```

✅ **Clear (Always Use)**:

```markdown
You MUST validate all input before processing.
Functions SHOULD include docstrings.
Examples SHOULD be wrapped in XML-style blocks.
You MAY include additional examples.
```

## Common Validation Standards

All AI artifacts are validated using these automated tools:

### Validation Commands

Run these commands before submitting:

```bash
# Validate frontmatter against schemas
npm run lint:frontmatter

# Check markdown quality
npm run lint:md

# Spell check
npm run spell-check

# Validate all links
npm run lint:md-links

# PowerShell analysis (if applicable)
npm run lint:ps

# Validate skill structure (if applicable)
npm run validate:skills
```

### Quality Gates

All submissions MUST pass:

* **Frontmatter Schema**: Valid YAML with required fields
* **Markdown Linting**: No markdown rule violations
* **Spell Check**: No spelling errors (or added to dictionary)
* **Link Validation**: All links accessible and valid
* **File Format**: Correct fences and structure

### Validation Checklist Template

Use this checklist structure in type-specific guides:

```markdown
### Validation Checklist

#### Frontmatter
- [ ] Valid YAML between `---` delimiters
- [ ] All required fields present and valid
- [ ] No trailing whitespace
- [ ] Single newline at EOF

#### Markdown Quality
- [ ] Heading hierarchy correct
- [ ] Code blocks have language tags
- [ ] No bare URLs
- [ ] Consistent list markers

#### XML-Style Blocks
- [ ] All blocks closed properly
- [ ] Unique tag names
- [ ] Code fences inside blocks

#### Technical
- [ ] File references valid
- [ ] External links accessible
- [ ] No conflicts with existing files
```

## Common Testing Practices

Before submitting any AI artifact:

### 1. Manual Testing

* Execute the artifact manually with realistic scenarios
* Verify outputs match expectations
* Check edge cases (missing data, invalid inputs, errors)

### 2. Example Verification

* All code examples are syntactically correct
* Examples run without errors
* Examples demonstrate intended patterns

### 3. Tool Validation

* Specified tools/commands exist and work
* Tool outputs match documentation
* Error messages are clear

### 4. Documentation Review

* All sections complete and coherent
* Cross-references valid
* No contradictory guidance

## Common Issues and Fixes

### Ambiguous Directives

* **Problem**: Using vague, non-committal language that doesn't clearly indicate requirements
* **Solution**: Use RFC 2119 keywords (MUST, SHOULD, MAY) to specify clear requirements

### Missing XML Block Closures

* **Problem**: XML-style comment blocks opened but never closed
* **Solution**: Always include matching closing tags for all XML-style comment blocks

### Code Blocks Without Language Tags

* **Problem**: Code blocks missing language identifiers for syntax highlighting
* **Solution**: Always specify the language for code blocks (python, bash, json, yaml, markdown, text, plaintext)

### Bare URLs

* **Problem**: URLs placed directly in text without proper markdown formatting
* **Solution**: Wrap URLs in angle brackets `<https://example.com>` or use proper markdown link syntax `[text](url)`

### Inconsistent List Markers

* **Problem**: Mixing different bullet point markers (* and -) in the same list
* **Solution**: Use consistent markers throughout (prefer * for bullets, - for nested or alternatives)

### Trailing Whitespace

* **Problem**: Extra spaces at the end of lines (except intentional 2-space line breaks)
* **Solution**: Remove all trailing whitespace from lines

### Skipped Heading Levels

* **Problem**: Jumping from H1 to H3 without an H2, breaking document hierarchy
* **Solution**: Follow proper heading sequence (H1 → H2 → H3) without skipping levels

## Attribution Requirements

All AI artifacts MUST include attribution footer at the end:

```markdown
---

Brought to you by microsoft/hve-core
```

**Placement**: After all content, before final closing fence.

**Format**:

* Horizontal rule (`---`)
* Blank line
* Exact text: "Brought to you by microsoft/hve-core"
* Or team-specific: "Brought to you by microsoft/edge-ai"

## GitHub Issue Title Conventions

When filing issues against hve-core, use Conventional Commit-style title prefixes that match the repository's commit message format.

### Issue Title Format

| Issue Type           | Title Prefix          | Example                                         |
|----------------------|-----------------------|-------------------------------------------------|
| Bug reports          | `fix:`                | `fix: validation script fails on Windows paths` |
| Agent requests       | `feat(agents):`       | `feat(agents): add Azure cost analysis agent`   |
| Prompt requests      | `feat(prompts):`      | `feat(prompts): add PR description generator`   |
| Instruction requests | `feat(instructions):` | `feat(instructions): add Go language standards` |
| Skill requests       | `feat(skills):`       | `feat(skills): add diagram generation skill`    |
| General features     | `feat:`               | `feat: support multi-root workspaces`           |
| Documentation        | `docs:`               | `docs: clarify installation steps`              |

### Benefits

* Issue titles align with commit and PR title conventions
* Automated changelog generation works correctly
* Scopes clearly identify affected artifact categories
* Consistent formatting across all project tracking

### Reference

See [commit-message.instructions.md](../../.github/instructions/hve-core/commit-message.instructions.md) for the complete list of types and scopes.

## Getting Help

When contributing AI artifacts:

### Review Examples

* **Agents**: Examine files in `.github/agents/{collection-id}/` (the conventional location)
* **Prompts**: Examine files in `.github/prompts/{collection-id}/` (the conventional location)
* **Instructions**: Examine files in `.github/instructions/{collection-id}/` (the conventional location)

### Check Repository Standards

* Read `.github/copilot-instructions.md` for repository-wide conventions
* Review existing files in same category for patterns
* Use `prompt-builder.agent.md` agent for guided assistance

### Ask Questions

* Open draft PR and ask in comments
* Reference specific validation errors
* Provide context about your use case

### Common Resources

* [Contributing Custom Agents](custom-agents.md) - Agent configurations
* [Contributing Prompts](prompts.md) - Workflow guidance
* [Contributing Instructions](instructions.md) - Technology standards
* [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist

---

<!-- markdownlint-disable MD036 -->
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
then carefully refined by our team of discerning human reviewers.*
<!-- markdownlint-enable MD036 -->
