Skip to content

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 list
tokeniser, 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 call
  • route "<task>" --top – just the winning stem on stdout, for scripting. Prints nothing when nothing scores
  • route "<task>" --roles-dir <dir> – override the pool outright
  • route "<task>" --table <file> – override the routing table
  • list – 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.

  • /role shells nu .claude/context/role-route.nu route "<task text>", shows finn the ranked table, and asks which to adopt through AskUserQuestion
  • compile-context.nu calls it with --top when a task was given and no .claude/ROLE.md exists, then appends a one line ## suggested role section to the bundle. A suggestion inside a context bundle, never an adoption
  • inject-project.nu is 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.

directorywho reads itwhat lives there
~/.claude/roles/role-route.nu, as its global fallbackthe live persona library, the old flat stems
<project>/.claude/roles/role-route.nu, preferred when presenta 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-path today, not future work
  • Tier three does not. An explicit --global that 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/*.md into the same pool the router reads, so a half-persona can currently be offered as a persona. It must be excluded twice over, by the subskills/ 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 /role asks before acting
  • The table is the entire tuning surface. $k in $words is 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.nu errors outright on a table carrying _router. Its scoring runs where over 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 to PWD. Running the script from elsewhere without --table finds 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 --separate has 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.nu alongside its table, and compile-context.nu is 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 roles browser – the installed view can rewrite roles.nuon in place, e retypes a role's keyword list and t flips the hyphens setting straight to disk. It also runs a second, unrelated roles browser over harness/roles/, see the three directories above
  • Generalised by project-router – M19 folds role-route and inject-project into one per-session multiplexer, so if that lands first this router resolves its pool inside that resolver rather than beside it