microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/getting-started/first-workflow.md
264lines · modecode
| 1 | --- |
| 2 | title: Your First Full Workflow |
| 3 | description: Hands-on tutorial using Research, Plan, Implement phases to create a validation script |
| 4 | sidebar_position: 6 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-02-18 |
| 7 | ms.topic: tutorial |
| 8 | keywords: |
| 9 | - getting started |
| 10 | - rpi workflow |
| 11 | - github copilot |
| 12 | - tutorial |
| 13 | - powershell script |
| 14 | estimated_reading_time: 10 |
| 15 | --- |
| 16 | |
| 17 | > [!NOTE] |
| 18 | > Step 3 of 4 in the [Getting Started Journey](./). |
| 19 | |
| 20 | 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. |
| 21 | |
| 22 | > [!TIP] |
| 23 | > This tutorial uses a PowerShell script as the example task. The RPI |
| 24 | > methodology works identically with any language. If PowerShell isn't |
| 25 | > relevant to you, substitute your own small task: a utility function, |
| 26 | > a configuration validator, a documentation checker. The prompts |
| 27 | > adapt to whatever you describe. |
| 28 | |
| 29 | ## Prerequisites |
| 30 | |
| 31 | * VS Code with GitHub Copilot Chat extension |
| 32 | * This repository cloned locally |
| 33 | * Basic familiarity with GitHub Copilot |
| 34 | * ~15 minutes to complete |
| 35 | |
| 36 | ## The Task |
| 37 | |
| 38 | You'll create: |
| 39 | |
| 40 | * `scripts/linting/Test-DocsReadme.ps1` - validation script |
| 41 | * npm script entry in `package.json` |
| 42 | |
| 43 | Multiple unknowns make RPI a good fit for this task: existing script patterns, PowerShell conventions, npm integration, output format. Research first reduces guesswork. |
| 44 | |
| 45 | > [!IMPORTANT] |
| 46 | > 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). |
| 47 | |
| 48 | ## Before You Start |
| 49 | |
| 50 | > [!TIP] |
| 51 | > Steps 1 and 2 ([Your First Interaction](first-interaction.md) and |
| 52 | > [Your First Research](first-research.md)) cover the basics. If you've |
| 53 | > already completed them or have experience with HVE Core agents, continue |
| 54 | > below. |
| 55 | |
| 56 | The `/clear` command resets Copilot's context between phases. Each RPI phase |
| 57 | should start fresh. The artifacts (research doc, plan) carry the context |
| 58 | forward, not the chat history. |
| 59 | |
| 60 | > [!NOTE] |
| 61 | > Understanding why `/clear` matters (not just that you should use it) helps you recognize when context degradation affects your results. See [Context Engineering](../rpi/context-engineering.md) for the full explanation. |
| 62 | |
| 63 | ## Phase 1: Research |
| 64 | |
| 65 | ### Switch to Task Researcher |
| 66 | |
| 67 | 1. Open Copilot Chat (`Ctrl+Alt+I`) |
| 68 | 1. Click the agent picker dropdown at the top |
| 69 | 1. Select **Task Researcher** |
| 70 | |
| 71 | ### Your Research Prompt |
| 72 | |
| 73 | Copy and paste this prompt: |
| 74 | |
| 75 | ```text |
| 76 | Research what's needed to create a PowerShell script for this repository that |
| 77 | validates every subfolder under docs/ contains a README.md file. |
| 78 | |
| 79 | Consider: |
| 80 | * Existing PowerShell script patterns in scripts/linting/ |
| 81 | * PSScriptAnalyzer conventions and settings |
| 82 | * How npm scripts are structured in package.json |
| 83 | * Expected output format (exit codes, messages) |
| 84 | ``` |
| 85 | |
| 86 | ### What You'll Get |
| 87 | |
| 88 | Task Researcher analyzes the codebase and returns findings about: |
| 89 | |
| 90 | * Existing PowerShell scripts and their patterns |
| 91 | * PSScriptAnalyzer settings and conventions |
| 92 | * Current npm scripts structure |
| 93 | * Recommended output format |
| 94 | |
| 95 | ### Key Findings to Note |
| 96 | |
| 97 | From the research output, identify: |
| 98 | |
| 99 | | Finding | Example | |
| 100 | |-------------------------|-----------------------------------------------| |
| 101 | | Script location pattern | `scripts/linting/*.ps1` | |
| 102 | | Naming convention | `Verb-Noun.ps1` (e.g., `Test-DocsReadme.ps1`) | |
| 103 | | npm script pattern | `"name": "pwsh scripts/path.ps1"` | |
| 104 | | Exit codes | `exit 0` = success, `exit 1` = failure | |
| 105 | |
| 106 | ## Phase 2: Plan |
| 107 | |
| 108 | ### Clear and Switch |
| 109 | |
| 110 | 1. Type `/clear` in the chat to reset context |
| 111 | 1. Click the agent picker dropdown |
| 112 | 1. Select **Task Planner** |
| 113 | |
| 114 | ### Your Planning Prompt |
| 115 | |
| 116 | Copy and paste this prompt (include findings from Phase 1): |
| 117 | |
| 118 | ```text |
| 119 | Create an implementation plan to add a README validation script. |
| 120 | |
| 121 | Requirements from research: |
| 122 | * Script location: scripts/linting/Test-DocsReadme.ps1 |
| 123 | * Follow PowerShell conventions (Verb-Noun naming, comment-based help) |
| 124 | * Add npm script "check:docs-readme" to package.json |
| 125 | * Exit 0 on success, exit 1 on failure |
| 126 | * Output list of folders missing README.md |
| 127 | ``` |
| 128 | |
| 129 | ### Plan Output |
| 130 | |
| 131 | Task Planner creates a structured plan with: |
| 132 | |
| 133 | * File creation steps |
| 134 | * Implementation details for each file |
| 135 | * Validation criteria |
| 136 | |
| 137 | ### Your Plan Should Include |
| 138 | |
| 139 | 1. Create `scripts/linting/Test-DocsReadme.ps1` with: |
| 140 | * Find all immediate subdirectories of `docs/` |
| 141 | * Check each has `README.md` |
| 142 | * Print missing folders |
| 143 | * Exit with appropriate code |
| 144 | |
| 145 | 1. Update `package.json`: |
| 146 | * Add `"check:docs-readme"` script |
| 147 | |
| 148 | ## Phase 3: Implement |
| 149 | |
| 150 | ### Clear and Switch to Implementor |
| 151 | |
| 152 | 1. Type `/clear` in the chat to reset context |
| 153 | 1. Click the agent picker dropdown |
| 154 | 1. Select **Task Implementor** |
| 155 | |
| 156 | ### Your Implementation Prompt |
| 157 | |
| 158 | Copy and paste this prompt: |
| 159 | |
| 160 | ```text |
| 161 | Implement this plan to add README validation. |
| 162 | |
| 163 | Plan: |
| 164 | 1. Create scripts/linting/Test-DocsReadme.ps1 |
| 165 | - Include comment-based help |
| 166 | - Find all immediate subdirectories of docs/ |
| 167 | - Check each has README.md |
| 168 | - Print missing folders with clear messaging |
| 169 | - Exit 0 if all pass, exit 1 if any missing |
| 170 | |
| 171 | 2. Update package.json |
| 172 | - Add "check:docs-readme": "pwsh scripts/linting/Test-DocsReadme.ps1" |
| 173 | ``` |
| 174 | |
| 175 | ### Watch It Work |
| 176 | |
| 177 | Task Implementor will: |
| 178 | |
| 179 | 1. Create the PowerShell script with proper structure |
| 180 | 1. Update `package.json` with the npm script |
| 181 | 1. Show you each file change for approval |
| 182 | |
| 183 | Confirm each tool call when prompted. |
| 184 | |
| 185 | ## Verify Your Work |
| 186 | |
| 187 | ### Run the Script |
| 188 | |
| 189 | ```powershell |
| 190 | npm run check:docs-readme |
| 191 | ``` |
| 192 | |
| 193 | ### Expected Output (Success) |
| 194 | |
| 195 | ```text |
| 196 | Checking docs subfolders for README.md... |
| 197 | ✓ docs/contributing/README.md |
| 198 | ✓ docs/getting-started/README.md |
| 199 | ✓ docs/rpi/README.md |
| 200 | |
| 201 | All docs subfolders have README.md |
| 202 | ``` |
| 203 | |
| 204 | ### Test Failure Detection |
| 205 | |
| 206 | Temporarily rename a README to see the failure case: |
| 207 | |
| 208 | ```powershell |
| 209 | Rename-Item docs/rpi/README.md README.md.bak |
| 210 | npm run check:docs-readme |
| 211 | Rename-Item docs/rpi/README.md.bak README.md |
| 212 | ``` |
| 213 | |
| 214 | ## Alternative: Single-Session with rpi-agent |
| 215 | |
| 216 | The three-agent workflow above separates research, planning, and implementation |
| 217 | into distinct phases with `/clear` between each. This is the best way to learn |
| 218 | RPI because you see each phase produce its own artifact. |
| 219 | |
| 220 | For day-to-day work, the [rpi-agent](https://github.com/microsoft/hve-core/blob/main/.github/CUSTOM-AGENTS.md#rpi-agent) |
| 221 | runs all three phases in a single session. It follows the same methodology but |
| 222 | handles the phase transitions automatically. |
| 223 | |
| 224 | To compare the experience, select **rpi-agent** from the agent picker and try |
| 225 | this prompt: |
| 226 | |
| 227 | > Create a PowerShell script that validates every subfolder under docs/ contains |
| 228 | > a README.md file. Place it at scripts/linting/Test-DocsReadme.ps1 and add an |
| 229 | > npm script entry. |
| 230 | |
| 231 | The rpi-agent researches, plans, and implements without `/clear` commands |
| 232 | between phases. |
| 233 | |
| 234 | ## What You Learned |
| 235 | |
| 236 | * Use `/clear` between phases to prevent context pollution through phase separation. |
| 237 | * Research reduces unknowns by discovering patterns before coding. |
| 238 | * The plan gives Implementor clear requirements, acting as a specification. |
| 239 | * Findings and plans bridge phases by carrying context, not chat history. |
| 240 | |
| 241 | ## Troubleshooting |
| 242 | |
| 243 | | Issue | Solution | |
| 244 | |-----------------------|---------------------------------------------------------------------------------------------------| |
| 245 | | PowerShell not found | Ensure `pwsh` is installed and in PATH | |
| 246 | | npm script not found | Check `package.json` was saved | |
| 247 | | Wrong folders checked | Verify script targets `docs/*` pattern | |
| 248 | | Agent skips phases | Use `/clear` before each `/rpi` request; see [Context Engineering](../rpi/context-engineering.md) | |
| 249 | |
| 250 | ## Next Step |
| 251 | |
| 252 | You've completed your first full RPI cycle. The methodology works the same |
| 253 | way for any task: research the unknowns, plan the approach, implement from |
| 254 | the plan. |
| 255 | |
| 256 | Continue your journey through the |
| 257 | [New Contributor Milestones](../hve-guide/roles/new-contributor.md#milestone-3-independent-workflow), |
| 258 | where Milestone 3 guides you through your first independent workflow on a |
| 259 | task you choose yourself. |
| 260 | |
| 261 | --- |
| 262 | |
| 263 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 264 | then carefully refined by our team of discerning human reviewers.* |
| 265 | |