refactor(instructions): consolidate and enhance AI artifact guidelines#206
Merged
agreaves-ms merged 12 commits intomainfrom Jan 18, 2026
Merged
refactor(instructions): consolidate and enhance AI artifact guidelines#206agreaves-ms merged 12 commits intomainfrom
agreaves-ms merged 12 commits intomainfrom
Conversation
…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
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
Contributor
There was a problem hiding this comment.
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.mdfiles - 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
approved these changes
Jan 18, 2026
Member
|
@agreaves-ms - really nice work here. |
🤖 - Generated by Copilot
This was referenced Jan 18, 2026
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>
This was referenced Jan 28, 2026
This was referenced Feb 6, 2026
This was referenced Feb 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
ado-create-pull-request.instructions.mdwith clearer reviewer identification and work item linking protocolsado-get-build-info.instructions.mdwith better structured build status retrievalado-update-wit-items.instructions.mdfor work item creation/update workflowsado-wit-discovery.instructions.mdandado-wit-planning.instructions.mdwith improved search patternsNew Terraform Instructions
terraform.instructions.mdfor Infrastructure as Code implementationLanguage-Specific Instruction Consolidation
bash.mdcontent intobash.instructions.md, removed redundant filebicep.mdandbicep-standards.mdinto unifiedbicep.instructions.mdcsharp.instructions.mdandcsharp-tests.instructions.mdwith improved patternspython-script.instructions.mdwith refined guidelinesshell.instructions.md(functionality merged into bash)Prompt Engineering Improvements
prompt-builder.instructions.mdwith clearer authoring standardsprompt-analyze.prompt.mdfor prompt analysis workflowsprompt-build.prompt.mdwith simplified step patternspull-request.prompt.mdwith improved PR generation workflowDocumentation Updates
.github/instructions/README.mdto reflect consolidated structurecopilot-instructions.mdfor improved clarityRelated Issue(s)
N/A - Internal documentation improvement initiative
Type of Change
Select all that apply:
Code & Documentation:
Infrastructure & Configuration:
AI Artifacts:
prompt-builderchatmode and addressed all feedback.github/instructions/*.instructions.md).github/prompts/*.prompt.md).github/chatmodes/*.chatmode.md)Other:
.ps1,.sh,.py)AI Artifacts Modified
ado-create-pull-request.instructions.mdado-get-build-info.instructions.mdado-update-wit-items.instructions.mdado-wit-discovery.instructions.mdado-wit-planning.instructions.mdbash/bash.instructions.mdbash/bash.mdbicep/bicep.instructions.mdbicep/bicep.mdbicep/bicep-standards.mdcsharp/csharp.instructions.mdcsharp/csharp-tests.instructions.mdpython-script.instructions.mdshell.instructions.mdterraform/terraform.instructions.mdprompt-builder.instructions.mdwriting-style.instructions.mdprompt-analyze.prompt.mdprompt-build.prompt.mdpull-request.prompt.mdSample Prompts (for AI Artifact Contributions)
User Request:
"Create a new Terraform module for Azure Key Vault with managed identity access"
Execution Flow:
terraform.instructions.mdwhen working in.tffilesOutput Artifacts:
Success Indicators:
Testing
Checklist
Required Checks
AI Artifact Contributions
prompt-builderchatmode to review contributionprompt-builderreviewRequired Automated Checks
The following validation commands must pass before merging:
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run lint:md-linksnpm run lint:psSecurity Considerations
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