Skip to content

Commit d81cf96

Browse files
WilliamBerryiiiWilliamBerryiii
authored
feat(docs): add comprehensive AI artifact contribution documentation (#76)
* docs: create AI artifact contribution documentation 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 * feat(prompts): add prompt-builder review requirement to PR template 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 * docs: update documentation for agent picker UI pattern Modernizes all documentation from deprecated @mention syntax to current agent picker dropdown UI. Adds troubleshooting for agent discovery. Closes #72 📝 Generated by Copilot * chore: update development configuration and spell-check dictionary 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 * fix(chatmodes): correct unordered list style in adr-creation to use dashes Change unordered list markers from asterisks (*) to dashes (-) at lines 64-65 to comply with MD004 markdownlint rule. 📚 - Generated by Copilot * docs: fix duplicate section and clarify fence formatting - remove duplicate 'Issue: Bare URLs' section (lines 429-442) - clarify fence type description to avoid rendering ambiguity 📝 - Generated by Copilot * style: fix markdown linting issues - add blank lines around lists in PR template - convert asterisks to dashes in chatmode lists - fix table formatting in SUPPORT.md ✨ - Generated by Copilot * docs: remove incorrect fence type specs from contributing guides - 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 * feat(docs): add chatmode rejection guidance and model requirements 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 * docs: add file format validation checklist and fix formatting issues - 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
1 parent 380885f commit d81cf96

14 files changed

Lines changed: 2156 additions & 85 deletions

‎.cspell/general-technical.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1451,4 +1451,10 @@ interceptable
14511451
Hypervelocity
14521452
junitxml
14531453
PSScriptAnalyzer
1454-
1454+
chatagent
1455+
docstrings
1456+
issubset
1457+
isort
1458+
mymodule
1459+
mypy
1460+
sandboxed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 73 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,66 @@
77
<!-- Link to the issue(s) this PR addresses using "Fixes #123" or "Closes #123" -->
88

99
## Type of Change
10-
<!-- Check the relevant option(s) -->
11-
- [ ] New instruction file
12-
- [ ] New prompt template
13-
- [ ] New chat mode/agent
14-
- [ ] Script or workflow addition
10+
11+
Select all that apply:
12+
13+
**Code & Documentation:**
14+
15+
- [ ] Bug fix (non-breaking change fixing an issue)
16+
- [ ] New feature (non-breaking change adding functionality)
17+
- [ ] Breaking change (fix or feature causing existing functionality to change)
1518
- [ ] Documentation update
16-
- [ ] Bug fix
19+
20+
**Infrastructure & Configuration:**
21+
22+
- [ ] GitHub Actions workflow
23+
- [ ] Linting configuration (markdown, PowerShell, etc.)
24+
- [ ] Security configuration
25+
- [ ] DevContainer configuration
26+
- [ ] Dependency update
27+
28+
**AI Artifacts:**
29+
30+
- [ ] Reviewed contribution with `prompt-builder` chatmode and addressed all feedback
31+
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
32+
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
33+
- [ ] Copilot chatmode (`.github/chatmodes/*.chatmode.md`)
34+
35+
> **Note for AI Artifact Contributors**:
36+
>
37+
> - **Chatmodes**: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation chatmodes likely already exist. Review `.github/chatmodes/` before creating new ones.
38+
> - **Model Versions**: Only contributions targeting the **latest Anthropic and OpenAI models** will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
39+
> - See [Chatmodes Not Accepted](../docs/contributing-chatmodes.md#chatmodes-not-accepted) and [Model Version Requirements](../docs/contributing-ai-artifacts-common.md#model-version-requirements).
40+
41+
**Other:**
42+
43+
- [ ] Script/automation (`.ps1`, `.sh`, `.py`)
1744
- [ ] Other (please describe):
1845

46+
## Sample Prompts (for AI Artifact Contributions)
47+
48+
<!-- If you checked any boxes under "AI Artifacts" above, provide a sample prompt showing how to use your contribution -->
49+
<!-- Delete this section if not applicable -->
50+
51+
**User Request:**
52+
<!-- What natural language request would trigger this chatmode/prompt/instruction? -->
53+
54+
**Execution Flow:**
55+
<!-- Step-by-step: what happens when invoked? Include tool usage, decision points -->
56+
57+
**Output Artifacts:**
58+
<!-- What files/content are created? Show first 10-20 lines as preview -->
59+
60+
**Success Indicators:**
61+
<!-- How does user know it worked correctly? What validation should they perform? -->
62+
63+
For detailed contribution requirements, see:
64+
65+
- **Common Standards**: [docs/contributing-ai-artifacts-common.md](../docs/contributing-ai-artifacts-common.md) - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
66+
- **Chatmodes**: [docs/contributing-chatmodes.md](../docs/contributing-chatmodes.md) - Agent configurations with tools and behavior patterns
67+
- **Prompts**: [docs/contributing-prompts.md](../docs/contributing-prompts.md) - Workflow-specific guidance with template variables
68+
- **Instructions**: [docs/contributing-instructions.md](../docs/contributing-instructions.md) - Technology-specific standards with glob patterns
69+
1970
## Testing
2071
<!-- Describe how you tested these changes -->
2172

@@ -27,14 +78,25 @@
2778
- [ ] Files follow existing naming conventions
2879
- [ ] Changes are backwards compatible (if applicable)
2980

30-
### Future Automated Checks
31-
<!-- These checks will be automated once package.json and npm scripts are added to the repository -->
32-
- [ ] All linting checks pass (`npm run lint:md`, `npm run spell-check`)
33-
- [ ] Tables are properly formatted (use `npm run format:tables`)
81+
### AI Artifact Contributions
82+
<!-- If contributing a chatmode, prompt, or instruction, complete these checks -->
83+
- [ ] Used `prompt-builder` chatmode to review contribution
84+
- [ ] Addressed all feedback from `prompt-builder` review
85+
- [ ] Verified contribution follows common standards and type-specific requirements
86+
87+
### Required Automated Checks
88+
89+
The following validation commands must pass before merging:
90+
91+
- [ ] Markdown linting: `npm run lint:md`
92+
- [ ] Spell checking: `npm run spell-check`
93+
- [ ] Frontmatter validation: `npm run lint:frontmatter`
94+
- [ ] Link validation: `npm run lint:md-links`
95+
- [ ] PowerShell analysis: `npm run lint:ps`
3496

3597
## Security Considerations
3698
<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys, passwords, or personal data -->
37-
- [ ] This PR does not contain any sensitive information
99+
- [ ] This PR does not contain any sensitive or NDA information
38100
- [ ] Any new dependencies have been reviewed for security issues
39101
- [ ] Security-related scripts follow the principle of least privilege
40102

‎.github/chatmodes/README.md‎

Lines changed: 45 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -17,65 +17,70 @@ Specialized GitHub Copilot behaviors for common development workflows. Each chat
1717

1818
## Quick Start
1919

20-
Invoke chat modes in GitHub Copilot Chat using `@` syntax:
20+
1. Open GitHub Copilot Chat view (Ctrl+Alt+I)
21+
2. Select the desired chat mode from the **agent picker dropdown** at the top of the chat panel
22+
3. Enter your request and press Enter
2123

22-
```markdown
23-
@task-planner Create a plan to add Docker SHA validation
24-
@pr-review Review this pull request for security issues
25-
```
24+
**Example:**
2625

27-
**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension
26+
* Select "task-planner" from dropdown
27+
* Type: "Create a plan to add Docker SHA validation"
28+
* Press Enter
29+
30+
**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see [Getting Started](../../docs/getting-started.md))
2831

2932
## Available Chat Modes
3033

31-
| Chat Mode | Purpose | Key Constraint |
32-
|-----------|---------|----------------|
33-
| `@task-planner` | Creates 3-file plan sets (plan, details, prompt) | Requires research first; never implements code |
34-
| `@task-researcher` | Produces research documents with evidence-based recommendations | Research-only; never plans or implements |
35-
| `@prompt-builder` | Engineers and validates instruction/prompt files | Dual-persona system with auto-testing |
36-
| `@pr-review` | 4-phase PR review with tracking artifacts | Review-only; never modifies code |
34+
Select from the **agent picker dropdown** in the Chat view:
35+
36+
| Agent Name | Purpose | Key Constraint |
37+
| -------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
38+
| **task-planner** | Creates 3-file plan sets (plan, details, prompt) | Requires research first; never implements code |
39+
| **task-researcher** | Produces research documents with evidence-based recommendations | Research-only; never plans or implements |
40+
| **prompt-builder** | Engineers and validates instruction/prompt files | Dual-persona system with auto-testing |
41+
| **pr-review** | 4-phase PR review with tracking artifacts | Review-only; never modifies code |
3742

3843
## Chat Mode Details
3944

40-
### `@task-planner`
45+
### task-planner
4146

4247
**Creates:** Three interconnected files per task:
4348

44-
- Plan checklist: `.copilot-tracking/plans/YYYYMMDD-task-plan.instructions.md`
45-
- Implementation details: `.copilot-tracking/details/YYYYMMDD-task-details.md`
46-
- Implementation prompt: `.copilot-tracking/prompts/implement-task.prompt.md`
49+
* Plan checklist: `.copilot-tracking/plans/YYYYMMDD-task-plan.instructions.md`
50+
* Implementation details: `.copilot-tracking/details/YYYYMMDD-task-details.md`
51+
* Implementation prompt: `.copilot-tracking/prompts/implement-task.prompt.md`
4752

4853
**Workflow:** Validates research → Creates plan files → User implements separately
49-
**Critical:** Automatically calls `@task-researcher` if research missing; treats ALL user input as planning requests (never implements actual code)
54+
**Critical:** Automatically calls task-researcher if research missing; treats ALL user input as planning requests (never implements actual code)
5055

51-
### `@task-researcher`
56+
### task-researcher
5257

5358
**Creates:** Single authoritative research document:
5459

55-
- `.copilot-tracking/research/YYYYMMDD-topic-research.md`
56-
- Subagent files: `.copilot-tracking/research/YYYYMMDD-topic-subagent/task-research.md`
60+
* `.copilot-tracking/research/YYYYMMDD-topic-research.md`
61+
* Subagent files: `.copilot-tracking/research/YYYYMMDD-topic-subagent/task-research.md`
5762

5863
**Workflow:** Deep tool-based research → Document findings → Consolidate to ONE approach → Hand off to planner
5964
**Critical:** Research-only specialist; uses `runSubagent` tool; continuously refines document; never plans or implements
6065

61-
### `@prompt-builder`
66+
### prompt-builder
6267

6368
**Creates:** Instruction files AND prompt files:
6469

65-
- `.github/instructions/*.instructions.md`
66-
- `.copilot-tracking/prompts/*.prompt.md`
70+
* `.github/instructions/*.instructions.md`
71+
* `.copilot-tracking/prompts/*.prompt.md`
6772

6873
**Workflow:** Research sources → Draft → Auto-validate with Prompt Tester → Iterate (up to 3 cycles)
6974
**Critical:** Dual-persona system; uses XML-style blocks (`<!-- <example-*> -->`); links to authoritative sources; minimal inline examples
7075

71-
### `@pr-review`
76+
### pr-review
7277

7378
**Creates:** Review tracking files in normalized branch folders:
7479

75-
- `.copilot-tracking/pr/review/{normalized-branch}/in-progress-review.md`
76-
- `.copilot-tracking/pr/review/{normalized-branch}/pr-reference.xml`
77-
- `.copilot-tracking/pr/review/{normalized-branch}/handoff.md`
78-
- `.copilot-tracking/pr/review/{normalized-branch}/hunk-*.txt`
80+
* `.copilot-tracking/pr/review/{normalized-branch}/in-progress-review.md`
81+
* `.copilot-tracking/pr/review/{normalized-branch}/pr-reference.xml`
82+
* `.copilot-tracking/pr/review/{normalized-branch}/handoff.md`
83+
* `.copilot-tracking/pr/review/{normalized-branch}/hunk-*.txt`
7984

8085
**Workflow:** 4 phases (Initialize → Analyze → Collaborative Review → Finalize)
8186
**Critical:** Review-only; never modifies code; evaluates 8 dimensions (functional correctness, design, idioms, reusability, performance, reliability, security, documentation)
@@ -84,38 +89,38 @@ Invoke chat modes in GitHub Copilot Chat using `@` syntax:
8489

8590
**Planning a Feature:**
8691

87-
1. `@task-researcher` - Create research document with findings
92+
1. Select **task-researcher** from agent picker - Create research document with findings
8893
2. Review research, provide decisions on approach
8994
3. Clear context or start new chat
90-
4. `@task-planner` - Generate 3-file plan set (attach research doc)
95+
4. Select **task-planner** from agent picker - Generate 3-file plan set (attach research doc)
9196
5. Use implementation prompt to execute (separate step)
9297

9398
**Code Review:**
9499

95-
1. `@pr-review` - Automatically runs 4-phase protocol
100+
1. Select **pr-review** from agent picker - Automatically runs 4-phase protocol
96101
2. Collaborate during Phase 3 (review items)
97102
3. Receive `handoff.md` with final PR comments
98103

99104
**Creating Instructions:**
100105

101-
1. `@prompt-builder` - Draft instruction file with conventions
106+
1. Select **prompt-builder** from agent picker - Draft instruction file with conventions
102107
2. Auto-validates with Prompt Tester persona
103108
3. Iterates up to 3 times for quality
104109
4. Delivered to `.github/instructions/`
105110

106111
## Important Notes
107112

108-
- **Linting Exemption:** Files in `.copilot-tracking/**` are exempt from repository linting rules
109-
- **Mode Switching:** User must manually switch between chat modes (e.g., from researcher to planner)
110-
- **Research First:** Task planner requires completed research; will automatically invoke researcher if missing
111-
- **No Implementation:** Task planner and researcher never implement actual project code—only create planning artifacts
113+
* **Linting Exemption:** Files in `.copilot-tracking/**` are exempt from repository linting rules
114+
* **Mode Switching:** User must manually switch between chat modes (e.g., from researcher to planner)
115+
* **Research First:** Task planner requires completed research; will automatically invoke researcher if missing
116+
* **No Implementation:** Task planner and researcher never implement actual project code—only create planning artifacts
112117

113118
## Tips
114119

115-
- Be specific in your requests for better results
116-
- Provide context about what you're working on
117-
- Review generated outputs before using
118-
- Chain modes together for complex tasks
120+
* Be specific in your requests for better results
121+
* Provide context about what you're working on
122+
* Review generated outputs before using
123+
* Chain modes together for complex tasks
119124

120125
---
121126

‎.github/chatmodes/adr-creation.chatmode.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,9 @@ Rather than following rigid steps, adapt your coaching to the user's responses a
6161

6262
**PURPOSE**: Establish final ADR location early to:
6363

64-
* Check for related decisions already documented
65-
* Reference similar ADRs during research phase
66-
* Ensure consistent organization from the start
64+
- Check for related decisions already documented
65+
- Reference similar ADRs during research phase
66+
- Ensure consistent organization from the start
6767

6868
<!-- <dialogue-adr-placement-question> -->
6969
**Dialogue Pattern for Placement Question**:
@@ -106,9 +106,9 @@ This location:
106106

107107
**Capture User Response**:
108108

109-
* Store chosen directory (e.g., `docs/decisions/`, `docs/adr/`)
110-
* Store file naming preference (ISO date prefix is default)
111-
* Acknowledge choice: "Great! We'll plan to finalize your ADR at `[chosen-location]/YYYY-MM-DD-[topic].md`"
109+
- Store chosen directory (e.g., `docs/decisions/`, `docs/adr/`)
110+
- Store file naming preference (ISO date prefix is default)
111+
- Acknowledge choice: "Great! We'll plan to finalize your ADR at `[chosen-location]/YYYY-MM-DD-[topic].md`"
112112

113113
### Phase 2: Collaborative Research and Analysis
114114

@@ -345,11 +345,11 @@ Before moving to final documentation, help users feel confident in their choice:
345345

346346
**Final File Name**:
347347

348-
* Format: `[user-chosen-location]/YYYY-MM-DD-[descriptive-topic]-v01.md`
349-
* Example: `docs/decisions/2025-11-18-api-gateway-selection-v01.md`
350-
* Use current date (ISO 8601 format)
351-
* Topic from core decision discussion
352-
* Version: Start with `-v01`; increment (`-v02`, `-v03`) for revisions or multiple decisions same day
348+
- Format: `[user-chosen-location]/YYYY-MM-DD-[descriptive-topic]-v01.md`
349+
- Example: `docs/decisions/2025-11-18-api-gateway-selection-v01.md`
350+
- Use current date (ISO 8601 format)
351+
- Topic from core decision discussion
352+
- Version: Start with `-v01`; increment (`-v02`, `-v03`) for revisions or multiple decisions same day
353353

354354
**Finalization Steps**:
355355

‎.github/instructions/README.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,12 @@ the codebase.
2929

3030
Chat modes reference and apply instructions automatically:
3131

32-
- **`@prompt-builder`** creates new instruction files in this directory
33-
- **All chat modes** respect instructions matching file patterns via `applyTo`
34-
field
32+
- **prompt-builder** agent creates new instruction files in this directory (select from agent picker dropdown)
33+
- **All chat modes** respect instructions matching file patterns via `applyTo` field
3534
- **Copilot** loads instructions when editing files matching the patterns
3635
- Instructions provide repository-specific guardrails and conventions
3736

38-
See [Chat Modes README](../chatmodes/README.md) for details on using `@prompt-builder`.
37+
See [Chat Modes README](../chatmodes/README.md) for details on using prompt-builder.
3938

4039
## XML-Style Blocks
4140

@@ -70,7 +69,7 @@ resource "azurerm_resource_group" "example" {
7069

7170
### Recommended Approach
7271

73-
1. Use `@prompt-builder` chat mode for creation
72+
1. Open Copilot Chat and select **prompt-builder** from the agent picker dropdown
7473
2. Provide context (files, folders, or requirements)
7574
3. Prompt Builder researches and drafts instructions
7675
4. Auto-validates with Prompt Tester (up to 3 iterations)

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99
".github/instructions/**/*.instructions.md": true,
1010
".github/prompts/**/*.prompt.md": true
1111
},
12+
"chat.modeFilesLocations": {
13+
".github/chatmodes": true
14+
},
1215
"yaml.schemas": {
1316
"./scripts/linting/schemas/root-community-frontmatter.schema.json": [
1417
"README.md",

‎README.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,15 @@ To use HVE Core's GitHub Copilot customizations in your project, clone this repo
3535

3636
### Using Chat Modes
3737

38-
Invoke specialized AI assistants directly in GitHub Copilot Chat:
39-
40-
```text
41-
@task-planner Create a plan for adding authentication to the API
42-
@task-researcher Research Azure service options for document processing
43-
@prompt-builder Create instructions for Terraform infrastructure files
44-
@pr-review Review this pull request for security and design issues
45-
```
38+
Select specialized AI assistants from the agent picker dropdown in GitHub Copilot Chat:
39+
40+
1. Open Chat view (Ctrl+Alt+I)
41+
2. Click the agent picker dropdown at the top
42+
3. Select your desired agent:
43+
* **task-planner** - Plan new features and refactoring
44+
* **task-researcher** - Research Azure services and approaches
45+
* **prompt-builder** - Create coding instructions and prompts
46+
* **pr-review** - Review pull requests comprehensively
4647

4748
[Learn more about chat modes →](.github/chatmodes/README.md)
4849

‎SUPPORT.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ HVE Core is an open-source project maintained by Microsoft and community contrib
3232

3333
**Note**: Response times indicate initial acknowledgment. Resolution time varies based on issue complexity and community availability.
3434

35+
### Our Support Performance
36+
37+
We track our response time commitments publicly. Our performance metrics demonstrate consistent delivery:
38+
39+
* **48-hour SLO Compliance**: High compliance rate with response targets
40+
* **Average PR Completion**: Typically completed within 3 days
41+
* **Fast Resolution**: Significant portion of issues/PRs resolved in under 1 day
42+
3543
## Filing Issues
3644

3745
### General Issues, Bugs, and Feature Requests

0 commit comments

Comments
 (0)