microsoft/hve-core

Public

mirrored from https://github.com/microsoft/hve-coreAvailable

CodeCommitsIssuesPull requestsActionsInsightsSecurity
hve-core-v2.2.0

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

docs/contributing/ai-artifacts-common.md

547lines · modecode

1---
2title: 'AI Artifacts Common Standards'
3description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
4author: Microsoft
5ms.date: 2025-11-26
6ms.topic: reference
7---
8
9This 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
13The 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
36These agent types are rejected because:
37
381. **Existing agents are hardened and heavily utilized**: The hve-core library already contains production-tested agents in these categories
392. **Consistency and maintenance**: Coalescing around existing agents reduces fragmentation and maintenance burden
403. **Avoid duplication**: Multiple agents serving the same purpose create confusion and divergent behavior
414. **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
45When planning to submit an agent that falls into these categories:
46
471. **Question necessity**: Does your use case truly require a new agent, or can existing agents meet your needs?
482. **Review existing agents**: Examine `.github/agents/` to identify agents that already serve your purpose
493. **Check tool integration**: Verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents
504. **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
535. **Propose enhancements**: Submit a PR to enhance an existing agent rather than creating a duplicate
54
55### What Makes a Good New Agent
56
57Focus 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
67All 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
831. **Feature parity**: Latest models support the most advanced features and capabilities
842. **Maintenance burden**: Supporting multiple model versions creates testing and compatibility overhead
853. **Performance**: Latest models provide superior reasoning, accuracy, and efficiency
864. **Future-proofing**: Older models will be deprecated and removed from service
87
88## Maturity Field Requirements
89
90All AI artifacts (agents, instructions, prompts) **MUST** include a `maturity` field in frontmatter.
91
92### Purpose
93
94The maturity field controls which extension channel includes the artifact:
95
96* **Stable channel**: Only artifacts with `maturity: stable`
97* **Pre-release channel**: Artifacts with `stable`, `preview`, or `experimental` maturity
98
99### Valid Values
100
101| Value | Description | Stable Channel | Pre-release Channel |
102|----------------|---------------------------------------------|----------------|---------------------|
103| `stable` | Production-ready, fully tested | ✅ Included | ✅ Included |
104| `preview` | Feature-complete, may have rough edges | ❌ Excluded | ✅ Included |
105| `experimental` | Early development, may change significantly | ❌ Excluded | ✅ Included |
106| `deprecated` | Scheduled for removal | ❌ Excluded | ❌ Excluded |
107
108### Default for New Contributions
109
110New artifacts **SHOULD** use `maturity: stable` unless:
111
112* The artifact is a proof-of-concept or experimental feature
113* The artifact requires additional testing or feedback before wide release
114* The contributor explicitly intends to target early adopters
115
116### Example
117
118```yaml
119---
120description: 'Specialized agent for security analysis'
121maturity: 'stable'
122tools: ['codebase', 'search']
123---
124```
125
126For detailed channel and lifecycle information, see [Release Process - Extension Channels](release-process.md#extension-channels-and-maturity).
127
128**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.
129
130## XML-Style Block Standards
131
132All AI artifacts use XML-style HTML comment blocks to wrap examples, schemas, templates, and critical instructions. This enables automated extraction, better navigation, and consistency.
133
134### Requirements
135
136* **Tag naming**: Use kebab-case (e.g., `<!-- <example-valid-frontmatter> -->`)
137* **Matching pairs**: Opening and closing tags MUST match exactly
138* **Unique names**: Each tag name MUST be unique within the file (no duplicates)
139* **Code fence placement**: Place code fences **inside** blocks, never outside
140* **Nested blocks**: Use 4-backtick outer fence when demonstrating blocks with code fences
141* **Single lines**: Opening and closing tags on their own lines
142
143### Valid XML-Style Block Structure
144
145````markdown
146<!-- <example-configuration> -->
147```json
148{
149 "enabled": true,
150 "timeout": 30
151}
152```
153<!-- </example-configuration> -->
154````
155
156### Demonstrating Blocks with Nested Fences
157
158When showing examples that contain XML blocks with code fences, use 4-backtick outer fence:
159
160`````markdown
161````markdown
162<!-- <example-bash-script> -->
163```bash
164#!/bin/bash
165echo "Hello World"
166```
167<!-- </example-bash-script> -->
168````
169`````
170
171### Common Tag Patterns
172
173* `<!-- <example-*> -->` - Code examples
174* `<!-- <schema-*> -->` - Schema definitions
175* `<!-- <pattern-*> -->` - Coding patterns
176* `<!-- <convention-*> -->` - Convention blocks
177* `<!-- <anti-pattern-*> -->` - Things to avoid
178* `<!-- <reference-sources> -->` - External documentation links
179* `<!-- <validation-checklist> -->` - Validation steps
180* `<!-- <file-structure> -->` - File organization
181
182### Common XML Block Issues
183
184#### Missing Closing Tag
185
186* **Problem**: XML-style comment blocks opened but never closed
187* **Solution**: Always include matching closing tags `<!-- </block-name> -->` for all opened blocks
188
189#### Duplicate Tag Names
190
191* **Problem**: Using the same XML block tag name multiple times in a file
192* **Solution**: Make each tag name unique (e.g., `<example-python-function>` and `<example-bash-script>` instead of multiple `<example-code>` blocks)
193
194## Markdown Quality Standards
195
196All AI artifacts MUST follow these markdown quality requirements:
197
198### Heading Hierarchy
199
200* Start with H1 title
201* No skipped levels (H1 → H2 → H3, not H1 → H3)
202* Use H1 for document title only
203* Use H2 for major sections, H3 for subsections
204
205### Code Blocks
206
207* All code blocks MUST have language tags
208* Use proper language identifiers: `bash`, `python`, `json`, `yaml`, `markdown`, `text`, `plaintext`
209* No naked code blocks without language specification
210
211❌ **Bad**:
212
213````markdown
214```
215code without language tag
216```
217````
218
219✅ **Good**:
220
221````markdown
222```python
223def example(): pass
224```
225````
226
227### URL Formatting
228
229* No bare URLs in prose
230* Wrap in angle brackets: `<https://example.com>`
231* Use markdown links: `[text](https://example.com)`
232
233❌ **Bad**:
234
235```markdown
236See https://example.com for details.
237```
238
239✅ **Good**:
240
241```markdown
242See <https://example.com> for details.
243# OR
244See [official documentation](https://example.com) for details.
245```
246
247### List Formatting
248
249* Use consistent list markers (prefer `*` for bullets)
250* Use `-` for nested lists or alternatives
251* Numbered lists use `1.`, `2.`, `3.` etc.
252
253### Line Length
254
255* Target ~500 characters per line
256* Exceptions: code blocks, tables, URLs, long technical terms
257* Not a hard limit, but improves readability
258
259### Whitespace
260
261* No hard tabs (use spaces)
262* No trailing whitespace (except 2 spaces for intentional line breaks)
263* File ends with single newline character
264
265### File Structure
266
267* Starts with frontmatter (YAML between `---` delimiters)
268* Followed by markdown content
269* Ends with attribution footer
270* Single newline at EOF
271
272## RFC 2119 Directive Language
273
274Use standardized keywords for clarity and enforceability:
275
276### Required Behavior
277
278* **MUST** / **WILL** / **MANDATORY** / **REQUIRED** / **CRITICAL**
279* Indicates absolute requirement
280* Non-compliance is a defect
281
282**Example**:
283
284```markdown
285All functions MUST include type hints for parameters and return values.
286You WILL validate frontmatter before proceeding (MANDATORY).
287```
288
289### Strong Recommendations
290
291* **SHOULD** / **RECOMMENDED**
292* Indicates best practice
293* Valid reasons may exist for exceptions
294* Non-compliance requires justification
295
296**Example**:
297
298```markdown
299Examples SHOULD be wrapped in XML-style blocks for reusability.
300Functions SHOULD include docstrings with parameter descriptions.
301```
302
303### Optional/Permitted
304
305* **MAY** / **OPTIONAL** / **CAN**
306* Indicates permitted but not required
307* Implementer choice
308
309**Example**:
310
311```markdown
312You MAY include version fields in frontmatter.
313Contributors CAN organize examples by complexity level.
314```
315
316### Avoid Ambiguous Language
317
318❌ **Ambiguous (Never Use)**:
319
320```markdown
321You might want to validate the input...
322It could be helpful to add docstrings...
323Perhaps consider wrapping examples...
324Try to follow the pattern...
325Maybe include tests...
326```
327
328✅ **Clear (Always Use)**:
329
330```markdown
331You MUST validate all input before processing.
332Functions SHOULD include docstrings.
333Examples SHOULD be wrapped in XML-style blocks.
334You MAY include additional examples.
335```
336
337## Common Validation Standards
338
339All AI artifacts are validated using these automated tools:
340
341### Validation Commands
342
343Run these commands before submitting:
344
345```bash
346# Validate frontmatter against schemas
347npm run lint:frontmatter
348
349# Check markdown quality
350npm run lint:md
351
352# Spell check
353npm run spell-check
354
355# Validate all links
356npm run lint:md-links
357
358# PowerShell analysis (if applicable)
359npm run lint:ps
360```
361
362### Quality Gates
363
364All submissions MUST pass:
365
366* **Frontmatter Schema**: Valid YAML with required fields
367* **Markdown Linting**: No markdown rule violations
368* **Spell Check**: No spelling errors (or added to dictionary)
369* **Link Validation**: All links accessible and valid
370* **File Format**: Correct fences and structure
371
372### Validation Checklist Template
373
374Use this checklist structure in type-specific guides:
375
376```markdown
377### Validation Checklist
378
379#### Frontmatter
380- [ ] Valid YAML between `---` delimiters
381- [ ] All required fields present and valid
382- [ ] No trailing whitespace
383- [ ] Single newline at EOF
384
385#### Markdown Quality
386- [ ] Heading hierarchy correct
387- [ ] Code blocks have language tags
388- [ ] No bare URLs
389- [ ] Consistent list markers
390
391#### XML-Style Blocks
392- [ ] All blocks closed properly
393- [ ] Unique tag names
394- [ ] Code fences inside blocks
395
396#### Technical
397- [ ] File references valid
398- [ ] External links accessible
399- [ ] No conflicts with existing files
400```
401
402## Common Testing Practices
403
404Before submitting any AI artifact:
405
406### 1. Manual Testing
407
408* Execute the artifact manually with realistic scenarios
409* Verify outputs match expectations
410* Check edge cases (missing data, invalid inputs, errors)
411
412### 2. Example Verification
413
414* All code examples are syntactically correct
415* Examples run without errors
416* Examples demonstrate intended patterns
417
418### 3. Tool Validation
419
420* Specified tools/commands exist and work
421* Tool outputs match documentation
422* Error messages are clear
423
424### 4. Documentation Review
425
426* All sections complete and coherent
427* Cross-references valid
428* No contradictory guidance
429
430## Common Issues and Fixes
431
432### Ambiguous Directives
433
434* **Problem**: Using vague, non-committal language that doesn't clearly indicate requirements
435* **Solution**: Use RFC 2119 keywords (MUST, SHOULD, MAY) to specify clear requirements
436
437### Missing XML Block Closures
438
439* **Problem**: XML-style comment blocks opened but never closed
440* **Solution**: Always include matching closing tags for all XML-style comment blocks
441
442### Code Blocks Without Language Tags
443
444* **Problem**: Code blocks missing language identifiers for syntax highlighting
445* **Solution**: Always specify the language for code blocks (python, bash, json, yaml, markdown, text, plaintext)
446
447### Bare URLs
448
449* **Problem**: URLs placed directly in text without proper markdown formatting
450* **Solution**: Wrap URLs in angle brackets `<https://example.com>` or use proper markdown link syntax `[text](url)`
451
452### Inconsistent List Markers
453
454* **Problem**: Mixing different bullet point markers (* and -) in the same list
455* **Solution**: Use consistent markers throughout (prefer * for bullets, - for nested or alternatives)
456
457### Trailing Whitespace
458
459* **Problem**: Extra spaces at the end of lines (except intentional 2-space line breaks)
460* **Solution**: Remove all trailing whitespace from lines
461
462### Skipped Heading Levels
463
464* **Problem**: Jumping from H1 to H3 without an H2, breaking document hierarchy
465* **Solution**: Follow proper heading sequence (H1 → H2 → H3) without skipping levels
466
467## Attribution Requirements
468
469All AI artifacts MUST include attribution footer at the end:
470
471```markdown
472---
473
474Brought to you by microsoft/hve-core
475```
476
477**Placement**: After all content, before final closing fence.
478
479**Format**:
480
481* Horizontal rule (`---`)
482* Blank line
483* Exact text: "Brought to you by microsoft/hve-core"
484* Or team-specific: "Brought to you by microsoft/edge-ai"
485
486## GitHub Issue Title Conventions
487
488When filing issues against hve-core, use Conventional Commit-style title prefixes that match the repository's commit message format.
489
490### Issue Title Format
491
492| Issue Type | Title Prefix | Example |
493|----------------------|-----------------------|-------------------------------------------------|
494| Bug reports | `fix:` | `fix: validation script fails on Windows paths` |
495| Agent requests | `feat(agents):` | `feat(agents): add Azure cost analysis agent` |
496| Prompt requests | `feat(prompts):` | `feat(prompts): add PR description generator` |
497| Instruction requests | `feat(instructions):` | `feat(instructions): add Go language standards` |
498| Skill requests | `feat(skills):` | `feat(skills): add diagram generation skill` |
499| General features | `feat:` | `feat: support multi-root workspaces` |
500| Documentation | `docs:` | `docs: clarify installation steps` |
501
502### Benefits
503
504* Issue titles align with commit and PR title conventions
505* Automated changelog generation works correctly
506* Scopes clearly identify affected artifact categories
507* Consistent formatting across all project tracking
508
509### Reference
510
511See [commit-message.instructions.md](../../.github/instructions/commit-message.instructions.md) for the complete list of types and scopes.
512
513## Getting Help
514
515When contributing AI artifacts:
516
517### Review Examples
518
519* **Agents**: Examine files in `.github/agents/`
520* **Prompts**: Examine files in `.github/prompts/`
521* **Instructions**: Examine files in `.github/instructions/`
522
523### Check Repository Standards
524
525* Read `.github/copilot-instructions.md` for repository-wide conventions
526* Review existing files in same category for patterns
527* Use `prompt-builder.agent.md` agent for guided assistance
528
529### Ask Questions
530
531* Open draft PR and ask in comments
532* Reference specific validation errors
533* Provide context about your use case
534
535### Common Resources
536
537* [Contributing Custom Agents](custom-agents.md) - Agent configurations
538* [Contributing Prompts](prompts.md) - Workflow guidance
539* [Contributing Instructions](instructions.md) - Technology standards
540* [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist
541
542---
543
544<!-- markdownlint-disable MD036 -->
545*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
546then carefully refined by our team of discerning human reviewers.*
547<!-- markdownlint-enable MD036 -->
548