Agent-Human Task Routing

// scripts/task-router.ts
import { readFileSync } from "fs";
import { parse } from "yaml";

interface RoutingConfig {
  task_classifications: {
    auto_agent: TaskType[];
    assisted_agent: TaskType[];
    human_only: TaskType[];
  };
}

interface TaskType {
  name: string;
  spec_completeness: number;
  pattern_coverage: number;
  blast_radius: number;
  novelty: number;
  notes?: string;
}

interface TaskScore {
  specCompleteness: number;
  patternCoverage: number;
  blastRadius: number;
  novelty: number;
}

type RouteDecision = "auto-agent" | "assisted-agent" | "human-only";

function loadConfig(path: string): RoutingConfig {
  const raw = readFileSync(path, "utf-8");
  return parse(raw) as RoutingConfig;
}

function scoreToRoute(score: TaskScore): RouteDecision {
  if (score.blastRadius <= 1) return "human-only";
  if (score.specCompleteness <= 2) return "human-only";

  const total =
    score.specCompleteness +
    score.patternCoverage +
    score.blastRadius +
    score.novelty;

  if (total >= 16) return "auto-agent";
  if (total >= 10) return "assisted-agent";
  return "human-only";
}

function findSimilarTask(
  description: string,
  config: RoutingConfig
): { route: RouteDecision; match: TaskType } | null {
  const allTasks = [
    ...config.task_classifications.auto_agent.map((t) => ({
      ...t,
      route: "auto-agent" as RouteDecision,
    })),
    ...config.task_classifications.assisted_agent.map((t) => ({
      ...t,
      route: "assisted-agent" as RouteDecision,
    })),
    ...config.task_classifications.human_only.map((t) => ({
      ...t,
      route: "human-only" as RouteDecision,
    })),
  ];

  const descLower = description.toLowerCase();
  const match = allTasks.find((t) =>
    t.name.toLowerCase().split(" ").some((word) => descLower.includes(word))
  );

  if (match) {
    return { route: match.route, match };
  }
  return null;
}

// Usage
const config = loadConfig("task-routing-config.yaml");
const suggestion = findSimilarTask("Add new CRUD endpoint for orders", config);

if (suggestion) {
  console.log(`Suggested route: ${suggestion.route}`);
  console.log(`Based on: ${suggestion.match.name}`);
  console.log(`Notes: ${suggestion.match.notes || "None"}`);
} else {
  console.log("No matching classification found. Score manually.");
}

# routing-log.yaml — Track decisions for retrospective analysis
entries:
  - date: "2026-02-20"
    task: "Add pagination to /api/products endpoint"
    scores:
      spec_completeness: 5
      pattern_coverage: 5
      blast_radius: 4
      novelty: 5
    route: "auto-agent"
    outcome: "passed-first-attempt"
    correction_needed: false

  - date: "2026-02-20"
    task: "Implement OAuth2 PKCE flow"
    scores:
      spec_completeness: 4
      pattern_coverage: 2
      blast_radius: 1
      novelty: 2
    route: "human-only"
    outcome: "completed-by-human"
    notes: "Security-critical path, blast radius override"

  - date: "2026-02-21"
    task: "Refactor UserService to repository pattern"
    scores:
      spec_completeness: 4
      pattern_coverage: 3
      blast_radius: 3
      novelty: 3
    route: "assisted-agent"
    outcome: "completed-after-2-corrections"
    correction_needed: true
    notes: "Agent missed edge case in error handling"