microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/rpi/using-together.md
416lines · modecode
| 1 | --- |
| 2 | title: Using RPI Agents Together |
| 3 | description: Complete walkthrough of the RPI workflow from research through review |
| 4 | sidebar_position: 8 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-01-24 |
| 7 | ms.topic: tutorial |
| 8 | keywords: |
| 9 | - rpi workflow |
| 10 | - task researcher |
| 11 | - task planner |
| 12 | - task implementor |
| 13 | - task reviewer |
| 14 | - complete workflow |
| 15 | estimated_reading_time: 5 |
| 16 | --- |
| 17 | |
| 18 | This guide walks through a complete RPI workflow, showing how the four custom agents work together to transform a complex task into validated code. |
| 19 | |
| 20 | ## The Complete Workflow |
| 21 | |
| 22 | ```text |
| 23 | ┌─────────────────┐ Handoff ┌─────────────────┐ Handoff ┌─────────────────┐ Handoff ┌─────────────────┐ |
| 24 | │ Task Researcher │ ──────────→ │ Task Planner │ ──────────→ │ Task Implementor│ ──────────→ │ Task Reviewer │ |
| 25 | │ │ 📋 Create │ │ ⚡ Implement │ │ ✅ Review │ │ |
| 26 | │ Uncertainty │ Plan │ Knowledge │ │ Strategy │ │ Working Code │ |
| 27 | │ ↓ │ │ ↓ │ │ ↓ │ │ ↓ │ |
| 28 | │ Knowledge │ │ Strategy │ │ Working Code │ │ Validated Code │ |
| 29 | └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ |
| 30 | ↓ ↓ ↓ ↓ |
| 31 | research.md plan.md + details.md code + changes.md review.md + findings |
| 32 | ↑ ↑ |
| 33 | └────────────────────────────────┴──────────────── 🔬 Research More / 📋 Revise Plan ────────────────────────┘ |
| 34 | ``` |
| 35 | |
| 36 | ## Critical Rule: Clear Context |
| 37 | |
| 38 | 🔴 **Use `/clear` or start a new chat between EVERY phase.** |
| 39 | |
| 40 | Why this matters: |
| 41 | |
| 42 | * Each agent has different instructions and behaviors |
| 43 | * Accumulated context causes confusion and errors |
| 44 | * Research findings are in files, not chat history |
| 45 | * Clean context lets each agent work optimally |
| 46 | |
| 47 | For the deeper explanation of how LLM context affects agent behavior, see [Context Engineering](context-engineering.md). |
| 48 | |
| 49 | ## Walkthrough: Adding Azure Blob Storage |
| 50 | |
| 51 | Let's walk through adding Azure Blob Storage to a Python data pipeline. |
| 52 | |
| 53 | ### Phase 1: Research |
| 54 | |
| 55 | 1. Use `/task-research` with your topic to start research (this automatically selects Task Researcher): |
| 56 | |
| 57 | ```text |
| 58 | /task-research Azure Blob Storage integration for Python data pipeline |
| 59 | ``` |
| 60 | |
| 61 | 1. Provide additional context in your message: |
| 62 | |
| 63 | ```text |
| 64 | I need to add Azure Blob Storage integration to our Python data pipeline. |
| 65 | The pipeline currently writes to local disk in src/pipeline/writers/. |
| 66 | |
| 67 | Research: |
| 68 | - Azure SDK for Python blob storage options |
| 69 | - Authentication approaches (managed identity vs connection string) |
| 70 | - Streaming uploads for files > 1GB |
| 71 | - Error handling and retry patterns |
| 72 | |
| 73 | Focus on approaches that match our existing patterns in the codebase. |
| 74 | ``` |
| 75 | |
| 76 | 1. Wait for completion (20-60 minutes). Task Researcher will: |
| 77 | |
| 78 | * Search your codebase for existing patterns |
| 79 | * Research Azure SDK documentation |
| 80 | * Evaluate authentication options |
| 81 | * Create a research document with recommendations |
| 82 | |
| 83 | 1. Review the output: |
| 84 | |
| 85 | ```text |
| 86 | ## 🔬 Task Researcher: Azure Blob Storage Integration |
| 87 | |
| 88 | ✅ Research document created at: |
| 89 | .copilot-tracking/research/2025-01-28-blob-storage-research.md |
| 90 | |
| 91 | Key findings: |
| 92 | - Recommended: azure-storage-blob SDK with async streaming |
| 93 | - Authentication: Managed identity for production, connection string for dev |
| 94 | - Existing pattern: WriterBase class in src/pipeline/writers/base.py |
| 95 | ``` |
| 96 | |
| 97 | ### Phase 2: Plan |
| 98 | |
| 99 | 1. Clear context: `/clear` |
| 100 | 1. Use `/task-plan` with the research file **open** (this automatically selects Task Planner): |
| 101 | |
| 102 | ```text |
| 103 | /task-plan |
| 104 | ``` |
| 105 | |
| 106 | 1. Provide additional planning guidance: |
| 107 | |
| 108 | ```text |
| 109 | /task-plan |
| 110 | Focus on: |
| 111 | - The streaming upload approach recommended in the research |
| 112 | - Phased rollout: storage client first, then writer class, then integration |
| 113 | - Include error handling and retry logic |
| 114 | ``` |
| 115 | |
| 116 | 1. Review the output. Task Planner creates two files: |
| 117 | |
| 118 | ```text |
| 119 | .copilot-tracking/plans/2025-01-28-blob-storage-plan.instructions.md |
| 120 | .copilot-tracking/details/2025-01-28-blob-storage-details.md |
| 121 | ``` |
| 122 | |
| 123 | 1. Verify the plan structure: |
| 124 | |
| 125 | ```markdown |
| 126 | ### [ ] Phase 1: Storage Client Setup |
| 127 | * [ ] Task 1.1: Create BlobStorageClient class |
| 128 | * [ ] Task 1.2: Add configuration schema |
| 129 | |
| 130 | ### [ ] Phase 2: Writer Implementation |
| 131 | * [ ] Task 2.1: Create BlobWriter extending WriterBase |
| 132 | * [ ] Task 2.2: Implement streaming upload |
| 133 | |
| 134 | ### [ ] Phase 3: Integration |
| 135 | * [ ] Task 3.1: Update pipeline factory |
| 136 | * [ ] Task 3.2: Add integration tests |
| 137 | ``` |
| 138 | |
| 139 | ### Phase 3: Implement |
| 140 | |
| 141 | 1. Clear context: `/clear` |
| 142 | 1. Use `/task-implement` to start implementation (automatically switches to Task Implementor): |
| 143 | |
| 144 | ```text |
| 145 | /task-implement |
| 146 | ``` |
| 147 | |
| 148 | Or use the generated prompt for a specific plan: |
| 149 | |
| 150 | ```text |
| 151 | /implement-blob-storage |
| 152 | ``` |
| 153 | |
| 154 | 1. Review at each phase. After Phase 1 completes: |
| 155 | |
| 156 | ```text |
| 157 | Phase 1 complete. Changes: |
| 158 | - Added: src/storage/blob_client.py |
| 159 | - Modified: src/config/schema.py |
| 160 | |
| 161 | Ready for review. Continue to Phase 2? |
| 162 | ``` |
| 163 | |
| 164 | Check the code, run linters, then continue. |
| 165 | |
| 166 | 1. Final output: |
| 167 | |
| 168 | When all phases complete: |
| 169 | |
| 170 | ```text |
| 171 | Implementation complete! |
| 172 | |
| 173 | Changes log: .copilot-tracking/changes/2025-01-28-blob-storage-changes.md |
| 174 | |
| 175 | Files created (3): |
| 176 | - src/storage/blob_client.py |
| 177 | - src/pipeline/writers/blob_writer.py |
| 178 | - tests/integration/test_blob_writer.py |
| 179 | |
| 180 | Files modified (2): |
| 181 | - src/config/schema.py |
| 182 | - src/pipeline/factory.py |
| 183 | |
| 184 | Ready for review. |
| 185 | ``` |
| 186 | |
| 187 | ### Phase 4: Review |
| 188 | |
| 189 | 1. Clear context: `/clear` |
| 190 | 2. Use `/task-review` to validate the implementation (automatically switches to Task Reviewer): |
| 191 | |
| 192 | ```text |
| 193 | /task-review |
| 194 | ``` |
| 195 | |
| 196 | 3. Task Reviewer validates against specifications: |
| 197 | |
| 198 | * Locates research, plan, and changes artifacts |
| 199 | * Extracts implementation checklist from source documents |
| 200 | * Validates each item with evidence from the codebase |
| 201 | * Runs validation commands (lint, build, test) |
| 202 | |
| 203 | 4. Review the findings: |
| 204 | |
| 205 | ```text |
| 206 | ## ✅ Task Reviewer: Blob Storage Integration |
| 207 | |
| 208 | | 📊 Summary | | |
| 209 | |-----------------------|-------------------------------------------------------------| |
| 210 | | **Review Log** | .copilot-tracking/reviews/2025-01-28-blob-storage-review.md | |
| 211 | | **Overall Status** | Complete | |
| 212 | | **Critical Findings** | 0 | |
| 213 | | **Major Findings** | 0 | |
| 214 | | **Minor Findings** | 2 | |
| 215 | | **Follow-Up Items** | 1 | |
| 216 | |
| 217 | Minor findings: |
| 218 | - Missing docstring on BlobStorageClient.upload_stream() |
| 219 | - Consider adding retry count to configuration schema |
| 220 | |
| 221 | Follow-up item: |
| 222 | - Add performance benchmarks for large file uploads (deferred from research) |
| 223 | |
| 224 | Ready for commit. |
| 225 | ``` |
| 226 | |
| 227 | 1. Address findings and commit: |
| 228 | |
| 229 | * Fix Minor findings if desired (optional for commit) |
| 230 | * Address Critical and Major findings before committing |
| 231 | * Note Follow-Up items for future RPI cycles |
| 232 | |
| 233 | ## Artifact Summary |
| 234 | |
| 235 | After completing RPI, you have: |
| 236 | |
| 237 | | Artifact | Location | Purpose | |
| 238 | |----------|-------------------------------|------------------------------| |
| 239 | | Research | `.copilot-tracking/research/` | Evidence and recommendations | |
| 240 | | Plan | `.copilot-tracking/plans/` | Checkboxes and phases | |
| 241 | | Details | `.copilot-tracking/details/` | Task specifications | |
| 242 | | Changes | `.copilot-tracking/changes/` | Change log | |
| 243 | | Review | `.copilot-tracking/reviews/` | Validation findings | |
| 244 | | Code | Your source directories | Working implementation | |
| 245 | |
| 246 | ## Common Patterns |
| 247 | |
| 248 | ### Iterating on Research |
| 249 | |
| 250 | If implementation reveals missing research: |
| 251 | |
| 252 | 1. Note the gap in your current session |
| 253 | 2. Clear context |
| 254 | 3. Return to Task Researcher |
| 255 | 4. Research the specific gap |
| 256 | 5. Update plan if needed |
| 257 | 6. Continue implementation |
| 258 | |
| 259 | ### Handling Complex Tasks |
| 260 | |
| 261 | For very large tasks: |
| 262 | |
| 263 | 1. Break into multiple RPI cycles |
| 264 | 2. Each cycle handles one component |
| 265 | 3. Use research from previous cycles |
| 266 | 4. Build incrementally |
| 267 | |
| 268 | ### Team Handoffs |
| 269 | |
| 270 | RPI artifacts support handoffs: |
| 271 | |
| 272 | * Research doc explains decisions |
| 273 | * Plan shows remaining work |
| 274 | * Changes log shows what's done |
| 275 | * Review log shows validation status |
| 276 | |
| 277 | ## Iteration Loops |
| 278 | |
| 279 | The Review phase can trigger iteration back to earlier phases when findings reveal gaps. |
| 280 | |
| 281 | ### Iteration Paths |
| 282 | |
| 283 | | Review Status | Action | Target Phase | |
| 284 | |---------------|-----------------------------|--------------| |
| 285 | | Complete | Commit changes | Done | |
| 286 | | Needs Rework | Fix implementation issues | Implement | |
| 287 | | Research Gap | Investigate missing context | Research | |
| 288 | | Plan Gap | Add missing scope | Plan | |
| 289 | |
| 290 | ### Rework Flow |
| 291 | |
| 292 | When Task Reviewer identifies Critical or Major findings: |
| 293 | |
| 294 | 1. Clear context: `/clear` |
| 295 | 2. Open the review log in your editor |
| 296 | 3. Use `/task-implement` to address findings |
| 297 | 4. Task Implementor uses the review log to guide fixes |
| 298 | 5. Return to review: `/task-review` |
| 299 | |
| 300 | ### Escalation Flow |
| 301 | |
| 302 | When Task Reviewer identifies research or planning gaps: |
| 303 | |
| 304 | 1. Clear context: `/clear` |
| 305 | 2. Open the review log in your editor |
| 306 | 3. Choose the appropriate phase: |
| 307 | * `/task-research` for missing technical context |
| 308 | * `/task-plan` for scope additions |
| 309 | 4. Complete the phase and continue through the workflow |
| 310 | |
| 311 | ## Quick Reference |
| 312 | |
| 313 | | Phase | Invoke With | Agent | Output | |
| 314 | |-----------|------------------------------|------------------|---------------------| |
| 315 | | Research | `/task-research <topic>` | Task Researcher | research.md | |
| 316 | | Plan | `/task-plan [research-path]` | Task Planner | plan.md, details.md | |
| 317 | | Implement | `/task-implement` | Task Implementor | code + changes.md | |
| 318 | | Review | `/task-review [scope]` | Task Reviewer | review.md | |
| 319 | |
| 320 | > [!TIP] |
| 321 | > `/task-research`, `/task-plan`, `/task-implement`, and `/task-review` all automatically switch to the appropriate custom agent. |
| 322 | |
| 323 | Remember: **Always `/clear` between phases!** |
| 324 | |
| 325 | ## Handoff Buttons |
| 326 | |
| 327 | RPI agents include handoff buttons that streamline transitions between workflow phases. When an agent completes its work, handoff buttons appear in the chat interface. |
| 328 | |
| 329 | ### Available Handoffs |
| 330 | |
| 331 | | From Agent | Handoff Button | Target Agent | Action | |
| 332 | |------------------|------------------|------------------|--------------------------------| |
| 333 | | Task Researcher | 📋 Create Plan | Task Planner | Starts planning with research | |
| 334 | | Task Planner | ⚡ Implement | Task Implementor | Executes the plan | |
| 335 | | Task Implementor | ✅ Review | Task Reviewer | Reviews implementation | |
| 336 | | Task Reviewer | 🔬 Research More | Task Researcher | Researches identified gaps | |
| 337 | | Task Reviewer | 📋 Revise Plan | Task Planner | Updates plan based on findings | |
| 338 | |
| 339 | ### Using Handoff Buttons |
| 340 | |
| 341 | 1. Complete work in current agent |
| 342 | 2. Click the handoff button in the chat interface |
| 343 | 3. The target agent activates with the appropriate prompt pre-filled |
| 344 | 4. Conversation context carries over automatically |
| 345 | |
| 346 | ### When to Use Manual Transitions |
| 347 | |
| 348 | Use `/clear` and manual `/task-*` commands instead of handoffs when: |
| 349 | |
| 350 | * You need to reset conversation context completely |
| 351 | * You want to provide custom parameters to the next agent |
| 352 | * The handoff button doesn't match your intended workflow |
| 353 | |
| 354 | > [!TIP] |
| 355 | > Use `/compact` when you want to reduce conversation length without losing all context. Unlike `/clear`, `/compact` summarizes the conversation history rather than removing it. This is useful mid-phase when context grows long but you want to continue the current task. |
| 356 | |
| 357 | ## Session Persistence |
| 358 | |
| 359 | The RPI Agent includes a **💾 Save** button that captures conversation context to a memory file, enabling you to resume work after a context reset or across sessions. |
| 360 | |
| 361 | ### Save a Session |
| 362 | |
| 363 | Click **💾 Save** in the RPI Agent chat interface at any point during a research, planning, or implementation phase. The memory agent creates a file at `.copilot-tracking/memory/YYYY-MM-DD/<description>-memory.md` containing: |
| 364 | |
| 365 | * Task overview and current phase |
| 366 | * Completed work summary |
| 367 | * Next steps and open decisions |
| 368 | * Key file paths and references |
| 369 | |
| 370 | ### Resume a Session |
| 371 | |
| 372 | 1. Start a new chat and type `/clear` to ensure a clean context. |
| 373 | 2. Type `/checkpoint continue <description>` to restore the saved session. |
| 374 | 3. The memory agent displays restored context, completed work, and next steps. |
| 375 | 4. Click **🚀 Continue with RPI** or switch to the appropriate RPI agent to continue. |
| 376 | |
| 377 | > [!TIP] |
| 378 | > Use **💾 Save** before any `/clear` between phases to preserve progress notes. The checkpoint file supplements but does not replace the planning artifacts in `.copilot-tracking/`. |
| 379 | |
| 380 | ## RPI Agent: When Simplicity Fits |
| 381 | |
| 382 | 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. |
| 383 | |
| 384 | ### Quick Decision Guide |
| 385 | |
| 386 | | Choose Strict RPI when... | Choose rpi-agent when... | |
| 387 | |------------------------------|------------------------------------| |
| 388 | | Deep research is critical | Scope is clear and straightforward | |
| 389 | | Multi-file pattern discovery | Minimal external research needed | |
| 390 | | Team handoff needed | Quick iteration during development | |
| 391 | | Compliance or security work | Exploratory or prototype work | |
| 392 | |
| 393 | ### Escalation Path |
| 394 | |
| 395 | 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. |
| 396 | |
| 397 | > [!TIP] |
| 398 | > For the full explanation of why constraints change AI behavior, see [Why the RPI Workflow Works](why-rpi.md#the-counterintuitive-insight). |
| 399 | |
| 400 | See [Agents Reference](https://github.com/microsoft/hve-core/blob/main/.github/CUSTOM-AGENTS.md) for rpi-agent implementation details. |
| 401 | |
| 402 | ## Related Guides |
| 403 | |
| 404 | * [RPI Overview](./) - Understand the workflow |
| 405 | * [Context Engineering](context-engineering.md) - Why context management matters |
| 406 | * [Task Researcher](task-researcher.md) - Deep research phase |
| 407 | * [Task Planner](task-planner.md) - Create actionable plans |
| 408 | * [Task Implementor](task-implementor.md) - Execute with precision |
| 409 | * [Task Reviewer](task-reviewer.md) - Validate implementations |
| 410 | |
| 411 | --- |
| 412 | |
| 413 | <!-- markdownlint-disable MD036 --> |
| 414 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 415 | then carefully refined by our team of discerning human reviewers.* |
| 416 | <!-- markdownlint-enable MD036 --> |
| 417 | |