fix: inline routing guidance in orchestrator agents by rjmurillo · Pull Request #25 · rjmurillo/ai-agents

rjmurillo · 2025-12-14T12:17:47Z

Summary

Replace external documentation links with inline content to make orchestrator agents self-contained and portable.

Problem

The orchestrator agents referenced three external documentation files:

../docs/task-classification-guide.md
../docs/orchestrator-routing-algorithm.md
../docs/diagrams/routing-flowchart.md

While these files exist, agents should be self-contained and not rely on external documentation for core functionality.

Solution

Inlined the essential routing guidance directly into all three orchestrator files:

claude/orchestrator.md
copilot-cli/orchestrator.agent.md
vs-code-agents/orchestrator.agent.md

Content Added

Task Classification - Three dimensions (Task Type, Complexity Level, Risk Level)
Agent Sequences by Task Type - Table showing recommended agent chains for each task type

Test Plan

Pre-commit hooks pass (markdown linting, security checks)
All three orchestrator files updated consistently

Fixes #24

🤖 Generated with Claude Code

Replace external documentation links with inline content to make orchestrator agents self-contained and portable. The external docs exist but agents should not rely on them for core functionality. Fixes #24 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

rjmurillo

Copilot

Pull request overview

This PR inlines routing guidance from external documentation files into the orchestrator agent definitions across all three platforms. The goal is to make orchestrator agents self-contained and portable by embedding task classification rules and agent sequence mappings directly in the agent files, eliminating dependencies on external documentation.

Key changes:

Removed references to three external documentation files (task-classification-guide.md, orchestrator-routing-algorithm.md, routing-flowchart.md)
Added inline Task Classification section defining three classification dimensions (Task Type, Complexity Level, Risk Level)
Added Agent Sequences by Task Type table mapping eight task types to their recommended agent chains

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

File	Description
vs-code-agents/orchestrator.agent.md	Replaced external documentation links with inline routing guidance including task classification and agent sequence table
copilot-cli/orchestrator.agent.md	Replaced external documentation links with inline routing guidance including task classification and agent sequence table
claude/orchestrator.md	Replaced external documentation links with inline routing guidance including task classification and agent sequence table

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Address PR review feedback: - Add missing Refactoring row to all orchestrator agent tables - Update docs/task-classification-guide.md to match enhanced sequences: - Infrastructure: analyst -> devops -> security -> critic -> qa - Security: analyst -> security -> architect -> critic -> implementer -> qa 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

coderabbitai · 2025-12-14T12:32:59Z

Caution

Review failed

The head commit changed during the review from 350c197 to a93ac9d.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch fix/issue-24-orchestrator-broken-links

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot · 2025-12-14T12:38:24Z

@rjmurillo I've opened a new pull request, #26, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2025-12-14T12:38:25Z

@rjmurillo I've opened a new pull request, #27, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2025-12-14T12:38:38Z

@rjmurillo I've opened a new pull request, #28, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2025-12-14T12:38:40Z

@rjmurillo I've opened a new pull request, #29, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2025-12-14T12:38:44Z

@rjmurillo I've opened a new pull request, #31, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2025-12-14T12:38:44Z

@rjmurillo I've opened a new pull request, #30, to work on those changes. Once the pull request is ready, I'll request review from you.

coderabbitai · 2025-12-14T12:38:59Z

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Multiple orchestrator agent documentation files are updated to inline task classification, complexity assessment, and agent sequences directly, removing external document references. Infrastructure and Security agent routing sequences are revised to include Analyst roles.

Changes

Cohort / File(s)	Summary
Orchestrator agent routing documentation `claude/orchestrator.md`, `copilot-cli/orchestrator.agent.md`, `vs-code-agents/orchestrator.agent.md`	Replace external routing algorithm references with inlined Task Classification (Task Type, Complexity Level, Risk Level), Complexity Assessment framework, and explicit Agent Sequences per task type. Removes links to non-existent docs.
Task classification guidance `docs/task-classification-guide.md`	Update Infrastructure agent sequence to include Analyst at start (analyst → devops → security → critic → qa). Update Security agent sequence to include Analyst at start and Critic in middle (analyst → security → architect → critic → implementer → qa).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Changes are primarily documentation restructuring with consistent patterns applied across multiple files
New routing sequences in task-classification-guide.md require verification against intended agent flow
No functional code changes; focus review on ensuring inlined guidance is accurate and complete

Possibly related PRs

PR #23: Modifies orchestrator/routing docs with identical task classification, complexity assessment, and agent sequences refactoring
PR #20: Makes the same routing documentation changes—replacing external routing algorithm references with inlined task classification and explicit agent sequences

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows conventional commit format with 'fix:' prefix and clearly describes the main change of inlining routing guidance.
Description check	✅ Passed	Description clearly explains the problem (broken external links), solution (inline content), and testing done, directly related to changeset.
Linked Issues check	✅ Passed	PR implements the primary solution from issue #24: removing broken links and inlining routing guidance into orchestrator agents [#24].
Out of Scope Changes check	✅ Passed	All changes focus on inlining routing guidance into orchestrator files and updating agent sequences consistently with issue #24 requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch fix/issue-24-orchestrator-broken-links

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c8cd59d and a93ac9d.

📒 Files selected for processing (4)

claude/orchestrator.md (1 hunks)
copilot-cli/orchestrator.agent.md (1 hunks)
docs/task-classification-guide.md (2 hunks)
vs-code-agents/orchestrator.agent.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.md

📄 CodeRabbit inference engine (.agents/architecture/ADR-001-markdown-linting.md)

**/*.md: Add language identifiers to all fenced code blocks (MD040). Use appropriate language identifiers: csharp for C#, powershell for PowerShell, bash for shell, json for JSON, yaml for YAML, markdown for Markdown, text for plain text or generic/pseudo code
Wrap generic types in backticks to escape angle brackets (e.g., ArrayPool<T> instead of ArrayPool) to comply with MD033 inline HTML restrictions and ensure proper rendering
Add blank lines around code blocks to comply with MD031 markdown linting requirements
Add blank lines around lists to comply with MD032 markdown linting requirements
Add blank lines around headings to comply with MD022 markdown linting requirements
Use ATX-style headings (# Heading) consistently across all markdown documents (MD003)
Use fenced code block style (triple backticks) consistently, with backtick delimiters rather than tildes (MD046, MD048)
Allow only specific HTML elements in markdown: <br>, <kbd>, <sup>, <sub>. Escape or avoid other inline HTML elements to comply with MD033 restrictions

MITRE CWE database references in security documentation must use the format [CWE-XXX](https://cwe.mitre.org/data/definitions/XXX.html) with the numeric ID in both the label and URL path

**/*.md: Use skill ID convention format: Skill-[Category]-[Number] for skills and Anti-[Category]-[Number] for anti-patterns
Each skill must follow the required structure: Statement (max 15 words), Context, Atomicity score (0-100%), Evidence, Impact, and Tags
Score skills for atomicity using the scale: 90-100% (Excellent - ready for storage), 70-89% (Good - may need refinement), 50-69% (Acceptable - consider splitting), <50% (Needs Work - too vague)
Tag each skill with one of: helpful (contributed to success), harmful (caused failure), or neutral (no measurable impact)
When citing skills during implementation, use the format: Applying [Skill-ID], Strategy [description], Expected [outcome], Result [actual outcome], Skill Validated...

Files:

vs-code-agents/orchestrator.agent.md
docs/task-classification-guide.md
claude/orchestrator.md
copilot-cli/orchestrator.agent.md

⚙️ CodeRabbit configuration file

**/*.md: Writing Quality: - Grade 9 reading level - Active voice, direct address - Short sentences (under 15 words ideal) - No fluff, filler, or marketing language - Replace adjectives with data where possible - Every sentence must pass the "so what" test
Flag: - Passive voice - Vague language (nearly, some, almost, very) - Jargon without definitions - Broken links and outdated procedures - Inconsistency with code changes in same PR - Missing context for new features or APIs
Ignore (handled by .markdownlint-cli2.yaml): - Markdown formatting and style - Heading level choices - Link formatting variations - Minor punctuation preferences

Files:

vs-code-agents/orchestrator.agent.md
docs/task-classification-guide.md
claude/orchestrator.md
copilot-cli/orchestrator.agent.md

{claude,vs-code-agents,copilot-cli}/{*.md,*.agent.md}

📄 CodeRabbit inference engine (.agents/planning/phase1-implementation-plan.md)

{claude,vs-code-agents,copilot-cli}/{*.md,*.agent.md}: Document all agent capabilities with one-sentence core specialty, 5-10 specific capabilities, critical limitations, input/output format specs, compatible partnerships, invocation guidelines, and use cases across all three platforms (Claude Code, VS Code Agents, Copilot CLI)
Establish and classify all 18 agents into three tiers (TIER 1: core, TIER 2: common, TIER 3: specialized) with justified tier assignments and documented overlapping capabilities with disambiguation rules

Files:

vs-code-agents/orchestrator.agent.md
claude/orchestrator.md
copilot-cli/orchestrator.agent.md

docs/{orchestrator-routing-algorithm.md,task-classification-guide.md}

📄 CodeRabbit inference engine (.agents/planning/phase-2-implementation-plan.md)

Document orchestrator routing logic that validates CWE-78 shell injection incident would have been routed to security agent with correct task classification, complexity assessment, and risk determination

Files:

docs/task-classification-guide.md

**/docs/**/*.md

📄 CodeRabbit inference engine (.agents/skills/documentation.md)

Structure requirements documents with Purpose, Configuration, Required Rules, Disabled Rules, Common Patterns, Troubleshooting, and References sections

Files:

docs/task-classification-guide.md

docs/**/*.md

📄 CodeRabbit inference engine (docs/markdown-linting.md)

docs/**/*.md: Every fenced code block must include a language identifier
Fenced code blocks must be surrounded by blank lines
Lists must be surrounded by blank lines
Headings must be surrounded by blank lines
Inline HTML is restricted; generic types must be wrapped in backticks to avoid being interpreted as HTML tags
Use appropriate language identifiers for code blocks: 'csharp' for C#, 'powershell' for PowerShell, 'bash' for Bash/Shell, 'json' for JSON, 'yaml' for YAML, 'markdown' for Markdown examples, 'text' for plain text/pseudo-code, 'sql' for SQL, 'xml' or 'html' for XML/HTML, 'javascript' for JavaScript, 'typescript' for TypeScript, 'python' for Python
Exclude node_modules/ and .agents/ directories from markdown linting

Files:

docs/task-classification-guide.md

🧠 Learnings (1)

📚 Learning: 2025-12-14T09:25:36.727Z

Learnt from: CR
Repo: rjmurillo/ai-agents PR: 0
File: .agents/planning/phase-2-implementation-plan.md:0-0
Timestamp: 2025-12-14T09:25:36.727Z
Learning: Applies to docs/orchestrator-routing-algorithm.md : Create explicit routing algorithm for task-to-agent assignment including task type classification (feature, bug, infrastructure, security, strategic), complexity assessment (simple, multi-step, multi-domain), risk level determination (low, medium, high, critical), execution strategy (serial vs. parallel), and result synthesis

Applied to files:

vs-code-agents/orchestrator.agent.md
claude/orchestrator.md
copilot-cli/orchestrator.agent.md

🔍 Remote MCP DeepWiki, GitHub Copilot

Quick context for PR #25 (fix/issue-24-orchestrator-broken-links → main)

PR metadata — fix: inline routing guidance in orchestrator agents #25 by rjmurillo (branch fix/issue-24-orchestrator-broken-links), created 2025-12-14; PR description: inline routing guidance to make orchestrator agents self-contained. citeGitHub Copilot::GitHub_Copilot_pull_request_read::
Files changed (patches): claude/orchestrator.md, copilot-cli/orchestrator.agent.md, vs-code-agents/orchestrator.agent.md — each inlines a “Task Classification” section (three dimensions) plus an “Agent Sequences by Task Type” table; docs/task-classification-guide.md also updated (Infrastructure & Security sequences now prefix with Analyst). See diff. citeGitHub Copilot::GitHub_Copilot_pull_request_read::
Replaced the three external references (../docs/task-classification-guide.md, ../docs/orchestrator-routing-algorithm.md, ../docs/diagrams/routing-flowchart.md) with inline guidance in the three orchestrator files. I searched the repo for those paths and found no remaining references. citeGitHub Copilot::GitHub_Copilot_search_code::
Repo wiki / docs (DeepWiki) contains orchestrator/routing and consistency pages; compare the new inline text to the canonical wiki guidance to ensure no semantic drift versus project-wide routing rules. citeDeepWiki::read_wiki_structure::DeepWiki::read_wiki_contents::
Orchestrator routing heuristics (task→agent mapping, conflict-resolution flow) are present in the indexed docs/wiki and should be cross-checked against the new inlined Agent Sequences to ensure required invariants (e.g., critic remains mandatory validation gate) were not changed. citeDeepWiki::ask_question::
This PR claims it “Fixes Orchestrator agent references non-existent documentation files #24” (the broken-docs issue) — issue Orchestrator agent references non-existent documentation files #24 describes the three missing external docs and that inlining was one proposed solution. citeGitHub Copilot::GitHub_Copilot_issue_read::

Concrete reviewer checklist (quick)

Verify the three orchestrator files contain semantically identical core identity, responsibilities, handoff table, and memory protocol (no platform drift). citeGitHub Copilot::GitHub_Copilot_pull_request_read::
Confirm docs/task-classification-guide.md change (analyst added to Infrastructure & Security sequences) is intentionally mirrored in all orchestrator implementations and does not violate the repo’s consistency rules. citeGitHub Copilot::GitHub_Copilot_pull_request_read::
Run a repo-wide search for any remaining references to the three original external paths (double-check the earlier automated search). citeGitHub Copilot::GitHub_Copilot_search_code::
Validate CI / pre-commit / markdown-lint checks the PR claims passed, and confirm there are no hidden link regressions or lint warnings. citeGitHub Copilot::GitHub_Copilot_pull_request_read::
Optionally compare the new inline routing table against the project’s canonical routing/consistency guidance (wiki/.github/copilot-code-review) to ensure no semantic regression (critic gate, memory/entity naming, output dirs). citeDeepWiki::read_wiki_contents::GitHub Copilot::GitHub_Copilot_pull_request_read::

Tools / sources I used

(PR metadata + file diffs).
(repo search for removed doc paths).
(issue Orchestrator agent references non-existent documentation files #24).
and (repo wiki index and pages).
(orchestrator routing heuristics summary).

🔇 Additional comments (7)

vs-code-agents/orchestrator.agent.md (2)

137-158: Agent Sequences table is complete and consistent across platforms.

The three previously flagged rows (Infrastructure, Security, Refactoring) are now present. Infrastructure and Security sequences correctly include Analyst at the start; Refactoring is properly documented. This matches the updated docs/task-classification-guide.md.

38-49: Code blocks correctly use text language identifier.

The code blocks at lines 38, 45, and 49 follow the MD040 requirement for language identifiers. text is the appropriate choice for pseudo-code and tool invocations per guidelines.

docs/task-classification-guide.md (1)

51-51: Agent Sequences correctly updated and consistent.

Infrastructure (line 51), Security (line 63), and Refactoring (line 107) now include Analyst and/or Critic roles as required. These match the sequences inlined in the three orchestrator agent files.

Also applies to: 63-63, 107-107

claude/orchestrator.md (2)

148-169: Agent Sequences table complete and consistent with platform implementations.

All three task types (Infrastructure, Security, Refactoring) are present with correct agent chains. Sequences match claude/orchestrator.md, copilot-cli, and vs-code-agents versions exactly.

50-50: Code blocks use correct text language identifiers.

Lines 50, 57, and 59 properly use text for pseudo-code and tool invocations per MD040 guidelines.

Also applies to: 57-57, 59-59

copilot-cli/orchestrator.agent.md (2)

137-158: Agent Sequences table is consistent across all three platform implementations.

Infrastructure, Security, and Refactoring sequences match the claude/orchestrator.md and vs-code-agents/orchestrator.agent.md versions exactly. No drift between platforms.

38-49: Code blocks correctly use text language identifier.

Lines 38, 40, and 49 properly use text for pseudo-code per MD040 guidelines.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot AI review requested due to automatic review settings December 14, 2025 12:17

Copilot started reviewing on behalf of rjmurillo December 14, 2025 12:18 View session

rjmurillo commented Dec 14, 2025

View reviewed changes

Copilot AI reviewed Dec 14, 2025

View reviewed changes

Copilot AI mentioned this pull request Dec 14, 2025

[WIP] Address feedback on inline routing guidance in orchestrator agents #26

Closed

Copilot AI mentioned this pull request Dec 14, 2025

Address PR feedback: Documentation already synchronized #27

Closed

21 tasks

This was referenced Dec 14, 2025

Address feedback on inline routing guidance in orchestrator agents #28

Closed

[WIP] Update inline routing guidance and infrastructure sequence documentation #29

Closed

This was referenced Dec 14, 2025

Address routing guidance feedback - no changes needed #30

Closed

[WIP] Update inline routing guidance in orchestrator agents #31

Closed

coderabbitai Bot approved these changes Dec 14, 2025

View reviewed changes

rjmurillo merged commit 35109a8 into main Dec 14, 2025
4 checks passed

rjmurillo deleted the fix/issue-24-orchestrator-broken-links branch December 14, 2025 12:43

coderabbitai Bot mentioned this pull request Dec 14, 2025

feat: Ideation Workflow, Prioritization Frameworks, and CodeRabbit Optimization #32

Merged

5 tasks

Uh oh!

Conversation

rjmurillo commented Dec 14, 2025

Summary

Problem

Solution

Content Added

Test Plan

Uh oh!

rjmurillo left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Dec 14, 2025

Review failed

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

Copilot AI commented Dec 14, 2025

Uh oh!

coderabbitai Bot commented Dec 14, 2025

Other AI code review bot(s) detected

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Pre-merge checks and finishing touches

Quick context for PR #25 (fix/issue-24-orchestrator-broken-links → main)

Concrete reviewer checklist (quick)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants