hierarchical-agents

Hierarchical Agent Management

This document describes the hierarchical agent management system in GitHub Agentic Workflows, which provides meta-orchestration capabilities to manage the 120+ agents in the repository.

Overview

The hierarchical agent system consists of specialized meta-orchestrator workflows that oversee, coordinate, and optimize the agent ecosystem. These meta-orchestrator agents operate at a higher level than regular workflows, monitoring and managing multiple agents to ensure overall system health and effectiveness.

Meta-Orchestrator Agents

1. Campaign Manager

**File:** `.github/workflows/campaign-manager.md`

**Purpose:** Strategic management of all active campaigns

**Responsibilities:**

• Discover and analyze all campaign specifications
• Monitor campaign health and performance
• Coordinate between campaigns to avoid conflicts
• Aggregate metrics across campaigns
• Make strategic decisions about campaign priorities
• Generate executive reports on campaign portfolio

**Schedule:** Daily

**Key Capabilities:**

• Cross-campaign coordination
• Resource optimization
• Performance trend analysis
• Strategic priority management
• Conflict detection and resolution

**Safe Outputs:**

• `create-issue`: Flag campaigns needing attention
• `add-comment`: Add coordination notes and recommendations
• `create-discussion`: Generate strategic reports
• `update-project`: Adjust campaign priorities

2. Workflow Health Manager

**File:** `.github/workflows/workflow-health-manager.md`

**Purpose:** Monitor and maintain health of all agentic workflows

**Responsibilities:**

• Track compilation status of all workflows
• Monitor workflow execution success/failure rates
• Analyze error patterns across workflows
• Map workflow dependencies and interactions
• Identify resource utilization issues
• Create maintenance issues proactively

**Schedule:** Daily

**Key Capabilities:**

• System-wide health monitoring (compilation status, execution rates, error patterns)
• Systemic issue detection
• Dependency mapping
• Performance optimization
• Proactive maintenance

**Safe Outputs:**

• `create-issue`: Report workflow problems (max: 10)
• `add-comment`: Update status and provide recommendations (max: 15)
• `update-issue`: Close resolved issues (max: 5)

3. Agent Performance Analyzer

**File:** `.github/workflows/agent-performance-analyzer.md`

**Purpose:** Analyze quality and effectiveness of AI agents

**Responsibilities:**

• Evaluate output quality of agent-created issues/PRs/comments
• Measure agent effectiveness and task completion rates
• Identify behavioral patterns and problematic behaviors
• Assess coverage and gaps in the agent ecosystem
• Generate quality improvement recommendations
• Track agent performance trends

**Schedule:** Daily

**Key Capabilities:**

• Quality assessment across all agent outputs
• Effectiveness measurement
• Behavioral pattern detection
• Ecosystem health analysis
• Actionable improvement recommendations

**Safe Outputs:**

• `create-issue`: Agent improvement recommendations (max: 5)
• `create-discussion`: Performance reports (max: 2)
• `add-comment`: Provide feedback and guidance (max: 10)

Architecture

Hierarchical Structure

┌─────────────────────────────────────────────┐
│      Meta-Orchestrators (Managerial)        │
│  ┌─────────────┐  ┌─────────────┐  ┌──────┐│
│  │  Campaign   │  │  Workflow   │  │Agent ││
│  │  Manager    │  │  Health     │  │Perf. ││
│  │             │  │  Manager    │  │Anal. ││
│  └──────┬──────┘  └──────┬──────┘  └───┬──┘│
└─────────┼─────────────────┼─────────────┼───┘
          │                 │             │
          ▼                 ▼             ▼
┌─────────────────────────────────────────────┐
│        Campaign Orchestrators               │
│  ┌─────────────┐         ┌─────────────┐   │
│  │  Campaign   │         │  Campaign   │   │
│  │  Alpha.g.md │         │  Beta.g.md  │   │
│  └──────┬──────┘         └──────┬──────┘   │
└─────────┼────────────────────────┼──────────┘
          │                        │
          ▼                        ▼
┌─────────────────────────────────────────────┐
│          Worker Workflows                   │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐   │
│  │Worker│  │Worker│  │Worker│  │Worker│   │
│  │  1   │  │  2   │  │  3   │  │  4   │   │
│  └──────┘  └──────┘  └──────┘  └──────┘   │
└─────────────────────────────────────────────┘

Key Principles

1. **Separation of Concerns:** Each meta-orchestrator has a distinct focus area 2. **Non-Intrusive:** Meta-orchestrators observe and recommend, they don't directly control workers 3. **Evidence-Based:** All decisions based on concrete metrics and data 4. **Actionable:** Outputs are specific recommendations with clear next steps 5. **Coordinated:** Meta-orchestrators complement each other without overlap 6. **Shared Memory:** Meta-orchestrators use common repo memory to share insights and coordinate actions

Shared Memory System

Meta-orchestrators use a shared repository memory branch (`memory/meta-orchestrators`) to persist data across runs and coordinate with each other.

**Memory Location:** `/tmp/gh-aw/repo-memory-default/memory/meta-orchestrators/`

**Shared Files:**

• `campaign-manager-latest.md` - Campaign portfolio health and decisions
• `workflow-health-latest.md` - Workflow compilation and execution status
• `agent-performance-latest.md` - Agent quality scores and patterns
• `shared-alerts.md` - Cross-orchestrator coordination notes and alerts

**Benefits:**

• **Avoid Duplicate Work:** Each orchestrator can see what others have already flagged
• **Coordinate Actions:** Orchestrators can build on each other's insights
• **Track Trends:** Historical data enables trend analysis across runs
• **Share Context:** Common understanding of ecosystem state

**Example Use Cases:**

• Campaign Manager sees that Workflow Health Manager flagged a failing workflow used by Campaign X
• Workflow Health Man