AI Artifacts Common Standards

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

Asset Reference Documentation

Every documentable agent, prompt, instruction, and skill MUST include its paired page under docs/reference/**. Follow the asset reference documentation guide to generate the page, preserve the generator-owned regions, author the usage sections, and satisfy the local and pull request validation gates.

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 use 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 used: 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 used 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 and 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:

Criterion	Description
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	Use 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 models listed in the model catalog (scripts/linting/model-catalog.json). The catalog defines which models are available in GitHub Copilot and which providers are accepted via the providerAllowlist field.

Accepted Models

Any model in the catalog whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references against the catalog.

Not Accepted

• ❌ Models not present in the catalog
• ❌ Models from providers outside the catalog's providerAllowlist
• ❌ Custom or fine-tuned models
• ❌ Models with retiring or retired status

Model Name Format

Model references in frontmatter use the VS Code display name with vendor suffix:

# Single model
model: Claude Haiku 4.5 (copilot)

# Prioritized fallback array (system tries each in order)
model:
  - Claude Haiku 4.5 (copilot)
  - GPT-5.4 mini (copilot)

The (copilot) suffix is required. Run npm run lint:models to validate all model references against the catalog.

Model Selection (Optional)

The model frontmatter property is optional. When omitted, the agent or prompt inherits the user's session model (whatever is selected in the VS Code model picker).

Use explicit model selection for cost optimization:

Tier	Multiplier	Use When	Example Models
Fast	0.25x–0.33x	Read-only research, mechanical file ops, classification	Claude Haiku 4.5, GPT-5.4 mini
Standard	1x	Code generation, architecture, complex synthesis	Claude Sonnet 4.6, GPT-5.4
Premium	3x–15x	Vision-capable tasks, complex architectural decisions	Claude Opus 4.6, GPT-5.5

Cost Tier Constraint

The model property is a preference hint, not a hard constraint. VS Code never fails a prompt or agent invocation due to model unavailability. When a specified model is unavailable or exceeds the cost tier of the parent model, VS Code falls back through the array entries in order, then to the session model (model picker selection).

VS Code enforces that subagent models cannot exceed the cost tier of the parent model. If the user selects Sonnet (standard) in the model picker, subagents can use Haiku (fast) but not Opus (premium). Fallback arrays provide resilience when the preferred model is unavailable or exceeds the cost tier. A single-model string is equally safe: it falls back to the session model when the specified model cannot be used.

Model Catalog Validation

Model references are validated against scripts/linting/model-catalog.json by the lint:models script. A scheduled GitHub Actions workflow (model-validation.yml) runs weekly to detect catalog drift and retiring models.

To refresh the catalog from upstream documentation:

npm run lint:models:refresh

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
5. Cost optimization: fast-tier models reduce consumption for tasks that do not require premium reasoning

Marketplace Packages

.github/plugin/marketplace.json is the sole distribution authority. Its active entries are ordinary, self-contained package recipes. Standard agents, commands, rules, skills, and optional hooks fields declare recipe membership.

An artifact may belong to one or more package recipes when its component maturity is aligned for each membership. x-hve.displayName supplies display metadata, componentMaturity records lifecycle disclosure and tombstones, and documentation points to docs/plugins/<name>.md. The starter profile belongs only to hve-core-all. Root-level repository-only artifacts are not declared.

When an agent handoff targets another catalog-declared agent, shared marketplace closure adds the dependency to the resolved projection. Unresolved or ambiguous targets fail. Run npm run lint:marketplace and npm run docs:generate:check after recipe changes.

Extension Packaging

Plugin and VSIX packaging consume one handoff-resolved projection per catalog entry. Prepare-Extension.ps1 maps canonical sources to VS Code contributions and derives deterministic extension identities. Package-Extension.ps1 stages only git-tracked files from those contribution roots plus explicit shared resources. Hooks remain plugin-only because VS Code has no declarative hook contribution point.

Lifecycle maturity belongs in marketplace metadata, not artifact frontmatter. Stable and PreRelease both include active stable, preview, and experimental components. deprecated and removed values are excluded from both channels. Labels are disclosure and governance metadata, not channel filters or Responsible AI assessment maturity ratings.

Plugin Package Staging

.github/plugin/marketplace.json declares canonical package membership. Temporary plugin bundles are materialized only for explicit package assembly under a caller-supplied absolute staging root outside the repository. Ordinary validation never creates a repository-root plugins/ tree.

Generation Workflow

When you add or change an artifact:

1. Author the artifact under .github/.
2. Add its .github-root-relative canonical path to every applicable catalog entry: agents/*.agent.md, prompts/*.prompt.md, instructions/*.instructions.md, a skills/* directory, or a hooks/*.json manifest.
3. Align component maturity for each declared membership.
4. Update the durable package document at docs/plugins/<name>.md.
5. Run npm run lint:marketplace.
6. Run npm run docs:generate:check and the focused tests for the changed artifact kind.

Package generators derive host-specific outputs from active catalog entries. Commit canonical sources and durable package documentation only.

Plugin Directory Structure

Each generated plugin directory contains:

Content	Description
Materialized artifacts	Regular-file copies of declared, Git-tracked .github/ sources
Generated README	Auto-generated documentation listing all included artifacts
Root plugin manifest	Generated plugin.json for Copilot clients
Shared resources	Declared templates and scripts required by packaged customizations

Critical Rules for Plugin Staging

WARNING

HVE_PLUGIN_STAGING_ROOT or -StagingRoot must name an absolute path outside the repository. Do not create, edit, or commit a repository-root plugins/ directory.

Rule	Description
Validate changes	Run non-mutating marketplace, documentation, and focused test commands
Stage explicitly	Materialize packages only under an external absolute staging root
Generated files	Materialized artifacts, README files, and manifests are generated fresh on each run
Source of truth	Edit .github/ sources, .github/plugin/marketplace.json, or the matching docs/plugins/<name>.md
Repository hygiene	Never create or commit a path under the repository-root plugins/ directory

When to Materialize Plugins

Materialize plugins only when you need to inspect or assemble package output. Supply external staging explicitly:

HVE_PLUGIN_STAGING_ROOT=/absolute/path/outside/hve-core npm run plugin:generate

For ordinary recipe and artifact changes, use npm run plugin:validate and npm run docs:generate:check without materializing packages.

Validating the Marketplace Recipe

Run npm run plugin:validate before package assembly. It validates canonical sources, standard membership, the display name, source containment, the documentation pointer, lifecycle maturity and tombstones, complete active coverage, the starter profile, root manifest mirrors, and handoff closure.

Plugin Generation Reference

For detailed documentation on the plugin generation system, including:

• Generation script implementation details
• Marketplace package validation rules
• Plugin directory structure specifications
• Troubleshooting generation errors

See the Plugin Scripts README.

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

Rule	Description
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

<!-- <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
<!-- <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

XML-style comment blocks opened but never closed. Always include matching closing tags <!-- </block-name> --> for all opened blocks.

Duplicate Tag Names

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

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:

```
code without language tag
```

✅ Good:

```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:

See https://example.com for details.

✅ Good:

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
• Omits any attribution suffix from the description field
• Single newline at EOF

RFC 2119 Directive Language

Use standardized keywords for clarity and enforceability:

Required Behavior

MUST, WILL, MANDATORY, REQUIRED, and CRITICAL indicate absolute requirements. Non-compliance is a defect.

Example: Required Behavior

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

Strong Recommendations

SHOULD and RECOMMENDED indicate best practices. Valid reasons may exist for exceptions, but non-compliance requires justification.

Example: Strong Recommendations

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

Optional/Permitted

MAY, OPTIONAL, and CAN indicate permitted but not required behavior. The choice is left to the implementer.

Example: Optional Behavior

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

Avoid Ambiguous Language

❌ Ambiguous (Never Use):

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):

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:

# 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

# Validate model references in agent/prompt frontmatter
npm run lint:models

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

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

# Scaffold reference pages for new documentable assets
npm run docs:generate

# Validate asset reference pages and AUTO-GENERATED regions
npm run lint:asset-docs

Quality Gates

All submissions MUST pass:

Gate	Description
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:

### 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

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

Missing XML Block Closures

XML-style comment blocks opened but never closed. Always include matching closing tags for all XML-style comment blocks.

Code Blocks Without Language Tags

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

Bare URLs

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

Inconsistent List Markers

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

Trailing Whitespace

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

Skipped Heading Levels

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

Attribution Requirements

Source artifacts carry no attribution suffix or footer. Author description: fields without a trailing attribution string, and do not add a blockquote attribution footer to SKILL.md bodies.

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 for the complete list of types and scopes.

Getting Help

When contributing AI artifacts:

Review Examples

Artifact Type	Location
Agents	Files in .github/agents/{package-id}/ (the conventional location)
Prompts	Files in .github/prompts/{package-id}/ (the conventional location)
Instructions	Files in .github/instructions/{package-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 the hve-builder skill for guided artifact authoring, review, and validation

Ask Questions

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

Common Resources

• Contributing Custom Agents - Agent configurations
• Contributing Prompts - Workflow guidance
• Contributing Instructions - Technology standards
• Pull Request Template - Submission checklist

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.