Skip to main content

ADR-071: Agent-Task Matching Algorithm

Status​

Accepted - January 13, 2026

Context​

With 150+ CODITECT agents and 500+ atomic tasks, manual agent selection is:

  1. Time-consuming
  2. Inconsistent
  3. Unable to leverage historical performance data

Decision​

Weighted Affinity Scoring​

Calculate agent-task affinity using four weighted factors:

affinity_score = (
    semantic_similarity * 0.4 +
    historical_success_rate * 0.3 +
    domain_expertise * 0.2 +
    availability * 0.1
)

Factor Calculations​

1. Semantic Similarity (40%)​

Cosine similarity between task title embedding and agent capability embedding:

def semantic_similarity(task: AtomicTask, agent: str) -> float:
    task_embedding = task.title_embedding  # vector(1536)
    agent_embedding = get_agent_capability_embedding(agent)
    return cosine_similarity(task_embedding, agent_embedding)

2. Historical Success Rate (30%)​

From agent_task_affinity table:

def historical_success(agent: str, task_type: str, domain: str) -> float:
    affinity = get_affinity(agent, task_type, domain)
    if affinity and affinity.total_executions >= 5:
        return affinity.success_rate
    return 0.5  # Default for insufficient data

3. Domain Expertise (20%)​

Based on track-to-agent mapping:

DOMAIN_EXPERTS = {
    'backend': ['senior-architect', 'backend-specialist'],
    'frontend': ['frontend-react-typescript-expert'],
    'devops': ['devops-engineer', 'cloud-architect'],
    # ...
}

def domain_expertise(agent: str, domain: str) -> float:
    experts = DOMAIN_EXPERTS.get(domain, [])
    if agent in experts:
        return 1.0 - (experts.index(agent) * 0.15)
    return 0.3

4. Availability (10%)​

Inverse of current workload:

def availability(agent: str) -> float:
    active = count_active_tasks(agent)
    return 1.0 / (1 + active * 0.2)

Selection Process​

def select_agent(task: AtomicTask, top_k: int = 3) -> List[AgentRecommendation]:
    candidates = get_candidate_agents(task.domain)

    scored = []
    for agent in candidates:
        score = calculate_affinity_score(task, agent)
        scored.append((agent, score))

    return sorted(scored, key=lambda x: x[1], reverse=True)[:top_k]

Consequences​

Positive​

  • Data-driven agent selection
  • Continuous improvement via learning loop
  • Transparent scoring breakdown
  • Graceful degradation (defaults for new agents/tasks)

Negative​

  • Requires historical data to be effective
  • Cold start problem for new agents

Mitigation​

  • Use domain expertise as primary factor for new agents
  • Bootstrap with expert-defined agent capabilities

References​

Local:

External (coditect-core):

  • ADR-068: Large Project Plan Token Economics

Decision Date: January 13, 2026 Implementation Priority: P1 (Core feature)