[Feature] Parallel Specialist Agents Execution Documentation

[JeremyDev87]

Parallel Specialist Agents Execution Documentation

Background

Currently, CodingBuddy’s parse_mode MCP tool returns the parallelAgentsRecommendation field to recommend parallel execution of specialist agents. However, the AI assistant does not automatically execute these agents.

In addition, documentation related to parallel execution is duplicated across claude-code.md and custom-instructions.md, creating an unnecessary maintenance burden.

---

Why Is This Work Necessary?

1. Parallel Specialist Agent Execution Is Not Working

Symptoms:

• Even when parallelAgentsRecommendation is returned in EVAL mode, the AI does not automatically dispatch parallel agents

• Users have no visibility into whether specialist agents are executed or not

Root Causes:

• Mandatory rules for parallel execution are not explicitly documented

• The AI interprets parallel execution as optional rather than required

Impact:

• Security reviews may be skipped (security-specialist not executed)

• Accessibility checks may be skipped (accessibility-specialist not executed)

• Performance analysis may be skipped (performance-specialist not executed)

• Overall code quality evaluation becomes incomplete

2. Maintenance Overhead Due to Documentation Duplication

Symptoms:

• Identical content exists in both claude-code.md and custom-instructions.md

• Any rule change requires manual synchronization across multiple files

Impact:

• Increased maintenance time (7 files × 5 minutes = 35 minutes)

• Risk of desynchronization between documents

• Inconsistent AI behavior due to documentation drift

---

Expected Benefits

1. Comprehensive Code Quality Evaluation

Before | After -- | -- Single-perspective review | Parallel analysis by 4 specialists Possible security review gaps | Mandatory execution of security specialist Manual agent invocation required | Automatic parallel execution

4. Establishment of a Single Source of Truth

claude-code.md (452 lines) ← Single Source of Truth
        ↑
custom-instructions.md (130 lines) ← Quick reference + links

Benefits:

• Consistent rule application

• Immediate propagation of changes

• Simplified document version management

---

Scope

Included:

• Add mandatory parallel execution rules to custom-instructions.md

• Add detailed parallel execution guidelines to claude-code.md

• Apply DRY principles (remove duplication and use link references)

• Document visibility patterns (emoji icons, status messages)

Excluded:

• MCP server code changes (already implemented)

• CI/CD link validation (follow-up issue)

• Updates to other adapter files (Cursor, Codex, etc.)

---

Success Criteria

• 4 specialist agents execute in parallel in EVAL mode

• Users can clearly see agent execution status

• Duplicate content removed from custom-instructions.md

• All tests pass (86 tests)