Summary

Create comprehensive contribution guidelines for AI artifacts (chatmodes, prompts, instructions) using DRY principles to consolidate common standards into a shared document with type-specific guides.

Background

Contributors need clear, consistent guidance for submitting chatmodes, prompts, and instructions files to hve-core. Previous documentation had ~500 lines of duplication per file type. This initiative consolidates shared standards while maintaining type-specific requirements.

Objectives

• Establish single source of truth for common AI artifact standards
• Create type-specific guides referencing common standards
• Reduce documentation redundancy while maintaining clarity
• Provide validation checklists and quality gates

Deliverables

• docs/contributing-ai-artifacts-common.md (481 lines) - Common standards for all AI artifacts

  • XML-style block standards
  • Markdown quality requirements
  • RFC 2119 directive language
  • Validation tooling and commands
  • Common testing practices
  • Attribution requirements

• docs/contributing-chatmodes.md (243 lines) - Chatmode-specific guide

  • Frontmatter requirements (description, tools, mode)
  • Agent configuration patterns
  • Tool usage discipline
  • Output formatting standards

• docs/contributing-prompts.md (359 lines) - Prompt-specific guide

  • Workflow definition standards
  • Template variable conventions
  • Decision logic patterns
  • Context requirements

• docs/contributing-instructions.md (359 lines) - Instructions-specific guide

  • Glob pattern guidelines for applyTo field
  • Code example requirements
  • Pattern definition standards
  • Anti-pattern documentation

Acceptance Criteria

• All 4 new documentation files pass validation:
  • npm run lint:frontmatter (PASS)
  • npm run lint:md (PASS)
  • npm run spell-check (PASS)
  • npm run lint:md-links (PASS)
• Cross-references between common and type-specific guides work correctly
• Common standards document eliminates ~500 lines duplication per type-specific guide
• All XML-style blocks properly formatted and closed
• RFC 2119 keywords used consistently throughout

Technical Notes

• Line count reduction: 2,183 lines (previous duplication) → 1,442 lines (optimized) = 34% reduction
• DRY architecture: Common document (481 lines) + 3 type-specific guides (961 lines combined)
• Validation: All files include frontmatter with description field
• Attribution: All files end with "Brought to you by microsoft/hve-core" footer

Related Issues

Part of AI artifact contribution documentation initiative (PR feat/ai-artifact-contrib-docs)