microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

b3fcbb5d710029cb4fe91fca91c5ebf46bfb362e

Find a branch or tag

Branches

b3fcbb5d710029cb4fe91fca91c5ebf46bfb362e

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/ai-artifacts-common.md

886lines · modecode

Raw Download

Latest commit unavailable.

unknown

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

microsoft/hve-core

Branches

Tags

Clone