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-v2.3.8

Find a branch or tag

Branches

hve-core-v2.3.8

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/prompts.md

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

microsoft/hve-core

Branches

Tags

Clone