<img src="banner.png" width="100%" alt="semantic-persona-routing banner">

Semantic Persona Routing

Route by capability first and apply personality second. Build a portable map that keeps semantic role choice, deterministic endpoint lookup and provider-specific loading separate.

Routing model

text
request
  -> semantic domain/coordinator role
  -> expert capability
  -> explicit or live-resolved skill endpoint
  -> optional persona overlay
  -> provider adapter loads and executes

A persona controls communication style, priorities and interaction patterns. It does not grant tools, permissions or subject-matter capability. A role coordinates; an expert narrows the domain; a skill is the executable endpoint.

Build the routing map

Use explicit metadata as authority and lexical similarity only as a candidate:

bash
python scripts/build_routing_map.py \
  --roles-dir path/to/roles \
  --personas-dir path/to/personas \
  --skills-dir path/to/skills \
  --out routing-map.json

The builder understands common SKILL.md fields such as type, orchestrates.experts, parent_agents, skills, descriptions and provenance. It produces a runtime map without requiring the source system to be installed. Read routing-map-schema.md before extending the format.

Each exported skill ID is unique. When multiple source files declare the same stable ID, the builder selects the lexicographically first relative source path deterministically and records a duplicate-skill-id issue; it never emits two skill entries with the same ID. Declared expert and persona skill references are normalized to a clean ID only when that ID exists in the exported registry. Malformed, unknown, and normalized references stay visible in issues; unknown or invalid references never become endpoints or persona compatibility links.

Do not automatically promote candidate_skills. Confirm them against a live skill resolver or source metadata first.

Route a request

1. Select the coordinator role semantically

Compare the request with role names, descriptions and use cases. Prefer the narrowest role that can coordinate the whole request. Keep multiple candidates visible when confidence is low; ask the user only when the choice materially changes the result.

2. Select an expert within the role

Use only experts connected to the chosen coordinator unless the request clearly spans roles. A direct expert request may skip the coordinator for execution, but retain the coordinator link in the route explanation.

3. Resolve executable endpoints

Resolve in this order:

1. endpoint_skills from explicit source metadata or exact provenance;
2. a current external skill resolver or local skill finder;
3. verified candidate_skills;
4. visible GAP when no endpoint exists.

Never route to an expert name as though it were an installed skill. A missing endpoint is a porting gap, not permission to fabricate one.

Read endpoint-resolution.md when connecting a live registry, lexical finder or provider-specific skill loader.

4. Apply the persona overlay

Choose a persona attached to the selected role or expert. If several personas fit, prefer one whose declared limits and style match the task. Apply no persona when none is explicitly connected.

Persona instructions cannot override safety rules, locks, user decisions, professional boundaries or tool permissions.

5. Load and execute

Use the provider's native skill/agent loading mechanism. Load the selected live skill instructions before execution. Keep the router lean; execution belongs to the worker or current agent with the resolved skills loaded.

Route receipt

Return or record:

text
ROLE: <coordinator or direct>
EXPERT: <expert or n/a>
SKILLS: <verified live endpoints>
PERSONA: <overlay or none>
RESOLUTION: explicit | provenance | live-resolver | verified-candidate | GAP
CONFIDENCE: high | medium | low
WHY: <one short reason>
GAPS: <missing endpoints or stale-map warnings>

Rebuild the map when source roles or skill inventory change. A live resolver may supersede a stale map for endpoint availability, but it must not silently rewrite the semantic role taxonomy.

Example

Request: "Organize my receipts and prepare the tax-year overview."

The router selects an office coordinator, then the tax expert, resolves the installed tax skill, and finally applies an explicitly linked meticulous tax persona. If the tax expert exists but no portable tax skill is installed, report GAP and continue only through an explicitly configured fallback.

Changelog

1.0.0 (2026-07-28)

• Extracted the provider-neutral role/expert/skill chain from a proven domain

router pattern and added portable map generation with visible endpoint gaps.