microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

3ed441c3d4a92f1fa944a2121273ba46fdab8a8d

Find a branch or tag

Branches

3ed441c3d4a92f1fa944a2121273ba46fdab8a8d

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/prompts.md

547lines · 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: 2025-11-26`
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	`mode` (string enum, MANDATORY for prompts)
73
74	`\| Property \| Value \|`
75	`\|----------\|----------------------------------------\|`
76	`\| Purpose \| Defines when/how the prompt is invoked \|`
77	\| Example \| `workflow` \|
78
79	`Valid values:`
80
81	* `agent` - Used by specialized AI agents
82	* `assistant` - General-purpose assistance context
83	* `copilot` - GitHub Copilot-specific workflows
84	* `workflow` - Automated workflow/pipeline context
85
86	`### Optional Fields`
87
88	`category` (string enum)
89
90	`Organizes prompts by domain.`
91
92	`Valid values:`
93
94	* `ado` - Azure DevOps workflows
95	* `git` - Git operations
96	* `documentation` - Documentation generation/maintenance
97	* `workflow` - General workflow automation
98	* `development` - Development tasks
99
100	`version` (string)
101
102	Tracks prompt revisions using semantic versioning (e.g., `1.0.0`).
103
104	`author` (string)
105
106	Attribution for the prompt creator (e.g., `microsoft/hve-core`, `your-team-name`).
107
108	`lastUpdated` (string)
109
110	`Timestamp of last modification in ISO 8601 format (YYYY-MM-DD).`
111
112	`### Frontmatter Example`
113
114	```yaml
115	`---`
116	`description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'`
117	`mode: 'workflow'`
118	`category: 'ado'`
119	`version: '1.0.0'`
120	`author: 'microsoft/hve-core'`
121	`lastUpdated: '2025-11-19'`
122	`---`
123	```
124
125	`## Collection Entry Requirements`
126
127	All prompts must have matching entries in one or more `collections/*.collection.yml` manifests. Collection entries control distribution and maturity.
128
129	`### Adding Your Prompt to a Collection`
130
131	After creating your prompt file, add an `items[]` entry in each target collection manifest:
132
133	```yaml
134	`items:`
135	`# path can reference artifacts from any subfolder`
136	`- path: .github/prompts/{collection-id}/my-prompt.prompt.md`
137	`kind: prompt`
138	`maturity: stable`
139	```
140
141	`### Selecting Collections for Prompts`
142
143	`Choose collections based on who invokes or benefits from the workflow:`
144
145	`\| Prompt Type \| Recommended Collections \|`
146	`\|-------------------------\|-------------------------------------------\|`
147	\| Git/PR workflows \| `hve-core-all`, `hve-core` \|
148	\| ADO work item workflows \| `hve-core-all`, `ado`, `project-planning` \|
149	\| GitHub issue workflows \| `hve-core-all`, `github` \|
150	\| RPI workflow prompts \| `hve-core-all`, `hve-core` \|
151	\| Documentation workflows \| `hve-core-all`, `hve-core` \|
152	\| Architecture prompts \| `hve-core-all`, `project-planning` \|
153
154	`For complete collection documentation, see [AI Artifacts Common Standards - Collection Manifests](ai-artifacts-common.md#collection-manifests-and-dependencies).`
155
156	`## Prompt Content Structure Standards`
157
158	`### Required Sections`
159
160	`#### 1. Title (H1)`
161
162	`* Clear, action-oriented heading describing the workflow`
163	`* Should align with filename and description`
164
165	```markdown
166	`# Azure DevOps Pull Request Creation Protocol`
167	```
168
169	`#### 2. Overview/Purpose`
170
171	`* Explains what the prompt does and when to use it`
172	`* Defines scope and prerequisites`
173	`* Lists expected outcomes`
174
175	```markdown
176	`## Overview`
177
178	`This prompt guides the creation of Azure DevOps pull requests with automated`
179	`work item discovery, reviewer identification, and compliance validation.`
180	```
181
182	`#### 3. Prerequisites/Context`
183
184	`* Lists required information, tools, or setup`
185	`* Specifies environment assumptions`
186	`* Defines input requirements`
187
188	```markdown
189	`## Prerequisites`
190
191	`* Active Azure DevOps connection`
192	`* Current branch with committed changes`
193	`* Work item IDs or branch naming following conventions`
194	```
195
196	`#### 4. Workflow Steps`
197
198	`* Provides clear, numbered steps for execution`
199	`* Uses imperative, unambiguous language`
200	`* Includes decision points and branching logic`
201	`* Specifies tool usage at each step`
202
203	```markdown
204	`## Workflow Steps`
205
206	`1. Discovery Phase: Identify related work items from branch name or commit messages`
207	`2. Reviewer Selection: Query ADO for default reviewers based on repository policies`
208	`3. PR Creation: Generate PR with title, description, and work item links`
209	`4. Validation: Verify PR was created successfully with correct metadata`
210	```
211
212	`#### 5. Success Criteria`
213
214	`* Defines completion conditions`
215	`* Specifies validation checkpoints`
216	`* Lists expected artifacts`
217
218	```markdown
219	`## Success Criteria`
220
221	`* [ ] PR created in target repository`
222	`* [ ] Work items linked to PR`
223	`* [ ] Required reviewers added`
224	`* [ ] PR description follows template`
225	```
226
227	`#### 6. Examples`
228
229	`* Demonstrates correct usage with realistic scenarios`
230	`* Shows input/output patterns`
231	`* Wraps in XML-style blocks for reusability`
232
233	`#### 7. Error Handling`
234
235	`* Documents common failure modes`
236	`* Provides recovery procedures`
237	`* Specifies fallback behaviors`
238
239	`#### 8. Attribution Footer`
240
241	`Always include an attribution footer at the end of the file.`
242
243	```markdown
244	`---`
245
246	`Brought to you by microsoft/hve-core`
247	```
248
249	`### XML-Style Block Requirements`
250
251	`See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.`
252
253	`### Template Variable Standards`
254
255	Use `{{double_curly_braces}}` for placeholders:
256
257	`<!-- <example-template-variables> -->`
258	```yaml
259	`# ✅ CORRECT: Template variables in YAML frontmatter`
260	`---`
261	`title: "{{feature_name}} - {{brief_description}}"`
262	`branch: "feature/{{work_item_id}}-{{task_name}}"`
263	`assignee: "{{user_email}}"`
264	`---`
265
266	`# ❌ INCORRECT: Non-standard variable syntax in YAML frontmatter`
267	`---`
268	`title: "<feature-name> - <brief-description>"`
269	`branch: "feature/<work-item-id>-<task-name>"`
270	`assignee: "<user.email>"`
271	`---`
272	```
273	`<!-- </example-template-variables> -->`
274
275	`#### Variable Naming`
276
277	* Use snake_case: `{{work_item_id}}`, `{{user_name}}`
278	* Be descriptive: `{{target_branch}}` not `{{tb}}`
279	* Group related variables: `{{pr_title}}`, `{{pr_description}}`, `{{pr_labels}}`
280
281	`### Directive Language Standards`
282
283	`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.`
284
285	`## Workflow Definition Standards`
286
287	`Prompts should clearly define:`
288
289	`### Entry Points`
290
291	`What triggers this prompt:`
292
293	```markdown
294	`## Invocation`
295
296	`This prompt is invoked when:`
297
298	`* User requests "create ADO pull request"`
299	* User runs command: `/prompt ado-create-pull-request`
300	`* Workflow automation reaches PR creation step`
301	```
302
303	`### Decision Points`
304
305	`Where choices affect flow:`
306
307	```markdown
308	`## Decision Logic`
309
310	`If work items found in branch name:`
311	`→ Use those work items for linking`
312
313	`Else if work items in commit messages:`
314	`→ Extract and use those work items`
315
316	`Else:`
317	`→ Prompt user for work item IDs`
318	```
319
320	`### Tool Usage`
321
322	`Which tools are used and when:`
323
324	```markdown
325	`## Required Tools`
326
327	1. `mcp_azure_devops` - Work item queries and PR creation
328	2. `git/*` - Branch and commit information
329	3. `search` - Repository policy lookups
330	```
331
332	`### Output Specifications`
333
334	`What artifacts are produced:`
335
336	```markdown
337	`## Output Artifacts`
338
339	`1. Pull Request: Created in ADO with metadata`
340	2. Handoff Document: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
341	`3. Validation Report: Summary of PR creation status`
342	```
343
344	`## Context Requirements`
345
346	`Prompts SHOULD specify:`
347
348	`### File/Path Contexts`
349
350	`When specific files/paths trigger behavior:`
351
352	```yaml
353	`---`
354	`description: 'Required protocol for creating Azure DevOps pull requests'`
355	`mode: 'workflow'`
356	`applyTo: '/.copilot-tracking/pr/new/' # Workflow-specific context`
357	`---`
358	```
359
360	`### Data Requirements`
361
362	`What information must be available:`
363
364	```markdown
365	`## Required Context`
366
367	* `{{current_branch}}` - Active git branch name
368	* `{{target_branch}}` - Destination branch (default: main/master)
369	* `{{repository_url}}` - ADO repository URL
370	* `{{user_email}}` - Current user's email for reviewer queries
371	```
372
373	`### State Assumptions`
374
375	`What must be true before execution:`
376
377	```markdown
378	`## Preconditions`
379
380	`* Working directory is a git repository`
381	`* Changes are committed to current branch`
382	`* User has ADO credentials configured`
383	`* Target branch exists in remote repository`
384	```
385
386	`## Output Formatting Requirements`
387
388	`Define how the prompt produces results:`
389
390	`### Response Format`
391
392	`Structure for user-facing output:`
393
394	```markdown
395	`## Output Format`
396
397	`### PR Creation Summary`
398
399	`Status: [Success\|Failed]`
400	`PR ID: [ID]`
401	`PR URL: [URL]`
402	`Work Items Linked: [IDs]`
403	`Reviewers Added: [Names]`
404
405	`### Validation Results`
406
407	`* [x] PR created successfully`
408	`* [x] Work items linked`
409	`* [ ] CI pipeline triggered`
410	```
411
412	`### File Outputs`
413
414	`Specifications for generated files:`
415
416	```markdown
417	`## Handoff Document Format`
418
419	File: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
420
421	`Content:`
422
423	`* PR metadata (ID, URL, title)`
424	`* Work item links with status`
425	`* Reviewer assignments`
426	`* Validation checklist`
427	```
428
429	`### Error Reporting`
430
431	`Format for failure scenarios:`
432
433	```markdown
434	`## Error Format`
435
436	`Error Type: [Authentication\|Validation\|Network]`
437	`Message: [Detailed error description]`
438	`Recovery Steps:`
439
440	`1. [Step to resolve]`
441	`2. [Alternative approach]`
442	```
443
444	`## Validation Checklist`
445
446	`Before submitting your prompt, verify:`
447
448	`### Frontmatter`
449
450	* [ ] Valid YAML between `---` delimiters
451	* [ ] `description` field present and descriptive (10-200 chars)
452	* [ ] `mode` field present with valid value
453	* [ ] `category` field appropriate for domain (if present)
454	`* [ ] No trailing whitespace in values`
455	`* [ ] Single newline at EOF`
456
457	`### Content Structure`
458
459	`* [ ] Clear H1 title describing workflow`
460	`* [ ] Overview/purpose section`
461	`* [ ] Maturity set in collection item (see [Common Standards - Maturity](ai-artifacts-common.md#maturity-field-requirements))`
462	`* [ ] Prerequisites or context section`
463	`* [ ] Workflow steps with clear sequence`
464	`* [ ] Success criteria defined`
465	`* [ ] Error handling documented`
466	`* [ ] Attribution footer present`
467
468	`### Workflow Definition`
469
470	`* [ ] Entry points/triggers specified`
471	`* [ ] Decision logic clearly documented`
472	`* [ ] Tool usage requirements listed`
473	`* [ ] Output artifacts defined`
474	`* [ ] State assumptions documented`
475
476	`### Common Standards`
477
478	`* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))`
479	`* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))`
480	`* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))`
481	* [ ] Template variables use `{{snake_case}}`
482
483	`### Technical Validation`
484
485	`* [ ] All file references point to existing files`
486	`* [ ] External links are valid and accessible`
487	`* [ ] Tool references use correct names`
488	`* [ ] Template variables are clearly defined`
489
490	`### Integration`
491
492	* [ ] Aligns with `.github/copilot-instructions.md`
493	`* [ ] Follows repository conventions`
494	`* [ ] Compatible with existing prompts/workflows`
495	`* [ ] Does not duplicate existing prompt functionality`
496
497	`## Testing Your Prompt`
498
499	`See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For prompts specifically:`
500
501	`1. Follow prompt steps manually to verify workflow logic`
502	`2. Test with AI execution using realistic scenarios`
503	`3. Verify all output artifacts match specifications`
504	`4. Test decision points with different data conditions`
505
506	`## Common Issues and Fixes`
507
508	`### Prompt-Specific Issues`
509
510	`### Template Variables with Wrong Format`
511
512	Using incorrect syntax for template variables (angle brackets or shell-style) causes failures. Always use `{{variable_name}}` handlebars format for template variables.
513
514	`### Ambiguous Workflow Steps`
515
516	`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.`
517
518	`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).`
519
520	`## Automated Validation`
521
522	`Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):`
523
524	* `npm run lint:frontmatter`
525	* `npm run lint:md`
526	* `npm run spell-check`
527	* `npm run lint:md-links`
528
529	`All checks MUST pass before merge.`
530
531	`## Related Documentation`
532
533	`* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions`
534	`* [Contributing Custom Agents](custom-agents.md) - AI agent configuration files`
535	`* [Contributing Instructions](instructions.md) - Technology-specific standards`
536	`* [Pull Request Template](https://github.com/microsoft/hve-core/blob/main/.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements`
537
538	`## Getting Help`
539
540	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).
541
542	`---`
543
544	`<!-- markdownlint-disable MD036 -->`
545	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
546	`then carefully refined by our team of discerning human reviewers.*`
547	`<!-- markdownlint-enable MD036 -->`
548

microsoft/hve-core

Branches

Tags

Clone