microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v3.0.2

Find a branch or tag

Branches

hve-core-v3.0.2

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/ai-artifacts-common.md

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

microsoft/hve-core

Branches

Tags

Clone