microsoft · WilliamBerryiii · Nov 27, 2025 · Nov 27, 2025 · Nov 27, 2025
diff --git a/.github/chatmodes/README.md b/.github/chatmodes/README.md
@@ -27,18 +27,18 @@ Specialized GitHub Copilot behaviors for common development workflows. Each chat
 * Type: "Create a plan to add Docker SHA validation"
 * Press Enter
 
-**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see [Getting Started](../../docs/getting-started.md))
+**Requirements:** GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see [Getting Started](../../docs/getting-started/README.md))
 
 ## Available Chat Modes
 
 Select from the **agent picker dropdown** in the Chat view:
 
-| Agent Name           | Purpose                                                          | Key Constraint                              |
-| -------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
+| Agent Name           | Purpose                                                          | Key Constraint                                 |
+| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
 | **task-planner**     | Creates 3-file plan sets (plan, details, prompt)                 | Requires research first; never implements code |
-| **task-researcher**  | Produces research documents with evidence-based recommendations  | Research-only; never plans or implements    |
-| **prompt-builder**   | Engineers and validates instruction/prompt files                 | Dual-persona system with auto-testing       |
-| **pr-review**        | 4-phase PR review with tracking artifacts                        | Review-only; never modifies code            |
+| **task-researcher**  | Produces research documents with evidence-based recommendations  | Research-only; never plans or implements       |
+| **prompt-builder**   | Engineers and validates instruction/prompt files                 | Dual-persona system with auto-testing          |
+| **pr-review**        | 4-phase PR review with tracking artifacts                        | Review-only; never modifies code               |
 
 ## Chat Mode Details
 

diff --git a/.github/instructions/README.md b/.github/instructions/README.md
@@ -60,10 +60,10 @@ resource "azurerm_resource_group" "example" {
 
 ## Available Instructions
 
-| File | Applies To | Purpose |
-|------|------------|---------|
-| [commit-message.instructions.md](commit-message.instructions.md) | `commit` | Conventional commit message format and standards |
-| [markdown.instructions.md](markdown.instructions.md) | `**/*.md` | Markdown formatting standards and style guide |
+| File                                                             | Applies To | Purpose                                          |
+| ---------------------------------------------------------------- | ---------- | ------------------------------------------------ |
+| [commit-message.instructions.md](commit-message.instructions.md) | `commit`   | Conventional commit message format and standards |
+| [markdown.instructions.md](markdown.instructions.md)             | `**/*.md`  | Markdown formatting standards and style guide    |
 
 ## Creating New Instructions
 

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ keywords:
   - conversational workflows
   - chat modes
   - copilot instructions
-estimated_reading_time: 3
+estimated_reading_time: 2
 ---
 
 An open-source library of Hypervelocity Engineering components that accelerates Azure solution development by enabling advanced conversational workflows.
@@ -31,44 +31,33 @@ HVE Core provides a unified set of optimized GitHub Copilot and Microsoft 365 Co
 
 ### Setup
 
-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.md) for step-by-step instructions.
+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.
 
-### Using Chat Modes
+### Try the RPI Workflow
 
-Select specialized AI assistants from the agent picker dropdown in GitHub Copilot Chat:
+Transform complex tasks into working code using Research → Plan → Implement:
 
-1. Open Chat view (Ctrl+Alt+I)
-2. Click the agent picker dropdown at the top
-3. Select your desired agent:
-   * **task-planner** - Plan new features and refactoring
-   * **task-researcher** - Research Azure services and approaches
-   * **prompt-builder** - Create coding instructions and prompts
-   * **pr-review** - Review pull requests comprehensively
+1. Complete the [Your First RPI Workflow](docs/getting-started/first-workflow.md) tutorial (~15 min)
+2. For simple tasks, use [prompts](.github/prompts/README.md) directly without the full workflow
 
-[Learn more about chat modes →](.github/chatmodes/README.md)
+## What's Included
 
-### Using Instructions
-
-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.
-
-[Learn more about instructions →](.github/instructions/README.md)
-
-## Features
-
-* 🤖 **Specialized Chat Modes** - Task planning, research, prompt engineering, and PR reviews
-* 📋 **Coding Instructions** - Repository-specific guidelines that Copilot automatically follows
-* 🚀 **Accelerated Development** - Pre-built workflows for common Azure development tasks
-* 🔄 **Reusable Components** - Curated templates and patterns for consistent solutions
+| Component    | Description                                                          | Documentation                                  |
+|--------------|----------------------------------------------------------------------|------------------------------------------------|
+| Chat Modes   | Specialized AI assistants for research, planning, and implementation | [Chat Modes](.github/chatmodes/README.md)      |
+| Instructions | Repository-specific coding guidelines applied automatically          | [Instructions](.github/instructions/README.md) |
+| Prompts      | Reusable templates for common tasks like commits and PRs             | [Prompts](.github/prompts/README.md)           |
+| Scripts      | Validation tools for linting, security, and quality                  | [Scripts](scripts/README.md)                   |
 
 ## Project Structure
 
 ```text
 .github/
 ├── chatmodes/       # Specialized Copilot chat assistants
 ├── instructions/    # Repository-specific coding guidelines
-└── workflows/       # CI/CD automation
-scripts/
-└── linting/         # Code quality and validation tools
+└── prompts/         # Reusable prompt templates
+docs/                # Learning guides and tutorials
+scripts/             # Validation and development tools
 ```
 
 ## Contributing
@@ -79,14 +68,15 @@ We appreciate contributions! Whether you're fixing typos or adding new component
 2. Check out [open issues](https://github.com/microsoft/hve-core/issues)
 3. Join the [discussion](https://github.com/microsoft/hve-core/discussions)
 
-## Resources
+## Documentation
 
-* [Chat Modes Documentation](.github/chatmodes/README.md)
-* [Instructions Documentation](.github/instructions/README.md)
-* [Contributing Guide](CONTRIBUTING.md)
-* [Code of Conduct](CODE_OF_CONDUCT.md)
-* [Security Policy](SECURITY.md)
-* [Support](SUPPORT.md)
+| Guide                                                    | Description                                  |
+|----------------------------------------------------------|----------------------------------------------|
+| [Getting Started](docs/getting-started/README.md)        | Setup and first workflow tutorial            |
+| [RPI Workflow](docs/rpi/README.md)                       | Deep dive into Research, Plan, Implement     |
+| [Contributing](docs/contributing/README.md)              | Create chat modes, instructions, and prompts |
+| [Chat Modes Reference](.github/chatmodes/README.md)      | All available chat modes                     |
+| [Instructions Reference](.github/instructions/README.md) | All coding instructions                      |
 
 ## Responsible AI
 

diff --git a/docs/contributing/README.md b/docs/contributing/README.md
@@ -0,0 +1,42 @@
+---
+title: Contributing AI Artifacts
+description: Guides for contributing chatmodes, instructions, and prompts to hve-core
+author: Microsoft
+ms.date: 2025-11-26
+ms.topic: overview
+keywords:
+  - contributing
+  - chatmodes
+  - instructions
+  - prompts
+  - ai artifacts
+estimated_reading_time: 2
+---
+
+Guidelines and standards for contributing AI artifacts to hve-core.
+
+## Contribution Guides
+
+| Guide                                      | Description                                                                     |
+|--------------------------------------------|---------------------------------------------------------------------------------|
+| [Common Standards](ai-artifacts-common.md) | Shared conventions, quality gates, and rejection criteria for all contributions |
+| [Chat Modes](chatmodes.md)                 | How to create and submit new chat mode definitions                              |
+| [Instructions](instructions.md)            | How to create repository-specific coding guidelines                             |
+| [Prompts](prompts.md)                      | How to create reusable prompt templates                                         |
+
+## Before You Start
+
+1. Read the [Common Standards](ai-artifacts-common.md) first - it defines quality gates that apply to all artifact types
+2. Check existing artifacts in `.github/` to avoid duplicating functionality
+3. Review the [main Contributing Guide](../../CONTRIBUTING.md) for general contribution process
+
+## Quick Links
+
+- [Chat Modes Directory](../../.github/chatmodes/)
+- [Instructions Directory](../../.github/instructions/)
+- [Prompts Directory](../../.github/prompts/)
+
+---
+
+*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
+then carefully refined by our team of discerning human reviewers.*
diff --git a/docs/contributing-ai-artifacts-common.md → docs/contributing/ai-artifacts-common.md b/docs/contributing-ai-artifacts-common.md → docs/contributing/ai-artifacts-common.md
@@ -1,6 +1,9 @@
 ---
 title: 'AI Artifacts Common Standards'
 description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
+author: Microsoft
+ms.date: 2025-11-26
+ms.topic: reference
 ---
 
 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:
 
 ### Common Resources
 
-* [Contributing Chatmodes](./contributing-chatmodes.md) - Agent configurations
-* [Contributing Prompts](./contributing-prompts.md) - Workflow guidance
-* [Contributing Instructions](./contributing-instructions.md) - Technology standards
-* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist
+* [Contributing Chatmodes](chatmodes.md) - Agent configurations
+* [Contributing Prompts](prompts.md) - Workflow guidance
+* [Contributing Instructions](instructions.md) - Technology standards
+* [Pull Request Template](../../../.github/PULL_REQUEST_TEMPLATE.md) - Submission checklist
 
 ---
 

diff --git a/docs/contributing-chatmodes.md → docs/contributing/chatmodes.md b/docs/contributing-chatmodes.md → docs/contributing/chatmodes.md
@@ -1,11 +1,14 @@
 ---
 title: 'Contributing Chatmodes to HVE Core'
 description: 'Requirements and standards for contributing GitHub Copilot chatmode files to hve-core'
+author: Microsoft
+ms.date: 2025-11-26
+ms.topic: how-to
 ---
 
 This guide defines the requirements, standards, and best practices for contributing GitHub Copilot chatmode files (`.chatmode.md`) to the hve-core library.
 
-**⚙️ Common Standards**: See [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
+**⚙️ Common Standards**: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
 
 ## What is a Chatmode?
 
@@ -236,11 +239,11 @@ Brought to you by microsoft/hve-core
 
 ### XML-Style Block Requirements
 
-See [AI Artifacts Common Standards - XML-Style Block Standards](./contributing-ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.
+See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples.
 
 ### Directive Language Standards
 
-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.
+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.
 
 ## Tool Usage Discipline
 
@@ -316,7 +319,7 @@ Report validation status:
 
 ## Research and External Sources
 
-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.
+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.
 
 ## Validation Checklist
 
@@ -342,9 +345,9 @@ Before submitting your chatmode, verify:
 
 ### Common Standards
 
-* [ ] Markdown quality (see [Common Standards - Markdown Quality](./contributing-ai-artifacts-common.md#markdown-quality-standards))
-* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](./contributing-ai-artifacts-common.md#xml-style-block-standards))
-* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](./contributing-ai-artifacts-common.md#rfc-2119-directive-language))
+* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))
+* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))
+* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))
 
 ### Technical Validation
 
@@ -362,7 +365,7 @@ Before submitting your chatmode, verify:
 
 ## Testing Your Chatmode
 
-See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai-artifacts-common.md#common-testing-practices) for testing guidelines. For chatmodes specifically:
+See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For chatmodes specifically:
 
 1. Test with realistic scenarios matching the agent's purpose
 2. Verify tool usage patterns execute correctly
@@ -378,11 +381,11 @@ See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai
 * **Problem**: Referencing tools that don't exist or using incorrect camelCase variants
 * **Solution**: Use exact tool names from VS Code Copilot's available tools list
 
-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).
+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).
 
 ## Automated Validation
 
-Run these commands before submission (see [Common Standards - Common Validation](./contributing-ai-artifacts-common.md#common-validation-standards)):
+Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):
 
 * `npm run lint:frontmatter`
 * `npm run lint:md`
@@ -393,14 +396,14 @@ All checks **MUST** pass before merge.
 
 ## Related Documentation
 
-* [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) - Shared standards for all contributions
-* [Contributing Prompts](./contributing-prompts.md) - Workflow-specific guidance files
-* [Contributing Instructions](./contributing-instructions.md) - Technology-specific standards
-* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
+* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions
+* [Contributing Prompts](prompts.md) - Workflow-specific guidance files
+* [Contributing Instructions](instructions.md) - Technology-specific standards
+* [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
 
 ## Getting Help
 
-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/`.
+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/`.
 
 ---