microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/rpi/using-together.md
269lines · modecode
| 1 | --- |
| 2 | title: Using RPI Modes Together |
| 3 | description: Complete walkthrough of the RPI workflow from research through implementation |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-01-28 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - rpi workflow |
| 9 | - task researcher |
| 10 | - task planner |
| 11 | - task implementor |
| 12 | - complete workflow |
| 13 | estimated_reading_time: 5 |
| 14 | --- |
| 15 | |
| 16 | This guide walks through a complete RPI workflow, showing how the three custom agents work together to transform a complex task into working code. |
| 17 | |
| 18 | ## The Complete Workflow |
| 19 | |
| 20 | ```text |
| 21 | ┌─────────────────┐ /clear ┌─────────────────┐ /clear ┌─────────────────┐ |
| 22 | │ Task Researcher │ ──────────→ │ Task Planner │ ──────────→ │ Task Implementor│ |
| 23 | │ │ │ │ │ │ |
| 24 | │ Uncertainty │ │ Knowledge │ │ Strategy │ |
| 25 | │ ↓ │ │ ↓ │ │ ↓ │ |
| 26 | │ Knowledge │ │ Strategy │ │ Working Code │ |
| 27 | └─────────────────┘ └─────────────────┘ └─────────────────┘ |
| 28 | ↓ ↓ ↓ |
| 29 | research.md plan.md + details.md code + changes.md |
| 30 | ``` |
| 31 | |
| 32 | ## Critical Rule: Clear Context |
| 33 | |
| 34 | 🔴 **Use `/clear` or start a new chat between EVERY phase.** |
| 35 | |
| 36 | Why this matters: |
| 37 | |
| 38 | * Each mode has different instructions and behaviors |
| 39 | * Accumulated context causes confusion and errors |
| 40 | * Research findings are in files, not chat history |
| 41 | * Clean context lets each mode work optimally |
| 42 | |
| 43 | ## Walkthrough: Adding Azure Blob Storage |
| 44 | |
| 45 | Let's walk through adding Azure Blob Storage to a Python data pipeline. |
| 46 | |
| 47 | ### Phase 1: Research |
| 48 | |
| 49 | 1. Use `/task-research` with your topic to start research (this automatically selects Task Researcher mode): |
| 50 | |
| 51 | ```text |
| 52 | /task-research Azure Blob Storage integration for Python data pipeline |
| 53 | ``` |
| 54 | |
| 55 | 1. Provide additional context in your message: |
| 56 | |
| 57 | ```text |
| 58 | I need to add Azure Blob Storage integration to our Python data pipeline. |
| 59 | The pipeline currently writes to local disk in src/pipeline/writers/. |
| 60 | |
| 61 | Research: |
| 62 | - Azure SDK for Python blob storage options |
| 63 | - Authentication approaches (managed identity vs connection string) |
| 64 | - Streaming uploads for files > 1GB |
| 65 | - Error handling and retry patterns |
| 66 | |
| 67 | Focus on approaches that match our existing patterns in the codebase. |
| 68 | ``` |
| 69 | |
| 70 | 1. Wait for completion (20-60 minutes). Task Researcher will: |
| 71 | |
| 72 | * Search your codebase for existing patterns |
| 73 | * Research Azure SDK documentation |
| 74 | * Evaluate authentication options |
| 75 | * Create a research document with recommendations |
| 76 | |
| 77 | 1. Review the output: |
| 78 | |
| 79 | ```text |
| 80 | ## **Task Researcher**: Deep Analysis of Azure Blob Storage Integration |
| 81 | |
| 82 | ✅ Research document created at: |
| 83 | .copilot-tracking/research/20250128-blob-storage-research.md |
| 84 | |
| 85 | Key findings: |
| 86 | - Recommended: azure-storage-blob SDK with async streaming |
| 87 | - Authentication: Managed identity for production, connection string for dev |
| 88 | - Existing pattern: WriterBase class in src/pipeline/writers/base.py |
| 89 | ``` |
| 90 | |
| 91 | ### Phase 2: Plan |
| 92 | |
| 93 | 1. Clear context: `/clear` |
| 94 | 1. Use `/task-plan` with the research file **open** (this automatically selects Task Planner mode): |
| 95 | |
| 96 | ```text |
| 97 | /task-plan |
| 98 | ``` |
| 99 | |
| 100 | 1. Provide additional planning guidance: |
| 101 | |
| 102 | ```text |
| 103 | /task-plan |
| 104 | Focus on: |
| 105 | - The streaming upload approach recommended in the research |
| 106 | - Phased rollout: storage client first, then writer class, then integration |
| 107 | - Include error handling and retry logic |
| 108 | ``` |
| 109 | |
| 110 | 1. Review the output. Task Planner creates three files: |
| 111 | |
| 112 | ```text |
| 113 | .copilot-tracking/plans/20250128-blob-storage-plan.instructions.md |
| 114 | .copilot-tracking/details/20250128-blob-storage-details.md |
| 115 | .copilot-tracking/prompts/implement-blob-storage.prompt.md |
| 116 | ``` |
| 117 | |
| 118 | 1. Verify the plan structure: |
| 119 | |
| 120 | ```markdown |
| 121 | ### [ ] Phase 1: Storage Client Setup |
| 122 | * [ ] Task 1.1: Create BlobStorageClient class |
| 123 | * [ ] Task 1.2: Add configuration schema |
| 124 | |
| 125 | ### [ ] Phase 2: Writer Implementation |
| 126 | * [ ] Task 2.1: Create BlobWriter extending WriterBase |
| 127 | * [ ] Task 2.2: Implement streaming upload |
| 128 | |
| 129 | ### [ ] Phase 3: Integration |
| 130 | * [ ] Task 3.1: Update pipeline factory |
| 131 | * [ ] Task 3.2: Add integration tests |
| 132 | ``` |
| 133 | |
| 134 | ### Phase 3: Implement |
| 135 | |
| 136 | 1. Clear context: `/clear` |
| 137 | 1. Use `/task-implement` to start implementation (automatically switches to Task Implementor mode): |
| 138 | |
| 139 | ```text |
| 140 | /task-implement |
| 141 | ``` |
| 142 | |
| 143 | Or use the generated prompt for a specific plan: |
| 144 | |
| 145 | ```text |
| 146 | /implement-blob-storage |
| 147 | ``` |
| 148 | |
| 149 | 1. Review at each phase. After Phase 1 completes: |
| 150 | |
| 151 | ```text |
| 152 | Phase 1 complete. Changes: |
| 153 | - Added: src/storage/blob_client.py |
| 154 | - Modified: src/config/schema.py |
| 155 | |
| 156 | Ready for review. Continue to Phase 2? |
| 157 | ``` |
| 158 | |
| 159 | Check the code, run linters, then continue. |
| 160 | |
| 161 | 1. Final output: |
| 162 | |
| 163 | When all phases complete: |
| 164 | |
| 165 | ```text |
| 166 | Implementation complete! |
| 167 | |
| 168 | Changes log: .copilot-tracking/changes/20250128-blob-storage-changes.md |
| 169 | |
| 170 | Files created (3): |
| 171 | - src/storage/blob_client.py |
| 172 | - src/pipeline/writers/blob_writer.py |
| 173 | - tests/integration/test_blob_writer.py |
| 174 | |
| 175 | Files modified (2): |
| 176 | - src/config/schema.py |
| 177 | - src/pipeline/factory.py |
| 178 | |
| 179 | Ready for commit. Planning files can be cleaned up. |
| 180 | ``` |
| 181 | |
| 182 | ## Artifact Summary |
| 183 | |
| 184 | After completing RPI, you have: |
| 185 | |
| 186 | | Artifact | Location | Purpose | |
| 187 | |----------|-------------------------------|------------------------------| |
| 188 | | Research | `.copilot-tracking/research/` | Evidence and recommendations | |
| 189 | | Plan | `.copilot-tracking/plans/` | Checkboxes and phases | |
| 190 | | Details | `.copilot-tracking/details/` | Task specifications | |
| 191 | | Prompt | `.copilot-tracking/prompts/` | Execution instructions | |
| 192 | | Changes | `.copilot-tracking/changes/` | Change log | |
| 193 | | Code | Your source directories | Working implementation | |
| 194 | |
| 195 | ## Common Patterns |
| 196 | |
| 197 | ### Iterating on Research |
| 198 | |
| 199 | If implementation reveals missing research: |
| 200 | |
| 201 | 1. Note the gap in your current session |
| 202 | 2. Clear context |
| 203 | 3. Return to Task Researcher |
| 204 | 4. Research the specific gap |
| 205 | 5. Update plan if needed |
| 206 | 6. Continue implementation |
| 207 | |
| 208 | ### Handling Complex Tasks |
| 209 | |
| 210 | For very large tasks: |
| 211 | |
| 212 | 1. Break into multiple RPI cycles |
| 213 | 2. Each cycle handles one component |
| 214 | 3. Use research from previous cycles |
| 215 | 4. Build incrementally |
| 216 | |
| 217 | ### Team Handoffs |
| 218 | |
| 219 | RPI artifacts support handoffs: |
| 220 | |
| 221 | * Research doc explains decisions |
| 222 | * Plan shows remaining work |
| 223 | * Changes log shows what's done |
| 224 | |
| 225 | ## Quick Reference |
| 226 | |
| 227 | | Phase | Invoke With | Mode | Output | |
| 228 | |-----------|------------------------------|------------------|--------------------------------| |
| 229 | | Research | `/task-research <topic>` | Task Researcher | research.md | |
| 230 | | Plan | `/task-plan [research-path]` | Task Planner | plan.md, details.md, prompt.md | |
| 231 | | Implement | `/task-implement` | Task Implementor | code + changes.md | |
| 232 | |
| 233 | > [!TIP] |
| 234 | > `/task-research`, `/task-plan`, and `/task-implement` all automatically switch to the appropriate custom agent. |
| 235 | |
| 236 | Remember: **Always `/clear` between phases!** |
| 237 | |
| 238 | ## RPI Agent: When Simplicity Fits |
| 239 | |
| 240 | For tasks that don't require strict phase separation, **rpi-agent** provides autonomous execution with subagent delegation. Use it when the scope is clear and you don't need the deep iterative research that comes from constraint-based separation. |
| 241 | |
| 242 | ### Quick Decision Guide |
| 243 | |
| 244 | | Choose Strict RPI when... | Choose rpi-agent when... | |
| 245 | |------------------------------|------------------------------------| |
| 246 | | Deep research is critical | Scope is clear and straightforward | |
| 247 | | Multi-file pattern discovery | Minimal external research needed | |
| 248 | | Team handoff needed | Quick iteration during development | |
| 249 | | Compliance or security work | Exploratory or prototype work | |
| 250 | |
| 251 | ### Escalation Path |
| 252 | |
| 253 | You don't have to decide upfront. Start with rpi-agent for speed, and if the task reveals hidden complexity, it can hand off to Task Researcher. This hybrid approach gives you speed for simple tasks and the verified truth that comes from constraint-based research when you need it. |
| 254 | |
| 255 | > [!TIP] |
| 256 | > For the full explanation of why constraints change AI behavior, see [Why the RPI Workflow Works](why-rpi.md#the-counterintuitive-insight). |
| 257 | |
| 258 | See [Agents Reference](../../.github/CUSTOM-AGENTS.md) for rpi-agent implementation details. |
| 259 | |
| 260 | ## Related Guides |
| 261 | |
| 262 | * [RPI Overview](README.md) - Understand the workflow |
| 263 | * [Task Researcher](task-researcher.md) - Deep research phase |
| 264 | * [Task Planner](task-planner.md) - Create actionable plans |
| 265 | * [Task Implementor](task-implementor.md) - Execute with precision |
| 266 | |
| 267 | --- |
| 268 | |
| 269 | 🤖 *Crafted with precision by ✨Copilot using the RPI workflow* |
| 270 | |