From 70dc77984f42c1b536060f3d724ce4d6397a991e Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 26 Nov 2025 17:11:27 -0800 Subject: [PATCH 1/3] feat(docs): add RPI workflow documentation and optimize getting-started guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add docs/rpi/ with overview, task-researcher, task-planner, task-implementor, using-together guides - restructure docs/getting-started/ with setup README and first-workflow tutorial - add docs/contributing/README.md as folder index - optimize root README with What's Included table and Documentation section - add optional scripts guidance to getting-started README πŸ“š - Generated by Copilot --- .github/chatmodes/README.md | 2 +- README.md | 58 ++--- docs/contributing/README.md | 42 ++++ .../ai-artifacts-common.md} | 8 +- .../chatmodes.md} | 30 +-- .../instructions.md} | 28 +-- .../prompts.md} | 28 +-- .../README.md} | 21 +- docs/getting-started/first-workflow.md | 222 +++++++++++++++++ docs/rpi/README.md | 101 ++++++++ docs/rpi/task-implementor.md | 177 +++++++++++++ docs/rpi/task-planner.md | 160 ++++++++++++ docs/rpi/task-researcher.md | 133 ++++++++++ docs/rpi/using-together.md | 232 ++++++++++++++++++ 14 files changed, 1157 insertions(+), 85 deletions(-) create mode 100644 docs/contributing/README.md rename docs/{contributing-ai-artifacts-common.md => contributing/ai-artifacts-common.md} (97%) rename docs/{contributing-chatmodes.md => contributing/chatmodes.md} (88%) rename docs/{contributing-instructions.md => contributing/instructions.md} (90%) rename docs/{contributing-prompts.md => contributing/prompts.md} (88%) rename docs/{getting-started.md => getting-started/README.md} (70%) create mode 100644 docs/getting-started/first-workflow.md create mode 100644 docs/rpi/README.md create mode 100644 docs/rpi/task-implementor.md create mode 100644 docs/rpi/task-planner.md create mode 100644 docs/rpi/task-researcher.md create mode 100644 docs/rpi/using-together.md diff --git a/.github/chatmodes/README.md b/.github/chatmodes/README.md index 76f3d64..360581d 100644 --- a/.github/chatmodes/README.md +++ b/.github/chatmodes/README.md @@ -27,7 +27,7 @@ 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 diff --git a/README.md b/README.md index e96b28a..37b3f8a 100644 --- 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,34 +31,23 @@ 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 @@ -66,9 +55,9 @@ Repository-specific coding guidelines are automatically applied by GitHub Copilo .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 new file mode 100644 index 0000000..b0143d3 --- /dev/null +++ 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 b/docs/contributing/ai-artifacts-common.md similarity index 97% rename from docs/contributing-ai-artifacts-common.md rename to docs/contributing/ai-artifacts-common.md index fe4f135..9520894 100644 --- a/docs/contributing-ai-artifacts-common.md +++ b/docs/contributing/ai-artifacts-common.md @@ -464,10 +464,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 b/docs/contributing/chatmodes.md similarity index 88% rename from docs/contributing-chatmodes.md rename to docs/contributing/chatmodes.md index fd9b997..81ce9c8 100644 --- a/docs/contributing-chatmodes.md +++ b/docs/contributing/chatmodes.md @@ -5,7 +5,7 @@ description: 'Requirements and standards for contributing GitHub Copilot chatmod 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 +236,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 +316,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 +342,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 +362,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 +378,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 +393,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/`. --- diff --git a/docs/contributing-instructions.md b/docs/contributing/instructions.md similarity index 90% rename from docs/contributing-instructions.md rename to docs/contributing/instructions.md index 986ab24..f876651 100644 --- a/docs/contributing-instructions.md +++ b/docs/contributing/instructions.md @@ -5,7 +5,7 @@ description: 'Requirements and standards for contributing GitHub Copilot instruc This guide defines the requirements, standards, and best practices for contributing GitHub Copilot instruction files (`.instructions.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 an Instructions File? @@ -264,7 +264,7 @@ 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. Common tags for instructions: +See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules. Common tags for instructions: * `` - Code examples * `` - Convention blocks @@ -274,7 +274,7 @@ See [AI Artifacts Common Standards - XML-Style Block Standards](./contributing-a ### 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. ## Pattern Definition Standards @@ -527,9 +527,9 @@ Before submitting your instructions file, 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 @@ -549,7 +549,7 @@ Before submitting your instructions file, verify: ## Testing Your Instructions -See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically: +See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically: 1. Verify `applyTo` glob pattern matches intended files 2. Test all code examples execute correctly @@ -570,11 +570,11 @@ See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai * **Problem**: Multiple instruction files with overlapping glob patterns causing ambiguity * **Solution**: Make patterns more specific (e.g., `**/tests/**/*.py` vs `**/*.py`) or ensure they target distinct file sets -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` @@ -585,14 +585,14 @@ All checks **MUST** pass before merge. ## Related Documentation -* [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) - Shared standards for all contributions -* [Contributing Chatmodes](./contributing-chatmodes.md) - AI agent configuration files -* [Contributing Prompts](./contributing-prompts.md) - Workflow-specific guidance -* [Pull Request Template](../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements +* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions +* [Contributing Chatmodes](chatmodes.md) - AI agent configuration files +* [Contributing Prompts](prompts.md) - Workflow-specific guidance +* [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 instructions-specific assistance: +See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For instructions-specific assistance: * Review existing examples in `.github/instructions/` * Test glob patterns using file search commands diff --git a/docs/contributing-prompts.md b/docs/contributing/prompts.md similarity index 88% rename from docs/contributing-prompts.md rename to docs/contributing/prompts.md index 98cd07f..08527e5 100644 --- a/docs/contributing-prompts.md +++ b/docs/contributing/prompts.md @@ -5,7 +5,7 @@ description: 'Requirements and standards for contributing GitHub Copilot prompt This guide defines the requirements, standards, and best practices for contributing GitHub Copilot prompt files (`.prompt.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 Prompt? @@ -204,7 +204,7 @@ 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. ### Template Variable Standards @@ -236,7 +236,7 @@ assignee: "" ### 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. ## Workflow Definition Standards @@ -430,9 +430,9 @@ Before submitting your prompt, 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)) * [ ] Template variables use `{{snake_case}}` ### Technical Validation @@ -451,7 +451,7 @@ Before submitting your prompt, verify: ## Testing Your Prompt -See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai-artifacts-common.md#common-testing-practices) for testing guidelines. For prompts specifically: +See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For prompts specifically: 1. Follow prompt steps manually to verify workflow logic 2. Test with AI execution using realistic scenarios @@ -472,11 +472,11 @@ See [AI Artifacts Common Standards - Common Testing Practices](./contributing-ai * **Problem**: Vague workflow steps without specific tools, conditions, or decision logic * **Solution**: Provide explicit tool usage, decision trees, and fallback strategies with clear conditional logic -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` @@ -487,14 +487,14 @@ All checks **MUST** pass before merge. ## Related Documentation -* [AI Artifacts Common Standards](./contributing-ai-artifacts-common.md) - Shared standards for all contributions -* [Contributing Chatmodes](./contributing-chatmodes.md) - AI agent configuration 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 Chatmodes](chatmodes.md) - AI agent configuration 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 prompt-specific assistance, review existing examples in `.github/prompts/`. +See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For prompt-specific assistance, review existing examples in `.github/prompts/`. --- diff --git a/docs/getting-started.md b/docs/getting-started/README.md similarity index 70% rename from docs/getting-started.md rename to docs/getting-started/README.md index c8839ef..8c666ff 100644 --- a/docs/getting-started.md +++ b/docs/getting-started/README.md @@ -99,11 +99,26 @@ Check that everything works: **Solution:** Ensure you opened the `.code-workspace` file, not just the folder. The window title should show the workspace name, and both folders should appear in Explorer. +## Optional Scripts + +HVE Core includes utility scripts you may want to copy into your project: + +| Script | Purpose | +|----------------------------------------------------|-----------------------------------------------------| +| `scripts/dev-tools/Generate-PrReference.ps1` | Generate PR reference docs for handoff to reviewers | +| `scripts/linting/Validate-MarkdownFrontmatter.ps1` | Validate markdown frontmatter against JSON schemas | +| `scripts/linting/Invoke-PSScriptAnalyzer.ps1` | Run PSScriptAnalyzer with project settings | +| `scripts/security/Test-DependencyPinning.ps1` | Check GitHub Actions for pinned dependencies | + +Copy the scripts you need to your project's `scripts/` directory and adjust paths as needed. + ## Next Steps -* Explore [Chat Modes](../.github/chatmodes/README.md) for available agents -* Review [Instructions](../.github/instructions/README.md) for coding guidelines -* Check the [README](../README.md) for feature overview +* Try [Your First Workflow](first-workflow.md) for a quick start +* Learn the [RPI Workflow](../rpi/README.md) for complex tasks +* Explore [Chat Modes](../../.github/chatmodes/README.md) for available agents +* Review [Instructions](../../.github/instructions/README.md) for coding guidelines +* Check the [README](../../README.md) for feature overview --- diff --git a/docs/getting-started/first-workflow.md b/docs/getting-started/first-workflow.md new file mode 100644 index 0000000..2ead93c --- /dev/null +++ b/docs/getting-started/first-workflow.md @@ -0,0 +1,222 @@ +--- +title: Your First RPI Workflow +description: Hands-on tutorial using Research, Plan, Implement phases to create a validation script +author: Microsoft +ms.date: 2025-11-26 +ms.topic: tutorial +keywords: + - getting started + - rpi workflow + - github copilot + - tutorial + - powershell script +estimated_reading_time: 10 +--- + +Build a real validation script using the Research β†’ Plan β†’ Implement workflow. You'll create a PowerShell script that checks every docs subfolder has a `README.md` file. + +## Prerequisites + +* VS Code with GitHub Copilot Chat extension +* This repository cloned locally +* Basic familiarity with GitHub Copilot +* ~15 minutes to complete + +## The Task + +You'll create: + +* `scripts/linting/Test-DocsReadme.ps1` - validation script +* npm script entry in `package.json` + +**Why use RPI for this?** Multiple unknowns: existing script patterns, PowerShell conventions, npm integration, output format. Research first reduces guesswork. + +## Before You Start + +**The `/clear` command** resets Copilot's context between phases. Each RPI phase should start freshβ€”the artifacts (research doc, plan) carry the context forward, not the chat history. + +## Phase 1: Research + +### Switch to Task Researcher + +1. Open Copilot Chat (`Ctrl+Alt+I`) +1. Click the chat mode dropdown at the top +1. Select **Task Researcher** + +### Your Research Prompt + +Copy and paste this prompt: + +```text +Research what's needed to create a PowerShell script for this repository that +validates every subfolder under docs/ contains a README.md file. + +Consider: +- Existing PowerShell script patterns in scripts/linting/ +- PSScriptAnalyzer conventions and settings +- How npm scripts are structured in package.json +- Expected output format (exit codes, messages) +``` + +### What You'll Get + +Task Researcher analyzes the codebase and returns findings about: + +* Existing PowerShell scripts and their patterns +* PSScriptAnalyzer settings and conventions +* Current npm scripts structure +* Recommended output format + +### Key Findings to Note + +From the research output, identify: + +| Finding | Example | +|-------------------------|-----------------------------------------------| +| Script location pattern | `scripts/linting/*.ps1` | +| Naming convention | `Verb-Noun.ps1` (e.g., `Test-DocsReadme.ps1`) | +| npm script pattern | `"name": "pwsh scripts/path.ps1"` | +| Exit codes | `exit 0` = success, `exit 1` = failure | + +## Phase 2: Plan + +### Clear and Switch + +1. Type `/clear` in the chat to reset context +1. Click the chat mode dropdown +1. Select **Task Planner** + +### Your Planning Prompt + +Copy and paste this prompt (include findings from Phase 1): + +```text +Create an implementation plan to add a README validation script. + +Requirements from research: +- Script location: scripts/linting/Test-DocsReadme.ps1 +- Follow PowerShell conventions (Verb-Noun naming, comment-based help) +- Add npm script "check:docs-readme" to package.json +- Exit 0 on success, exit 1 on failure +- Output list of folders missing README.md +``` + +### Plan Output + +Task Planner creates a structured plan with: + +* File creation steps +* Implementation details for each file +* Validation criteria + +### Your Plan Should Include + +1. Create `scripts/linting/Test-DocsReadme.ps1` with: + * Find all immediate subdirectories of `docs/` + * Check each has `README.md` + * Print missing folders + * Exit with appropriate code + +1. Update `package.json`: + * Add `"check:docs-readme"` script + +## Phase 3: Implement + +### Clear and Switch to Implementor + +1. Type `/clear` in the chat to reset context +1. Click the chat mode dropdown +1. Select **Task Implementor** + +### Your Implementation Prompt + +Copy and paste this prompt: + +```text +Implement this plan to add README validation. + +Plan: +1. Create scripts/linting/Test-DocsReadme.ps1 + - Include comment-based help + - Find all immediate subdirectories of docs/ + - Check each has README.md + - Print missing folders with clear messaging + - Exit 0 if all pass, exit 1 if any missing + +2. Update package.json + - Add "check:docs-readme": "pwsh scripts/linting/Test-DocsReadme.ps1" +``` + +### Watch It Work + +Task Implementor will: + +1. Create the PowerShell script with proper structure +1. Update `package.json` with the npm script +1. Show you each file change for approval + +Confirm each tool call when prompted. + +## Verify Your Work + +### Run the Script + +```powershell +npm run check:docs-readme +``` + +### Expected Output (Success) + +```text +Checking docs subfolders for README.md... +βœ“ docs/contributing/README.md +βœ“ docs/getting-started/README.md +βœ“ docs/rpi/README.md + +All docs subfolders have README.md +``` + +### Test Failure Detection + +Temporarily rename a README to see the failure case: + +```powershell +Rename-Item docs/rpi/README.md README.md.bak +npm run check:docs-readme +Rename-Item docs/rpi/README.md.bak README.md +``` + +## What You Learned + +* **Phase separation** - `/clear` between phases prevents context pollution +* **Research reduces unknowns** - You discovered patterns before coding +* **Plans are specifications** - The plan gave Implementor clear requirements +* **Artifacts bridge phases** - Findings and plans carry context, not chat history + +## Troubleshooting + +| Issue | Solution | +|-----------------------|----------------------------------------| +| PowerShell not found | Ensure `pwsh` is installed and in PATH | +| npm script not found | Check `package.json` was saved | +| Wrong folders checked | Verify script targets `docs/*` pattern | + +## Next Steps + +* **Complex multi-file tasks** - See [RPI Workflow Overview](../rpi/README.md) +* **Simple tasks** - Skip RPI and use prompts directly +* **Contribute** - Read [Contributing Guide](../contributing/README.md) + +## Resources + +| Resource | Description | +|------------------------------------------------|-----------------------------------| +| [RPI Overview](../rpi/README.md) | Full RPI workflow documentation | +| [Task Researcher](../rpi/task-researcher.md) | Deep dive on research phase | +| [Task Planner](../rpi/task-planner.md) | Deep dive on planning phase | +| [Task Implementor](../rpi/task-implementor.md) | Deep dive on implementation phase | + +--- + +*πŸ€– Crafted with precision by ✨Copilot following brilliant human instruction, +then carefully refined by our team of discerning human reviewers.* diff --git a/docs/rpi/README.md b/docs/rpi/README.md new file mode 100644 index 0000000..c3e2935 --- /dev/null +++ b/docs/rpi/README.md @@ -0,0 +1,101 @@ +--- +title: Understanding the RPI Workflow +description: Learn the Research, Plan, Implement workflow for transforming complex tasks into working code +author: Microsoft +ms.date: 2025-01-28 +ms.topic: conceptual +keywords: + - rpi workflow + - task researcher + - task planner + - task implementor + - github copilot +estimated_reading_time: 4 +--- + +The RPI (Research, Plan, Implement) workflow transforms complex coding tasks into working solutions through three structured phases. Think of it as a type transformation pipeline: + +> Uncertainty β†’ Knowledge β†’ Strategy β†’ Working Code + +## Why Use RPI? + +Traditional AI coding assistants work well for simple tasks but struggle with complex, multi-file changes. Without structure: + +* AI makes assumptions instead of investigating +* Context gets polluted with accumulated guesses +* Implementation details contradict earlier decisions +* You spend time correcting rather than building + +RPI solves this by separating concerns into distinct phases, each with its own specialized chat mode. + +## The Three Phases + +### πŸ” Research Phase (Task Researcher) + +**Purpose:** Transform uncertainty into verified knowledge + +* Investigates codebase, external APIs, and documentation +* Documents findings with evidence and sources +* Creates ONE recommended approach per scenario +* **Output:** `YYYYMMDD--research.md` + +### πŸ“‹ Plan Phase (Task Planner) + +**Purpose:** Transform knowledge into actionable strategy + +* Creates coordinated planning files with checkboxes and details +* Includes line number references for precision +* Validates research exists before proceeding +* **Output:** Plan, details, and implementation prompt files + +### ⚑ Implement Phase (Task Implementor) + +**Purpose:** Transform strategy into working code + +* Executes plan task by task with verification +* Tracks all changes in a changes log +* Supports stop controls for review +* **Output:** Working code + `YYYYMMDD--changes.md` + +## The Critical Rule: Clear Context Between Phases + +πŸ”΄ **Always use `/clear` or start a new chat between phases.** + +Each chat mode has different instructions. Accumulated context causes confusion: + +```text +Task Researcher β†’ /clear β†’ Task Planner β†’ /clear β†’ Task Implementor +``` + +Research findings are preserved in files, not chat history. Clean context lets each mode work optimally. + +## When to Use RPI + +| Use RPI When... | Use Quick Edits When... | +|--------------------------------|-------------------------| +| Changes span multiple files | Fixing a typo | +| Learning new patterns/APIs | Adding a log statement | +| External dependencies involved | Refactoring < 50 lines | +| Requirements are unclear | Change is obvious | + +**Rule of Thumb:** If you need to understand something before implementing, use RPI. + +## Quick Start + +1. **Define the problem** clearly +2. **Research** using Task Researcher chat mode +3. **Clear context** with `/clear` +4. **Plan** using Task Planner chat mode +5. **Clear context** with `/clear` +6. **Implement** using Task Implementor chat mode + +## Next Steps + +* [Task Researcher Guide](task-researcher.md) - Deep dive into research phase +* [Task Planner Guide](task-planner.md) - Create actionable plans +* [Task Implementor Guide](task-implementor.md) - Execute with precision +* [Using Them Together](using-together.md) - Complete workflow example + +--- + +πŸ€– *Crafted with precision by ✨Copilot using the RPI workflow* diff --git a/docs/rpi/task-implementor.md b/docs/rpi/task-implementor.md new file mode 100644 index 0000000..fc39a92 --- /dev/null +++ b/docs/rpi/task-implementor.md @@ -0,0 +1,177 @@ +--- +title: Task Implementor Guide +description: Use the Task Implementor chat mode to execute implementation plans with precision and tracking +author: Microsoft +ms.date: 2025-01-28 +ms.topic: tutorial +keywords: + - task implementor + - rpi workflow + - implementation phase + - github copilot +estimated_reading_time: 4 +--- + +The Task Implementor chat mode transforms planning files into working code. It executes plans task by task, tracks all changes, and supports stop controls for review between phases. + +## When to Use Task Implementor + +Use Task Implementor after completing planning when you need: + +* ⚑ **Precise execution** following the plan exactly +* πŸ“ **Change tracking** documenting all modifications +* ⏸️ **Stop controls** for review between phases +* βœ… **Verification** that success criteria are met + +## What Task Implementor Does + +1. **Reads** the plan phase by phase, task by task +2. **Loads** only needed details using line ranges +3. **Implements** code following workspace conventions +4. **Tracks** changes in a changes log +5. **Verifies** success criteria before marking complete +6. **Pauses** at stop points for your review + +## Output Artifacts + +Task Implementor creates working code and a changes log: + +```text +.copilot-tracking/ +└── changes/ + └── YYYYMMDD--changes.md # Log of all changes made +``` + +Plus all the actual code files created or modified during implementation. + +## How to Use Task Implementor + +### Step 1: Clear Context + +πŸ”΄ **Start with `/clear` or a new chat** after Task Planner completes. + +### Step 2: Select the Chat Mode + +1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) +2. Click the chat mode dropdown +3. Select **Task Implementor** + +### Step 3: Reference Your Plan + +Provide the path to your plan file or use the generated implementation prompt. + +### Step 4: Set Stop Controls + +Choose your review cadence: + +* `phaseStop=true` (default): Pause after each phase +* `taskStop=true`: Pause after each task +* Both false: Run to completion + +### Step 5: Review and Continue + +At each stop point: + +1. Review the changes made +2. Verify code compiles and lints +3. Approve or request adjustments +4. Continue to next phase/task + +## Example Prompt + +```text +Implement the plan from .copilot-tracking/plans/20250128-blob-storage-plan.instructions.md. +Use phaseStop=true so I can review the storage client before you implement the writer. +``` + +**Or use the generated prompt:** + +```text +@workspace /implement-blob-storage +``` + +## Understanding Stop Controls + +### Phase Stop (Default: true) + +Pauses after completing all tasks in a phase: + +```text +Phase 1: [x] Task 1.1, [x] Task 1.2 β†’ STOP for review +Phase 2: [ ] Task 2.1, [ ] Task 2.2 +``` + +### Task Stop (Default: false) + +Pauses after each individual task: + +```text +Phase 1: [x] Task 1.1 β†’ STOP + [ ] Task 1.2 +``` + +## Tips for Better Implementation + +βœ… **Do:** + +* Review changes at each stop point +* Run linters and validators +* Check that success criteria are met +* Ask for adjustments before continuing + +❌ **Don't:** + +* Skip reviewing changes +* Ignore failing tests or lints +* Rush through all phases without checking + +## The Changes Log + +Task Implementor maintains a changes log with sections: + +```markdown +## Changes + +### Added +* src/storage/blob_client.py - Azure Blob Storage client class + +### Modified +* src/pipeline/config.py - Added blob storage configuration + +### Removed +* (none this implementation) +``` + +## At Completion + +When all phases are complete, Task Implementor provides: + +1. **Summary** of all changes from the changes log +2. **Links** to planning files for cleanup +3. **Recommendation** to review and commit + +## Common Pitfalls + +| Pitfall | Solution | +|-------------------------|------------------------------------------| +| Plan not found | Complete Task Planner first | +| Skipping reviews | Use phaseStop=true for important changes | +| Not running validations | Check lint/test after each phase | + +## Next Steps + +After Task Implementor completes: + +1. **Review** the changes log and all modified files +2. **Run** any validation commands (lint, test, build) +3. **Commit** your changes with a descriptive message +4. πŸ”΄ **Delete prompt file** - Prompt cleanup is MANDATORY after implementation +5. **Clean up** other planning files if no longer needed + +For your next task, you can start the RPI workflow again with Task Researcher. + +> ⚠️ **Important**: Task Implementor requires deleting the implementation prompt file (`.copilot-tracking/prompts/implement-*.prompt.md`) after completion. This is enforced by the chatmode to prevent stale prompts from accumulating. + +--- + +πŸ€– *Crafted with precision by ✨Copilot using the RPI workflow* diff --git a/docs/rpi/task-planner.md b/docs/rpi/task-planner.md new file mode 100644 index 0000000..0143039 --- /dev/null +++ b/docs/rpi/task-planner.md @@ -0,0 +1,160 @@ +--- +title: Task Planner Guide +description: Use the Task Planner chat mode to create actionable implementation plans from research findings +author: Microsoft +ms.date: 2025-01-28 +ms.topic: tutorial +keywords: + - task planner + - rpi workflow + - planning phase + - github copilot +estimated_reading_time: 4 +--- + +The Task Planner chat mode transforms research findings into actionable implementation plans. It creates coordinated planning files with checkboxes, detailed specifications, and line number references for precise execution. + +## When to Use Task Planner + +Use Task Planner after completing research when you need: + +* πŸ“‹ **Structured implementation steps** with clear checkboxes +* πŸ“ **Detailed specifications** for each task +* πŸ”— **Cross-references** to research findings +* ⏱️ **Phased execution** with dependencies + +## What Task Planner Does + +1. **Validates** that research exists (MANDATORY first step) +2. **Creates** three coordinated planning files +3. **Links** specifications to research with line numbers +4. **Organizes** tasks into logical phases with dependencies +5. **Generates** an implementation prompt for Task Implementor + +## Output Artifacts + +Task Planner creates three files: + +```text +.copilot-tracking/ +β”œβ”€β”€ plans/ +β”‚ └── YYYYMMDD--plan.instructions.md # Checklist with phases +β”œβ”€β”€ details/ +β”‚ └── YYYYMMDD--details.md # Specifications for each task +└── prompts/ + └── implement-.prompt.md # Execution instructions +``` + +### Plan File + +Contains checkboxes for phases and tasks, references to details with line numbers. + +### Details File + +Contains specifications for each task: files to modify, success criteria, research references. + +### Implementation Prompt + +Contains step-by-step instructions for Task Implementor, including stop controls. + +## How to Use Task Planner + +### Step 1: Clear Context + +πŸ”΄ **Start with `/clear` or a new chat** after Task Researcher completes. + +### Step 2: Select the Chat Mode + +1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) +2. Click the chat mode dropdown +3. Select **Task Planner** + +### Step 3: Reference Your Research + +Provide the path to your research document and any additional context. + +### Step 4: Review the Plan + +Task Planner will create all three files. Review: + +* Are phases in logical order? +* Do tasks have clear success criteria? +* Are dependencies correctly identified? + +## Example Prompt + +```text +Using the research from .copilot-tracking/research/20250128-blob-storage-research.md, +create an implementation plan for adding Azure Blob Storage integration. + +Focus on: +- The streaming upload approach recommended in the research +- Phased rollout: storage client first, then writer class, then tests +- Include error handling and retry logic in each phase +``` + +## Tips for Better Plans + +βœ… **Do:** + +* Reference specific research document +* Mention which recommended approach to use +* Suggest logical phases if you have preferences +* Include any additional constraints + +❌ **Don't:** + +* Skip the research phase +* Ask for implementation (that's next step) +* Ignore the planning files once created + +## Understanding the Plan Structure + +### Phases + +High-level groupings of related work: + +```markdown +### [ ] Phase 1: Storage Client Setup +### [ ] Phase 2: Writer Implementation +### [ ] Phase 3: Integration Testing +``` + +### Tasks + +Specific work items within phases: + +```markdown +* [ ] Task 1.1: Create BlobStorageClient class + * Details: .copilot-tracking/details/20250128-blob-storage-details.md (Lines 10-25) +``` + +### Line References + +Every task references exact lines in the details file, which in turn references research: + +```text +Plan β†’ Details (Lines X-Y) β†’ Research (Lines A-B) +``` + +## Common Pitfalls + +| Pitfall | Solution | +|----------------------|--------------------------------------| +| Research not found | Complete Task Researcher first | +| Phases too large | Break into smaller, verifiable tasks | +| Missing dependencies | Review task order and prerequisites | + +## Next Steps + +After Task Planner completes: + +1. **Review** all three planning files +2. **Clear context** using `/clear` or starting a new chat +3. **Proceed to implementation** with [Task Implementor](task-implementor.md) + +Use the generated implementation prompt (`.copilot-tracking/prompts/implement-*.prompt.md`) with Task Implementor. + +--- + +πŸ€– *Crafted with precision by ✨Copilot using the RPI workflow* diff --git a/docs/rpi/task-researcher.md b/docs/rpi/task-researcher.md new file mode 100644 index 0000000..3cc6fae --- /dev/null +++ b/docs/rpi/task-researcher.md @@ -0,0 +1,133 @@ +--- +title: Task Researcher Guide +description: Use the Task Researcher chat mode to conduct deep, evidence-based research before coding +author: Microsoft +ms.date: 2025-01-28 +ms.topic: tutorial +keywords: + - task researcher + - rpi workflow + - research phase + - github copilot +estimated_reading_time: 4 +--- + +The Task Researcher chat mode transforms uncertainty into verified knowledge through deep, autonomous research. It investigates your codebase, external documentation, and APIs to create evidence-backed recommendations. + +## When to Use Task Researcher + +Escalate to Task Researcher when your task involves: + +* πŸ”„ **Multi-file changes** requiring coordination +* πŸ“š **New patterns or frameworks** you haven't used before +* πŸ”Œ **External API integrations** with authentication or complex workflows +* ❓ **Unclear requirements** needing investigation +* πŸ—οΈ **Architecture decisions** affecting multiple components + +## What Task Researcher Does + +1. **Investigates** using workspace search, file reads, and external tools +2. **Documents** findings with evidence, sources, and line references +3. **Evaluates** alternatives with benefits and trade-offs +4. **Recommends** ONE approach per technical scenario +5. **Outputs** a comprehensive research document + +## Output Artifact + +Task Researcher creates a research document at: + +```text +.copilot-tracking/research/YYYYMMDD--research.md +``` + +This document includes: + +* Scope and success criteria +* Evidence log with sources +* Code examples from the codebase +* External research findings +* Recommended approach with rationale + +## How to Use Task Researcher + +### Step 1: Select the Chat Mode + +1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) +2. Click the chat mode dropdown at the top +3. Select **Task Researcher** + +### Step 2: Describe Your Task + +Provide context about what you're trying to accomplish. Be specific about: + +* The problem you're solving +* Technologies or patterns involved +* Any constraints or requirements + +### Step 3: Let It Research + +Task Researcher works autonomously for 20-60 minutes. It will: + +* Search your codebase for patterns +* Read relevant files and documentation +* Use external tools (Context7, Azure docs, etc.) +* Create the research document + +### Step 4: Review the Research + +When complete, Task Researcher provides: + +* Summary of key findings +* Location of the research document +* Next steps for planning phase + +## Example Prompt + +```text +I need to add Azure Blob Storage integration to our Python data pipeline. +The pipeline currently writes to local disk in src/pipeline/writers/. +Research: +- Azure SDK for Python blob storage options +- Authentication approaches (managed identity vs connection string) +- Streaming uploads for files > 1GB +- Error handling and retry patterns + +Focus on approaches that match our existing patterns in the codebase. +``` + +## Tips for Better Research + +βœ… **Do:** + +* Provide specific technical context +* Mention existing code patterns to match +* List specific questions to answer +* Include constraints (performance, security, etc.) + +❌ **Don't:** + +* Ask for implementation (that's Task Implementor's job) +* Skip research for complex tasks +* Provide vague descriptions + +## Common Pitfalls + +| Pitfall | Solution | +|----------------------|--------------------------------------------------| +| Research too broad | Focus on specific technical questions | +| Skipping research | Always research multi-file or unfamiliar changes | +| Not reviewing output | Read the research doc before planning | + +## Next Steps + +After Task Researcher completes: + +1. **Review** the research document in `.copilot-tracking/research/` +2. **Clear context** using `/clear` or starting a new chat +3. **Proceed to planning** with [Task Planner](task-planner.md) + +Pass the research document path to Task Planner so it can create an actionable implementation plan. + +--- + +πŸ€– *Crafted with precision by ✨Copilot using the RPI workflow* diff --git a/docs/rpi/using-together.md b/docs/rpi/using-together.md new file mode 100644 index 0000000..160431a --- /dev/null +++ b/docs/rpi/using-together.md @@ -0,0 +1,232 @@ +--- +title: Using RPI Modes Together +description: Complete walkthrough of the RPI workflow from research through implementation +author: Microsoft +ms.date: 2025-01-28 +ms.topic: tutorial +keywords: + - rpi workflow + - task researcher + - task planner + - task implementor + - complete workflow +estimated_reading_time: 5 +--- + +This guide walks through a complete RPI workflow, showing how the three chat modes work together to transform a complex task into working code. + +## The Complete Workflow + +```text +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” /clear β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” /clear β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Task Researcher β”‚ ──────────→ β”‚ Task Planner β”‚ ──────────→ β”‚ Task Implementorβ”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ Uncertainty β”‚ β”‚ Knowledge β”‚ β”‚ Strategy β”‚ +β”‚ ↓ β”‚ β”‚ ↓ β”‚ β”‚ ↓ β”‚ +β”‚ Knowledge β”‚ β”‚ Strategy β”‚ β”‚ Working Code β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ ↓ ↓ + research.md plan.md + details.md code + changes.md +``` + +## Critical Rule: Clear Context + +πŸ”΄ **Use `/clear` or start a new chat between EVERY phase.** + +Why this matters: + +* Each mode has different instructions and behaviors +* Accumulated context causes confusion and errors +* Research findings are in files, not chat history +* Clean context lets each mode work optimally + +## Walkthrough: Adding Azure Blob Storage + +Let's walk through adding Azure Blob Storage to a Python data pipeline. + +### Phase 1: Research + +1. Select Task Researcher mode +2. Submit your research request: + +```text +I need to add Azure Blob Storage integration to our Python data pipeline. +The pipeline currently writes to local disk in src/pipeline/writers/. + +Research: +- Azure SDK for Python blob storage options +- Authentication approaches (managed identity vs connection string) +- Streaming uploads for files > 1GB +- Error handling and retry patterns + +Focus on approaches that match our existing patterns in the codebase. +``` + +1. Wait for completion (20-60 minutes). Task Researcher will: + + * Search your codebase for existing patterns + * Research Azure SDK documentation + * Evaluate authentication options + * Create a research document with recommendations + +1. Review the output: + +```text +## **Task Researcher**: Deep Analysis of Azure Blob Storage Integration + +βœ… Research document created at: +.copilot-tracking/research/20250128-blob-storage-research.md + +Key findings: +- Recommended: azure-storage-blob SDK with async streaming +- Authentication: Managed identity for production, connection string for dev +- Existing pattern: WriterBase class in src/pipeline/writers/base.py +``` + +### Phase 2: Plan + +1. Clear context: `/clear` +1. Select Task Planner mode +1. Submit your planning request: + + ```text + Using the research from .copilot-tracking/research/20250128-blob-storage-research.md, + create an implementation plan for adding Azure Blob Storage integration. + + Focus on: + - The streaming upload approach recommended in the research + - Phased rollout: storage client first, then writer class, then integration + - Include error handling and retry logic + ``` + +1. Review the output. Task Planner creates three files: + + ```text + .copilot-tracking/plans/20250128-blob-storage-plan.instructions.md + .copilot-tracking/details/20250128-blob-storage-details.md + .copilot-tracking/prompts/implement-blob-storage.prompt.md + ``` + +1. Verify the plan structure: + +```markdown +### [ ] Phase 1: Storage Client Setup +* [ ] Task 1.1: Create BlobStorageClient class +* [ ] Task 1.2: Add configuration schema + +### [ ] Phase 2: Writer Implementation +* [ ] Task 2.1: Create BlobWriter extending WriterBase +* [ ] Task 2.2: Implement streaming upload + +### [ ] Phase 3: Integration +* [ ] Task 3.1: Update pipeline factory +* [ ] Task 3.2: Add integration tests +``` + +### Phase 3: Implement + +1. Clear context: `/clear` +1. Select Task Implementor mode +1. Submit your implementation request: + + ```text + Implement the plan from .copilot-tracking/plans/20250128-blob-storage-plan.instructions.md. + Use phaseStop=true so I can review after each phase. + ``` + +1. Review at each phase. After Phase 1 completes: + +```text +Phase 1 complete. Changes: +- Added: src/storage/blob_client.py +- Modified: src/config/schema.py + +Ready for review. Continue to Phase 2? +``` + +Check the code, run linters, then continue. + +**5. Final output:** + +When all phases complete: + +```text +Implementation complete! + +Changes log: .copilot-tracking/changes/20250128-blob-storage-changes.md + +Files created (3): +- src/storage/blob_client.py +- src/pipeline/writers/blob_writer.py +- tests/integration/test_blob_writer.py + +Files modified (2): +- src/config/schema.py +- src/pipeline/factory.py + +Ready for commit. Planning files can be cleaned up. +``` + +## Artifact Summary + +After completing RPI, you have: + +| Artifact | Location | Purpose | +|----------|-------------------------------|------------------------------| +| Research | `.copilot-tracking/research/` | Evidence and recommendations | +| Plan | `.copilot-tracking/plans/` | Checkboxes and phases | +| Details | `.copilot-tracking/details/` | Task specifications | +| Prompt | `.copilot-tracking/prompts/` | Execution instructions | +| Changes | `.copilot-tracking/changes/` | Change log | +| Code | Your source directories | Working implementation | + +## Common Patterns + +### Iterating on Research + +If implementation reveals missing research: + +1. Note the gap in your current session +2. Clear context +3. Return to Task Researcher +4. Research the specific gap +5. Update plan if needed +6. Continue implementation + +### Handling Complex Tasks + +For very large tasks: + +1. Break into multiple RPI cycles +2. Each cycle handles one component +3. Use research from previous cycles +4. Build incrementally + +### Team Handoffs + +RPI artifacts support handoffs: + +* Research doc explains decisions +* Plan shows remaining work +* Changes log shows what's done + +## Quick Reference + +| Phase | Mode | Input | Output | +|-----------|------------------|---------------------|--------------------------------| +| Research | Task Researcher | Problem description | research.md | +| Plan | Task Planner | Research doc path | plan.md, details.md, prompt.md | +| Implement | Task Implementor | Plan path | code + changes.md | + +Remember: **Always `/clear` between phases!** + +## Related Guides + +* [RPI Overview](README.md) - Understand the workflow +* [Task Researcher](task-researcher.md) - Deep research phase +* [Task Planner](task-planner.md) - Create actionable plans +* [Task Implementor](task-implementor.md) - Execute with precision + +--- + +πŸ€– *Crafted with precision by ✨Copilot using the RPI workflow* From 7ab348582eb070de28fd1e0cf0fd8f5c788fc831 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 26 Nov 2025 18:40:06 -0800 Subject: [PATCH 2/3] fix(linting): resolve Copilot review feedback and schema validation issues - Fix inconsistent list format in using-together.md - Add missing conjunction in first-workflow.md - Fix typo: conceptual -> concept in rpi/README.md - Expand ms.topic enum values in frontmatter schemas - Fix schema mapping to correctly scope root patterns to repo root Closes #103 --- docs/getting-started/first-workflow.md | 2 +- docs/rpi/README.md | 2 +- docs/rpi/using-together.md | 2 +- .../linting/Validate-MarkdownFrontmatter.ps1 | 23 +++++++++++++++---- .../schemas/base-frontmatter.schema.json | 2 +- .../schemas/docs-frontmatter.schema.json | 2 +- .../root-community-frontmatter.schema.json | 2 +- 7 files changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/getting-started/first-workflow.md b/docs/getting-started/first-workflow.md index 2ead93c..e7818ca 100644 --- a/docs/getting-started/first-workflow.md +++ b/docs/getting-started/first-workflow.md @@ -13,7 +13,7 @@ keywords: estimated_reading_time: 10 --- -Build a real validation script using the Research β†’ Plan β†’ Implement workflow. You'll create a PowerShell script that checks every docs subfolder has a `README.md` file. +Build a real validation script using the Research β†’ Plan β†’ Implement workflow. You'll create a PowerShell script that checks that every docs subfolder has a `README.md` file. ## Prerequisites diff --git a/docs/rpi/README.md b/docs/rpi/README.md index c3e2935..64227e7 100644 --- a/docs/rpi/README.md +++ b/docs/rpi/README.md @@ -3,7 +3,7 @@ title: Understanding the RPI Workflow description: Learn the Research, Plan, Implement workflow for transforming complex tasks into working code author: Microsoft ms.date: 2025-01-28 -ms.topic: conceptual +ms.topic: concept keywords: - rpi workflow - task researcher diff --git a/docs/rpi/using-together.md b/docs/rpi/using-together.md index 160431a..8196eeb 100644 --- a/docs/rpi/using-together.md +++ b/docs/rpi/using-together.md @@ -146,7 +146,7 @@ Ready for review. Continue to Phase 2? Check the code, run linters, then continue. -**5. Final output:** +1. Final output: When all phases complete: diff --git a/scripts/linting/Validate-MarkdownFrontmatter.ps1 b/scripts/linting/Validate-MarkdownFrontmatter.ps1 index 8884e72..5b227b5 100644 --- a/scripts/linting/Validate-MarkdownFrontmatter.ps1 +++ b/scripts/linting/Validate-MarkdownFrontmatter.ps1 @@ -260,15 +260,28 @@ function Get-SchemaForFile { $fileName = [System.IO.Path]::GetFileName($FilePath) foreach ($rule in $mapping.mappings) { - # Simple pattern matching for file names - if ($rule.pattern -match '\|') { + # Directory-based patterns (check these FIRST for proper specificity) + if ($rule.pattern -like "*/**/*") { + # Convert glob to regex: '**/' => '(.*/)?', '*' => '[^/]*', '.' => '\.' + $regexPattern = $rule.pattern + $regexPattern = $regexPattern -replace '\*\*/', '(.*/)?' + $regexPattern = $regexPattern -replace '\*', '[^/]*' + $regexPattern = $regexPattern -replace '\.', '\.' + $regexPattern = '^' + $regexPattern + '$' + if ($relativePath -match $regexPattern) { + return Join-Path -Path $schemaDir -ChildPath $rule.schema + } + } + # Simple pattern matching for root file names only + elseif ($rule.pattern -match '\|') { $patterns = $rule.pattern -split '\|' - if ($fileName -in $patterns) { + # Only match if file is in root (relativePath equals fileName) + if ($relativePath -eq $fileName -and $fileName -in $patterns) { return Join-Path -Path $schemaDir -ChildPath $rule.schema } } - # Directory-based patterns - elseif ($rule.pattern -like "*/**/*") { + # Simple file patterns + elseif ($relativePath -like $rule.pattern -or $fileName -like $rule.pattern) { # Convert glob to regex: '**/' => '(.*/)?', '*' => '[^/]*', '.' => '\.' $regexPattern = $rule.pattern $regexPattern = $regexPattern -replace '\*\*/', '(.*/)?' diff --git a/scripts/linting/schemas/base-frontmatter.schema.json b/scripts/linting/schemas/base-frontmatter.schema.json index b1f142f..00824cb 100644 --- a/scripts/linting/schemas/base-frontmatter.schema.json +++ b/scripts/linting/schemas/base-frontmatter.schema.json @@ -43,7 +43,7 @@ }, "ms.topic": { "type": "string", - "enum": ["overview", "concept", "tutorial", "reference", "how-to", "troubleshooting", "research"], + "enum": ["overview", "concept", "tutorial", "reference", "how-to", "troubleshooting", "research", "guide", "hub-page", "architecture"], "description": "Microsoft documentation topic type" }, "keywords": { diff --git a/scripts/linting/schemas/docs-frontmatter.schema.json b/scripts/linting/schemas/docs-frontmatter.schema.json index ec6dafb..dd78020 100644 --- a/scripts/linting/schemas/docs-frontmatter.schema.json +++ b/scripts/linting/schemas/docs-frontmatter.schema.json @@ -29,7 +29,7 @@ }, "ms.topic": { "type": "string", - "enum": ["overview", "concept", "tutorial", "reference", "how-to", "troubleshooting"], + "enum": ["overview", "concept", "tutorial", "reference", "how-to", "troubleshooting", "architecture"], "description": "Recommended: Documentation topic type" }, "keywords": { diff --git a/scripts/linting/schemas/root-community-frontmatter.schema.json b/scripts/linting/schemas/root-community-frontmatter.schema.json index 4289d56..d1c8dff 100644 --- a/scripts/linting/schemas/root-community-frontmatter.schema.json +++ b/scripts/linting/schemas/root-community-frontmatter.schema.json @@ -29,7 +29,7 @@ }, "ms.topic": { "type": "string", - "enum": ["overview", "concept", "reference"], + "enum": ["overview", "concept", "reference", "guide", "hub-page"], "description": "Recommended: Document topic type" }, "keywords": { From 45ed180ead61326997ae7d6a506e4c8121d33cc7 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 26 Nov 2025 19:13:51 -0800 Subject: [PATCH 3/3] style: fix MD060 table alignment and add missing frontmatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix table column alignment in .github/chatmodes/README.md - Fix table column alignment in .github/instructions/README.md - Add author, ms.date, ms.topic to docs/contributing/*.md πŸ“ - Generated by Copilot --- .github/chatmodes/README.md | 10 +++++----- .github/instructions/README.md | 8 ++++---- docs/contributing/ai-artifacts-common.md | 3 +++ docs/contributing/chatmodes.md | 3 +++ docs/contributing/instructions.md | 3 +++ docs/contributing/prompts.md | 3 +++ 6 files changed, 21 insertions(+), 9 deletions(-) diff --git a/.github/chatmodes/README.md b/.github/chatmodes/README.md index 360581d..8f6fd9e 100644 --- a/.github/chatmodes/README.md +++ b/.github/chatmodes/README.md @@ -33,12 +33,12 @@ Specialized GitHub Copilot behaviors for common development workflows. Each chat 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 index 177fde4..7aa1e9c 100644 --- 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/docs/contributing/ai-artifacts-common.md b/docs/contributing/ai-artifacts-common.md index 9520894..92fe45e 100644 --- a/docs/contributing/ai-artifacts-common.md +++ b/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). diff --git a/docs/contributing/chatmodes.md b/docs/contributing/chatmodes.md index 81ce9c8..3516c10 100644 --- a/docs/contributing/chatmodes.md +++ b/docs/contributing/chatmodes.md @@ -1,6 +1,9 @@ --- 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. diff --git a/docs/contributing/instructions.md b/docs/contributing/instructions.md index f876651..b035e99 100644 --- a/docs/contributing/instructions.md +++ b/docs/contributing/instructions.md @@ -1,6 +1,9 @@ --- title: 'Contributing Instructions to HVE Core' description: 'Requirements and standards for contributing GitHub Copilot instruction 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 instruction files (`.instructions.md`) to the hve-core library. diff --git a/docs/contributing/prompts.md b/docs/contributing/prompts.md index 08527e5..8340878 100644 --- a/docs/contributing/prompts.md +++ b/docs/contributing/prompts.md @@ -1,6 +1,9 @@ --- title: 'Contributing Prompts to HVE Core' description: 'Requirements and standards for contributing GitHub Copilot prompt 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 prompt files (`.prompt.md`) to the hve-core library.