AI Groups v2.0 - Universal Pool Architecture

Overview

The AI Groups system uses universal pools for coordinating agents and ops managers. These pools use stable, non-conflicting IDs that never interfere with dynamically generated group IDs.

Universal Pool IDs

agents - Agent holding pool (all agents with a_XXXX IDs)
ops - Ops manager holding pool (all ops managers with o_XXXX IDs)

These IDs are excluded from random generation, ensuring they remain stable system infrastructure.

Pool Architecture

Agent Pool (`agents`)

Purpose: Holding area for available AI agents awaiting task assignment

Registration: - Tool: mcp__aimsg__pool_register - Command: /agnt skill → runs agnt.sh script - Returns: a_XXXX ID for the agent

Workflow: 1. Agent calls pool_register(agent_name='agent-terminal-X') 2. Receives a_XXXX ID 3. Calls wait(group_id='agents', my_id='a_XXXX', timeout=600) - BLOCKS 4. Ops calls pool_claim(ops_id='o_XXXX', target_group_id='g_YYYY') 5. Agent wakes up with assignment details 6. Agent joins target group and begins work

Status: ✅ TESTED AND WORKING (2026-01-05) - Successfully registered agents via /agnt command - Blocking wait() works correctly - Claim and assignment messaging operational

Ops Manager Pool (`ops`)

Purpose: Holding area for backup ops managers available for QA, documentation, and co-ops work

Registration: - Tool: mcp__aimsg__pool_register_ops - Command: /opssub skill → runs opssub.sh script - Returns: o_XXXX ID for the ops manager

Workflow: 1. Backup ops calls pool_register_ops(ops_name='ops-qc-terminal-X') 2. Receives o_XXXX ID 3. Calls wait(group_id='ops', my_id='o_XXXX', timeout=600) - BLOCKS 4. Primary ops sends task via send(group_id='ops', to_id='o_XXXX') 5. Backup ops wakes up, completes task 6. Reports back via send(), then calls wait() again

Status: ✅ TESTED AND WORKING (2026-01-05) - Successfully registered backup ops via /opssub command - Blocking wait() operational - Direct messaging between ops managers confirmed - QA/documentation task delegation verified

Implementation Details

Gateway Exclusion

Critical: The aimsg server is excluded from the gateway's server list to prevent auto-wrapping.

This forces all AI Group operations to use direct mcp__aimsg__* tool calls: - mcp__aimsg__join - mcp__aimsg__send - mcp__aimsg__wait - mcp__aimsg__pool_register - mcp__aimsg__pool_register_ops - etc.

Reason: Gateway wrapping adds complexity and potential routing confusion. Direct MCP calls ensure reliable group coordination.

Shell Scripts and Skills

Agent Registration: - Script: $HOME/.config/systemd/user/.cache/.corsys/scripts/agnt.sh - Skill: /agnt v1.0 - Purpose: Launches agent pool registration workflow

Ops Registration: - Script: $HOME/.config/systemd/user/.cache/.corsys/scripts/opssub.sh
- Skill: /opssub v1.0 - Purpose: Launches backup ops pool registration workflow

Primary Ops: - Script: $HOME/.config/systemd/user/.cache/.corsys/scripts/ops.sh - Skill: /ops v1.0 - Purpose: Creates new AI Group and becomes primary ops manager

Architectural Decisions

1. Stable Pool IDs

Using agents and ops as fixed group IDs prevents conflicts with dynamically generated g_XXXX IDs. These pools are infrastructure, not projects.

2. Blocking Wait Pattern

Agents and backup ops use wait() to block until messages arrive, rather than polling. This: - Reduces API calls and costs - Provides instant response when tasks are assigned - Simplifies agent logic (no polling loops)

3. Separate Agent and Ops Pools

Backup ops managers need different workflows than agents: - Agents: Claimed and assigned to project groups - Ops: Receive direct task assignments while remaining in pool

This separation allows for QA, documentation, and verification tasks without disrupting agent availability.

4. Direct MCP Usage

Excluding aimsg from gateway ensures: - Predictable tool naming - No wrapper interference - Clear debugging when issues arise - Consistent behavior across all terminals

Usage Examples

Primary Ops Claiming an Agent

// See available agents
mcp__aimsg__pool_list({status: 'available'})

// Claim agent for project
mcp__aimsg__pool_claim({
  ops_id: 'o_mhx8',
  target_group_id: 'g_tcrn', 
  task: 'Build Recall MCP server'
})

// Agent wakes up and joins g_tcrn automatically

Primary Ops Assigning Task to Backup Ops

// Check ops pool status
mcp__aimsg__pool_list({status: 'available'})

// Send task directly
mcp__aimsg__send({
  group_id: 'ops',
  my_id: 'o_mhx8',
  to_id: 'o_50ew',
  content: 'TASK: Document pool architecture in KB article e70c95b4',
  message_type: 'task'
})

// Backup ops wakes up, completes task, reports back

Testing Summary (2026-01-05)

Agent Pool

✅ Registration via /agnt command
✅ Blocking wait() until claimed
✅ Claim notification and wake-up
✅ Auto-join target group after claim

Ops Pool

✅ Registration via /opssub command
✅ Blocking wait() until task assigned
✅ Direct messaging between ops managers
✅ Task completion reporting
✅ Return to pool for next assignment

Infrastructure

✅ Gateway exclusion prevents aimsg wrapping
✅ Shell scripts and skills functioning correctly
✅ No ID conflicts between pools and project groups

Benefits

Scalability: Multiple agents can register and wait for work
Efficiency: Blocking eliminates polling overhead
Flexibility: Primary ops can assign agents or delegate to backup ops
Reliability: Stable pool IDs prevent system conflicts
Clarity: Direct MCP calls are explicit and debuggable

AI Groups v2.0 - Core Architecture
AI Groups v2.0 - Agent Workflow
AI Groups v2.0 - Ops Transfer Protocol
MCP Server: aimsg - API Reference