Skip to content

refactor(instructions): consolidate and enhance AI artifact guidelines#206

Merged
agreaves-ms merged 12 commits intomainfrom
feat/instructions-cleanup
Jan 18, 2026
Merged

refactor(instructions): consolidate and enhance AI artifact guidelines#206
agreaves-ms merged 12 commits intomainfrom
feat/instructions-cleanup

Conversation

@agreaves-ms
Copy link
Copy Markdown
Collaborator

refactor(instructions): consolidate and enhance AI artifact guidelines

Description

This PR consolidates and refines AI artifact documentation across the repository, focusing on instructions files, prompts, and related templates. The changes improve clarity, reduce redundancy, and establish more consistent patterns across all instruction types.

Key Changes

Azure DevOps Instructions Refactoring

  • Enhanced ado-create-pull-request.instructions.md with clearer reviewer identification and work item linking protocols
  • Improved ado-get-build-info.instructions.md with better structured build status retrieval
  • Streamlined ado-update-wit-items.instructions.md for work item creation/update workflows
  • Refined ado-wit-discovery.instructions.md and ado-wit-planning.instructions.md with improved search patterns

New Terraform Instructions

  • Added comprehensive terraform.instructions.md for Infrastructure as Code implementation
  • Covers provider configuration, resource naming, state management, and security patterns

Language-Specific Instruction Consolidation

  • Bash: Consolidated bash.md content into bash.instructions.md, removed redundant file
  • Bicep: Merged bicep.md and bicep-standards.md into unified bicep.instructions.md
  • C#: Enhanced both csharp.instructions.md and csharp-tests.instructions.md with improved patterns
  • Python: Updated python-script.instructions.md with refined guidelines
  • Removed obsolete shell.instructions.md (functionality merged into bash)

Prompt Engineering Improvements

  • Enhanced prompt-builder.instructions.md with clearer authoring standards
  • Added new prompt-analyze.prompt.md for prompt analysis workflows
  • Streamlined prompt-build.prompt.md with simplified step patterns
  • Updated pull-request.prompt.md with improved PR generation workflow

Documentation Updates

  • Updated .github/instructions/README.md to reflect consolidated structure
  • Streamlined root copilot-instructions.md for improved clarity

Related Issue(s)

N/A - Internal documentation improvement initiative

Type of Change

Select all that apply:

Code & Documentation:

  • Bug fix (non-breaking change fixing an issue)
  • New feature (non-breaking change adding functionality)
  • Breaking change (fix or feature causing existing functionality to change)
  • Documentation update

Infrastructure & Configuration:

  • GitHub Actions workflow
  • Linting configuration (markdown, PowerShell, etc.)
  • Security configuration
  • DevContainer configuration
  • Dependency update

AI Artifacts:

  • Reviewed contribution with prompt-builder chatmode and addressed all feedback
  • Copilot instructions (.github/instructions/*.instructions.md)
  • Copilot prompt (.github/prompts/*.prompt.md)
  • Copilot chatmode (.github/chatmodes/*.chatmode.md)

Other:

  • Script/automation (.ps1, .sh, .py)
  • Other (please describe):

AI Artifacts Modified

File Change Type Description
ado-create-pull-request.instructions.md Modified Enhanced reviewer identification and work item linking
ado-get-build-info.instructions.md Modified Improved build status retrieval structure
ado-update-wit-items.instructions.md Modified Streamlined work item creation/update
ado-wit-discovery.instructions.md Modified Improved work item search patterns
ado-wit-planning.instructions.md Modified Enhanced planning file specifications
bash/bash.instructions.md Modified Consolidated from separate bash.md file
bash/bash.md Deleted Content merged into bash.instructions.md
bicep/bicep.instructions.md Modified Consolidated from bicep.md and bicep-standards.md
bicep/bicep.md Deleted Content merged into bicep.instructions.md
bicep/bicep-standards.md Deleted Content merged into bicep.instructions.md
csharp/csharp.instructions.md Modified Enhanced project guidelines and patterns
csharp/csharp-tests.instructions.md Modified Streamlined test instructions
python-script.instructions.md Modified Refined Python scripting guidelines
shell.instructions.md Deleted Functionality merged into bash.instructions.md
terraform/terraform.instructions.md Added New comprehensive Terraform IaC instructions
prompt-builder.instructions.md Modified Clarified authoring standards
writing-style.instructions.md Modified Updated writing conventions
prompt-analyze.prompt.md Added New prompt analysis workflow
prompt-build.prompt.md Modified Simplified step patterns
pull-request.prompt.md Modified Improved PR generation workflow

Sample Prompts (for AI Artifact Contributions)

User Request:
"Create a new Terraform module for Azure Key Vault with managed identity access"

Execution Flow:

  1. Agent reads terraform.instructions.md when working in .tf files
  2. Applies provider configuration patterns from instructions
  3. Implements resource naming conventions and security patterns
  4. Generates module with proper state management configuration

Output Artifacts:

# main.tf - Azure Key Vault module
resource "azurerm_key_vault" "this" {
  name                = "kv-${var.project}-${var.environment}"
  location            = var.location
  resource_group_name = var.resource_group_name
  tenant_id           = data.azurerm_client_config.current.tenant_id
  sku_name            = "standard"
  # ... additional configuration
}

Success Indicators:

  • Generated Terraform follows naming conventions from instructions
  • Security patterns (RBAC, network rules) applied correctly
  • Module structure matches documented patterns

Testing

  • Reviewed all modified instruction files for consistency
  • Verified cross-references between related instruction files
  • Confirmed frontmatter follows schema requirements
  • Validated markdown formatting and link integrity

Checklist

Required Checks

  • Documentation is updated (if applicable)
  • Files follow existing naming conventions
  • Changes are backwards compatible (if applicable)

AI Artifact Contributions

  • Used prompt-builder chatmode to review contribution
  • Addressed all feedback from prompt-builder review
  • Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

  • Markdown linting: npm run lint:md
  • Spell checking: npm run spell-check
  • Frontmatter validation: npm run lint:frontmatter
  • Link validation: npm run lint:md-links
  • PowerShell analysis: npm run lint:ps

Security Considerations

  • This PR does not contain any sensitive or NDA information
  • Any new dependencies have been reviewed for security issues
  • Security-related scripts follow the principle of least privilege

Additional Notes

This PR represents a significant consolidation effort to reduce duplication and improve maintainability of AI artifact documentation. The changes establish clearer patterns that should make future instruction authoring more consistent.

Files Removed: 4 (bash.md, bicep.md, bicep-standards.md, shell.instructions.md)
Files Added: 2 (terraform.instructions.md, prompt-analyze.prompt.md)
Files Modified: 16

…teps

- consolidate input descriptions for clarity
- enhance step instructions for user request interpretation
- improve protocol iteration and outcome reporting

🔧 - Generated by Copilot
…cture

- improve clarity in user request interpretation steps
- refine protocol iteration instructions for subagents
- summarize outcomes reporting for better user understanding

🔍 - Generated by Copilot
…details

- add project configuration section for target framework and language version
- include implicit usings and multi-project solutions guidance
- update coding conventions with modern C# patterns and features

🔧 - Generated by Copilot
…nd consistency

- remove redundant phrasing for better readability
- clarify subagent usage and required phases
- enhance overall structure of the instructions

🔧 - Generated by Copilot
…and organization

- consolidate project structure and configuration sections
- enhance clarity of naming conventions and folder organization
- simplify dotnet CLI commands for managing projects

🔧 - Generated by Copilot
…ython scripting guidelines

- Consolidate C# test conventions and improve clarity
- Expand Python script instructions for better structure and usability
- Update writing style guidelines for consistency and clarity
- Revise prompt analysis instructions for improved evaluation process

🔧 - Generated by Copilot
…for clarity and structure

- redefine protocol for retrieving build information
- clarify tooling usage and summarization rules
- improve conversational response guidelines

🔧 - Generated by Copilot
…lementation

- define project structure and file organization
- establish naming conventions for resources and variables
- outline variable and output declaration standards
- specify comment styles and module conventions
- include state management and lifecycle management practices

🔒 - Generated by Copilot
…s instructions

- update diagram name format for consistency
- enhance section headers for user-centric discovery paths
- remove unnecessary example tags for cleaner presentation

🔧 - Generated by Copilot
- replace example prompts with more relevant task names
- add new acronyms to the industry acronyms list

🔄 - Generated by Copilot
@agreaves-ms agreaves-ms requested a review from a team as a code owner January 18, 2026 05:59
Copilot AI review requested due to automatic review settings January 18, 2026 05:59
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 18, 2026

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request consolidates and enhances AI artifact documentation across the repository by merging redundant files, adding new comprehensive instructions for Terraform, and streamlining existing prompt and instruction files. The changes improve clarity, reduce duplication, and establish more consistent patterns for instruction authoring.

Changes:

  • Consolidated bash, bicep, and shell instructions from multiple files into unified .instructions.md files
  • Added comprehensive Terraform IaC instructions and a new prompt-analyze workflow
  • Streamlined pull request, prompt builder, and writing style instructions with clearer structure
  • Enhanced ADO work item planning, discovery, update, build info, and PR creation protocols
  • Updated C# and Python instructions with improved examples and conventions
  • Removed 4 files (bash.md, bicep.md, bicep-standards.md, shell.instructions.md) and added 2 (terraform.instructions.md, prompt-analyze.prompt.md)

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
extension/package.json Removed shell-instructions entry from package configuration
.vscode/settings.json Added commit message generation instructions configuration
.github/prompts/pull-request.prompt.md Refactored from directive-heavy style to guidance-based protocol with simplified steps
.github/prompts/prompt-build.prompt.md Streamlined step patterns and clarified delegation to prompt-builder chatmode
.github/prompts/prompt-analyze.prompt.md New prompt for evaluating prompt artifacts against quality criteria
.github/prompts/README.md Updated example prompts and removed outdated getting-started reference
.github/instructions/writing-style.instructions.md Restructured with tables, removed XML blocks, improved readability
.github/instructions/terraform/terraform.instructions.md New comprehensive Terraform IaC instructions covering conventions, patterns, and best practices
.github/instructions/python-script.instructions.md Expanded from minimal to comprehensive Python 3.11+ scripting guide
.github/instructions/prompt-builder.instructions.md Removed redundant inline examples, streamlined guidance
.github/instructions/csharp/csharp.instructions.md Updated for .NET 10/C# 14 with enhanced documentation examples and modern patterns
.github/instructions/csharp/csharp-tests.instructions.md Simplified to focus on NSubstitute, removed Moq-specific patterns
.github/instructions/bicep/bicep.instructions.md Consolidated from bicep.md and bicep-standards.md into unified comprehensive guide
.github/instructions/bash/bash.instructions.md Consolidated from bash.md into comprehensive bash scripting guide
.github/instructions/ado-wit-planning.instructions.md Enhanced with MCP tool reference, similarity assessment guidance, improved templates
.github/instructions/ado-wit-discovery.instructions.md Restructured with three discovery paths (user-centric, artifact-driven, search-based)
.github/instructions/ado-update-wit-items.instructions.md Enhanced error handling, added work item hierarchy, improved tool examples
.github/instructions/ado-get-build-info.instructions.md Restructured with comprehensive tool reference and clearer step protocol
.github/instructions/ado-create-pull-request.instructions.md Streamlined phases, added MCP tool consolidation, enhanced reviewer resolution
.github/instructions/README.md Reorganized with categorized tables, updated directory structure
.github/copilot-instructions.md Condensed from 280 to 90 lines, removed redundant structure documentation
.cspell/industry-acronyms.txt Added openssf and OpenSSF entries

@WilliamBerryiii
Copy link
Copy Markdown
Member

@agreaves-ms - really nice work here.

@agreaves-ms agreaves-ms merged commit 54dd959 into main Jan 18, 2026
15 checks passed
@agreaves-ms agreaves-ms deleted the feat/instructions-cleanup branch January 18, 2026 18:45
WilliamBerryiii pushed a commit that referenced this pull request Jan 19, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.1.0](hve-core-v1.0.0...hve-core-v1.1.0)
(2026-01-19)


### ✨ Features

* **.devcontainer:** add development container configuration
([#24](#24))
([45debf5](45debf5))
* **.github:** add github metadata and mcp configuration
([#23](#23))
([1cb898d](1cb898d))
* **agent:** Add automated installation via hve-core-installer agent
([#82](#82))
([a2716d5](a2716d5))
* **agents:** add brd-builder.agent.md for building BRDs
([#122](#122))
([bfdc9f3](bfdc9f3))
* **agents:** redesign installer with Codespaces support and method
documentation ([#123](#123))
([6329fc0](6329fc0))
* **ai:** Establish AI-Assisted Development Framework
([#48](#48))
([f5199a4](f5199a4))
* **build:** implement automated release management with release-please
([#86](#86))
([90150e2](90150e2))
* **chatmodes:** add architecture diagram builder agent
([#145](#145))
([db24637](db24637))
* **config:** add development tools configuration files
([#19](#19))
([9f97522](9f97522))
* **config:** add npm package configuration and dependencies
([#20](#20))
([fcba198](fcba198))
* **copilot:** add GitHub Copilot instruction files
([#22](#22))
([4927284](4927284))
* **copilot:** add specialized chat modes for development workflows
([#21](#21))
([ae8495f](ae8495f))
* **docs:** add comprehensive AI artifact contribution documentation
([#76](#76))
([d81cf96](d81cf96))
* **docs:** add getting started guide for project configuration
([#57](#57))
([3b864fa](3b864fa))
* **docs:** add repository foundation and documentation files
([#18](#18))
([ad7efb6](ad7efb6)),
closes [#2](#2)
* **docs:** add RPI workflow documentation and restructure docs folder
([#102](#102))
([c3af708](c3af708))
* **extension:** hve core vs code extension
([#149](#149))
([041a1fd](041a1fd))
* **extension:** implement pre-release versioning with agent maturity
filtering ([#179](#179))
([fb38233](fb38233))
* **instructions:** add authoring standards for prompt engineering
artifacts ([#177](#177))
([5de3af9](5de3af9))
* **instructions:** add extension quick install and enhance installer
agent ([#176](#176))
([48e3d58](48e3d58))
* **instructions:** add VS Code variant prompt and gitignore
recommendation to installer
([#185](#185))
([b400493](b400493))
* **instructions:** add writing style guide for markdown content
([#151](#151))
([02df6a8](02df6a8))
* **instructions:** consolidate C# guidelines and update prompt agent
fields ([#158](#158))
([65342d4](65342d4))
* **instructions:** provide guidance on using safe commands to reduce
interactive prompting
([#117](#117))
([1268580](1268580))
* **linting:** add linting and validation scripts
([#26](#26))
([66be136](66be136))
* **prompt-builder:** enhance prompt engineering instructions and
validation protocols
([#155](#155))
([bc5004f](bc5004f))
* **prompts:** add ADR placement planning and update template paths
([#69](#69))
([380885f](380885f))
* **prompts:** add git workflow prompts from edge-ai
([#84](#84))
([56d66b6](56d66b6))
* **prompts:** add github-add-issue prompt and github-issue-manager
chatmode with delegation pattern
([#55](#55))
([d0e1789](d0e1789))
* **prompts:** add PR template discovery and integration to pull-request
prompt ([#141](#141))
([b8a4c7a](b8a4c7a))
* **prompts:** add task research initiation prompt and rpi
agent([#124](#124))
([5113e3b](5113e3b))
* **release:** implement release management strategy
([#161](#161))
([6164c3b](6164c3b))
* Risk Register Prompt
([#146](#146))
([843982c](843982c))
* **scripts:** enhanced JSON Schema validation for markdown frontmatter
([#59](#59))
([aba152c](aba152c))
* **security:** add checksum validation infrastructure
([#106](#106))
([07528fb](07528fb))
* **security:** add security scanning scripts
([#25](#25))
([82de5a1](82de5a1))
* **workflows:** add CodeQL security analysis to PR validation
([#132](#132))
([e5b6e8f](e5b6e8f))
* **workflows:** add orchestration workflows and documentation
([#29](#29))
([de442e0](de442e0))
* **workflows:** add security reusable workflows
([#28](#28))
([2c74399](2c74399))
* **workflows:** add validation reusable workflows
([#27](#27))
([f52352d](f52352d))


### 🐛 Bug Fixes

* **build:** add token parameter to release-please action
([#166](#166))
([c9189ec](c9189ec))
* **build:** disable MD012 lint rule in CHANGELOG for release-please
compatibility ([#173](#173))
([54502d8](54502d8)),
closes [#172](#172)
* **build:** pin npm commands for OpenSSF Scorecard compliance
([#181](#181))
([c29db54](c29db54))
* **build:** remediate GHSA-g9mf-h72j-4rw9 undici vulnerability
([#188](#188))
([634bf36](634bf36))
* **build:** seed CHANGELOG.md with version entry for release-please
frontmatter preservation
([#170](#170))
([2b299ac](2b299ac))
* **build:** use GitHub App token for release-please
([#167](#167))
([070e042](070e042))
* **build:** use hashtable splatting for named parameters
([#164](#164))
([02a965f](02a965f))
* **devcontainer:** remove unused Python requirements check
([#78](#78))
([f17a872](f17a872)),
closes [#77](#77)
* **docs:** fix broken links and update validation for .vscode/README.md
([#118](#118))
([160ae7a](160ae7a))
* **docs:** improve language consistency in Automated Installation
section ([#139](#139))
([a932918](a932918))
* **docs:** replace install button anchor with VS Code protocol handler
([#111](#111))
([41a265e](41a265e))
* **docs:** update install badges to use aka.ms redirect URLs
([#114](#114))
([868f655](868f655))
* **linting:** use cross-platform path separators in gitignore pattern
matching ([#121](#121))
([3f0aa1b](3f0aa1b))
* **scripts:** accepts the token (YYYY-MM-dd) in frontmatter validation
([#133](#133))
([2648215](2648215))
* **tools:** correct Method 5 path resolution in hve-core-installer
([#129](#129))
([57ef20d](57ef20d))


### 📚 Documentation

* add comprehensive RPI workflow documentation
([#153](#153))
([cbaa4a9](cbaa4a9))
* enhance README with contributing, responsible AI, and legal sections
([#52](#52))
([a424adc](a424adc))


### ♻️ Refactoring

* **instructions:** consolidate and enhance AI artifact guidelines
([#206](#206))
([54dd959](54dd959))
* migrate chatmodes to agents architecture
([#210](#210))
([712b0b7](712b0b7))


### 🔧 Maintenance

* **build:** clean up workflow permissions for Scorecard compliance
([#183](#183))
([64686e7](64686e7))
* **deps-dev:** bump cspell in the npm-dependencies group
([#61](#61))
([38650eb](38650eb))
* **deps-dev:** bump glob from 10.4.5 to 10.5.0
([#74](#74))
([b3ca9fd](b3ca9fd))
* **deps-dev:** bump markdownlint-cli2 from 0.19.1 to 0.20.0 in the
npm-dependencies group
([#134](#134))
([ebfbe84](ebfbe84))
* **deps-dev:** bump the npm-dependencies group across 1 directory with
2 updates ([#109](#109))
([936ab84](936ab84))
* **deps-dev:** bump the npm-dependencies group with 2 updates
([#30](#30))
([cf99cbf](cf99cbf))
* **deps:** bump actions/upload-artifact from 5.0.0 to 6.0.0 in the
github-actions group
([#142](#142))
([91eac8a](91eac8a))
* **deps:** bump js-yaml, markdown-link-check and markdownlint-cli2
([#75](#75))
([af03d0e](af03d0e))
* **deps:** bump the github-actions group with 2 updates
([#108](#108))
([3e56313](3e56313))
* **deps:** bump the github-actions group with 2 updates
([#135](#135))
([4538a03](4538a03))
* **deps:** bump the github-actions group with 2 updates
([#62](#62))
([d1e0c09](d1e0c09))
* **deps:** bump the github-actions group with 3 updates
([#87](#87))
([ed550f4](ed550f4))
* **deps:** bump the github-actions group with 6 updates
([#162](#162))
([ec5bb12](ec5bb12))
* **devcontainer:** enhance gitleaks installation with checksum
verification ([#100](#100))
([5a8507d](5a8507d))
* **devcontainer:** refactor setup scripts for improved dependency
management ([#94](#94))
([f5f50d1](f5f50d1)),
closes [#98](#98)
* **security:** configure GitHub branch protection for OpenSSF
compliance ([#191](#191))
([90aab1a](90aab1a))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants