Appearance
The Role Router
A persona picker that suggests and never adopts. role-route.nu scores every ROLE.md in a pool against the words of a task, ranks the ones that overlap, and hands the list back. Choosing stays finn's, always – the router names candidates, /role puts them to him, and nothing writes a ROLE.md without him saying so. It ships inside the context module rather than as a part of its own, so installing context installs the router.
How the ranking works
The router is a lookup, not a matcher. $k in $words is exact whole-token membership – no stemming, no fuzz, no substrings, so sprite matches sprite and never sprites. The table is the entire tuning surface. A keyword that is not literally in it can never score, however close a synonym might be.
The pool is a directory of .md files, one persona each. roles-dir-path resolves it in a fixed order: the --roles-dir flag if you passed one, else the project's own .claude/roles/ if that directory exists, else the global ~/.claude/roles/. A project with its own roles dir is therefore already scoped to it, and a project without one ranks the whole global library.
The table is roles.nuon, read from .claude/context/roles.nuon under CLAUDE_PROJECT_DIR unless --table overrides it. It maps a role file stem to a list of single lowercase keywords. It also carries one reserved key, _router, that is never a role – the same underscore convention subprojects.nuon runs, so any key starting with _ is settings rather than a persona. table-roles reads every key except that one, and both route and list go through it, so the two can never disagree about what counts as a role.
The tokeniser lives under _router.hyphens, and it is the one place the router's word split is allowed to differ from the memory stores. include keeps a hyphen as a word character, so claude-code survives whole – the LESSON store needs this, its domain slugs are hyphenated and splitting them would stop them matching the thing they name. exclude splits on the hyphen, so sprite-texture scores against both sprite and texture separately. router-opts reads the key and falls back to include when it is absent, which is exactly what words-of always did before this setting existed, so a table written before it behaves identically.
The score is then plain keyword overlap over that tokenised set. The task text is lowercased and split, single characters are dropped, and each role scores one point per keyword of its own that appears in the set. Highest score first, nothing weighted.
Using it
nu .claude/context/role-route.nu route "fix the sprite texture on the renderwindow"╭───┬───────┬───────┬────────╮
│ # │ role │ score │ exists │
├───┼───────┼───────┼────────┤
│ 0 │ sfml3 │ 3 │ true │
╰───┴───────┴───────┴────────╯The tokeniser setting changes this. Against the shipped table (hyphens absent, so include), a hyphenated form of the same task, "fix the sprite-texture on the renderwindow", scores sfml3 only 1 – sprite-texture survives as one token and matches neither the sprite nor the texture keyword on its own, so only renderwindow lands. Flip the table to exclude and the same task scores 3 – the hyphen splits, and sprite and texture each match their own keyword again.
nu .claude/context/role-route.nu listtokeniser, hyphens include...followed by one row per role, role and keywords, from table-roles – the _router key never shows up as a row, because it was never a role to begin with. The tokeniser line prints first on purpose: a table that splits hyphens and one that does not rank the same task differently, and the table alone cannot show you which you have.
route "<task>"– the ranked table, the normal callroute "<task>" --top– just the winning stem on stdout, for scripting. Prints nothing when nothing scoresroute "<task>" --roles-dir <dir>– override the pool outrightroute "<task>" --table <file>– override the routing tablelist– the table itself plus the tokeniser state, one row per role with its keywords
Nothing matching is not an error. When no role scores above zero the router prints no strong role match and returns the whole pool sorted by name, so a task in an unfamiliar domain still gets a list to choose from rather than silence.
A missing file is ranked anyway. Every row carries an exists boolean. A role named in the table whose .md is not on disk still appears, flagged exists false, so the table and the pool can drift apart without the router dying. This is deliberate and it is what makes the whole thing safe to hand-edit.
Who calls it
Two callers, and one near-miss worth knowing about.
/roleshellsnu .claude/context/role-route.nu route "<task text>", shows finn the ranked table, and asks which to adopt throughAskUserQuestioncompile-context.nucalls it with--topwhen a task was given and no.claude/ROLE.mdexists, then appends a one line## suggested rolesection to the bundle. A suggestion inside a context bundle, never an adoptioninject-project.nuis the near-miss. Its no-role fallback prints a hardcoded string pointing at~/.claude/roles/rather than calling the router, so it names the global directory even from a project that has its own pool. Rewiring it is the shared item both H9.4 and H10.A.4 call for
The three directories
The single most confusing thing about roles in this repo, and the source of a plan-level mistake that took a gate run to catch. There are three roles directories and they are not meant to agree.
| directory | who reads it | what lives there |
|---|---|---|
~/.claude/roles/ | role-route.nu, as its global fallback | the live persona library, the old flat stems |
<project>/.claude/roles/ | role-route.nu, preferred when present | a project's own copies, also where the composer writes |
harness/roles/ | installer/src/models/roles.ts via rolesDir() | the harness collection, 6 base roles and 11 subskills |
The harness roles browser and composer read the third. The router reads the first two. So a rebuild of the harness collection does not touch what the dispatcher ranks, and comparing roles.nuon against harness/roles/ will make it look catastrophically stale when it is not. Whether these three should be reconciled is an open design question, tracked as H10.1.
What H10.A would change
The router is not finished, and the sub-plan describing it was written blind in a clone that did not contain this module. After a gate run against the real source, the honest remaining scope is smaller than the plan first claimed:
- Tiers one and two already exist. Project pool preferred, global fallback otherwise – that is
roles-dir-pathtoday, not future work - Tier three does not. An explicit
--globalthat unions the wider library into a scoped project's ranking, with the extra rows marked as out-of-set - Subskill exclusion does not. The composer writes
.claude/roles/subskills/*.mdinto the same pool the router reads, so a half-persona can currently be offered as a persona. It must be excluded twice over, by thesubskills/subfolder and by the# Subskill:first heading - Keywords on the file. Reading a role's own
tags:frontmatter instead of the central table, so a role dropped into a project describes itself. This is an improvement rather than a repair – the table currently resolves every one of its stems
Gotchas
- It suggests, it never adopts. Nothing here writes a
ROLE.md. Two callers surface a suggestion and/roleasks before acting - The table is the entire tuning surface.
$k in $wordsis exact whole-token membership, no stemming, no fuzz, no substrings. Tuning the table means adding the words people actually type, not making the matching smarter - An old
role-route.nuerrors outright on a table carrying_router. Its scoring runswhereover every value in the table, and a record is not a list, so it does not degrade quietly – it stops. This is why the table only carries the key when a setting departs from the default - Two roles can tie. Nothing breaks a tie beyond the sort, so a table with heavily overlapping keyword sets returns an arbitrary order among equal scores
- The table path is project-scoped. It resolves under
CLAUDE_PROJECT_DIR, falling back toPWD. Running the script from elsewhere without--tablefinds no table and it says so rather than guessing - Subskills currently pollute a composed project's pool. Until H10.A.1 lands, a project that ran the composer with
--separatehas subskill files sitting in the directory the router ranks
Connects to
- Ships inside context – the router is one of that module's files, installed to
.claude/context/role-route.nualongside its table, andcompile-context.nuis its main caller. Read the context page for how the bundle it feeds is assembled - Mirrors memory – the lessons store routes a task to a domain slice by the same keyword-overlap method, deliberately, so the two routers behave alike
- Edited by the installer's
harness rolesbrowser – theinstalledview can rewriteroles.nuonin place,eretypes a role's keyword list andtflips thehyphenssetting straight to disk. It also runs a second, unrelated roles browser overharness/roles/, see the three directories above - Generalised by project-router – M19 folds
role-routeandinject-projectinto one per-session multiplexer, so if that lands first this router resolves its pool inside that resolver rather than beside it