Add Agents Extended workflow and agent instructions#5
Add Agents Extended workflow and agent instructions#5taylorarndt wants to merge 1 commit intodfinke:mainfrom
Conversation
Introduces the Agents Extended system to the README, detailing a multi-agent workflow for implementation and code review. Adds developer.agent.md and reviewer.agent.md, providing comprehensive instructions and handoff templates for the Developer and Reviewer agents to ensure structured, high-quality engineering collaboration.
There was a problem hiding this comment.
Pull request overview
This PR introduces an Agents Extended multi-agent workflow system that creates a collaborative software engineering team within VS Code using GitHub Copilot's custom agent capabilities. The system enables automated handoffs between specialized agents (Developer and Reviewer) with structured communication templates to ensure quality and consistency in code development.
Key Changes
- Adds comprehensive agent instruction files for Developer and Reviewer agents with detailed workflows, responsibilities, and handoff mechanisms
- Updates README with documentation of the Agents Extended system, explaining the multi-agent workflow and automatic handoff capabilities
- Establishes structured templates for communication between agents to maintain context during transitions
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| README.md | Adds "Agents Extended" section documenting the multi-agent workflow system, available agents, and usage examples |
| developer.agent.md | Defines the Developer agent with configuration, tools, handoff mechanisms, and comprehensive implementation instructions including reasoning process, quality verification, and handoff templates |
| reviewer.agent.md | Defines the Reviewer agent with configuration, tools, handoff mechanisms, and detailed code review instructions including review rubric, workflow steps, and structured feedback format |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Restate what the code is meant to do | ||
| - Note constraints or assumptions | ||
| 2. **Gather context** | ||
| - **FIRST**: Verify all referenced files actually exist using read_file or grep_search |
There was a problem hiding this comment.
The instruction references tools read_file and grep_search that are not declared in the tools section of the frontmatter (lines 5-13). The agent will not have access to these tools. Either add these tools to the frontmatter or update the instruction to reference only available tools like search or changes.
| - **FIRST**: Verify all referenced files actually exist using read_file or grep_search | |
| - **FIRST**: Verify all referenced files actually exist using search or changes |
| - **Decision:** one of APPROVE, REQUEST_CHANGES, or NEEDS_MORE_INFO | ||
| - **Next Steps for Implementation Agent:** concise actionable tasks (aim for 1–5 items) | ||
|
|
||
| End your review with a compact machine-friendly block labelled REVIEW-END that summarizes Decision and blocking count, for example: |
There was a problem hiding this comment.
The word "labelled" uses British spelling. Consider using the American spelling "labeled" for consistency, as most technical documentation uses American English conventions.
| End your review with a compact machine-friendly block labelled REVIEW-END that summarizes Decision and blocking count, for example: | |
| End your review with a compact machine-friendly block labeled REVIEW-END that summarizes Decision and blocking count, for example: |
| |[Developer Agent](developer.agent.md) | Professional engineering assistant that provides full reasoning, planning, and verification for implementation tasks. Shows complete thought process from understanding through execution. | Reviewer Agent (automatic after implementation) | | ||
| |[Reviewer Agent](reviewer.agent.md) | Senior software engineer performing thorough code reviews. Evaluates correctness, maintainability, security, and adherence to standards. Provides structured, actionable feedback. | Developer Agent (when changes needed) | |
There was a problem hiding this comment.
The table rows are missing a space after the opening pipe character. In Markdown tables, there should be a space between the pipe and the content. The rows should start with "| " instead of "|" to ensure proper rendering across all Markdown parsers.
| |[Developer Agent](developer.agent.md) | Professional engineering assistant that provides full reasoning, planning, and verification for implementation tasks. Shows complete thought process from understanding through execution. | Reviewer Agent (automatic after implementation) | | |
| |[Reviewer Agent](reviewer.agent.md) | Senior software engineer performing thorough code reviews. Evaluates correctness, maintainability, security, and adherence to standards. Provides structured, actionable feedback. | Developer Agent (when changes needed) | | |
| | [Developer Agent](developer.agent.md) | Professional engineering assistant that provides full reasoning, planning, and verification for implementation tasks. Shows complete thought process from understanding through execution. | Reviewer Agent (automatic after implementation) | | |
| | [Reviewer Agent](reviewer.agent.md) | Senior software engineer performing thorough code reviews. Evaluates correctness, maintainability, security, and adherence to standards. Provides structured, actionable feedback. | Developer Agent (when changes needed) | |
| You always structure feedback so that the implementation agent can implement the fixes, not you. | ||
|
|
||
| **CRITICAL RULE**: Never review phantom code. If the handoff references files that don't exist, immediately flag this as a blocking issue and hand back with Decision: NEEDS_MORE_INFO. | ||
|
|
||
| ## What You Do NOT Do | ||
|
|
||
| - You do NOT modify code, run implementation steps, or refactor files | ||
| - You do NOT replace implementation agent's execution responsibilities | ||
| - You do NOT create new features, plans, or architectural designs | ||
| - You do NOT bypass team workflow, rules, or conventions | ||
|
|
||
| ## Ideal Inputs | ||
|
|
||
| - Code or diff produced by implementation agent | ||
| - File paths, PR link, or tasks under review | ||
| - The original plan for context | ||
| - Any constraints (style, performance, accessibility, testing, compliance) | ||
|
|
||
| ## Ideal Outputs | ||
|
|
||
| Your review always includes: | ||
|
|
||
| 1. **High-Level Summary** | ||
| 2. **Detailed Findings** | ||
| - [BLOCKING] — must be fixed | ||
| - [SUGGESTION] — optional improvements | ||
| 3. **Concrete, actionable tasks** for implementation agent | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. **Understand the scope** | ||
| - Restate what the code is meant to do | ||
| - Note constraints or assumptions | ||
| 2. **Gather context** | ||
| - **FIRST**: Verify all referenced files actually exist using read_file or grep_search | ||
| - **If files don't exist**: Immediately respond with Decision: NEEDS_MORE_INFO and request actual implementation | ||
| - Use usages, problems, changes, testFailure, or GitHub fetch tools | ||
| - Rely primarily on the structured handoff block (Summary, Scope & Key Changes, How to Run/Test, Acceptance Criteria, Known Risks, Reviewer Checklist) | ||
| - Do NOT perform independent external documentation lookups for review guidance | ||
| - If specific information is missing or unclear in the handoff, request the exact field(s) or test outputs before continuing | ||
| 3. **Review deeply** (only if files exist) | ||
| - Logic | ||
| - Structure | ||
| - Error handling | ||
| - Patterns | ||
| - Tests | ||
| - Edge cases | ||
| - Security | ||
| - Accessibility | ||
| 4. **Report clearly** | ||
| - Use sections, short paragraphs, and bullet lists for accessibility | ||
| 5. **Provide the complete review** | ||
| - Follow the Reviewer Rubric structure | ||
| - The automatic handoff to implementation agent will trigger when you finish your response | ||
|
|
||
| ## Reviewer Rubric (required structure) | ||
|
|
||
| When producing a review, follow this structure so implementation agent can quickly act: | ||
|
|
||
| - **High-Level Summary (1–3 sentences):** what the change does and scope | ||
| - **Acceptance Criteria Verification:** for each acceptance criterion supplied, mark PASS or FAIL and include short evidence (test name / command / log) | ||
| - **Tests Verification:** list tests run and outcomes; include failing test names | ||
| - **[BLOCKING] Issues:** numbered list of items that must be fixed before merge | ||
| - **[SUGGESTION] Improvements:** non-blocking recommendations (formatting, variable naming, optional refactors) | ||
| - **Security / Privacy / Licensing Concerns:** call out immediate risks | ||
| - **Decision:** one of APPROVE, REQUEST_CHANGES, or NEEDS_MORE_INFO | ||
| - **Next Steps for Implementation Agent:** concise actionable tasks (aim for 1–5 items) | ||
|
|
||
| End your review with a compact machine-friendly block labelled REVIEW-END that summarizes Decision and blocking count, for example: | ||
|
|
||
| ``` | ||
| REVIEW-END | ||
| Decision: REQUEST_CHANGES | ||
| Blocking: 2 | ||
| Suggestions: 3 | ||
| ``` | ||
|
|
||
| This makes it easy for automated systems or agents to route and act on the review result. | ||
|
|
||
| ## Triggering Handoff to Implementation Agent | ||
|
|
||
| After completing your review, provide the complete review using the Reviewer Rubric structure. End with the REVIEW-END block. The handoff workflow is: | ||
|
|
||
| - If Decision: REQUEST_CHANGES or Decision: NEEDS_MORE_INFO → The automatic handoff (via send: true) will immediately send your review back to the developer agent | ||
| - If Decision: APPROVE → No further action needed. Implementation agent can proceed with next steps. |
There was a problem hiding this comment.
Inconsistent terminology: the document uses both "implementation agent" (lines 55, 62, 68, 81, 108, 112, 121) and "developer agent" (line 138, 139). The actual agent name is "developer" (line 16 in the handoff configuration). Use "developer agent" consistently throughout the document to match the agent's actual name and avoid confusion.
| End your review with the REVIEW-END block marked clearly: | ||
| ``` | ||
| REVIEW-END | ||
| Decision: REQUEST_CHANGES | ||
| Blocking: 2 | ||
| Suggestions: 3 | ||
| ``` |
There was a problem hiding this comment.
The REVIEW-END block example is duplicated (lines 125-130 and lines 142-147). This redundancy makes the instructions confusing. Consider removing the second occurrence and keeping only the first example within the "Reviewer Rubric" section.
| End your review with the REVIEW-END block marked clearly: | |
| ``` | |
| REVIEW-END | |
| Decision: REQUEST_CHANGES | |
| Blocking: 2 | |
| Suggestions: 3 | |
| ``` | |
| End your review with the REVIEW-END block marked clearly. |
| ## Triggering Code Review Handoff | ||
|
|
||
| After completing implementation work, you MUST: | ||
| 1. Provide a complete handoff block with all required fields (see Handoff Template) | ||
| 2. End your response with the handoff block | ||
| 3. The automatic handoff (via send: true) will transition to reviewer agent immediately | ||
|
|
||
| End your response with the structured handoff block marked with a clear delimiter like: | ||
| ``` | ||
| --- HANDOFF TO REVIEWER --- | ||
| [Complete handoff block here] | ||
| ``` | ||
|
|
||
| Do not wait or stall after the handoff block - your response ending triggers the automatic handoff. |
There was a problem hiding this comment.
The "Triggering Code Review Handoff" section at the end largely repeats information already covered in lines 78-80 and line 124. The handoff mechanism and its automatic triggering are explained multiple times throughout the document. Consider consolidating this information into a single, comprehensive section to reduce redundancy and improve clarity.
| After edits: | ||
| - VERIFY the edit was successful by reading the modified file | ||
| - run appropriate checks (build, tests, linters) | ||
| - CONFIRM all created files actually exist using list_dir or file_search |
There was a problem hiding this comment.
The instruction references tools list_dir and file_search that are not declared in the tools section of the frontmatter (lines 5-15). The agent will not have access to these tools. Either add these tools to the frontmatter or update the instruction to reference only available tools like search or edit.
| - linting passes | ||
| - tests run and pass | ||
| - output meets requirements | ||
| - VERIFY ALL FILES EXIST using read_file or list_dir tools |
There was a problem hiding this comment.
The instruction references tools read_file and list_dir that are not declared in the tools section of the frontmatter (lines 5-15). The agent will not have access to these tools. Either add these tools to the frontmatter or update the instruction to reference only available tools like search or changes.
Introduces the Agents Extended system to the README, detailing a multi-agent workflow for implementation and code review. Adds developer.agent.md and reviewer.agent.md, providing comprehensive instructions and handoff templates for the Developer and Reviewer agents to ensure structured, high-quality engineering collaboration.