Skip to content

prompts.md

Latest commit

 

History

History
621 lines (431 loc) · 20.6 KB

prompts.md

File metadata and controls

621 lines (431 loc) · 20.6 KB
title Contributing Prompts to HVE Core
description Requirements and standards for contributing GitHub Copilot prompt files to hve-core
sidebar_position 4
author Microsoft
ms.date 2026-03-17
ms.topic how-to

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)

Property Value
Purpose Concise explanation of prompt purpose and use case
Format Single sentence, 10-200 characters
Style Sentence case with proper punctuation
Example 'Required protocol for creating Azure DevOps pull requests with work item discovery and reviewer identification'

Optional Fields

agent (string)

Property Value
Purpose Delegates execution to a named custom agent
Format Human-readable agent name matching the agent's name: frontmatter field
Style Quote the value when the agent name contains spaces
Example 'ADO Backlog Manager'

argument-hint (string)

Property Value
Purpose Displays expected inputs in the VS Code prompt picker
Format Brief string; required arguments first, then optional; [] for positional, key=value for named, {option1|option2} for enumerated choices
Style Keep hints concise; lead with required arguments
Example "project=... [type={Epic|Feature|UserStory|Bug|Task}] [title=...]"

model (string)

Property Value
Purpose Specifies a preferred AI model for prompt invocation
Format Model identifier string
Style Use the model's canonical identifier; omit if the workspace default is acceptable
Example gpt-4o

disable-model-invocation (boolean)

Property Value
Purpose Prevents the prompt from automatically invoking an AI model at start
Format Boolean (true or false)
Style Use for prompts that gather context or run setup steps before handing off to the user
Example true

mode (string)

Property Value
Purpose Specifies the invocation context
Format Enumerated string; valid values: agent, assistant, copilot, workflow
Style Lowercase
Example agent

category (string)

Property Value
Purpose Groups the prompt by topic or domain for organizational purposes
Format String identifying the domain or topic area
Style Lowercase kebab-case (e.g., code-review, ado, git)
Example code-review

version (string)

Property Value
Purpose Tracks prompt revisions
Format Semantic versioning string (MAJOR.MINOR.PATCH)
Style Quoted string
Example '1.0.0'

author (string)

Property Value
Purpose Attribution for the prompt creator
Format Team or repository identifier string
Style Use org/repo format or a team name
Example 'microsoft/hve-core'

lastUpdated (string)

Property Value
Purpose Timestamp of last modification
Format ISO 8601 date string (YYYY-MM-DD)
Style Quoted string
Example '2026-03-17'

Frontmatter Example

---
description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'
agent: 'ADO Backlog Manager'
argument-hint: "project-slug=... [type={PR|Draft}]"
version: '1.0.0'
author: 'microsoft/hve-core'
lastUpdated: '2026-03-17'
---

Input Variables

Prompts can declare input variables that VS Code resolves at invocation time. The syntax is:

${input:varName}
${input:varName:defaultValue}

Declare variables in an Inputs section and reference them in prompt content:

## Inputs

* ${input:topic}: (Required) Primary topic or focus area.
* ${input:scope:all}: (Optional, defaults to all) Scope of the operation.

Required inputs (no default) are inferred from the user's conversation or attached files when not explicitly supplied.

Activation Lines

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.

---

Begin by reading the current branch state and identifying open work items.

Prompts that delegate to a custom agent via agent: typically omit the activation line because the agent's phases define execution order.

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 Type Recommended Collections
Git/PR workflows hve-core-all, hve-core
ADO work item workflows hve-core-all, ado, project-planning
GitHub issue workflows hve-core-all, github
RPI workflow prompts hve-core-all, hve-core
Documentation workflows hve-core-all, hve-core
Architecture prompts hve-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

8. Attribution Footer

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'
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.

Related Documentation

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.