microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/getting-started/first-workflow.md
222lines · modecode
| 1 | --- |
| 2 | title: Your First RPI Workflow |
| 3 | description: Hands-on tutorial using Research, Plan, Implement phases to create a validation script |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-11-26 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - getting started |
| 9 | - rpi workflow |
| 10 | - github copilot |
| 11 | - tutorial |
| 12 | - powershell script |
| 13 | estimated_reading_time: 10 |
| 14 | --- |
| 15 | |
| 16 | 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. |
| 17 | |
| 18 | ## Prerequisites |
| 19 | |
| 20 | * VS Code with GitHub Copilot Chat extension |
| 21 | * This repository cloned locally |
| 22 | * Basic familiarity with GitHub Copilot |
| 23 | * ~15 minutes to complete |
| 24 | |
| 25 | ## The Task |
| 26 | |
| 27 | You'll create: |
| 28 | |
| 29 | * `scripts/linting/Test-DocsReadme.ps1` - validation script |
| 30 | * npm script entry in `package.json` |
| 31 | |
| 32 | **Why use RPI for this?** Multiple unknowns: existing script patterns, PowerShell conventions, npm integration, output format. Research first reduces guesswork. |
| 33 | |
| 34 | ## Before You Start |
| 35 | |
| 36 | **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. |
| 37 | |
| 38 | ## Phase 1: Research |
| 39 | |
| 40 | ### Switch to Task Researcher |
| 41 | |
| 42 | 1. Open Copilot Chat (`Ctrl+Alt+I`) |
| 43 | 1. Click the chat mode dropdown at the top |
| 44 | 1. Select **Task Researcher** |
| 45 | |
| 46 | ### Your Research Prompt |
| 47 | |
| 48 | Copy and paste this prompt: |
| 49 | |
| 50 | ```text |
| 51 | Research what's needed to create a PowerShell script for this repository that |
| 52 | validates every subfolder under docs/ contains a README.md file. |
| 53 | |
| 54 | Consider: |
| 55 | - Existing PowerShell script patterns in scripts/linting/ |
| 56 | - PSScriptAnalyzer conventions and settings |
| 57 | - How npm scripts are structured in package.json |
| 58 | - Expected output format (exit codes, messages) |
| 59 | ``` |
| 60 | |
| 61 | ### What You'll Get |
| 62 | |
| 63 | Task Researcher analyzes the codebase and returns findings about: |
| 64 | |
| 65 | * Existing PowerShell scripts and their patterns |
| 66 | * PSScriptAnalyzer settings and conventions |
| 67 | * Current npm scripts structure |
| 68 | * Recommended output format |
| 69 | |
| 70 | ### Key Findings to Note |
| 71 | |
| 72 | From the research output, identify: |
| 73 | |
| 74 | | Finding | Example | |
| 75 | |-------------------------|-----------------------------------------------| |
| 76 | | Script location pattern | `scripts/linting/*.ps1` | |
| 77 | | Naming convention | `Verb-Noun.ps1` (e.g., `Test-DocsReadme.ps1`) | |
| 78 | | npm script pattern | `"name": "pwsh scripts/path.ps1"` | |
| 79 | | Exit codes | `exit 0` = success, `exit 1` = failure | |
| 80 | |
| 81 | ## Phase 2: Plan |
| 82 | |
| 83 | ### Clear and Switch |
| 84 | |
| 85 | 1. Type `/clear` in the chat to reset context |
| 86 | 1. Click the chat mode dropdown |
| 87 | 1. Select **Task Planner** |
| 88 | |
| 89 | ### Your Planning Prompt |
| 90 | |
| 91 | Copy and paste this prompt (include findings from Phase 1): |
| 92 | |
| 93 | ```text |
| 94 | Create an implementation plan to add a README validation script. |
| 95 | |
| 96 | Requirements from research: |
| 97 | - Script location: scripts/linting/Test-DocsReadme.ps1 |
| 98 | - Follow PowerShell conventions (Verb-Noun naming, comment-based help) |
| 99 | - Add npm script "check:docs-readme" to package.json |
| 100 | - Exit 0 on success, exit 1 on failure |
| 101 | - Output list of folders missing README.md |
| 102 | ``` |
| 103 | |
| 104 | ### Plan Output |
| 105 | |
| 106 | Task Planner creates a structured plan with: |
| 107 | |
| 108 | * File creation steps |
| 109 | * Implementation details for each file |
| 110 | * Validation criteria |
| 111 | |
| 112 | ### Your Plan Should Include |
| 113 | |
| 114 | 1. Create `scripts/linting/Test-DocsReadme.ps1` with: |
| 115 | * Find all immediate subdirectories of `docs/` |
| 116 | * Check each has `README.md` |
| 117 | * Print missing folders |
| 118 | * Exit with appropriate code |
| 119 | |
| 120 | 1. Update `package.json`: |
| 121 | * Add `"check:docs-readme"` script |
| 122 | |
| 123 | ## Phase 3: Implement |
| 124 | |
| 125 | ### Clear and Switch to Implementor |
| 126 | |
| 127 | 1. Type `/clear` in the chat to reset context |
| 128 | 1. Click the chat mode dropdown |
| 129 | 1. Select **Task Implementor** |
| 130 | |
| 131 | ### Your Implementation Prompt |
| 132 | |
| 133 | Copy and paste this prompt: |
| 134 | |
| 135 | ```text |
| 136 | Implement this plan to add README validation. |
| 137 | |
| 138 | Plan: |
| 139 | 1. Create scripts/linting/Test-DocsReadme.ps1 |
| 140 | - Include comment-based help |
| 141 | - Find all immediate subdirectories of docs/ |
| 142 | - Check each has README.md |
| 143 | - Print missing folders with clear messaging |
| 144 | - Exit 0 if all pass, exit 1 if any missing |
| 145 | |
| 146 | 2. Update package.json |
| 147 | - Add "check:docs-readme": "pwsh scripts/linting/Test-DocsReadme.ps1" |
| 148 | ``` |
| 149 | |
| 150 | ### Watch It Work |
| 151 | |
| 152 | Task Implementor will: |
| 153 | |
| 154 | 1. Create the PowerShell script with proper structure |
| 155 | 1. Update `package.json` with the npm script |
| 156 | 1. Show you each file change for approval |
| 157 | |
| 158 | Confirm each tool call when prompted. |
| 159 | |
| 160 | ## Verify Your Work |
| 161 | |
| 162 | ### Run the Script |
| 163 | |
| 164 | ```powershell |
| 165 | npm run check:docs-readme |
| 166 | ``` |
| 167 | |
| 168 | ### Expected Output (Success) |
| 169 | |
| 170 | ```text |
| 171 | Checking docs subfolders for README.md... |
| 172 | ✓ docs/contributing/README.md |
| 173 | ✓ docs/getting-started/README.md |
| 174 | ✓ docs/rpi/README.md |
| 175 | |
| 176 | All docs subfolders have README.md |
| 177 | ``` |
| 178 | |
| 179 | ### Test Failure Detection |
| 180 | |
| 181 | Temporarily rename a README to see the failure case: |
| 182 | |
| 183 | ```powershell |
| 184 | Rename-Item docs/rpi/README.md README.md.bak |
| 185 | npm run check:docs-readme |
| 186 | Rename-Item docs/rpi/README.md.bak README.md |
| 187 | ``` |
| 188 | |
| 189 | ## What You Learned |
| 190 | |
| 191 | * **Phase separation** - `/clear` between phases prevents context pollution |
| 192 | * **Research reduces unknowns** - You discovered patterns before coding |
| 193 | * **Plans are specifications** - The plan gave Implementor clear requirements |
| 194 | * **Artifacts bridge phases** - Findings and plans carry context, not chat history |
| 195 | |
| 196 | ## Troubleshooting |
| 197 | |
| 198 | | Issue | Solution | |
| 199 | |-----------------------|----------------------------------------| |
| 200 | | PowerShell not found | Ensure `pwsh` is installed and in PATH | |
| 201 | | npm script not found | Check `package.json` was saved | |
| 202 | | Wrong folders checked | Verify script targets `docs/*` pattern | |
| 203 | |
| 204 | ## Next Steps |
| 205 | |
| 206 | * **Complex multi-file tasks** - See [RPI Workflow Overview](../rpi/README.md) |
| 207 | * **Simple tasks** - Skip RPI and use prompts directly |
| 208 | * **Contribute** - Read [Contributing Guide](../contributing/README.md) |
| 209 | |
| 210 | ## Resources |
| 211 | |
| 212 | | Resource | Description | |
| 213 | |------------------------------------------------|-----------------------------------| |
| 214 | | [RPI Overview](../rpi/README.md) | Full RPI workflow documentation | |
| 215 | | [Task Researcher](../rpi/task-researcher.md) | Deep dive on research phase | |
| 216 | | [Task Planner](../rpi/task-planner.md) | Deep dive on planning phase | |
| 217 | | [Task Implementor](../rpi/task-implementor.md) | Deep dive on implementation phase | |
| 218 | |
| 219 | --- |
| 220 | |
| 221 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 222 | then carefully refined by our team of discerning human reviewers.* |
| 223 | |