Skip to main content

Contributing Prompts to HVE Core

This guide defines the requirements, standards, and best practices for contributing GitHub Copilot prompt files (.prompt.md) to the hve-core library.

⚙️ Common Standards: See AI Artifacts Common Standards for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).

What is a Prompt?​

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.

Use Cases for Prompts​

Create a prompt when you need to:

  • Guide a specific workflow or process (e.g., creating pull requests, processing work items)
  • Provide context-sensitive instructions triggered by user actions
  • Define a repeatable task with clear inputs and outputs
  • Document a multi-step procedure for AI execution
  • Establish standards for a particular type of deliverable

File Structure Requirements​

Location​

Prompt files are typically organized in a collection subdirectory by convention:

.github/prompts/{collection-id}/
└── your-prompt-name.prompt.md

NOTE

Collections can reference artifacts from any subfolder. The path: field in collection YAML files accepts any valid repo-relative path regardless of the artifact's parent directory.

Naming Convention​

  • Use lowercase kebab-case: pull-request.prompt.md
  • Be specific about workflow/task: ado-create-pull-request.prompt.md
  • Include domain prefix when relevant: ado-, git-, github-
  • Avoid generic names: workflow.prompt.md ❌ → ado-process-my-work-items-for-task-planning.prompt.md ✅

File Format​

Prompt files MUST:

  1. Use the .prompt.md extension
  2. Start with valid YAML frontmatter between --- delimiters
  3. Begin content directly after frontmatter
  4. End with single newline character

Frontmatter Requirements​

Required Fields​

description (string, MANDATORY)

PropertyValue
PurposeConcise explanation of prompt purpose and use case
FormatSingle sentence, 10-200 characters
StyleSentence case with proper punctuation
Example'Required protocol for creating Azure DevOps pull requests with work item discovery and reviewer identification'

mode (string enum, MANDATORY for prompts)

PropertyValue
PurposeDefines when/how the prompt is invoked
Exampleworkflow

Valid values:

  • agent - Used by specialized AI agents
  • assistant - General-purpose assistance context
  • copilot - GitHub Copilot-specific workflows
  • workflow - Automated workflow/pipeline context

Optional Fields​

category (string enum)

Organizes prompts by domain.

Valid values:

  • ado - Azure DevOps workflows
  • git - Git operations
  • documentation - Documentation generation/maintenance
  • workflow - General workflow automation
  • development - Development tasks

version (string)

Tracks prompt revisions using semantic versioning (e.g., 1.0.0).

author (string)

Attribution for the prompt creator (e.g., microsoft/hve-core, your-team-name).

lastUpdated (string)

Timestamp of last modification in ISO 8601 format (YYYY-MM-DD).

Frontmatter Example​

---
description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'
mode: 'workflow'
category: 'ado'
version: '1.0.0'
author: 'microsoft/hve-core'
lastUpdated: '2025-11-19'
---

Collection Entry Requirements​

All prompts must have matching entries in one or more collections/*.collection.yml manifests. Collection entries control distribution and maturity.

Adding Your Prompt to a Collection​

After creating your prompt file, add an items[] entry in each target collection manifest:

items:
  # path can reference artifacts from any subfolder
  - path: .github/prompts/{collection-id}/my-prompt.prompt.md
    kind: prompt
    maturity: stable

Selecting Collections for Prompts​

Choose collections based on who invokes or benefits from the workflow:

Prompt TypeRecommended Collections
Git/PR workflowshve-core-all, hve-core
ADO work item workflowshve-core-all, ado, project-planning
GitHub issue workflowshve-core-all, github
RPI workflow promptshve-core-all, hve-core
Documentation workflowshve-core-all, hve-core
Architecture promptshve-core-all, project-planning

For complete collection documentation, see AI Artifacts Common Standards - Collection Manifests.

Prompt Content Structure Standards​

Required Sections​

1. Title (H1)​

  • Clear, action-oriented heading describing the workflow
  • Should align with filename and description
# Azure DevOps Pull Request Creation Protocol

2. Overview/Purpose​

  • Explains what the prompt does and when to use it
  • Defines scope and prerequisites
  • Lists expected outcomes
## Overview

This prompt guides the creation of Azure DevOps pull requests with automated
work item discovery, reviewer identification, and compliance validation.

3. Prerequisites/Context​

  • Lists required information, tools, or setup
  • Specifies environment assumptions
  • Defines input requirements
## Prerequisites

* Active Azure DevOps connection
* Current branch with committed changes
* Work item IDs or branch naming following conventions

4. Workflow Steps​

  • Provides clear, numbered steps for execution
  • Uses imperative, unambiguous language
  • Includes decision points and branching logic
  • Specifies tool usage at each step
## Workflow Steps

1. Discovery Phase: Identify related work items from branch name or commit messages
2. Reviewer Selection: Query ADO for default reviewers based on repository policies
3. PR Creation: Generate PR with title, description, and work item links
4. Validation: Verify PR was created successfully with correct metadata

5. Success Criteria​

  • Defines completion conditions
  • Specifies validation checkpoints
  • Lists expected artifacts
## Success Criteria

* [ ] PR created in target repository
* [ ] Work items linked to PR
* [ ] Required reviewers added
* [ ] PR description follows template

6. Examples​

  • Demonstrates correct usage with realistic scenarios
  • Shows input/output patterns
  • Wraps in XML-style blocks for reusability

7. Error Handling​

  • Documents common failure modes
  • Provides recovery procedures
  • Specifies fallback behaviors

Always include an attribution footer at the end of the file.

---

Brought to you by microsoft/hve-core

XML-Style Block Requirements​

See AI Artifacts Common Standards - XML-Style Block Standards for complete rules and examples.

Template Variable Standards​

Use {{double_curly_braces}} for placeholders:

# ✅ CORRECT: Template variables in YAML frontmatter
---
title: "{{feature_name}} - {{brief_description}}"
branch: "feature/{{work_item_id}}-{{task_name}}"
assignee: "{{user_email}}"
---

# ❌ INCORRECT: Non-standard variable syntax in YAML frontmatter
---
title: "<feature-name> - <brief-description>"
branch: "feature/<work-item-id>-<task-name>"
assignee: "<user.email>"
---

Variable Naming​

  • Use snake_case: {{work_item_id}}, {{user_name}}
  • Be descriptive: {{target_branch}} not {{tb}}
  • Group related variables: {{pr_title}}, {{pr_description}}, {{pr_labels}}

Directive Language Standards​

Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See AI Artifacts Common Standards - RFC 2119 Directive Language for complete guidance.

Workflow Definition Standards​

Prompts should clearly define:

Entry Points​

What triggers this prompt:

## Invocation

This prompt is invoked when:

* User requests "create ADO pull request"
* User runs command: `/prompt ado-create-pull-request`
* Workflow automation reaches PR creation step

Decision Points​

Where choices affect flow:

## Decision Logic

**If** work items found in branch name:
  → Use those work items for linking

**Else if** work items in commit messages:
  → Extract and use those work items

Else:
  → Prompt user for work item IDs

Tool Usage​

Which tools are used and when:

## Required Tools

1. `mcp_azure_devops` - Work item queries and PR creation
2. `git/*` - Branch and commit information
3. `search` - Repository policy lookups

Output Specifications​

What artifacts are produced:

## Output Artifacts

1. Pull Request: Created in ADO with metadata
2. Handoff Document: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
3. Validation Report: Summary of PR creation status

Context Requirements​

Prompts SHOULD specify:

File/Path Contexts​

When specific files/paths trigger behavior:

---
description: 'Required protocol for creating Azure DevOps pull requests'
mode: 'workflow'
applyTo: '**/.copilot-tracking/pr/new/**'  # Workflow-specific context
---

Data Requirements​

What information must be available:

## Required Context

* `{{current_branch}}` - Active git branch name
* `{{target_branch}}` - Destination branch (default: main/master)
* `{{repository_url}}` - ADO repository URL
* `{{user_email}}` - Current user's email for reviewer queries

State Assumptions​

What must be true before execution:

## Preconditions

* Working directory is a git repository
* Changes are committed to current branch
* User has ADO credentials configured
* Target branch exists in remote repository

Output Formatting Requirements​

Define how the prompt produces results:

Response Format​

Structure for user-facing output:

## Output Format

### PR Creation Summary

Status: [Success|Failed]
PR ID: [ID]
PR URL: [URL]
Work Items Linked: [IDs]
Reviewers Added: [Names]

### Validation Results

* [x] PR created successfully
* [x] Work items linked
* [ ] CI pipeline triggered

File Outputs​

Specifications for generated files:

## Handoff Document Format

File: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`

Content:

* PR metadata (ID, URL, title)
* Work item links with status
* Reviewer assignments
* Validation checklist

Error Reporting​

Format for failure scenarios:

## Error Format

Error Type: [Authentication|Validation|Network]
Message: [Detailed error description]
Recovery Steps:

1. [Step to resolve]
2. [Alternative approach]

Validation Checklist​

Before submitting your prompt, verify:

Frontmatter​

  • Valid YAML between --- delimiters
  • description field present and descriptive (10-200 chars)
  • mode field present with valid value
  • category field appropriate for domain (if present)
  • No trailing whitespace in values
  • Single newline at EOF

Content Structure​

  • Clear H1 title describing workflow
  • Overview/purpose section
  • Maturity set in collection item (see Common Standards - Maturity)
  • Prerequisites or context section
  • Workflow steps with clear sequence
  • Success criteria defined
  • Error handling documented
  • Attribution footer present

Workflow Definition​

  • Entry points/triggers specified
  • Decision logic clearly documented
  • Tool usage requirements listed
  • Output artifacts defined
  • State assumptions documented

Common Standards​

Technical Validation​

  • All file references point to existing files
  • External links are valid and accessible
  • Tool references use correct names
  • Template variables are clearly defined

Integration​

  • Aligns with .github/copilot-instructions.md
  • Follows repository conventions
  • Compatible with existing prompts/workflows
  • Does not duplicate existing prompt functionality

Testing Your Prompt​

See AI Artifacts Common Standards - Common Testing Practices for testing guidelines. For prompts specifically:

  1. Follow prompt steps manually to verify workflow logic
  2. Test with AI execution using realistic scenarios
  3. Verify all output artifacts match specifications
  4. Test decision points with different data conditions

Common Issues and Fixes​

Prompt-Specific Issues​

Template Variables with Wrong Format​

Using incorrect syntax for template variables (angle brackets or shell-style) causes failures. Always use {{variable_name}} handlebars format for template variables.

Ambiguous Workflow Steps​

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.

For additional common issues (XML blocks, markdown, directives), see AI Artifacts Common Standards - Common Issues and Fixes.

Automated Validation​

Run these commands before submission (see Common Standards - Common Validation):

  • npm run lint:frontmatter
  • npm run lint:md
  • npm run spell-check
  • npm run lint:md-links

All checks MUST pass before merge.

Getting Help​

See AI Artifacts Common Standards - Getting Help for support resources. For prompt-specific assistance, review existing examples in .github/prompts/{collection-id}/ (the conventional location for prompt files).

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.