microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

d2868d5a528025edc91b39f912e210ed391fd6c1

Find a branch or tag

Branches

d2868d5a528025edc91b39f912e210ed391fd6c1

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/prompts.md

627lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`---`
2	`title: 'Contributing Prompts to HVE Core'`
3	`description: 'Requirements and standards for contributing GitHub Copilot prompt files to hve-core'`
4	`sidebar_position: 4`
5	`author: Microsoft`
6	`ms.date: 2026-03-17`
7	`ms.topic: how-to`
8	`---`
9
10	This guide defines the requirements, standards, and best practices for contributing GitHub Copilot prompt files (`.prompt.md`) to the hve-core library.
11
12	`⚙️ Common Standards: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).`
13
14	`## What is a Prompt?`
15
16	`A prompt is a workflow-specific guidance document that provides context, requirements, and step-by-step instructions for GitHub Copilot to complete a particular task or process. Prompts are typically invoked in specific contexts or workflows.`
17
18	`## Use Cases for Prompts`
19
20	`Create a prompt when you need to:`
21
22	`* Guide a specific workflow or process (e.g., creating pull requests, processing work items)`
23	`* Provide context-sensitive instructions triggered by user actions`
24	`* Define a repeatable task with clear inputs and outputs`
25	`* Document a multi-step procedure for AI execution`
26	`* Establish standards for a particular type of deliverable`
27
28	`## File Structure Requirements`
29
30	`### Location`
31
32	`Prompt files are typically organized in a collection subdirectory by convention:`
33
34	```text
35	`.github/prompts/{collection-id}/`
36	`└── your-prompt-name.prompt.md`
37	```
38
39	`> [!NOTE]`
40	> Collections can reference artifacts from any subfolder. The `path:` field in collection YAML files
41	`> accepts any valid repo-relative path regardless of the artifact's parent directory.`
42
43	`### Naming Convention`
44
45	* Use lowercase kebab-case: `pull-request.prompt.md`
46	* Be specific about workflow/task: `ado-create-pull-request.prompt.md`
47	* Include domain prefix when relevant: `ado-`, `git-`, `github-`
48	* Avoid generic names: `workflow.prompt.md` ❌ → `ado-process-my-work-items-for-task-planning.prompt.md` ✅
49
50	`### File Format`
51
52	`Prompt files MUST:`
53
54	1. Use the `.prompt.md` extension
55	2. Start with valid YAML frontmatter between `---` delimiters
56	`3. Begin content directly after frontmatter`
57	`4. End with single newline character`
58
59	`## Frontmatter Requirements`
60
61	`### Required Fields`
62
63	`description` (string, MANDATORY)
64
65	`\| Property \| Value \|`
66	`\|----------\|--------------------------------------------------------------------------------------------------------------------\|`
67	`\| Purpose \| Concise explanation of prompt purpose and use case \|`
68	`\| Format \| Single sentence, 10-200 characters \|`
69	`\| Style \| Sentence case with proper punctuation \|`
70	\| Example \| `'Required protocol for creating Azure DevOps pull requests with work item discovery and reviewer identification'` \|
71
72	`### Optional Fields`
73
74	`agent` (string)
75
76	`\| Property \| Value \|`
77	`\|----------\|--------------------------------------------------------------------------\|`
78	`\| Purpose \| Delegates execution to a named custom agent \|`
79	\| Format \| Human-readable agent name matching the agent's `name:` frontmatter field \|
80	`\| Style \| Quote the value when the agent name contains spaces \|`
81	\| Example \| `'ADO Backlog Manager'` \|
82
83	`argument-hint` (string)
84
85	`\| Property \| Value \|`
86	`\|----------\|------------------------------------------------------------------------------------------------------------------------------------------------\|`
87	`\| Purpose \| Displays expected inputs in the VS Code prompt picker \|`
88	\| Format \| Brief string; required arguments first, then optional; `[]` for positional, `key=value` for named, `{option1\\|option2}` for enumerated choices \|
89	`\| Style \| Keep hints concise; lead with required arguments \|`
90	\| Example \| `"project=... [type={Epic\\|Feature\\|UserStory\\|Bug\\|Task}] [title=...]"` \|
91
92	`model` (string or array of strings)
93
94	`\| Property \| Value \|`
95	`\|----------\|------------------------------------------------------------------------------------------------\|`
96	`\| Purpose \| Specifies a preferred AI model for prompt invocation (cost optimization) \|`
97	\| Format \| Model display name with `(copilot)` suffix, or prioritized array for fallback \|
98	\| Style \| Use names from `scripts/linting/model-catalog.json`; omit if the session default is acceptable \|
99	\| Example \| `Claude Haiku 4.5 (copilot)` \|
100
101	Use `model` on prompts that perform mechanical operations (git commits, issue creation, file I/O) rather than complex reasoning or code generation.
102
103	The `model` property is a preference hint, not a hard requirement. When the specified model is unavailable or exceeds the user's session model cost tier, VS Code falls back through the array (if specified) then to the session model. A single-model string is safe: it never causes failure. Fallback arrays add resilience when cost-tier constraints may make the primary model unavailable.
104
105	Run `npm run lint:models` to validate model references against the catalog.
106
107	`disable-model-invocation` (boolean)
108
109	`\| Property \| Value \|`
110	`\|----------\|---------------------------------------------------------------------------------------\|`
111	`\| Purpose \| Prevents the prompt from automatically invoking an AI model at start \|`
112	\| Format \| Boolean (`true` or `false`) \|
113	`\| Style \| Use for prompts that gather context or run setup steps before handing off to the user \|`
114	\| Example \| `true` \|
115
116	`mode` (string)
117
118	`\| Property \| Value \|`
119	`\|----------\|------------------------------------------------------------------------------\|`
120	`\| Purpose \| Specifies the invocation context \|`
121	\| Format \| Enumerated string; valid values: `agent`, `assistant`, `copilot`, `workflow` \|
122	`\| Style \| Lowercase \|`
123	\| Example \| `agent` \|
124
125	`category` (string)
126
127	`\| Property \| Value \|`
128	`\|----------\|------------------------------------------------------------------\|`
129	`\| Purpose \| Groups the prompt by topic or domain for organizational purposes \|`
130	`\| Format \| String identifying the domain or topic area \|`
131	\| Style \| Lowercase kebab-case (e.g., `code-review`, `ado`, `git`) \|
132	\| Example \| `code-review` \|
133
134	`version` (string)
135
136	`\| Property \| Value \|`
137	`\|----------\|------------------------------------------------\|`
138	`\| Purpose \| Tracks prompt revisions \|`
139	`\| Format \| Semantic versioning string (MAJOR.MINOR.PATCH) \|`
140	`\| Style \| Quoted string \|`
141	\| Example \| `'1.0.0'` \|
142
143	`author` (string)
144
145	`\| Property \| Value \|`
146	`\|----------\|--------------------------------------\|`
147	`\| Purpose \| Attribution for the prompt creator \|`
148	`\| Format \| Team or repository identifier string \|`
149	\| Style \| Use `org/repo` format or a team name \|
150	\| Example \| `'microsoft/hve-core'` \|
151
152	`lastUpdated` (string)
153
154	`\| Property \| Value \|`
155	`\|----------\|-----------------------------------\|`
156	`\| Purpose \| Timestamp of last modification \|`
157	`\| Format \| ISO 8601 date string (YYYY-MM-DD) \|`
158	`\| Style \| Quoted string \|`
159	\| Example \| `'2026-03-17'` \|
160
161	`### Frontmatter Example`
162
163	```yaml
164	`---`
165	`description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'`
166	`agent: 'ADO Backlog Manager'`
167	`argument-hint: "project-slug=... [type={PR\|Draft}]"`
168	`version: '1.0.0'`
169	`author: 'microsoft/hve-core'`
170	`lastUpdated: '2026-03-17'`
171	`---`
172	```
173
174	`### Input Variables`
175
176	`Prompts can declare input variables that VS Code resolves at invocation time. The syntax is:`
177
178	```text
179	`${input:varName}`
180	`${input:varName:defaultValue}`
181	```
182
183	`Declare variables in an Inputs section and reference them in prompt content:`
184
185	```markdown
186	`## Inputs`
187
188	`* ${input:topic}: (Required) Primary topic or focus area.`
189	`* ${input:scope:all}: (Optional, defaults to all) Scope of the operation.`
190	```
191
192	`Required inputs (no default) are inferred from the user's conversation or attached files when not explicitly supplied.`
193
194	`### Activation Lines`
195
196	Prompts that need to clarify the workflow entry point can include an activation line: a `---` separator followed by an instruction that tells the agent where to begin. Activation lines apply only to prompt files and are omitted when the delegated agent's phases already define the workflow start.
197
198	```markdown
199	`---`
200
201	`Begin by reading the current branch state and identifying open work items.`
202	```
203
204	Prompts that delegate to a custom agent via `agent:` typically omit the activation line because the agent's phases define execution order.
205
206	`## Collection Entry Requirements`
207
208	All prompts must have matching entries in one or more `collections/*.collection.yml` manifests. Collection entries control distribution and maturity.
209
210	`### Adding Your Prompt to a Collection`
211
212	After creating your prompt file, add an `items[]` entry in each target collection manifest:
213
214	```yaml
215	`items:`
216	`# path can reference artifacts from any subfolder`
217	`- path: .github/prompts/{collection-id}/my-prompt.prompt.md`
218	`kind: prompt`
219	`maturity: stable`
220	```
221
222	`### Selecting Collections for Prompts`
223
224	`Choose collections based on who invokes or benefits from the workflow:`
225
226	`\| Prompt Type \| Recommended Collections \|`
227	`\|-------------------------\|-------------------------------------------\|`
228	\| Git/PR workflows \| `hve-core-all`, `hve-core` \|
229	\| ADO work item workflows \| `hve-core-all`, `ado`, `project-planning` \|
230	\| GitHub issue workflows \| `hve-core-all`, `github` \|
231	\| RPI workflow prompts \| `hve-core-all`, `hve-core` \|
232	\| Documentation workflows \| `hve-core-all`, `hve-core` \|
233	\| Architecture prompts \| `hve-core-all`, `project-planning` \|
234
235	`For complete collection documentation, see [AI Artifacts Common Standards - Collection Manifests](ai-artifacts-common.md#collection-manifests-and-dependencies).`
236
237	`## Prompt Content Structure Standards`
238
239	`### Required Sections`
240
241	`#### 1. Title (H1)`
242
243	`* Clear, action-oriented heading describing the workflow`
244	`* Should align with filename and description`
245
246	```markdown
247	`# Azure DevOps Pull Request Creation Protocol`
248	```
249
250	`#### 2. Overview/Purpose`
251
252	`* Explains what the prompt does and when to use it`
253	`* Defines scope and prerequisites`
254	`* Lists expected outcomes`
255
256	```markdown
257	`## Overview`
258
259	`This prompt guides the creation of Azure DevOps pull requests with automated`
260	`work item discovery, reviewer identification, and compliance validation.`
261	```
262
263	`#### 3. Prerequisites/Context`
264
265	`* Lists required information, tools, or setup`
266	`* Specifies environment assumptions`
267	`* Defines input requirements`
268
269	```markdown
270	`## Prerequisites`
271
272	`* Active Azure DevOps connection`
273	`* Current branch with committed changes`
274	`* Work item IDs or branch naming following conventions`
275	```
276
277	`#### 4. Workflow Steps`
278
279	`* Provides clear, numbered steps for execution`
280	`* Uses imperative, unambiguous language`
281	`* Includes decision points and branching logic`
282	`* Specifies tool usage at each step`
283
284	```markdown
285	`## Workflow Steps`
286
287	`1. Discovery Phase: Identify related work items from branch name or commit messages`
288	`2. Reviewer Selection: Query ADO for default reviewers based on repository policies`
289	`3. PR Creation: Generate PR with title, description, and work item links`
290	`4. Validation: Verify PR was created successfully with correct metadata`
291	```
292
293	`#### 5. Success Criteria`
294
295	`* Defines completion conditions`
296	`* Specifies validation checkpoints`
297	`* Lists expected artifacts`
298
299	```markdown
300	`## Success Criteria`
301
302	`* [ ] PR created in target repository`
303	`* [ ] Work items linked to PR`
304	`* [ ] Required reviewers added`
305	`* [ ] PR description follows template`
306	```
307
308	`#### 6. Examples`
309
310	`* Demonstrates correct usage with realistic scenarios`
311	`* Shows input/output patterns`
312	`* Wraps in XML-style blocks for reusability`
313
314	`#### 7. Error Handling`
315
316	`* Documents common failure modes`
317	`* Provides recovery procedures`
318	`* Specifies fallback behaviors`
319
320	`#### 8. Attribution Footer`
321
322	`Always include an attribution footer at the end of the file.`
323
324	```markdown
325	`---`
326
327	`Brought to you by microsoft/hve-core`
328	```
329
330	`### XML-Style Block Requirements`
331
332	`See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.`
333
334	`### Template Variable Standards`
335
336	Use `{{double_curly_braces}}` for placeholders:
337
338	`<!-- <example-template-variables> -->`
339	```yaml
340	`# ✅ CORRECT: Template variables in YAML frontmatter`
341	`---`
342	`title: "{{feature_name}} - {{brief_description}}"`
343	`branch: "feature/{{work_item_id}}-{{task_name}}"`
344	`assignee: "{{user_email}}"`
345	`---`
346
347	`# ❌ INCORRECT: Non-standard variable syntax in YAML frontmatter`
348	`---`
349	`title: "<feature-name> - <brief-description>"`
350	`branch: "feature/<work-item-id>-<task-name>"`
351	`assignee: "<user.email>"`
352	`---`
353	```
354	`<!-- </example-template-variables> -->`
355
356	`#### Variable Naming`
357
358	* Use snake_case: `{{work_item_id}}`, `{{user_name}}`
359	* Be descriptive: `{{target_branch}}` not `{{tb}}`
360	* Group related variables: `{{pr_title}}`, `{{pr_description}}`, `{{pr_labels}}`
361
362	`### Directive Language Standards`
363
364	`Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.`
365
366	`## Workflow Definition Standards`
367
368	`Prompts should clearly define:`
369
370	`### Entry Points`
371
372	`What triggers this prompt:`
373
374	```markdown
375	`## Invocation`
376
377	`This prompt is invoked when:`
378
379	`* User requests "create ADO pull request"`
380	* User runs command: `/prompt ado-create-pull-request`
381	`* Workflow automation reaches PR creation step`
382	```
383
384	`### Decision Points`
385
386	`Where choices affect flow:`
387
388	```markdown
389	`## Decision Logic`
390
391	`If work items found in branch name:`
392	`→ Use those work items for linking`
393
394	`Else if work items in commit messages:`
395	`→ Extract and use those work items`
396
397	`Else:`
398	`→ Prompt user for work item IDs`
399	```
400
401	`### Tool Usage`
402
403	`Which tools are used and when:`
404
405	```markdown
406	`## Required Tools`
407
408	1. `mcp_azure_devops` - Work item queries and PR creation
409	2. `git/*` - Branch and commit information
410	3. `search` - Repository policy lookups
411	```
412
413	`### Output Specifications`
414
415	`What artifacts are produced:`
416
417	```markdown
418	`## Output Artifacts`
419
420	`1. Pull Request: Created in ADO with metadata`
421	2. Handoff Document: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
422	`3. Validation Report: Summary of PR creation status`
423	```
424
425	`## Context Requirements`
426
427	`Prompts SHOULD specify:`
428
429	`### File/Path Contexts`
430
431	`When specific files/paths trigger behavior:`
432
433	```yaml
434	`---`
435	`description: 'Required protocol for creating Azure DevOps pull requests'`
436	`applyTo: '/.copilot-tracking/pr/new/' # Workflow-specific context`
437	`---`
438	```
439
440	`### Data Requirements`
441
442	`What information must be available:`
443
444	```markdown
445	`## Required Context`
446
447	* `{{current_branch}}` - Active git branch name
448	* `{{target_branch}}` - Destination branch (default: main/master)
449	* `{{repository_url}}` - ADO repository URL
450	* `{{user_email}}` - Current user's email for reviewer queries
451	```
452
453	`### State Assumptions`
454
455	`What must be true before execution:`
456
457	```markdown
458	`## Preconditions`
459
460	`* Working directory is a git repository`
461	`* Changes are committed to current branch`
462	`* User has ADO credentials configured`
463	`* Target branch exists in remote repository`
464	```
465
466	`## Output Formatting Requirements`
467
468	`Define how the prompt produces results:`
469
470	`### Response Format`
471
472	`Structure for user-facing output:`
473
474	```markdown
475	`## Output Format`
476
477	`### PR Creation Summary`
478
479	`Status: [Success\|Failed]`
480	`PR ID: [ID]`
481	`PR URL: [URL]`
482	`Work Items Linked: [IDs]`
483	`Reviewers Added: [Names]`
484
485	`### Validation Results`
486
487	`* [x] PR created successfully`
488	`* [x] Work items linked`
489	`* [ ] CI pipeline triggered`
490	```
491
492	`### File Outputs`
493
494	`Specifications for generated files:`
495
496	```markdown
497	`## Handoff Document Format`
498
499	File: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
500
501	`Content:`
502
503	`* PR metadata (ID, URL, title)`
504	`* Work item links with status`
505	`* Reviewer assignments`
506	`* Validation checklist`
507	```
508
509	`### Error Reporting`
510
511	`Format for failure scenarios:`
512
513	```markdown
514	`## Error Format`
515
516	`Error Type: [Authentication\|Validation\|Network]`
517	`Message: [Detailed error description]`
518	`Recovery Steps:`
519
520	`1. [Step to resolve]`
521	`2. [Alternative approach]`
522	```
523
524	`## Validation Checklist`
525
526	`Before submitting your prompt, verify:`
527
528	`### Frontmatter`
529
530	* [ ] Valid YAML between `---` delimiters
531	* [ ] `description` field present and descriptive (10-200 chars)
532	* [ ] `mode` field present with valid value
533	* [ ] `category` field appropriate for domain (if present)
534	`* [ ] No trailing whitespace in values`
535	`* [ ] Single newline at EOF`
536
537	`### Content Structure`
538
539	`* [ ] Clear H1 title describing workflow`
540	`* [ ] Overview/purpose section`
541	`* [ ] Maturity set in collection item (see [Common Standards - Maturity](ai-artifacts-common.md#maturity-field-requirements))`
542	`* [ ] Prerequisites or context section`
543	`* [ ] Workflow steps with clear sequence`
544	`* [ ] Success criteria defined`
545	`* [ ] Error handling documented`
546	`* [ ] Attribution footer present`
547
548	`### Workflow Definition`
549
550	`* [ ] Entry points/triggers specified`
551	`* [ ] Decision logic clearly documented`
552	`* [ ] Tool usage requirements listed`
553	`* [ ] Output artifacts defined`
554	`* [ ] State assumptions documented`
555
556	`### Common Standards`
557
558	`* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))`
559	`* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))`
560	`* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))`
561	* [ ] Template variables use `{{snake_case}}`
562
563	`### Technical Validation`
564
565	`* [ ] All file references point to existing files`
566	`* [ ] External links are valid and accessible`
567	`* [ ] Tool references use correct names`
568	`* [ ] Template variables are clearly defined`
569
570	`### Integration`
571
572	* [ ] Aligns with `.github/copilot-instructions.md`
573	`* [ ] Follows repository conventions`
574	`* [ ] Compatible with existing prompts/workflows`
575	`* [ ] Does not duplicate existing prompt functionality`
576
577	`## Testing Your Prompt`
578
579	`See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For prompts specifically:`
580
581	`1. Follow prompt steps manually to verify workflow logic`
582	`2. Test with AI execution using realistic scenarios`
583	`3. Verify all output artifacts match specifications`
584	`4. Test decision points with different data conditions`
585
586	`## Common Issues and Fixes`
587
588	`### Prompt-Specific Issues`
589
590	`### Template Variables with Wrong Format`
591
592	Using incorrect syntax for template variables (angle brackets or shell-style) causes failures. Always use `{{variable_name}}` handlebars format for template variables.
593
594	`### Ambiguous Workflow Steps`
595
596	`Vague workflow steps without specific tools, conditions, or decision logic cause confusion. Provide explicit tool usage, decision trees, and fallback strategies with clear conditional logic.`
597
598	`For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](ai-artifacts-common.md#common-issues-and-fixes).`
599
600	`## Automated Validation`
601
602	`Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):`
603
604	* `npm run lint:frontmatter`
605	* `npm run lint:md`
606	* `npm run spell-check`
607	* `npm run lint:md-links`
608
609	`All checks MUST pass before merge.`
610
611	`## Related Documentation`
612
613	`* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions`
614	`* [Contributing Custom Agents](custom-agents.md) - AI agent configuration files`
615	`* [Contributing Instructions](instructions.md) - Technology-specific standards`
616	`* [Pull Request Template](https://github.com/microsoft/hve-core/blob/main/.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements`
617
618	`## Getting Help`
619
620	See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For prompt-specific assistance, review existing examples in `.github/prompts/{collection-id}/` (the conventional location for prompt files).
621
622	`---`
623
624	`<!-- markdownlint-disable MD036 -->`
625	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
626	`then carefully refined by our team of discerning human reviewers.*`
627	`<!-- markdownlint-enable MD036 -->`
628

microsoft/hve-core

Branches

Tags

Clone