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