Routing & Experts

The assistant uses a multi-stage routing chain to match every message to the right specialist, tools, and model.

Message Classification

The orchestrator classifies incoming messages using keyword heuristics:

Casual patterns — greetings, thanks, yes/no get a direct response (no agent spawned)
Task keywords — matched against 12 categories with scoring (multi-word keywords get 1.5x weight, score >= 1.5 is high confidence)
Ambiguous — falls through to LLM decision

The Routing Chain

User message
  ↓
Classifier (keyword matching)
  ↓
Role (determines tools + system prompt)
  = Topic (determines which model)
  ↓
Model Registry: getModelForTopic(topic)
  ↓
Agent spawned with: role tools + topic model + expert prompt + skills

Topic = Role. Every role has a matching topic with the same name. Assigning a model to a topic means that model is used for all agents with that role.

Roles & Topics

Role / Topic	Tools	Use Case
`general`	filesystem, browser-ext, websearch, messaging, knowledge, scheduling, profiles, email-processor, mcp	Multi-purpose, browsing, messaging
`coding`	filesystem, shell, git, knowledge, mcp	Code generation, debugging, git
`research`	browser, browser-ext, websearch, knowledge, filesystem, profiles, mcp	Web search, investigation
`architecture`	filesystem, shell, knowledge, websearch, mcp	System design, specs
`review`	filesystem, shell, git, knowledge	Code review, linting (read-only)
`qa`	browser, browser-ext, shell, docker, filesystem, knowledge	Testing, bug reports
`communication`	google-workspace, microsoft365, messaging, scheduling, profiles, email-processor, voice	Email, calendar, calls
`design`	browser, filesystem	UI/UX design, mockups
`devops`	shell, docker, git, filesystem, mcp	CI/CD, Docker, infrastructure
`security`	shell, filesystem, browser, browser-ext, websearch, knowledge, mcp	Vulnerability analysis
`data`	shell, filesystem, knowledge, mcp	Databases, SQL, data pipelines
`ai`	shell, filesystem, browser, browser-ext, websearch, knowledge, mcp	ML/AI, RAG, model training
`finance`	browser, websearch, filesystem	Financial analysis
`automation`	shell, docker, filesystem, scheduling, mcp	Cron tasks, hooks, workflows
`pm`	filesystem, messaging	Project planning, tracking
`writing`	filesystem, browser, websearch, knowledge, messaging	Documentation, technical writing

Special Topics (No Role Equivalent)

These are used for model capability routing only:

Topic	Purpose
`chat`	Casual conversations (orchestrator direct response)
`embedding`	Vector embeddings (knowledge base)
`ocr`	Text extraction from images
`vision`	Image understanding
`voice`	Phone call conversations (low latency)

Prompt Examples

"Fix the login bug in auth.ts"
  → coding role → filesystem, shell, git tools

"Search the web for React best practices"
  → research role → browser, websearch tools

"Deploy the Docker container to production"
  → devops role → shell, docker, git tools

"Check my Gmail inbox"
  → communication role → google-workspace tools

"Create a daily reminder at 9 AM"
  → automation role → scheduling tool

"Take a screenshot of my browser"
  → general role → browser-ext tool

Special Routing Overrides

These patterns override keyword classification:

Pattern	Routes To	Reason
”use my browser”, “check this website”	general	Has browser-ext + messaging
”run tests”, “test suite”	qa	Discovers and runs project tests
”review the code”	review	Read-only analysis + linters
”gmail”, “calendar”, “call me”	communication	Google Workspace + voice
”who is my wife”, “my dog”	general	Has profiles tool
”create a schedule”, “every morning”	automation	Built-in scheduling tool

Experts

Experts are pre-configured personas with structured prompts, critical rules, deliverable templates, and success metrics. Each expert maps to a role (which determines tools and topic).

Expert → Role → Topic Mapping

Expert	Role/Topic	Skills
Coder	`coding`	software-architecture, data-structures, database-design, api-design, plugin-development
Reviewer	`review`	software-architecture, test-automation, security-practices, performance-engineering
Researcher	`research`	technical-writing
UI/UX Designer	`design`	design-principles, design-frameworks
DevOps Engineer	`devops`	devops-practices, container-orchestration, cloud-platforms, networking
Security Analyst	`security`	security-practices, networking, cloud-platforms
Data Engineer	`data`	database-design, data-engineering, performance-engineering
AI Engineer	`ai`	ai-engineering, machine-learning, data-structures
QA Engineer	`qa`	test-automation, performance-engineering
Financial Analyst	`finance`	financial-analysis
Automation Engineer	`automation`	automation-patterns, devops-practices
Project Manager	`pm`	project-management, technical-writing
Technical Writer	`writing`	technical-writing, api-design
Communicator	`communication`	—
General	`general`	—

Using `/expert`

/expert Coder "implement login"
  ↓
1. Look up "Coder" in experts table → role: "coding"
2. getRoleConfig("coding") → tools: [filesystem, shell, git, ...]
3. getModelForTopic("coding") → model with coding topic assigned
4. Build prompt: security preamble + expert identity + role prompt + rules + skills
5. Spawn worker with role tools + topic model + expert prompt

Works in WebChat, TUI, Telegram, Slack, and Teams. The activeExpertId persists in the session until /expert reset.

Skill → Expert Mapping

Skills are domain knowledge documents (markdown with principles, best practices, anti-patterns) injected into the expert’s system prompt.

Skill	Used By
software-architecture	Coder, Reviewer
data-structures	Coder, AI Engineer
test-automation	Reviewer, QA Engineer
design-principles	UI/UX Designer
design-frameworks	UI/UX Designer
devops-practices	DevOps Engineer, Automation Engineer
container-orchestration	DevOps Engineer
security-practices	Security Analyst, Reviewer
cloud-platforms	DevOps Engineer, Security Analyst
financial-analysis	Financial Analyst
ai-engineering	AI Engineer
automation-patterns	Automation Engineer
database-design	Data Engineer, Coder
api-design	Coder, Technical Writer
project-management	Project Manager
technical-writing	Researcher, Project Manager, Technical Writer
performance-engineering	Data Engineer, Reviewer, QA Engineer
data-engineering	Data Engineer
machine-learning	AI Engineer
plugin-development	Coder
networking	DevOps Engineer, Security Analyst

Pipeline Stage Topics

Pipeline stages specify a topic field that determines both the role (tools) and model:

Pipeline	Stage	Topic
Full Development Cycle	Research & Discovery	`research`
Full Development Cycle	Requirements & Architecture	`architecture`
Full Development Cycle	Implementation	`coding`
Full Development Cycle	Testing	`qa`
Full Development Cycle	Code Review	`review`
Full Development Cycle	QA Validation	`qa`
Full Development Cycle	Summary & Handoff	`general`
Research & Analysis	Deep Investigation	`research`
Research & Analysis	Analysis & Recommendations	`general`
Bug Fix	Reproduce & Diagnose	`coding`
Bug Fix	Implement Fix	`coding`
Bug Fix	Verify Fix	`coding`

Model Configuration

To assign a model to a topic, use the Models page in the web UI:

Click on a model and select Edit
Select the topic(s) this model should handle
The model will be used when agents with that role/topic are spawned

If no model is explicitly assigned to a topic, the default model is used as fallback.