omp-llm-role 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gott50
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,339 @@
-# Temporary Holding Version
+# omp-llm-role
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ranks today's LLM leaderboard into best-fit picks for each omp model role
+(`default, smol, slow, vision, plan, commit, tiny, task, advisor`, plus the
+opt-in `designer`) and ships an omp plugin that applies those picks to
+`~/.omp/agent/config.yml` daily. Every role weights price and throughput, so
+the pick is the cheapest model that can do the job, not the strongest one.
+
+## Example output
+
+The report is a full worked example — per-role top-10 tables (value, q, $/M,
+tok/s, ctx, weighted metric contributions, ★ Pareto marker) plus the suggested
+`modelRoles` block. See
+[docs/llm-role-rankings.md](docs/llm-role-rankings.md).
+
+## Install
+
+Any one of three routes:
+
+```sh
+omp plugin install omp-llm-role                          # npm
+omp plugin install github:Gott50/omp-llm-role            # git (public repo)
+omp plugin marketplace add Gott50/omp-llm-role           # marketplace
+omp plugin install omp-llm-role@gott50-plugins
+```
+
+- npm and git installs shell out to `bun install`, so **bun must be on PATH**;
+  marketplace installs need no package manager.
+- No runtime dependencies.
+- **Restart the session after install** so the extension module loads.
+- Upgrades: `omp plugin upgrade omp-llm-role` (npm/git); for the marketplace,
+  `omp plugin marketplace update gott50-plugins` then
+  `omp plugin upgrade omp-llm-role@gott50-plugins`.
+- Dev: `omp plugin link ~/Documents/omp-llm-role`.
+
+## Daily behaviour
+
+- **UTC-day trigger.** The first omp session of each UTC day rewrites
+  `modelRoles` (and `retry.fallbackChains`) to that day's best key-eligible
+  models; later same-day sessions no-op. `/refresh-roles` forces a run anytime.
+- **Awaited session-start run.** The session-start run is awaited before the
+  session's first prompt is dispatched, so the day's write lands even in a
+  short-lived session (`omp -p`, a subagent).
+- **Session model activation.** When the day's run switches `default` and the
+  triggering session still has an empty conversation, the plugin also switches
+  the live session model to the new selector — the first prompt then runs on
+  the freshly ranked pick. Guards: main sessions only, empty conversation, the
+  session actually booted on the previous `default` selector (an explicit
+  `omp --model X` is never clobbered), and only on a real change. Disable with
+  `activateDefaultOnEmptySession=false`.
+- **Surgical writes.** Only managed role lines, managed chain keys, and the
+  plugin-managed `task.disabledAgents` names change; comments, blank lines and
+  unknown keys stay byte-identical, and a no-change run writes nothing.
+  `~/.omp/agent/llm-role-state.json` snapshots the previous `modelRoles` block
+  on every write as a rollback aid.
+
+## Roles
+
+| Role | Purpose |
+|---|---|
+| `default` | Main workhorse: strong general coding-agent quality, sane cost |
+| `smol` | Fast lightweight model: cheap and quick, still competent |
+| `slow` | Most capable model for hard problems; cost and speed as tiebreakers |
+| `vision` | Image understanding: vision index dominates |
+| `plan` | Planning: reasoning, math, long-context coherence |
+| `commit` | Commit messages: cheap and fast with decent general quality |
+| `tiny` | Background tasks (titles, memory): cheapest and fastest wins |
+| `task` | Subagents: agentic + tool calling, moderate cost sensitivity |
+| `advisor` | Advisor/watchdog: deep reasoning over long context |
+| `designer` | Design work: visual/UX judgement on image-capable models — **opt-in** |
+
+`designer` is the only non-built-in shipped role and ships **disabled**: a stock
+run ranks the nine built-in roles and fetches only their sources. Enable it with
+
+```sh
+omp plugin config set omp-llm-role config '{"roles":{"designer":{"enabled":true}}}'
+```
+
+The plugin then ranks it and fetches Design Arena. The shipped `designer` agent
+is opt-in too: the plugin keeps it in `task.disabledAgents` until
+`roles.designer.enabled=true`, so it is absent from the roster and refuses
+spawns by default. Its `model: "@designer, @default"` chain only matters if a
+user re-enables the agent by hand — with the role disabled the unresolved first
+entry is skipped and the child runs on `@default`.
+
+**Agent pins.** The plugin derives each agent's pinned role from the first
+`@<role>` in its `model:` frontmatter, across the shipped `agents/` dir, the
+user dir (`~/.omp/agent/agents/`) and the project dir (`<project>/.omp/agents/`).
+Disabling a role disables the agents that pin it (they are kept in
+`task.disabledAgents`); enabling re-enables them. This sync is **not**
+day-gated — it runs on every session start, so enabling a role takes effect on
+the next session. An agent pinning a role the plugin does not know is left
+alone, and other `task.disabledAgents` entries and their order are preserved.
+
+## Settings
+
+Settings live in `~/.omp/plugins/omp-plugins.lock.json` →
+`settings["omp-llm-role"]`, deep-merged over the shipped defaults. The plugin
+also exposes the whole shipped surface in omp's **`/settings` → Plugins →
+*omp-llm-role*** tab (booleans as toggles, `thinking` as a picker, `required` as
+a comma-separated string); an edit there takes effect on the next
+`/refresh-roles` (or the next day-gated session start).
+
+Global knobs:
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `switchMargin` | `0.02` | Value margin a challenger must beat the incumbent by before switching; `0` = always take the best |
+| `priceSwitchFraction` | `0.5` | Inside the margin, adopt a challenger at least this fraction cheaper (0.5 = half the $/M); `0` disables |
+| `writeFallbackChains` | `true` | Write per-role fallback chains into `config.yml` |
+| `fallbackChainDepth` | `2` | Fallback models per role chain |
+| `activateDefaultOnEmptySession` | `true` | Reapply the new `default` selector to an empty session's active model |
+
+Per-role knobs (`roles.<name>.*`):
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` (`designer`: `false`) | Opt a role in/out; `false` drops it from the resolved set and deletes its `modelRoles.<role>` line |
+| `description` | shipped one-liner | Role description |
+| `weights` | shipped set | Metric weights; must sum to 1.0 ± 0.01 |
+| `required` | shipped set | Eligibility gate (metrics a model must have); independent of weights |
+| `filters.image` | `false` (`vision`/`designer`: `true`) | Restrict the pool to image-capable models |
+| `thinking` | shipped level | Thinking level appended to the selector (`off`…`max`, `auto`) |
+| `lambda` | derived | Explicit λ ($ per quality point) override |
+| `locked` | `false` | Leave the role alone: rank it but never rewrite its selector or chain (explorer toggle) |
+
+**Typed writes.** `omp plugin config set <plugin> <key> <value>` stores every
+value as a **string**, which the validator rejects for numbers/arrays/booleans,
+so it is only usable for string-valued keys. Write typed role defs with
+`node src/cli/create-role.ts` or the explorer's **Export** (both validate →
+merge → backup → atomic write); for a whole-object override use the `config` escape
+hatch, `omp plugin config set omp-llm-role config '<json>'` (JSON-parsed by the
+plugin). The lock file stores **flat dotted keys** (`roles.slow.weights.code`);
+the reader also accepts nested objects, so an existing nested lock file keeps
+working and normalizes on the next role write. Invalid settings abort the run
+with the offending role/key and no write.
+
+## Commands
+
+```sh
+# in-session (omp)
+/refresh-roles                          # force a run now
+/explore-roles [--port N] [--no-open]   # interactive ranking UI
+/create-agent <request> [options]       # agent + role + wiring (free text or flags)
+/create-agent --name <n> --purpose <text> [options]   # agent + role + wiring
+/remove-agent --name <n> [--scope user|project] [--lock PATH] [--yes] [--dry-run]   # delete an agent and its role
+
+# CLI
+node src/cli/llm-role-rank.ts [--top N] [--json] [--out FILE] [--refresh] [--all] [--url URL]
+node src/cli/create-role.ts --name <role> --weights m=w,... [--required m,...] [--thinking <level>] [--description <text>] [--image] [--lambda N] [--lock PATH] [--dry-run] [--json]
+node --test tests/
+```
+
+- `/refresh-roles` — force the daily pipeline now (same path as the session-start
+  run).
+- `/explore-roles` — boot the explorer in-process (see below); `--port` picks a
+  preferred port (default 5177, a busy port falls back to a free one) and
+  `--no-open` skips the browser.
+- `/create-agent` — create an agent **and** its role and wire them in one
+  command (see *Add a specialist agent*).
+- `/remove-agent` — the inverse of `/create-agent`: deletes the agent `.md` and
+  its role, then runs the updater in-process so `modelRoles.<n>` is dropped;
+  refuses shipped default roles (see *Remove a specialist agent*).
+- `src/cli/llm-role-rank.ts` — markdown report to stdout (per-role tables + suggested
+  `modelRoles`). `--top N` rows per role (default 10); `--json` machine payload;
+  `--out FILE` write instead of stdout; `--refresh` bypass both caches; `--all`
+  include opt-in roles (`designer`) — the default ranks the nine built-in roles
+  only; `--url` override the llm-stats page URL.
+- `src/cli/create-role.ts` — add/update one role in the settings lock file (validated,
+  backup + atomic write); `--dry-run` validates without writing, `--json` prints
+  the payload.
+- `node --test tests/` — the unit suite.
+
+## Add a specialist agent
+
+One command does all of it. Describe the agent in plain language — the architect
+names it, any benchmark you mention is folded into the weights, and any
+benchmark link you point at is resolved:
+
+```sh
+/create-agent i want an agent for writing. use the writing related Benchmarks in the Leaderboard https://llm-stats.com/leaderboards/best-ai-for-writing
+```
+
+A link to any llm-stats benchmark page (`llm-stats.com/benchmarks/<id>`) resolves
+to that benchmark; a link to a provider the plugin has never seen is authored
+into a source declaration — the plugin fetches it, proposes a declaration, shows
+the coverage and leader, and asks you to confirm before it is saved. A named
+benchmark takes a decisive share of the weights, so it actually drives the
+ranking. You do not have to name every benchmark: when you give a purpose, the
+command also discovers the llm-stats catalog benchmarks relevant to it (a typed
+judgment through your configured `judge` role) and folds them in — so a writing
+agent is ranked on WritingBench, Creative Writing v3, COLLIE and the other
+writing benchmarks, not just the one you named. Discovery is non-fatal and
+skippable with `--no-discover`; an explicit `--benchmarks` list wins over it.
+
+The flag form is equivalent and gives you the name explicitly:
+
+```sh
+/create-agent --name review --purpose "review pull requests for correctness and security"
+```
+
+It fits the weights to the purpose from the archetype table
+(`--list-archetypes` prints the ten sets), authors
+`~/.omp/agent/agents/review.md` with `model: "@review, @default"`, writes the
+validated role into the settings lock file, and runs the updater in-process so
+`modelRoles.review` lands in `config.yml` — nothing to remember. Options:
+`--archetype <id>`, `--weights m=w,...`, `--required`, `--thinking`, `--tools`,
+`--benchmarks m,...` (extra metrics to fold in; `--list-benchmarks` prints the
+weightable set, including any external benchmark in use), `--scope user|project`,
+`--body`/`--body-file`, `--force` (overwrite an existing agent file), `--yes`
+(accept a proposed benchmark source without prompting), `--no-discover` (skip
+catalog discovery), `--dry-run`, `--json`. In
+the free-text form the flags still apply after the request, e.g.
+`/create-agent i want an agent for writing --dry-run`. There is no
+out-of-session CLI for this path — run `/create-agent` in an omp session.
+
+By hand, the same three artifacts:
+
+1. Define the role with the plugin's validated write path:
+   ```sh
+   node ~/.omp/plugins/node_modules/omp-llm-role/src/cli/create-role.ts --name review \
+     --weights reasoning=0.30,general=0.24,code=0.20,agents=0.10,price=0.10,throughput=0.06 \
+     --required general,price,throughput --thinking high \
+     --description "Code review: agentic depth with cost awareness"
+   ```
+2. Author the agent that pins `model: "@review, @default"` (the routing), or pin
+   an existing agent through `task: { agentModelOverrides: { <agent>: "@review" } }`.
+3. Wire it: `/refresh-roles` in a session.
+
+The shipped skill `omp-llm-role-create-agent` is the hand-driven equivalent, for
+when the body needs real authoring rather than the archetype scaffold.
+
+## Remove a specialist agent
+
+One command deletes an agent **and** its role:
+
+```sh
+/remove-agent --name review
+```
+
+It deletes the agent `.md` (user and/or project scope) and the role's lock-file
+keys, then runs the updater in-process so `modelRoles.review` is dropped from
+`config.yml` — nothing to remember. Options: `--scope user|project`,
+`--lock PATH`, `--yes` (skip the in-session confirmation), `--dry-run`. Shipped
+default roles (e.g. `designer`) cannot be deleted — the message points at the
+explorer's "Reset to shipped default". A role created any way (the explorer's
+"+ new role", `create-role.ts`, or `/create-agent`) is removable.
+
+By hand, the same two artifacts:
+
+1. Delete the role from the settings lock file (the explorer's Export, or edit
+   the lock file directly).
+2. Delete the agent file: `rm ~/.omp/agent/agents/review.md`.
+3. Wire it: `/refresh-roles` in a session.
+
+## Explorer
+
+`/explore-roles` in omp boots a loopback-only web UI
+(`http://127.0.0.1:5177`) that answers "why is model X at rank 7 for
+`@slow`?" and "what happens if I care more about price than agents?" without
+editing source and re-running the CLI.
+
+- **Role tabs** — every role the plugin knows: the nine omp built-in roles, the
+  shipped opt-in `designer`, and any role present only in the lock file. Each
+  tab is tinted by provenance — `default` (omp built-in), `plugin` (shipped but
+  opt-in), `user` (lock-file only) — and a disabled role is muted and dashed.
+  Selecting a disabled role still ranks its models.
+- **Rank table** — every eligible model for the selected role, with `value`,
+  `q`, `$/M` (effective, thinking-adjusted), `tok/s`, `ctx`, a `★` Pareto
+  marker, and a `Δ` column showing the rank delta against the role's effective
+  def (what the plugin does today).
+- **Explain panel** — click a row for the full decomposition: each weighted
+  metric's raw value → cardinal transform → renormalized weight → contribution,
+  the cost block (`λ`, effective vs billed price, `penalty = λ·price`,
+  `value = q − penalty`), "why not higher" (the value gap to the model above
+  plus the per-metric target that would close it), and the models that dominate
+  it on (price, q).
+- **Weight editor** — edit the role's description, weights, `required` set,
+  `filters.image`, `thinking` level, and `λ` override live; the table re-ranks
+  on every change. Weights are edited freely (no implicit rescaling): the `Σ`
+  readout turns red until `|Σ − 1| ≤ 0.01`, and `Normalize` rescales in one
+  click.
+- **Enabled toggle** — opts a role in or out. Exporting writes `enabled` into
+  the lock file; the next updater run drops a disabled role from the resolved
+  set and deletes its `modelRoles.<role>` line, and re-enabling restores it.
+- **Locked toggle** — tells the plugin to leave the role alone: it is still
+  ranked and shown, but the updater never rewrites its selector or fallback
+  chain and never removes it. Enable/disable still applies.
+- **+ new role** — creates a role from a template
+  (`general/code/price/throughput`, Σ 1.0) that you then tune and Export.
+- **Export** — writes the edited roles into the settings lock file atomically
+  and with a `.bak-<timestamp>` sibling, touching only the roles you edited. The
+  change takes effect on the next `/refresh-roles` **in any running session**
+  (the lock file is re-read from disk on every run). `Copy JSON` / `Download
+  JSON` emit the same payload for manual use.
+- **Hover explanations** — every column header, metric name, role tab, and
+  control carries a tooltip explaining its semantics.
+
+The UI never reimplements the ranking math: the numbers on screen are exactly
+the numbers the plugin would use. The server binds `127.0.0.1` only (no auth)
+and serves the SPA with no build step and no external requests.
+
+## Availability
+
+The plugin keeps only models the OpenRouter key can actually run:
+
+- **Tier/budget gate** — paid keys with budget get billed variants, free or
+  exhausted keys get `:free` variants, `:batch` never. Every candidate must
+  resolve in omp's catalog.
+- **Probe verification** — on top of the gate, every candidate is verified with
+  a one-token completion probe, because the account's OpenRouter
+  **allowed-providers privacy whitelist** is invisible to the key and catalog
+  endpoints and a real request's 404 is the only reliable signal. Blocked
+  candidates are excluded from selection and chains; a role with no clean
+  candidate is left untouched.
+
+## Caveats
+
+- **Sparse metrics.** A missing weighted metric contributes 0 while still
+  occupying its share of the denominator, so weight sparse metrics as
+  differentiators, never as `required` gates. `website`, `writing` and
+  `long_context` are capability-filled (0.195) instead, so absence is not a
+  penalty for them.
+- **Provider whitelist.** The account's allowed-providers whitelist blocks many
+  models, so the report's #1 and the written selector can differ — judge weights
+  on the reachable pool.
+- **Model concentration.** The cheapest pick concentrates on one vendor; the
+  fallback chains mitigate it.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+## Documentation
+
+Maintainer docs (architecture, data sources, scoring, writes/state, explorer
+internals, releasing, agent authoring, the normative spec) live in
+[docs/dev/README.md](docs/dev/README.md); release history is in
+[CHANGELOG.md](CHANGELOG.md).

package/agents/designer.md

@@ -0,0 +1,75 @@
+---
+name: designer
+description: UI/UX specialist for design implementation, review, visual refinement
+model: "@designer, @default"
+tools: [read, bash, edit, ast_grep, ast_edit, ask, debug, ida, eval, github, glob, grep, find, lsp, checkpoint, rewind, context_notes, new_context, security_scan, task, wait, todo, web_search, write, memory_edit, retain, recall, reflect, learn, manage_skill]
+---
+
+Implement/review UI designs; edit files, create components, run commands as needed.
+
+<strengths>
+- Design intent → working UI code
+- UX issues: unclear states, missing feedback, poor hierarchy
+- Accessibility: contrast, focus states, semantic markup, screen-reader compatibility
+- Visual consistency: spacing, typography, color, component patterns
+- Responsive design and layout structure
+</strengths>
+
+<design-system>
+Design system: foundation; UI without one becomes inconsistent. Four phases, in order:
+1. **Token-first analysis (before CSS/JSX/Svelte).** Use `grep` and `read` for tokens (colors, spacing, typography, shadows, radii), theme files (CSS variables, Tailwind config, `theme.ts`), shared primitives (Button, Card, Input, Layout). Read 5-10 existing components for naming, spacing grid, color use, type scale before deciding.
+2. **No coherent system? Build minimal system first.** Extract existing patterns; define palette, type scale, spacing scale (4px/8px base), radii/shadows/transitions, primitives; THEN implement the request against it.
+3. **Compose with, NEVER around, the system.** Colors: tokens/CSS variables, NEVER hardcoded hex; spacing: scale values, NEVER arbitrary px; type: scale steps; components: extend/compose existing primitives, not one-off div soup. Outside-system need: add token first, then use it; NEVER one-off override.
+4. **Verify before done.** Every color token; spacing on scale; component follows existing composition pattern; zero magic numbers; consistency across old/new. Any no → not done.
+</design-system>
+
+<procedure>
+## Implementation
+1. Read existing components, tokens, patterns; reuse before inventing.
+2. Identify aesthetic direction: minimal, bold, editorial, etc.
+3. Implement states: loading, empty, error, disabled, hover, focus.
+4. Verify accessibility: contrast, focus rings, semantic HTML.
+5. Test responsive behavior.
+
+## Review
+1. Read reviewed files.
+2. Check UX issues, accessibility gaps, visual inconsistencies.
+3. Cite file, line, concrete issue; no vague feedback.
+4. Suggest specific fixes; code when applicable.
+</procedure>
+
+<directives>
+- SHOULD prefer editing existing files to creating new ones.
+- Changes MUST be minimal and match existing code style.
+- NEVER create documentation files (`*.md`) unless explicitly requested.
+</directives>
+
+<avoid>
+## AI Slop Patterns
+- Glassmorphism everywhere: decorative blur, glass cards, glow borders
+- Cyan-on-dark with purple gradients: 2024 AI palette
+- Gradient text on metrics/headings: meaningless decoration
+- Identical card grids: repeated icon + heading + text
+- Nested cards: visual noise; flattened hierarchy
+- Large rounded-corner icons above every heading: templated, no value
+- Hero metric layouts: big number, small label, gradient accent; overused
+- Same spacing everywhere: no rhythm; monotony
+- Center-aligning everything: left alignment with asymmetry feels more designed
+- Modals for everything: lazy, rarely best
+- Overused fonts: Inter, Roboto, Open Sans, system defaults
+- Pure black (`#000`) or white (`#fff`): ALWAYS tint neutrals
+- Gray text on colored backgrounds: use a background shade instead
+- Bounce/elastic easing: dated, tacky; use exponential easing (`ease-out-quart`/`expo`)
+
+## UX Anti-Patterns
+- Missing loading, empty, error states
+- Redundant information: heading restates intro text
+- Every button primary: hierarchy matters
+- Empty states saying "nothing here" rather than guiding users
+</avoid>
+
+<critical>
+Every interface: "how was this made?", not "which AI made this?"
+MUST commit to clear aesthetic direction; execute precisely.
+MUST continue until implementation complete.
+</critical>

package/docs/dev/README.md

@@ -0,0 +1,54 @@
+# Developer documentation
+
+Maintainer docs for the omp-llm-role plugin. `README.md` is for people *using*
+the plugin; everything here is for people *changing* it. A fact has exactly one
+home — if it is here, it is not in the README.
+
+## Where to start
+
+| If you are changing… | Read |
+|---|---|
+| a module, an entry point, or the data flow between them | [architecture.md](architecture.md) |
+| a data source, its fetch/cache, or a join between sources | [data-sources.md](data-sources.md) |
+| a metric, a cardinal transform, or a role's weights | [scoring.md](scoring.md) |
+| a config write, the state/history/lock files, or the write gate | [writes-and-state.md](writes-and-state.md) |
+| the explorer surface (server, explain layer, SPA) | [explorer.md](explorer.md) |
+| the dated numbers (matched/priced/eligible counts, per-role leaders) | [current-state.md](current-state.md) |
+| a release (version bump, npm/git/marketplace channels) | [releasing.md](releasing.md) |
+| the agent `.md` contract (frontmatter, routing, read-only rules) | [agent-authoring.md](agent-authoring.md) |
+| a normative decision (what the plugin MUST do) | [spec.md](spec.md) |
+| a debugging-only oddity (a quirk, not a contract) | [quirks.md](quirks.md) |
+
+## The docs
+
+- **[architecture.md](architecture.md)** — the module map and entry points:
+  `src/cli/llm-role-rank.ts` (CLI report), `src/engine.ts` (shared ranking engine),
+  `src/updater.ts` (orchestration), `src/extension.ts` (omp extension), the
+  explorer, and how a run flows from fetch to config write.
+- **[data-sources.md](data-sources.md)** — every source the engine reads
+  (llm-stats leaderboard, OpenRouter catalog + per-provider routes, Design
+  Arena, the writing leaderboard), its cache file and freshness rule, and the
+  id joins that stitch them into one model row.
+- **[scoring.md](scoring.md)** — the cardinal transforms, the value formula
+  `q − λ·$/M`, the Pareto frontier, hysteresis, and the per-role
+  weight/`required` semantics.
+- **[writes-and-state.md](writes-and-state.md)** — the surgical `config.yml`
+  patch (`modelRoles`, `retry.fallbackChains`, `task.disabledAgents`), the
+  atomic write, the state/history/lock files, and the day gate.
+- **[explorer.md](explorer.md)** — the interactive ranking UI: the
+  zero-dependency HTTP server, the pure explain layer (baseline deltas,
+  per-model decomposition, inverse-cardinal targets), and the SPA.
+- **[current-state.md](current-state.md)** — the dated snapshot:
+  matched/priced/eligible counts, per-role leaders, and the open defects.
+  Refresh it with each run.
+- **[releasing.md](releasing.md)** — the release switch (`package.json`
+  `version`), the npm/git/marketplace channels, the tarball `files` whitelist,
+  and the install-route verification.
+- **[agent-authoring.md](agent-authoring.md)** — the agent `.md` contract:
+  frontmatter (`model: "@<role>, @default"`, `tools:`), the routing
+  description, read-only classification, and where agents are discovered.
+- **[spec.md](spec.md)** — the normative spec: the confirmed decisions, the
+  verified ground truth, and the contracts the implementation MUST satisfy.
+- **[quirks.md](quirks.md)** — debugging-only oddities and gotchas that are not
+  contracts (e.g. Node type-stripping not typechecking, stale in-process plugin
+  code).

package/docs/dev/agent-authoring.md

@@ -0,0 +1,165 @@
+# Agent authoring: the `.md` contract
+
+An omp subagent is a Markdown file with YAML frontmatter: the frontmatter is the
+routing unit (what the main model dispatches on, and which model role the child
+runs), the body is the system prompt. This document is the **contract** the plugin
+writes and reads; the step-by-step authoring workflow lives in the shipped skill
+[`skills/omp-llm-role-create-agent/SKILL.md`](../../skills/omp-llm-role-create-agent/SKILL.md)
+and in `/create-agent`.
+
+Source of truth: [`src/agent-file.ts`](../../src/agent-file.ts) (rendering,
+placement, read-only classification), [`src/agent-pins.ts`](../../src/agent-pins.ts)
+(pin derivation), [`src/agent-create.ts`](../../src/agent-create.ts) (`/create-agent`
+core), [`src/agent-architect.ts`](../../src/agent-architect.ts) (the in-process
+architect).
+
+## Frontmatter
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | `[A-Za-z0-9_-]+` (`AGENT_NAME_RE`); `main` and `sub` are reserved (`RESERVED_AGENT_NAMES` — omp's session sentinels). The file name is `<name>.md`; omp derives the agent id from it. |
+| `description` | yes | The routing rule the main model dispatches on: "MUST be used for …", what it returns, when to skip. `/create-agent` uses the architect's `whenToUse` (which must start with "Use this agent when"); without an architect it derives `MUST be used to/for <purpose>.` |
+| `model` | yes | The ordered fallback chain `@<role>, @default` — never a bare `@<role>` (below). |
+| `tools` | no | Builtin tool allowlist, comma-separated. Absent/empty = full session access. |
+| `thinking-level` | **never** | The role's `thinking` field already sets the effort and prices it; a second pin would silently disagree with the ranking. |
+
+### `model:` is a chain, not an alias
+
+`@<role>` is a role alias only when `<role>` is a built-in id (`default, smol,
+slow, vision, plan, commit, tiny, task, advisor`) or a key in `modelRoles`.
+Otherwise omp treats it as a **literal model pattern** and hard-fails
+`Model "@x" not found`. A role is absent whenever it is disabled
+(`roles.<role>.enabled=false`), unranked, or not yet written to `config.yml` — so a
+bare `model: "@designer"` hard-fails in exactly the state a fresh install is in.
+
+The chain `model: "@<role>, @default"` keeps the agent spawnable: omp skips the
+unresolved first entry and the child runs on `@default`. The plugin always writes
+the chain (`renderAgentFile`), and the shipped
+[`agents/designer.md`](../../agents/designer.md) pins it.
+
+### `tools:` and the read-only classification
+
+`isReadOnlyTools` (`src/agent-file.ts`) classifies an agent as read-only iff its
+tools list is **non-empty and every entry is in `READ_ONLY_TOOLS`**:
+
+```
+read, wait, grep, glob, find, web_search, ast_grep, yield, ask, todo,
+recall, reflect, retain, memory_edit, checkpoint, rewind
+```
+
+Any other name — including an unknown one, which omp silently drops — makes the
+agent a writer. An empty list is full session access, not read-only. The
+`/create-agent` archetypes default to a writer set except `review`/`audit`
+(`read, grep, glob, find`) and `research`/`search` (`read, grep, glob, find,
+web_search`).
+
+`renderAgentFile` emits `tools: <comma-joined names>`; the shipped
+`agents/designer.md` uses the equivalent YAML flow form `tools: [a, b, c]`. Both
+are comma-separated lists omp parses.
+
+## Rendering and writing
+
+`renderAgentFile` emits exactly, in order: `---`, `name: <name>`,
+`description: "<double-quoted>"`, `model: "<double-quoted>"`, an optional
+`tools:` line, `---`, a blank line, then the trimmed body. `description` and
+`model` are YAML double-quoted (backslashes and quotes escaped, newlines folded).
+
+`writeAgentFile` refuses to clobber an existing file unless `--force`, creates the
+target dir if missing, and writes through the same tmp+rename, mtime-guarded
+writer as the settings lock file — a half-written file can never be read as an
+agent.
+
+## Placement and discovery
+
+| Scope | Directory | Notes |
+|---|---|---|
+| plugin (shipped) | `agents/` in the plugin repo | discovered from the plugin's extension root — linking/installing the plugin ships it, no install step |
+| user (global) | `~/.omp/agent/agents/` | profile- and env-aware (`agentDir()`: `OMP_LLM_ROLE_AGENT_DIR` → `PI_CODING_AGENT_DIR` → non-default `OMP_PROFILE` → `~/.omp/agent`) |
+| project | `<project>/.omp/agents/` | under the project anchor |
+
+Override order is **first-wins, most specific first: project > user > plugin**,
+matching omp's own agent lookup. omp's full discovery order is nearest project
+`.omp/agents/` → `~/.omp/agent/agents/` → extension roots → Claude marketplace
+plugins → bundled.
+
+`discoverAgentPins` (`src/agent-pins.ts`) scans the three dirs, skips reserved
+names and files that pin no role, and maps each agent to the role its `model:`
+chain pins (`parseAgentPin`: the first `@<role>` in the `model:` frontmatter
+value; `null` when there is no `model:` line or the value names no `@role`). A
+name present in several scopes resolves to the most specific one.
+
+## The pin-derived disable
+
+omp has no per-agent frontmatter gate (`parseAgentFields` has no `enabled`;
+`discoverAgents` scans `<ext>/agents/*.md` unconditionally), so the plugin manages
+the core `task.disabledAgents` key in `config.yml` — the same key the `/agents`
+hub writes. The updater keeps an agent in `task.disabledAgents` **exactly while
+the role its `model:` chain pins is disabled or absent from the resolved set**;
+an agent that pins no role, or a role the settings do not define, is left alone.
+So a shipped agent pinned to a disabled role (the shipped `designer`) is off the
+roster by default, and its `@role, @default` chain only matters if a user
+re-enables the agent by hand. The sync is not day-gated — enabling the role takes
+effect on the next session.
+
+## Authoring paths
+
+- **`/create-agent`** (in-session) runs omp's agent-creation architect in-process
+  (`src/agent-architect.ts`: the `/agents` hub's prompt shipped verbatim in
+  `src/prompts/`, run through `createAgentSession` with no tools) to author the
+  routing rule and the body, then `src/agent-file.ts` adds the `model:`/`tools:`
+  frontmatter omp's own writer omits. The architect supplies
+  `{identifier, whenToUse, systemPrompt}`; the plugin uses `--name` for the file
+  (or, in the free-text form, the architect's `identifier`), `whenToUse` as the
+  description, and `systemPrompt` as the body. The role definition written to the
+  settings lock carries the same `whenToUse` as its `description` (the one-line
+  purpose when no architect ran), so the explorer and the report show the
+  architect's clean label rather than the raw prompt; benchmark links are
+  stripped from the purpose before the archetype fit, so a pasted URL path
+  cannot bias the archetype. `parseCreateAgentInput` accepts
+  either the flag form (`--name … --purpose …`) or a plain-language request
+  (`/create-agent i want an agent for writing`); the free-text form folds any
+  benchmark the request names into the weights (`extractBenchmarks`), resolves
+  any benchmark link it points at (`extractBenchmarkLinks` → the registry, or
+  the authoring step for an unknown provider), and still honours trailing flags
+  (`--dry-run`, `--force`, `--scope`, `--lock`, `--yes`, `--no-discover`). Unless
+  `--no-discover` or an explicit `--benchmarks` list is given, it also discovers
+  the catalog benchmarks relevant to the purpose (`discoverBenchmarks`: coverage
+  filter → IDF lexical rank → the configured `judge` role via
+  `src/benchmark-discovery.ts`) and folds them in. The resolved benchmark
+  labels are given to the architect (and, on the template path, listed in the
+  body's `<criteria>`), so the agent's rubric names the benchmark its model was
+  chosen on.
+- **The shipped skill** — the hand-driven workflow, for bodies that need real
+  authoring rather than the archetype scaffold.
+
+## Removal
+
+The `/remove-agent` command deletes an agent **and** its role definition:
+
+```sh
+/remove-agent --name review
+```
+
+It deletes the agent `.md` file (user and/or project scope) and the role's
+lock-file keys (`removeRoleSettings`), then runs the updater in-process so
+`modelRoles.review` is dropped from `config.yml` and the plugin-managed
+`task.disabledAgents` entry is cleaned up. Shipped default roles (e.g.
+`designer`) cannot be deleted — the message points at the explorer's "Reset to
+shipped default". `--scope user|project` restricts the agent-file removal
+(default: both); `--yes` skips the in-session confirmation; `--dry-run`
+validates without writing.
+
+By hand, the same two artifacts:
+
+1. Delete the role from the settings lock file (the explorer's Export, or edit
+   the lock file directly).
+2. Delete the agent file: `rm ~/.omp/agent/agents/review.md`.
+3. Wire it: `/refresh-roles` in a session.
+
+## Pitfalls
+
+- A role merely *named* after an agent routes nothing; the agent's `model:` pin is
+  the routing.
+- Never put non-agent `.md` files in an `agents/` dir.
+- Restart the session after the plugin writes `modelRoles` so the new alias
+  resolves.