Skip to content

feat(docs): add comprehensive AI artifact contribution documentation#76

Merged
WilliamBerryiii merged 10 commits intomainfrom
feat/ai-artifact-contrib-docs
Nov 20, 2025
Merged

feat(docs): add comprehensive AI artifact contribution documentation#76
WilliamBerryiii merged 10 commits intomainfrom
feat/ai-artifact-contrib-docs

Conversation

@WilliamBerryiii
Copy link
Copy Markdown
Member

feat(docs): add comprehensive AI artifact contribution documentation

Creates comprehensive contribution guidelines for AI artifacts (chatmodes, prompts, instructions) using DRY optimization, enhances PR template with mandatory quality gates, modernizes documentation for current GitHub Copilot UI patterns, and updates development configuration.

  • docs: Created AI artifact contribution documentation with 4 guides (common standards + 3 type-specific) totaling 1,442 lines, eliminating ~500 lines duplication through DRY principles

    • contributing-ai-artifacts-common.md (548 lines) - Single source of truth for XML blocks, markdown quality, RFC 2119 keywords, validation, and attribution
    • contributing-chatmodes.md (357 lines) - Chatmode-specific requirements for frontmatter, file structure, and tool usage
    • contributing-prompts.md (525 lines) - Prompt workflow standards including frontmatter, template variables, and workflow definition
    • contributing-instructions.md (626 lines) - Instructions file guidelines with glob patterns, naming conventions, and code examples
  • feat(prompts): Enhanced PR template requiring prompt-builder agent review for all AI artifact contributions with dual-placement checkbox (type selection + detailed checklist section)

  • docs: Modernized 5 documentation files from deprecated @mention syntax to agent picker dropdown UI pattern

    • Updated README.md, getting-started.md, chatmodes/README.md, instructions/README.md with numbered agent picker steps
    • Added troubleshooting guidance for agent discovery using chat.modeFilesLocations setting
    • Fixed SUPPORT.md table formatting and added performance metrics section
  • chore: Updated development configuration with chat.modeFilesLocations setting for VS Code agent discovery, streamlined package.json by removing 5 security scripts (security:scan, security:scan:staged, security:checkov, security:checkov:report, precommit), added 7 terms to spell-check dictionary (chatagent, docstrings, issubset, isort, mymodule, mypy, sandboxed)

Notes

  • Documentation passes all validation: lint:frontmatter, lint:md, spell-check, lint:md-links
  • VS Code requires reload after .vscode/settings.json changes to discover agents
  • Branch rebased from feat/adr-template-migration onto main for proper PR lineage

Related Issue(s)

Closes #70
Closes #71
Closes #72
Closes #73

Type of Change

Code & Documentation:

  • Documentation 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)

Testing

  • All 4 new documentation files validated using existing linting scripts
  • Verified documentation cross-references resolve to existing files
  • Tested VS Code agent picker with updated chat.modeFilesLocations setting
  • Verified spell-check with added technical terms

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

📚 - Generated by Copilot

Creates comprehensive contribution guides for chatmodes, prompts, and
instructions with DRY optimization. Establishes common standards document
to eliminate ~500 lines duplication per type-specific guide.

Closes #70

📚 Generated by Copilot
Adds mandatory prompt-builder review checkbox to AI Artifacts type selection
and detailed validation checklist for chatmode/prompt/instruction contributions.

Closes #71

✨ Generated by Copilot
Modernizes all documentation from deprecated @mention syntax to current
agent picker dropdown UI. Adds troubleshooting for agent discovery.

Closes #72

📝 Generated by Copilot
Adds chat.modeFilesLocations setting for agent discovery, streamlines
npm scripts by removing security tooling, and adds 7 new dictionary terms.

Closes #73

🔧 Generated by Copilot
Copilot AI review requested due to automatic review settings November 19, 2025 22:29
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Nov 19, 2025

Dependency Review

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

Scanned Files

None

…ashes

Change unordered list markers from asterisks (*) to dashes (-) at lines 64-65 to comply with MD004 markdownlint rule.

📚 - Generated by Copilot
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 PR creates comprehensive contribution guidelines for AI artifacts (chatmodes, prompts, instructions), implementing DRY principles to eliminate ~500 lines of duplication. It modernizes documentation from deprecated @mention syntax to current GitHub Copilot agent picker UI patterns, enhances the PR template with mandatory quality gates for AI artifact contributions, and updates development configuration.

Key Changes:

  • Created 4 AI artifact contribution guides (1,442 lines total) with single source of truth for common standards
  • Updated 5 documentation files to replace @mention syntax with agent picker dropdown instructions
  • Enhanced PR template with AI artifact review checklist and sample prompt requirements
  • Updated VS Code configuration for agent discovery and removed unused security scripts from package.json

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs/contributing-ai-artifacts-common.md Common standards for XML blocks, markdown quality, RFC 2119 keywords, and validation - shared by all AI artifact types
docs/contributing-chatmodes.md Chatmode-specific requirements including frontmatter schema, tool usage patterns, and file format structure
docs/contributing-prompts.md Prompt workflow standards with template variable conventions and workflow definition requirements
docs/contributing-instructions.md Instructions file guidelines including glob patterns, naming conventions, and code pattern examples
README.md Updated chat mode invocation from @mention to agent picker dropdown with numbered steps
docs/getting-started.md Modernized agent discovery instructions with troubleshooting for chat.modeFilesLocations setting
.github/chatmodes/README.md Converted @mention examples to agent picker selection workflow with updated terminology
.github/instructions/README.md Updated prompt-builder references from @mention to agent picker dropdown selection
SUPPORT.md Fixed table column alignment and added performance metrics section with SLO compliance data
.github/PULL_REQUEST_TEMPLATE.md Enhanced with AI artifacts section, sample prompts requirement, and prompt-builder review checkbox
.vscode/settings.json Added chat.modeFilesLocations configuration for VS Code agent discovery
package.json Removed 5 unused security scripts (security:scan, security:checkov, precommit, etc.)
.cspell/general-technical.txt Added 7 technical terms (chatagent, docstrings, issubset, isort, mymodule, mypy, sandboxed)

- remove duplicate 'Issue: Bare URLs' section (lines 429-442)
- clarify fence type description to avoid rendering ambiguity

📝 - Generated by Copilot
- add blank lines around lists in PR template
- convert asterisks to dashes in chatmode lists
- fix table formatting in SUPPORT.md

✨ - Generated by Copilot
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

Copilot reviewed 14 out of 14 changed files in this pull request and generated 16 comments.

- remove fence type requirements from file structure documentation
- fix 4 closing fence examples to use 4 backticks consistently
- consolidate validation checklists by merging file format into frontmatter sections
- apply corrections across all AI artifact contributing guides

📚 - Generated by Copilot
Add guidance for chatmode types that will be rejected:

- Research/discovery, indexing/referencing, planning, implementation agents

- Emphasize existing hardened chatmodes in hve-core

- Callout VS Code GitHub Copilot and MCP tool integration

- Require latest Anthropic (Claude Sonnet 4, Opus 4) and OpenAI (GPT-5.1, o1) models only

✨ - Generated by Copilot
Copilot AI review requested due to automatic review settings November 20, 2025 00:38
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

Copilot reviewed 14 out of 14 changed files in this pull request and generated 9 comments.

- add file format structure section to contributing-instructions.md validation checklist
- fix duplicate heading in contributing-instructions.md
- add blank line in PULL_REQUEST_TEMPLATE.md for list formatting
- update template variable example in contributing-prompts.md to use YAML format

📝 - Generated by Copilot
@WilliamBerryiii WilliamBerryiii merged commit d81cf96 into main Nov 20, 2025
10 checks passed
@WilliamBerryiii WilliamBerryiii deleted the feat/ai-artifact-contrib-docs branch November 20, 2025 01:03
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

4 participants