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