OpenAgentsControl/.opencode/context/core/delegation/routing-patterns.md

Routing Patterns - Phase 1 Decision Logic

Purpose

Fast, pattern-based routing decisions to determine execution path BEFORE approval stage.

When to use: Stage 1.75 (after Discover, before Approve)

Output: JSON routing decision with pre-actions

Routing Categories

1. execute_direct

When to use:

• Single file modification
• Straightforward change (typo, comment, simple update)
• Clear bug fix with known solution
• No dependencies or complexity

Patterns:

/single file/i
/typo|fix typo|correct spelling/i
/add comment|update comment/i
/simple (change|update|fix)/i
/straightforward/i

File count: 1-2 files

Pre-actions:

• Load relevant context if code/docs/tests
• No delegation needed

Example:

{
  "routing": "execute_direct",
  "reason": "Single file typo fix, no complexity",
  "pre_actions": [],
  "context_files": [],
  "confidence": "high"
}

---

2. delegate_taskmanager

When to use:

• 4+ files involved
• Multi-component feature
• Dependencies between tasks
• Complex workflow (auth, API, multi-step)
• User explicitly requests task breakdown

Patterns:

/\d+ files/i (where count >= 4)
/(complex|multi-step|multi-component) (feature|system)/i
/(auth|authentication) system/i
/with (dependencies|tests|middleware)/i
/break.*down|plan.*tasks/i

File count: 4+ files

Pre-actions:

• use_contextscout (if not already done)
• load_standards (code-quality.md)
• load_task_management_context (task-management/navigation.md)

Example:

{
  "routing": "delegate_taskmanager",
  "reason": "Complex feature spanning 6 files with dependencies",
  "pre_actions": ["load_standards", "load_task_management_context"],
  "context_files": [
    ".opencode/context/core/standards/code-quality.md",
    ".opencode/context/core/task-management/navigation.md"
  ],
  "confidence": "high"
}

---

3. needs_context_first

When to use:

• No context discovered yet
• New domain/technology not in codebase
• Unclear patterns or standards
• Implementation needs discovery first

Patterns:

/no context (found|available)/i
/unclear (pattern|standard|approach)/i
/new (domain|technology|framework)/i
/need.*discover|find.*patterns/i

Context files: Empty or insufficient

Pre-actions:

• use_contextscout (mandatory)
• Wait for context discovery before routing

Example:

{
  "routing": "needs_context_first",
  "reason": "API implementation needs patterns/standards discovery",
  "pre_actions": ["use_contextscout"],
  "context_files": [],
  "confidence": "high"
}

---

4. execute_existing_task

When to use:

• Continuing work on existing task
• Task JSON files exist (.tmp/tasks/{feature}/)
• User says "continue", "next task", "work on {task}"

Patterns:

/continue (working|task|feature)/i
/next (task|subtask)/i
/work on (task|subtask)/i
/resume/i

Task files: .tmp/tasks/{feature}/task.json exists

Pre-actions:

• check_task_status (run task-cli.ts status)
• load_task_context (read task.json + subtask_NN.json)
• mark_in_progress (update status)

Example:

{
  "routing": "execute_existing_task",
  "reason": "Continuing existing auth-system task",
  "pre_actions": ["check_task_status", "load_task_context", "mark_in_progress"],
  "context_files": [".tmp/tasks/auth-system/subtask_02.json"],
  "confidence": "high"
}

---

5. batch_delegate_coder

When to use:

• Multiple parallel/isolated tasks
• Tasks marked parallel: true in JSON
• No dependencies between tasks
• Can be executed concurrently

Patterns:

/parallel tasks/i
/isolated (tasks|subtasks)/i
/batch (execute|process)/i

Task files: Multiple subtasks with parallel: true

Pre-actions:

• check_parallel_tasks (run task-cli.ts parallel)
• load_task_contexts (read all parallel subtask JSONs)
• mark_all_in_progress

Example:

{
  "routing": "batch_delegate_coder",
  "reason": "3 parallel subtasks ready (no dependencies)",
  "pre_actions": ["check_parallel_tasks", "load_task_contexts"],
  "context_files": [
    ".tmp/tasks/auth-system/subtask_03.json",
    ".tmp/tasks/auth-system/subtask_04.json",
    ".tmp/tasks/auth-system/subtask_05.json"
  ],
  "confidence": "high"
}

---

Decision Algorithm

Step 1: Check for existing tasks

IF .tmp/tasks/{feature}/ exists:
  → routing = "execute_existing_task"
  → RETURN

Step 2: Check context availability

IF context_files.length == 0 AND task_needs_context:
  → routing = "needs_context_first"
  → RETURN

Step 3: Check complexity

IF file_count >= 4 OR has_dependencies OR multi_component:
  → routing = "delegate_taskmanager"
  → RETURN

Step 4: Check for parallel tasks

IF multiple_tasks AND all_parallel:
  → routing = "batch_delegate_coder"
  → RETURN

Step 5: Default to direct execution

ELSE:
  → routing = "execute_direct"
  → RETURN

Confidence Levels

• high: Clear pattern match, unambiguous
• medium: Multiple patterns match, needs user confirmation
• low: Unclear, recommend asking user for clarification

Edge Cases

Ambiguous file count

User: "Update authentication"
Files: Unknown

→ routing = "needs_context_first"
→ reason = "File count unknown, need discovery first"

User override

User: "Just do it directly, don't delegate"

→ routing = "execute_direct"
→ reason = "User explicitly requested direct execution"
→ confidence = "high"

Missing information

User: "Implement feature X"
Context: None
Files: Unknown

→ routing = "needs_context_first"
→ pre_actions = ["use_contextscout", "clarify_scope"]

Output Format

Always return JSON:

{
  "phase": "routing",
  "routing": "execute_direct|delegate_taskmanager|needs_context_first|execute_existing_task|batch_delegate_coder",
  "reason": "Brief 1-sentence explanation",
  "pre_actions": ["action1", "action2"],
  "context_files": ["path1", "path2"],
  "confidence": "high|medium|low"
}

Integration with OpenAgent

OpenAgent calls DelegationController at Stage 1.75:

const routingDecision = await task({
  subagent_type: "DelegationController",
  description: "Route decision",
  prompt: `Phase: routing
  
User request: ${userRequest}
Discovered context: ${contextFiles}
Files involved: ${fileCount}
Existing tasks: ${taskFiles}

Determine routing decision.`
});

// Use routing decision in approval plan
const approvalPlan = `
## Proposed Plan

**Routing**: ${routingDecision.routing}
**Reason**: ${routingDecision.reason}

**Pre-execution actions**:
${routingDecision.pre_actions.map(a => `- ${a}`).join('\n')}

**Approval needed before proceeding.**
`;

Related

• validation-checks.md - Phase 2 validation logic
• navigation.md - Overview and integration
• .opencode/context/core/workflows/task-delegation.md - Full delegation process