V3 Qe Fleet Coordination

v3-qe-fleet-coordination

Purpose

Guide the implementation of hierarchical multi-agent coordination for the AQE v3 fleet of 21 specialized QE agents.

Activation

• When orchestrating multiple QE agents
• When implementing agent communication protocols
• When building coordination workflows
• When managing agent lifecycle

Fleet Architecture

1. Hierarchical Coordination Structure

// v3/src/coordination/QEFleetCoordinator.ts
export class QEFleetCoordinator {
  private readonly queen: QueenCoordinator;
  private readonly groups: Map<string, AgentGroup>;
  private readonly eventBus: DomainEventBus;
  private readonly memory: CrossAgentMemory;

  constructor(config: FleetConfig) {
    this.queen = new QueenCoordinator(config);
    this.groups = new Map();
    this.eventBus = new DomainEventBus();
    this.memory = new CrossAgentMemory(config.memory);

    this.initializeGroups();
  }

  private initializeGroups(): void {
    const groupConfigs: GroupConfig[] = [
      {
        name: 'test-generation',
        agents: ['v3-qe-test-architect', 'v3-qe-tdd-specialist', 'v3-qe-integration-tester', 'v3-qe-property-tester'],
        domain: 'test-generation'
      },
      {
        name: 'quality-gates',
        agents: ['v3-qe-quality-gate', 'v3-qe-deployment-advisor', 'v3-qe-risk-assessor'],
        domain: 'quality-assessment'
      },
      {
        name: 'intelligence',
        agents: ['v3-qe-defect-predictor', 'v3-qe-pattern-learner', 'v3-qe-root-cause-analyzer'],
        domain: 'defect-intelligence'
      },
      {
        name: 'execution',
        agents: ['v3-qe-parallel-executor', 'v3-qe-flaky-hunter', 'v3-qe-retry-handler'],
        domain: 'test-execution'
      },
      {
        name: 'coverage',
        agents: ['v3-qe-coverage-specialist', 'v3-qe-gap-detector', 'v3-qe-risk-scorer'],
        domain: 'coverage-analysis'
      },
      {
        name: 'learning',
        agents: ['v3-qe-learning-coordinator', 'v3-qe-transfer-specialist', 'v3-qe-metrics-optimizer', 'v3-qe-knowledge-manager'],
        domain: 'learning-optimization'
      }
    ];

    for (const config of groupConfigs) {
      this.groups.set(config.name, new AgentGroup(config));
    }
  }

  // Queen delegates to appropriate group
  async orchestrate(task: QETask): Promise<TaskResult> {
    // 1. Queen analyzes task
    const plan = await this.queen.planExecution(task);

    // 2. Share context with relevant agents
    await this.memory.shareContext('queen', plan.targetAgents, {
      taskId: task.id,
      requirements: task.requirements,
      context: task.context
    });

    // 3. Execute through agent groups
    const results = await this.executeGroupTasks(plan);

    // 4. Consolidate and return
    return this.queen.consolidateResults(results);
  }

  private async executeGroupTasks(plan: ExecutionPlan): Promise<GroupResult[]> {
    const groupTasks = this.groupTasksByDomain(plan.tasks);
    const results: GroupResult[] = [];

    // Parallel group execution
    await Promise.all(
      Array.from(groupTasks.entries()).map(async ([groupName, tasks]) => {
        const group = this.groups.get(groupName)!;
        const result = await group.execute(tasks);
        results.push(result);
      })
    );

    return results;
  }
}

2. Agent Group Implementation

// v3/src/coordination/AgentGroup.ts
export class AgentGroup {
  private readonly name: string;
  private readonly agents: Map<string, QEAgent>;
  private readonly loadBalancer: GroupLoadBalancer;

  constructor(config: GroupConfig) {
    this.name = config.name;
    this.agents = new Map();
    this.loadBalancer = new GroupLoadBalancer();

    for (const agentId of config.agents) {
      this.agents.set(agentId, this.createAgent(agentId));
    }
  }

  async execute(tasks: GroupTask[]): Promise<GroupResult> {
    const assignments = this.loadBalancer.assign(tasks, Array.from(this.agents.values()));
    const results: AgentResult[] = [];

    // Execute with coordination
    await Promise.all(
      assignments.map(async (assignment) => {
        const agent = this.agents.get(assignment.agentId)!;
        const result = await agent.execute(assignment.task);
        results.push(result);

        // Share learnings within group
        if (result.learnings) {
          await this.shareWithinGroup(agent.id, result.learnings);
        }
      })
    );

    return {
      group: this.name,
      results,
      aggregatedMetrics: this.aggregateMetrics(results)
    };
  }

  private async shareWithinGroup(sourceAgent: string, learnings: Learning[]): Promise<void> {
    const targetAgents = Array.from(this.agents.keys()).filter(a => a !== sourceAgent);
    for (const learning of learnings) {
      await this.memory.shareContext(sourceAgent, targetAgents, learning);
    }
  }
}

3. Communication Protocols

// v3/src/coordination/protocols/QEProtocols.ts
export const QE_PROTOCOLS = {
  // Morning sync - daily coordination
  MORNING_SYNC: {
    name: 'morning-sync',
    participants: 'all',
    schedule: '0 9 * * *',
    steps: [
      { agent: 'v3-qe-queen', action: 'gather-status' },
      { agent: 'v3-qe-coverage-specialist', action: 'report-coverage' },
      { agent: 'v3-qe-quality-gate', action: 'report-quality' },
      { agent: 'v3-qe-defect-predictor', action: 'report-risks' },
      { agent: 'v3-qe-queen', action: 'prioritize-day' }
    ]
  },

  // Quality gate - pre-release evaluation
  QUALITY_GATE: {
    name: 'quality-gate',
    participants: ['v3-qe-queen', 'v3-qe-quality-gate', 'v3-qe-coverage-specialist', 'v3-qe-risk-assessor'],
    trigger: 'release-candidate',
    steps: [
      { agent: 'v3-qe-coverage-specialist', action: 'analyze-coverage', timeout: 60000 },
      { agent: 'v3-qe-quality-gate', action: 'evaluate-criteria', timeout: 30000 },
      { agent: 'v3-qe-risk-assessor', action: 'assess-risks', timeout: 45000 },
      { agent: 'v3-qe-queen', action: 'make-decision', timeout: 10000 }
    ]
  },

  // Learning consolidation - end of sprint
  LEARNING_CONSOLIDATION: {
    name: 'learning-consolidation',
    participants: ['v3-qe-learning-coordinator', 'v3-qe-transfer-specialist', 'v3-qe-pattern-learner'],
    schedule: '0 18 * * 5', // Friday 6pm
    steps: [
      { agent: 'v3-qe-pattern-learner', action: 'extract-patterns' },
      { agent: 'v3-qe-transfer-specialist', action: 'identify-transfers' },
      { agent: 'v3-qe-learning-coordinator', action: 'consolidate-knowledge' }
    ]
  },

  // Defect investigation - triggered on failure
  DEFECT_INVESTIGATION: {
    name: 'defect-investigation',
    participants: ['v3-qe-defect-predictor', 'v3-qe-root-cause-analyzer', 'v3-qe-flaky-hunter'],
    trigger: 'test-failure',
    steps: [
      { agent: 'v3-qe-flaky-hunter', action: 'check-flakiness' },
      { agent: 'v3-qe-root-cause-analyzer', action: 'analyze-root-cause' },
      { agent: 'v3-qe-defect-predictor', action: 'predict-related-failures' }
    ]
  }
};

// Protocol executor
export class ProtocolExecutor {
  async execute(protocol: Protocol, context: ProtocolContext): Promise<ProtocolResult> {
    const results: StepResult[] = [];

    for (const step of protocol.steps) {
      const agent = await this.getAgent(step.agent);
      const result = await this.executeStep(agent, step, context, step.timeout);
      results.push(result);

      // Pass result to next step
      context.previousResults.push(result);
    }

    return { protocol: protocol.name, results };
  }
}

4. Task Queue with Priority

// v3/src/coordination/TaskQueue.ts
export class QETaskQueue {
  private readonly queues: Map<Priority, Task[]> = new Map();
  private readonly agentAssignments: Map<string, Task[]> = new Map();

  constructor() {
    // Initialize priority queues
    for (const priority of ['critical', 'high', 'medium', 'low']) {
      this.queues.set(priority as Priority, []);
    }
  }

  enqueue(task: Task): void {
    const queue = this.queues.get(task.priority)!;
    queue.push(task);
    this.eventBus.publish(new TaskEnqueued(task));
  }

  // Dequeue highest priority task for agent
  dequeue(agentId: string): Task | null {
    for (const priority of ['critical', 'high', 'medium', 'low']) {
      const queue = this.queues.get(priority as Priority)!;
      const task = queue.find(t => this.canAgentHandle(agentId, t));

      if (task) {
        queue.splice(queue.indexOf(task), 1);
        this.assignToAgent(agentId, task);
        return task;
      }
    }
    return null;
  }

  // Work stealing
  stealFrom(fromAgent: string, toAgent: string): Task | null {
    const fromQueue = this.agentAssignments.get(fromAgent) || [];
    if (fromQueue.length > 1) {
      const task = fromQueue.pop()!;
      this.assignToAgent(toAgent, task);
      return task;
    }
    return null;
  }
}

5. Agent State Management

// v3/src/coordination/AgentStateManager.ts
export class AgentStateManager {
  private readonly states: Map<string, AgentState> = new Map();
  private readonly memory: QEAgentDB;

  async getState(agentId: string): Promise<AgentState> {
    // Check memory cache
    const cached = this.states.get(agentId);
    if (cached) return cached;

    // Load from persistent storage
    const persisted = await this.memory.get(`agent:${agentId}:state`);
    if (persisted) {
      this.states.set(agentId, persisted);
      return persisted;
    }

    // Create default state
    return this.createDefaultState(agentId);
  }

  async updateState(agentId: string, update: Partial<AgentState>): Promise<void> {
    const current = await this.getState(agentId);
    const updated = { ...current, ...update, lastUpdated: new Date() };

    this.states.set(agentId, updated);
    await this.memory.store({
      id: `agent:${agentId}:state`,
      index: 'coordination',
      data: updated
    });

    this.eventBus.publish(new AgentStateUpdated(agentId, updated));
  }

  async getAllActiveAgents(): Promise<AgentState[]> {
    const results = await this.memory.search('active', {
      index: 'coordination',
      filter: { 'data.status': 'active' }
    });
    return results.map(r => r.data);
  }
}

export interface AgentState {
  agentId: string;
  status: 'idle' | 'busy' | 'error' | 'inactive';
  currentTask: string | null;
  completedTasks: number;
  errorCount: number;
  lastUpdated: Date;
  metrics: AgentMetrics;
}

6. Event-Driven Coordination

// v3/src/coordination/events/CoordinationEvents.ts
export class CoordinationEventBus {
  private readonly handlers: Map<string, EventHandler[]> = new Map();

  // Domain events for coordination
  readonly EVENTS = {
    TASK_ASSIGNED: 'coordination.task.assigned',
    TASK_COMPLETED: 'coordination.task.completed',
    TASK_FAILED: 'coordination.task.failed',
    AGENT_IDLE: 'coordination.agent.idle',
    AGENT_BUSY: 'coordination.agent.busy',
    PROTOCOL_STARTED: 'coordination.protocol.started',
    PROTOCOL_COMPLETED: 'coordination.protocol.completed',
    KNOWLEDGE_SHARED: 'coordination.knowledge.shared'
  };

  subscribe(event: string, handler: EventHandler): void {
    const handlers = this.handlers.get(event) || [];
    handlers.push(handler);
    this.handlers.set(event, handlers);
  }

  async publish(event: DomainEvent): Promise<void> {
    const handlers = this.handlers.get(event.type) || [];
    await Promise.all(handlers.map(h => h(event)));

    // Persist event for replay
    await this.memory.store({
      id: `event:${event.id}`,
      index: 'coordination',
      data: event,
      ttl: 86400 * 7 // 7 days
    });
  }
}

Fleet Topology

                    ┌─────────────────┐
                    │  Queen Coord.   │
                    │   (v3-queen)    │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│Test Generation│   │Quality Gates  │   │ Intelligence  │
│   Group (4)   │   │   Group (3)   │   │   Group (3)   │
└───────────────┘   └───────────────┘   └───────────────┘
        │                    │                    │
        ▼                    ▼                    ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  Execution    │   │   Coverage    │   │   Learning    │
│   Group (3)   │   │   Group (3)   │   │   Group (4)   │
└───────────────┘   └───────────────┘   └───────────────┘

Implementation Checklist

• Implement QEFleetCoordinator
• Create AgentGroup class
• Define communication protocols
• Build priority task queue
• Add agent state management
• Implement event-driven coordination
• Add work stealing algorithm
• Write coordination tests

Related Skills

• v3-qe-core-implementation - Domain logic
• v3-qe-memory-system - Cross-agent memory
• v3-qe-mcp - MCP tool integration