feat: establish ROOT delegation model, optimize model selection, enhance agent workflows#46
Merged
Conversation
Add canonical workflow paths and PR comment routing to orchestrator: - Add Workflow Paths (Canonical Reference) table with Quick Fix, Standard, Strategic paths - Add PR Comment Routing section with decision tree - Add PR Comment entries to Agent Sequences by Task Type (quick fix, standard, strategic) - Add PR review comment to Quick Classification table - Add PR comment triage to Routing Heuristics - Add .agents/pr-comments/ to Output Directory Regenerated VS Code and Copilot CLI agent files from updated template. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update template with full workflow protocol (Context Gathering, Comment Map, Analysis, Task List, Immediate Replies, Implementation, PR Update, Verification) - Add pagination support for comment retrieval - Add Comment Map template saved to .agents/pr-comments/PR-[number]/ - Simplify Core Identity to thin coordination layer - Streamline Memory Protocol - Add Anti-Patterns to Avoid section - Fix nested markdown code blocks to use 4-backtick fences 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…ed activities - Add Retrospective Flow diagram showing all 6 phases (0-5) - Phase 0: Data Gathering with 4-Step Debrief, Execution Trace, Outcome Classification - Phase 1: Generate Insights with Five Whys, Fishbone, Force Field, Patterns, Learning Matrix - Phase 2: Diagnosis with priority order and template - Phase 3: Decide What to Do with Action Classification, SMART Validation, Dependency Ordering - Phase 4: Learning Extraction with atomicity scoring and templates - Phase 5: Close the Retrospective with +/Delta, ROTI, Helped/Hindered/Hypothesis - Add Memory Storage section delegating to memory agent - Update description to match Claude conventions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add comprehensive 'When to Create an ADR' criteria - Add Definition of Ready (START) checklist - Add Definition of Done (ecADR) checklist - Upgrade ADR template to MADR 4.0 format with frontmatter - Add ADR anti-patterns to avoid table - Add ADR review checklist - Standardize file naming to architecture-impact-analysis-[feature].md - Update output location to ADR-NNNN and DESIGN-REVIEW naming
- Synchronize MADR 4.0 ADR template from Claude agent - Add START (Definition of Ready) and ecADR (Definition of Done) sections - Add ADR anti-patterns and review checklist - Update file naming conventions for consistency - Update Memory Protocol language for clarity
Regenerated using Generate-Agents.ps1 after template sync: - VS Code architect.agent.md - Copilot CLI architect.agent.md Drift detection: architect agent at 100% similarity
Update agent descriptions with action-oriented, scoped, trigger-aware patterns for all agents in the Claude folder. Changes include: - explainer: document type specification, lifecycle guidance - high-level-advisor: strategic advisory triggers - implementer: code/test execution conditions - independent-thinker: contrarian analysis triggers - memory: cross-session context operations - orchestrator: coordination routing conditions - planner: work package planning triggers - pr-comment-responder: PR feedback handling - qa: test strategy and verification triggers - retrospective: full structured framework sync (Phases 0-5) - roadmap: strategic outcome focus - security: vulnerability assessment triggers - skillbook: atomic skill management - task-generator: epic decomposition triggers
Update all shared template descriptions to match Claude source agents. This ensures consistent descriptions across all generated platforms. Pattern applied: [Role/Expertise] + [Primary Actions] + [Trigger Conditions] All 18 templates updated: - analyst, architect, critic, devops - explainer, high-level-advisor, implementer, independent-thinker - memory, orchestrator, planner, pr-comment-responder - qa, retrospective, roadmap, security, skillbook, task-generator
Regenerate VS Code and Copilot CLI agents using Generate-Agents.ps1. All 36 agent files updated with new robust descriptions. Drift detection verified: - 18 agents compared - All pass 80% similarity threshold - 0 drift detected
Changed from impact-analysis-[feature]-[domain].md to impact-analysis-[domain]-[feature].md for consistency across agents. Affected agents: architect, security, qa, implementer, devops, planner
…is paths Aligned with Claude source file path pattern change: impact-analysis-[domain]-[feature].md
VS Code and Copilot CLI agents regenerated from updated shared templates.
Standardized file naming pattern across CLAUDE.md and USING-AGENTS.md.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR comprehensively enhances the agent system with improved workflows, standardized descriptions, and consistent file naming patterns across all three platforms (Claude, VS Code, Copilot CLI). The changes focus on making agents more discoverable and usable through detailed descriptions with explicit use cases and triggers.
Key Changes:
- Enhanced 4 major agents with comprehensive structured workflows (orchestrator, pr-comment-responder, retrospective, architect)
- Added robust 2-3 sentence descriptions to all 18 agents explaining what they do, key capabilities, and when to use them
- Standardized impact analysis file naming from
impact-analysis-[feature]-[domain].mdtoimpact-analysis-[domain]-[feature].mdfor alphabetical sorting
Reviewed changes
Copilot reviewed 74 out of 74 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| templates/agents/*.shared.md (18 files) | Enhanced descriptions with use cases; standardized impact analysis paths |
| src/vs-code-agents/*.agent.md (18 files) | Regenerated from templates with enhanced descriptions and paths |
| src/copilot-cli/*.agent.md (18 files) | Regenerated from templates with enhanced descriptions and paths |
| src/claude/*.md (18 files) | Enhanced descriptions matching shared templates |
| templates/agents/retrospective.shared.md | Added comprehensive 6-phase workflow with 10+ structured retrospective activities |
| templates/agents/pr-comment-responder.shared.md | Added 8-phase workflow for PR comment handling with detailed delegation patterns |
| templates/agents/orchestrator.shared.md | Added PR comment routing section with canonical workflow path definitions |
| templates/agents/architect.shared.md | Enhanced with MADR 4.0 ADR template, START/ecADR checklists, anti-patterns table |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Update regex to use [\w-]+ for key matching to support keys like 'argument-hint' - Add 'argument-hint' to field order in Format-FrontmatterYaml - Enables new UX affordance field for agent prompting hints
Add argument-hint field to YAML frontmatter for all 18 agent definitions providing inline prompting guidance for users: - analyst: Describe the topic, issue, or feature to research - architect: Describe the design decision or architecture concern - critic: Describe the plan or document to review critically - devops: Describe the CI/CD, infrastructure, or deployment task - explainer: Describe the feature or concept to document - high-level-advisor: Describe your strategic question or decision - implementer: Describe the code changes or feature to implement - independent-thinker: Describe the decision or assumption to challenge - memory: Describe what to store, retrieve, or manage in memory - orchestrator: Describe your task or goal for end-to-end orchestration - planner: Describe the epic or feature to break into work packages - pr-comment-responder: Provide the PR comment or review to address - qa: Describe the feature or changes to verify and test - retrospective: Describe the completed work to analyze for learnings - roadmap: Describe the product vision or strategic question - security: Describe the security concern or code to audit - skillbook: Describe the skill or pattern to document - task-generator: Describe the PRD or milestone to decompose into tasks This UX affordance helps users understand how to prompt each agent effectively from IDE integrations and CLI tools.
Auto-generated by Generate-Agents.ps1 from updated shared templates. VS Code agents: argument-hint appears in frontmatter for IDE integration Copilot CLI agents: argument-hint included for consistency (not used by CLI)
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughOrchestrator becomes the ROOT coordinator: planner produces an impact plan, orchestrator invokes specialists one‑at‑a‑time (orchestrator-managed sequential/parallel), specialists return results to orchestrator, outputs renamed to domain-first impact-analysis files, memory calls standardized to cloudmcp-manager, and subagents are forbidden from delegating. Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Files/areas requiring extra attention:
Possibly related issues
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (72)
Comment |
📝 WalkthroughWalkthroughReorganizes agent metadata and deliverable filename conventions across Claude, Copilot CLI, and VS Code platforms. Renames impact-analysis output files from Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Areas requiring extra attention:
Possibly related issues
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
templates/agents/memory.shared.md (1)
205-251: Skill citation protocol enhances feedback loop integration.The new section adds explicit format for agents to cite skills during execution (Applying [Skill-ID], Strategy, Expected Outcome, Result, Skill Validated). This creates measurable data for retrospective analysis. Verify that retrospective agent documentation aligns with this citation format and can consume validation feedback.
…chitecture - Add Architecture Constraint section defining ROOT agent role - Document that subagents CANNOT delegate to other subagents - Show valid vs invalid delegation patterns with diagrams - Update impact analysis flow: orchestrator manages all routing - Clarify planner creates analysis plan, orchestrator executes consultations - Update handoff protocol to emphasize ROOT agent responsibility - Add visual workflow showing orchestrator at center of all delegation - Update ideation workflow to show orchestrator sequential routing BREAKING CHANGE: Subagents can no longer delegate. All delegation flows through orchestrator. Refs #46
Analysis & Planning Agents: - analyst: Add handoff protocol, return recommendations to orchestrator - architect: Update to return results rather than announcing handoffs - planner: Clarify mandatory return to orchestrator for critic routing - critic: Update escalation to return conflict to orchestrator (no direct delegation) Remove Task() calls to high-level-advisor, planner, implementer All agents now explicitly state they CANNOT delegate to other agents. Subagents return results and recommendations; orchestrator handles routing. Refs #46
Execution Agents: - implementer: Return completion status to orchestrator (no direct qa delegation) - qa: Return test results with failure routing recommendations - devops: Add handoff protocol for infrastructure work completion - security: Add handoff protocol for security assessment completion All agents now return results to orchestrator who handles next routing decision. Refs #46
…tocols Strategic & Documentation Agents: - roadmap: Update to recommend routing rather than direct routing - high-level-advisor: Add handoff protocol returning guidance to orchestrator - independent-thinker: Add handoff protocol returning analysis to orchestrator - explainer: Add handoff protocol returning documentation to orchestrator - task-generator: Add handoff protocol returning task breakdown to orchestrator All agents now return results to orchestrator with routing recommendations. Refs #46
Learning & Memory Agents: - retrospective: Add handoff protocol returning learnings to orchestrator - skillbook: Coordinate with orchestrator for skill updates routing - memory: Clarify unique service role, returns memory operation results Memory agent is unique as a service agent - other agents delegate TO it, and it returns results to them. Refs #46
- Update impact analysis section to show orchestrator manages all routing - Clarify orchestrator is ROOT agent, subagents cannot delegate - Update feature development workflow to show orchestrator coordination - Fix example workflow to show planner creates plan, orchestrator executes - Update consultation process to show orchestrator invokes each specialist - Add critical note about one-level delegation architecture constraint Documentation now accurately reflects Claude Code's one-level delegation architecture where orchestrator is the only agent capable of delegation. Refs #46
Add handoff protocol sections to 9 agent templates to enforce one-level delegation architecture: - devops, security, explainer (execution & documentation) - high-level-advisor, independent-thinker (strategic) - task-generator, retrospective (planning & learning) - memory, pr-comment-responder (support) Each protocol includes: - CANNOT delegate constraint - Return to orchestrator requirement - Handoff options table (recommendations for orchestrator) Refs #46
Regenerate Copilot CLI agent files from updated templates. All agents now include handoff protocols enforcing one-level delegation: - devops, security, explainer - high-level-advisor, independent-thinker - task-generator, retrospective - memory, pr-comment-responder Generated from templates via build/Generate-Agents.ps1 Refs #46
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 80 out of 80 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Owner
Author
PR Comment Review SummaryAll CodeRabbit review comments have been addressed: Verified Resolutions
Re: CodeRabbit Follow-up on skillbook.md (comment 2622884060)The Memory Protocol section at line 124 already states 'Use cloudmcp-manager memory tools directly for cross-session context'. The Handoff Protocol section (line 237) also correctly references 'cloudmcp-manager memory tools'. The current file state is consistent with the clarification note at line 249. All 15 original CodeRabbit comments resolved. |
- Use POST /pulls/{pull_number}/comments with in_reply_to field
- Remove incorrect /issues/{number}/comments usage for replies
- Add anti-pattern warning about wrong reply API
- Issue comments API places replies out of context
Fixes reply threading for PR review comments
Regenerated pr-comment-responder agents with corrected reply API
… responses for PR comments
This was referenced Dec 18, 2025
This was referenced Jan 24, 2026
Closed
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Agent System Architecture Overhaul
Summary
This PR introduces significant architectural changes to the multi-agent system, establishing a strict one-level delegation model, optimizing model selection for cost efficiency, and enhancing several agent workflows with comprehensive phase-based execution patterns.
Key Impact: 77 files changed, ~6,500 insertions, ~2,100 deletions across all platforms (Claude, VS Code, Copilot CLI)
Breaking Changes
ROOT Agent Delegation Model
Establishes orchestrator as the ROOT agent with strict one-level delegation:
Orchestrator -> Subagent -> Back to OrchestratorRationale: Prevents infinite nesting while maintaining clear orchestrator-worker separation. Orchestrator is responsible for all coordination, handoffs, and routing decisions.
Major Enhancements
1. Agent Model Selection Optimization (ADR-002)
Optimized model selection for cost and latency based on structured evaluation criteria:
Model Assignments:
Expected Impact: 40-50% cost reduction on agent invocations
2. Enhanced Agent Workflows
PR Comment Responder - 8-Phase Workflow
Retrospective Agent - 6-Phase Workflow
Orchestrator - PR Comment Routing
3. Architect Enhancements
Standardization & Fixes
UX Improvements
Path Standardization
impact-analysis-[feature]-[domain].md->impact-analysis-[domain]-[feature].mdBuild Fixes
model-id)Documentation
Platform Synchronization
All 36 platform agents regenerated from shared templates:
Commits by Theme
Architecture (Breaking)
feat(orchestrator): establish ROOT agent with one-level delegation architecturerefactor(agents): update *-agents handoff protocols(4 commits)docs(claude): update documentation for one-level delegation modelCost Optimization
refactor: optimize agent model selection for cost and latencydocs: add ADR-002 agent model selection optimizationEnhanced Workflows
feat(orchestrator): add PR comment routing and workflow pathsfeat(pr-comment-responder): add comprehensive 8-phase workflowfeat(retrospective): add comprehensive 6-phase workflow with structured activitiesfeat(architect): enhance ADR section with MADR 4.0 templateUX & Tooling
feat(agents): add argument-hint UX affordance to all agentsfeat: add 'serena/*' tool to various agents and templatesStandardization
fix(claude): standardize impact analysis file path patternfeat(claude): add robust descriptions to remaining agentsfix(build): support hyphenated keys in YAML frontmatter parsingPlatform Sync (Chore)
refactor(templates): add handoff protocols to agent templateschore(agents): regenerate platform agents(multiple commits)Type of Change
Testing
Validation Performed
Review Checklist
Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com