Skip to content

Commit c3af708

Browse files
WilliamBerryiiiWilliamBerryiii
authored
feat(docs): add RPI workflow documentation and restructure docs folder (#102)
## Summary Adds comprehensive RPI (Research → Plan → Implement) workflow documentation and restructures the docs folder for better discoverability. ## Changes ### New Documentation Structure - `docs/getting-started/` - Setup guide and first workflow tutorial - `docs/rpi/` - Five RPI workflow articles (overview, researcher, planner, implementor, using-together) - `docs/contributing/` - Consolidated contributing guides ### RPI Workflow Articles | Article | Purpose | |---------|---------| | `README.md` | RPI framework overview and when to use it | | `task-researcher.md` | How to use the Task Researcher chat mode | | `task-planner.md` | How to use the Task Planner chat mode | | `task-implementor.md` | How to use the Task Implementor chat mode | | `using-together.md` | Complete workflow walkthrough with example | ### Getting Started Updates - `first-workflow.md` - Hands-on 15-minute RPI tutorial using PowerShell script creation - `README.md` - Added optional scripts section for users to copy to their projects ### Root README Optimization - Replaced verbose agent list with "Try the RPI Workflow" section - Added "What's Included" table consolidating features - Replaced "Resources" with "Documentation" table linking new guides - Updated project structure to show docs/ and prompts/ ### Linting Fixes - Fixed schema mapping to correctly scope root patterns to repo root - Expanded `ms.topic` enum values in frontmatter schemas (`guide`, `hub-page`, `architecture`, `research`) - Fixed typo: `conceptual` → `concept` in `docs/rpi/README.md` - Fixed grammar and list formatting per Copilot review feedback ## Testing - All markdown files pass `markdownlint-cli2` validation - All files pass `cspell` spelling check - All tables formatted with `npm run format:tables` - All frontmatter passes schema validation with no warnings ## Closes Closes #101 Closes #103 ## Related Work Establishes the primary learning path for new HVE Core users.
1 parent 936ab84 commit c3af708

18 files changed

Lines changed: 1191 additions & 90 deletions

‎.github/chatmodes/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Specialized GitHub Copilot behaviors for common development workflows. Each chat
2727
* Type: "Create a plan to add Docker SHA validation"
2828
* Press Enter
2929

30-
**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see [Getting Started](../../docs/getting-started.md))
30+
**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see [Getting Started](../../docs/getting-started/README.md))
3131

3232
## Available Chat Modes
3333

‎README.md‎

Lines changed: 25 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ keywords:
1212
- conversational workflows
1313
- chat modes
1414
- copilot instructions
15-
estimated_reading_time: 3
15+
estimated_reading_time: 2
1616
---
1717

1818
An open-source library of Hypervelocity Engineering components that accelerates Azure solution development by enabling advanced conversational workflows.
@@ -53,42 +53,35 @@ To use HVE Core's GitHub Copilot customizations in your project, clone this repo
5353
* Git installed and available in PATH
5454
* Node.js and npm (for development and validation)
5555

56-
### Using Chat Modes
56+
### Setup
5757

58-
Select specialized AI assistants from the agent picker dropdown in GitHub Copilot Chat:
58+
To use HVE Core's GitHub Copilot customizations in your project, clone this repository as a sibling to your project and configure a multi-root workspace. See the [Getting Started Guide](docs/getting-started/README.md) for step-by-step instructions.
5959

60-
1. Open Chat view (Ctrl+Alt+I)
61-
2. Click the agent picker dropdown at the top
62-
3. Select your desired agent:
63-
* **task-planner** - Plan new features and refactoring
64-
* **task-researcher** - Research Azure services and approaches
65-
* **prompt-builder** - Create coding instructions and prompts
66-
* **pr-review** - Review pull requests comprehensively
60+
### Try the RPI Workflow
6761

68-
[Learn more about chat modes →](.github/chatmodes/README.md)
62+
Transform complex tasks into working code using Research → Plan → Implement:
6963

70-
### Using Instructions
64+
1. Complete the [Your First RPI Workflow](docs/getting-started/first-workflow.md) tutorial (~15 min)
65+
2. For simple tasks, use [prompts](.github/prompts/README.md) directly without the full workflow
7166

72-
Repository-specific coding guidelines are automatically applied by GitHub Copilot when you edit files. Instructions ensure consistent code style, conventions, and best practices across your codebase without manual intervention.
67+
## What's Included
7368

74-
[Learn more about instructions →](.github/instructions/README.md)
75-
76-
## Features
77-
78-
* 🤖 **Specialized Chat Modes** - Task planning, research, prompt engineering, and PR reviews
79-
* 📋 **Coding Instructions** - Repository-specific guidelines that Copilot automatically follows
80-
* 🚀 **Accelerated Development** - Pre-built workflows for common Azure development tasks
81-
* 🔄 **Reusable Components** - Curated templates and patterns for consistent solutions
69+
| Component | Description | Documentation |
70+
|--------------|----------------------------------------------------------------------|------------------------------------------------|
71+
| Chat Modes | Specialized AI assistants for research, planning, and implementation | [Chat Modes](.github/chatmodes/README.md) |
72+
| Instructions | Repository-specific coding guidelines applied automatically | [Instructions](.github/instructions/README.md) |
73+
| Prompts | Reusable templates for common tasks like commits and PRs | [Prompts](.github/prompts/README.md) |
74+
| Scripts | Validation tools for linting, security, and quality | [Scripts](scripts/README.md) |
8275

8376
## Project Structure
8477

8578
```text
8679
.github/
8780
├── chatmodes/ # Specialized Copilot chat assistants
8881
├── instructions/ # Repository-specific coding guidelines
89-
└── workflows/ # CI/CD automation
90-
scripts/
91-
└── linting/ # Code quality and validation tools
82+
└── prompts/ # Reusable prompt templates
83+
docs/ # Learning guides and tutorials
84+
scripts/ # Validation and development tools
9285
```
9386

9487
## Contributing
@@ -99,14 +92,15 @@ We appreciate contributions! Whether you're fixing typos or adding new component
9992
2. Check out [open issues](https://github.com/microsoft/hve-core/issues)
10093
3. Join the [discussion](https://github.com/microsoft/hve-core/discussions)
10194

102-
## Resources
95+
## Documentation
10396

104-
* [Chat Modes Documentation](.github/chatmodes/README.md)
105-
* [Instructions Documentation](.github/instructions/README.md)
106-
* [Contributing Guide](CONTRIBUTING.md)
107-
* [Code of Conduct](CODE_OF_CONDUCT.md)
108-
* [Security Policy](SECURITY.md)
109-
* [Support](SUPPORT.md)
97+
| Guide | Description |
98+
|----------------------------------------------------------|----------------------------------------------|
99+
| [Getting Started](docs/getting-started/README.md) | Setup and first workflow tutorial |
100+
| [RPI Workflow](docs/rpi/README.md) | Deep dive into Research, Plan, Implement |
101+
| [Contributing](docs/contributing/README.md) | Create chat modes, instructions, and prompts |
102+
| [Chat Modes Reference](.github/chatmodes/README.md) | All available chat modes |
103+
| [Instructions Reference](.github/instructions/README.md) | All coding instructions |
110104

111105
## Responsible AI
112106

‎docs/contributing/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Contributing AI Artifacts
3+
description: Guides for contributing chatmodes, instructions, and prompts to hve-core
4+
author: Microsoft
5+
ms.date: 2025-11-26
6+
ms.topic: overview
7+
keywords:
8+
- contributing
9+
- chatmodes
10+
- instructions
11+
- prompts
12+
- ai artifacts
13+
estimated_reading_time: 2
14+
---
15+
16+
Guidelines and standards for contributing AI artifacts to hve-core.
17+
18+
## Contribution Guides
19+
20+
| Guide | Description |
21+
|--------------------------------------------|---------------------------------------------------------------------------------|
22+
| [Common Standards](ai-artifacts-common.md) | Shared conventions, quality gates, and rejection criteria for all contributions |
23+
| [Chat Modes](chatmodes.md) | How to create and submit new chat mode definitions |
24+
| [Instructions](instructions.md) | How to create repository-specific coding guidelines |
25+
| [Prompts](prompts.md) | How to create reusable prompt templates |
26+
27+
## Before You Start
28+
29+
1. Read the [Common Standards](ai-artifacts-common.md) first - it defines quality gates that apply to all artifact types
30+
2. Check existing artifacts in `.github/` to avoid duplicating functionality
31+
3. Review the [main Contributing Guide](../../CONTRIBUTING.md) for general contribution process
32+
33+
## Quick Links
34+
35+
- [Chat Modes Directory](../../.github/chatmodes/)
36+
- [Instructions Directory](../../.github/instructions/)
37+
- [Prompts Directory](../../.github/prompts/)
38+
39+
---
40+
41+
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
42+
then carefully refined by our team of discerning human reviewers.*

docs/contributing-ai-artifacts-common.md renamed to docs/contributing/ai-artifacts-common.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
---
22
title: 'AI Artifacts Common Standards'
33
description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
4+
author: Microsoft
5+
ms.date: 2025-11-26
6+
ms.topic: reference
47
---
58

69
This document defines shared standards, conventions, and quality gates that apply to **all** AI artifact contributions to hve-core (chatmodes, prompts, and instructions files).
@@ -464,10 +467,10 @@ When contributing AI artifacts:
464467

465468
### Common Resources
466469

467-
* [Contributing Chatmodes](./contributing-chatmodes.md) - Agent configurations
468-
* [Contributing Prompts](./contributing-prompts.md) - Workflow guidance
469-
* [Contributing Instructions](./contributing-instructions.md) - Technology standards
470-
* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist
470+
* [Contributing Chatmodes](chatmodes.md) - Agent configurations
471+
* [Contributing Prompts](prompts.md) - Workflow guidance
472+
* [Contributing Instructions](instructions.md) - Technology standards
473+
* [Pull Request Template](../../../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist
471474

472475
---
473476

docs/contributing-chatmodes.md renamed to docs/contributing/chatmodes.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
---
22
title: 'Contributing Chatmodes to HVE Core'
33
description: 'Requirements and standards for contributing GitHub Copilot chatmode files to hve-core'
4+
author: Microsoft
5+
ms.date: 2025-11-26
6+
ms.topic: how-to
47
---
58

69
This guide defines the requirements, standards, and best practices for contributing GitHub Copilot chatmode files (`.chatmode.md`) to the hve-core library.
710

8-
**⚙️ Common Standards**: See [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
11+
**⚙️ Common Standards**: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
912

1013
## What is a Chatmode?
1114

@@ -236,11 +239,11 @@ Brought to you by microsoft/hve-core
236239

237240
### XML-Style Block Requirements
238241

239-
See [AI Artifacts Common Standards - XML-Style Block Standards](./contributing-ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.
242+
See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.
240243

241244
### Directive Language Standards
242245

243-
Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](./contributing-ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.
246+
Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.
244247

245248
## Tool Usage Discipline
246249

@@ -316,7 +319,7 @@ Report validation status:
316319

317320
## Research and External Sources
318321

319-
When chatmodes integrate external knowledge, consult authoritative sources and provide minimal, annotated snippets with reference links. See [AI Artifacts Common Standards - Attribution Requirements](./contributing-ai-artifacts-common.md#attribution-requirements) for guidelines.
322+
When chatmodes integrate external knowledge, consult authoritative sources and provide minimal, annotated snippets with reference links. See [AI Artifacts Common Standards - Attribution Requirements](ai-artifacts-common.md#attribution-requirements) for guidelines.
320323

321324
## Validation Checklist
322325

@@ -342,9 +345,9 @@ Before submitting your chatmode, verify:
342345

343346
### Common Standards
344347

345-
* [ ] Markdown quality (see [Common Standards - Markdown Quality](./contributing-ai-artifacts-common.md#markdown-quality-standards))
346-
* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](./contributing-ai-artifacts-common.md#xml-style-block-standards))
347-
* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](./contributing-ai-artifacts-common.md#rfc-2119-directive-language))
348+
* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))
349+
* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))
350+
* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))
348351

349352
### Technical Validation
350353

@@ -362,7 +365,7 @@ Before submitting your chatmode, verify:
362365

363366
## Testing Your Chatmode
364367

365-
See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai-artifacts-common.md#common-testing-practices) for testing guidelines. For chatmodes specifically:
368+
See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For chatmodes specifically:
366369

367370
1. Test with realistic scenarios matching the agent's purpose
368371
2. Verify tool usage patterns execute correctly
@@ -378,11 +381,11 @@ See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai
378381
* **Problem**: Referencing tools that don't exist or using incorrect camelCase variants
379382
* **Solution**: Use exact tool names from VS Code Copilot's available tools list
380383

381-
For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](./contributing-ai-artifacts-common.md#common-issues-and-fixes).
384+
For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](ai-artifacts-common.md#common-issues-and-fixes).
382385

383386
## Automated Validation
384387

385-
Run these commands before submission (see [Common Standards - Common Validation](./contributing-ai-artifacts-common.md#common-validation-standards)):
388+
Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):
386389

387390
* `npm run lint:frontmatter`
388391
* `npm run lint:md`
@@ -393,14 +396,14 @@ All checks **MUST** pass before merge.
393396

394397
## Related Documentation
395398

396-
* [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) - Shared standards for all contributions
397-
* [Contributing Prompts](./contributing-prompts.md) - Workflow-specific guidance files
398-
* [Contributing Instructions](./contributing-instructions.md) - Technology-specific standards
399-
* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
399+
* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions
400+
* [Contributing Prompts](prompts.md) - Workflow-specific guidance files
401+
* [Contributing Instructions](instructions.md) - Technology-specific standards
402+
* [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
400403

401404
## Getting Help
402405

403-
See [AI Artifacts Common Standards - Getting Help](./contributing-ai-artifacts-common.md#getting-help) for support resources. For chatmode-specific assistance, review existing examples in `.github/chatmodes/`.
406+
See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For chatmode-specific assistance, review existing examples in `.github/chatmodes/`.
404407

405408
---
406409

docs/contributing-instructions.md renamed to docs/contributing/instructions.md

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
---
22
title: 'Contributing Instructions to HVE Core'
33
description: 'Requirements and standards for contributing GitHub Copilot instruction files to hve-core'
4+
author: Microsoft
5+
ms.date: 2025-11-26
6+
ms.topic: how-to
47
---
58

69
This guide defines the requirements, standards, and best practices for contributing GitHub Copilot instruction files (`.instructions.md`) to the hve-core library.
710

8-
**⚙️ Common Standards**: See [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
11+
**⚙️ Common Standards**: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
912

1013
## What is an Instructions File?
1114

@@ -264,7 +267,7 @@ Brought to you by microsoft/hve-core
264267

265268
### XML-Style Block Requirements
266269

267-
See [AI Artifacts Common Standards - XML-Style Block Standards](./contributing-ai-artifacts-common.md#xml-style-block-standards) for complete rules. Common tags for instructions:
270+
See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules. Common tags for instructions:
268271

269272
* `<!-- <example-{pattern-name}> -->` - Code examples
270273
* `<!-- <convention-{category}> -->` - Convention blocks
@@ -274,7 +277,7 @@ See [AI Artifacts Common Standards - XML-Style Block Standards](./contributing-a
274277

275278
### Directive Language Standards
276279

277-
Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](./contributing-ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.
280+
Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.
278281

279282
## Pattern Definition Standards
280283

@@ -527,9 +530,9 @@ Before submitting your instructions file, verify:
527530

528531
### Common Standards
529532

530-
* [ ] Markdown quality (see [Common Standards - Markdown Quality](./contributing-ai-artifacts-common.md#markdown-quality-standards))
531-
* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](./contributing-ai-artifacts-common.md#xml-style-block-standards))
532-
* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](./contributing-ai-artifacts-common.md#rfc-2119-directive-language))
533+
* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))
534+
* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))
535+
* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))
533536

534537
### Technical Validation
535538

@@ -549,7 +552,7 @@ Before submitting your instructions file, verify:
549552

550553
## Testing Your Instructions
551554

552-
See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically:
555+
See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically:
553556

554557
1. Verify `applyTo` glob pattern matches intended files
555558
2. Test all code examples execute correctly
@@ -570,11 +573,11 @@ See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai
570573
* **Problem**: Multiple instruction files with overlapping glob patterns causing ambiguity
571574
* **Solution**: Make patterns more specific (e.g., `**/tests/**/*.py` vs `**/*.py`) or ensure they target distinct file sets
572575

573-
For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](./contributing-ai-artifacts-common.md#common-issues-and-fixes).
576+
For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](ai-artifacts-common.md#common-issues-and-fixes).
574577

575578
## Automated Validation
576579

577-
Run these commands before submission (see [Common Standards - Common Validation](./contributing-ai-artifacts-common.md#common-validation-standards)):
580+
Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):
578581

579582
* `npm run lint:frontmatter`
580583
* `npm run lint:md`
@@ -585,14 +588,14 @@ All checks **MUST** pass before merge.
585588

586589
## Related Documentation
587590

588-
* [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) - Shared standards for all contributions
589-
* [Contributing Chatmodes](./contributing-chatmodes.md) - AI agent configuration files
590-
* [Contributing Prompts](./contributing-prompts.md) - Workflow-specific guidance
591-
* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
591+
* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions
592+
* [Contributing Chatmodes](chatmodes.md) - AI agent configuration files
593+
* [Contributing Prompts](prompts.md) - Workflow-specific guidance
594+
* [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
592595

593596
## Getting Help
594597

595-
See [AI Artifacts Common Standards - Getting Help](./contributing-ai-artifacts-common.md#getting-help) for support resources. For instructions-specific assistance:
598+
See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For instructions-specific assistance:
596599

597600
* Review existing examples in `.github/instructions/`
598601
* Test glob patterns using file search commands

0 commit comments

Comments
 (0)