@yemi33/minions 0.1.2221 → 0.1.2222

package/dashboard/js/refresh.js

@@ -136,7 +136,7 @@ const RENDER_VERSIONS = {
   inbox: 2,
   projects: 3,
   notes: 1,
-  prd: 2,
+  prd: 3,
   prs: 3,
   archivedPrds: 1,
   engine: 4,

package/dashboard/js/render-prd.js

@@ -143,9 +143,19 @@ function renderPrd(prd, prog) {
   section.innerHTML = '';
 }
 
+// Color a PR status for the PRD page pills/glyphs: merged -> green,
+// abandoned/closed (any terminal-non-merged) -> red, active/other -> neutral
+// default text color (no accent highlight).
+function _prStatusColor(status) {
+  if (status === 'merged') return 'var(--green)';
+  if (!status || status === 'active') return 'var(--text)';
+  return 'var(--red)';
+}
+
 function _renderPrLink(pr, opts) {
   var size = (opts && opts.size) || '10px';
   var statusIcon = pr.status === 'merged' ? '✓' : pr.status === 'abandoned' ? '✗' : '○';
+  var iconColor = _prStatusColor(pr.status);
   // P-79b47b0c — render as an in-stack modal chip via renderArtifactLink
   // (was a raw <a target="_blank">). The status icon stays as a non-link
   // prefix so the chip body remains the canonical id, matching the WI/PRD
@@ -154,7 +164,7 @@ function _renderPrLink(pr, opts) {
     ? renderArtifactLink({ type: 'pr', id: pr.id, label: pr.id, title: (pr.title || '') + ' (' + (pr.status || 'active') + ')' })
     : '<code>' + escHtml(pr.id) + '</code>';
   return '<span style="font-size:' + size + ';margin-left:4px;display:inline-flex;align-items:center;gap:3px">' +
-    '<span title="' + escHtml(pr.status || 'active') + '">' + statusIcon + '</span>' + chip + '</span>';
+    '<span style="color:' + iconColor + '" title="' + escHtml(pr.status || 'active') + '">' + statusIcon + '</span>' + chip + '</span>';
 }
 
 function _renderPrdWorkItemIdBadge(workItemId, prdItemId, size, padding) {
@@ -621,7 +631,7 @@ function renderPrdProgress(prog) {
     if (prs.length > 0) {
       html += '<div style="font-size:var(--text-sm);font-weight:600;color:var(--blue);margin-bottom:4px">E2E Aggregate PRs</div>';
       html += prs.map(pr => {
-        const statusColor = pr.status === 'active' ? 'var(--green)' : pr.status === 'merged' ? 'var(--purple)' : 'var(--muted)';
+        const statusColor = _prStatusColor(pr.status);
         // P-79b47b0c — render PR id as in-stack chip (was raw <a target="_blank">).
         const prChip = (typeof renderArtifactLink === 'function')
           ? renderArtifactLink({ type: 'pr', id: pr.id, label: pr.id, title: pr.title || pr.id })

package/dashboard/js/settings.js

@@ -70,7 +70,7 @@ async function openSettings() {
     return '<tr>' +
       '<td style="font-weight:600">' + escHtml(a.emoji || '') + ' ' + escHtml(a.name || id) + '</td>' +
       '<td><input data-agent="' + escHtml(id) + '" data-field="role" value="' + escHtml(a.role || '') + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
-      '<td><input data-agent="' + escHtml(id) + '" data-field="skills" value="' + escHtml((a.skills || []).join(', ')) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
+      '<td><input data-agent="' + escHtml(id) + '" data-field="expertise" value="' + escHtml((a.expertise || []).join(', ')) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
       '<td data-runtime-cli="' + escHtml(id) + '" style="min-width:110px">' +
         // Initial loading placeholder — initRuntimeFleetUI() replaces this with a
         // <select> populated from /api/runtimes once the registry resolves.

package/dashboard.js

@@ -10684,7 +10684,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         for (const [id, updates] of Object.entries(body.agents)) {
           if (!config.agents[id]) continue;
           if (updates.role !== undefined) config.agents[id].role = String(updates.role);
-          if (updates.skills !== undefined) config.agents[id].skills = Array.isArray(updates.skills) ? updates.skills : String(updates.skills).split(',').map(s => s.trim()).filter(Boolean);
+          // Descriptive capability tags. Field renamed `skills` -> `expertise`
+          // (issue: name collision with executable runtime skills). Accept the
+          // legacy `skills` key from older clients and persist as `expertise`.
+          const expertiseUpdate = updates.expertise !== undefined ? updates.expertise
+            : (updates.skills !== undefined ? updates.skills : undefined);
+          if (expertiseUpdate !== undefined) {
+            config.agents[id].expertise = Array.isArray(expertiseUpdate) ? expertiseUpdate : String(expertiseUpdate).split(',').map(s => s.trim()).filter(Boolean);
+            delete config.agents[id].skills;
+          }
           if (updates.monthlyBudgetUsd !== undefined) {
             const val = updates.monthlyBudgetUsd === '' || updates.monthlyBudgetUsd === null ? undefined : Number(updates.monthlyBudgetUsd);
             if (val === undefined || isNaN(val)) delete config.agents[id].monthlyBudgetUsd;

package/docs/README.md

@@ -15,7 +15,8 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
-- [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library: Phase 1 exposes & edits each role's definition + skills; Phase 2 adds role/agent CRUD. Covers the additive `config.roles` model, resolver tiering, migration from per-agent `charter.md`, and API/UI surface.
+- [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
+- [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
 - [constants.md](constants.md) — Cross-cutting status / type / condition constants (`WI_STATUS`, `WORK_TYPE`, `PR_STATUS`, `WATCH_CONDITION`, …) and the no-magic-strings invariant.
 - [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
@@ -33,6 +34,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
+- [named-agents.md](named-agents.md) — The named-agent roster (Ripley / Dallas / Lambert / Rebecca / Ralph): per-agent `config.json` shape, the per-agent → `engine.*` → runtime resolution chain, how `routing.md` (not the `role`/`skills` metadata) drives dispatch, descriptive vs runtime skills, and per-agent memory files.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) — Short reference table mapping each PR auto-fix / review dispatch site in `engine.js#discoverFromPrs` to its gate flag, plus the `pollingPaused` / `autoFixPaused` master kill-switches and the per-provider polling gates.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.

package/docs/deprecated.json

@@ -1,4 +1,17 @@
 [
+  {
+    "id": "agent-config-skills-field",
+    "description": "Legacy per-agent descriptive-metadata array `agents.<id>.skills` in config.json, renamed to `agents.<id>.expertise` to remove the name collision with executable runtime/harness skills (SKILL.md). The field is metadata only (capability tags like `architecture`, `bug-fixes`); nothing in the dispatch path reads it for behavior. A read-compat shim honors the old key so operator configs still carrying `skills` (and no `expertise`) keep working.",
+    "code": [
+      { "file": "engine/playbook.js", "lines": "950", "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line" },
+      { "file": "engine/lifecycle.js", "lines": "4620-4621", "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback" },
+      { "file": "engine/queries.js", "lines": "731", "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`" },
+      { "file": "dashboard.js", "lines": "10708-10716", "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key" }
+    ],
+    "removalGate": "Telemetry / a config sweep across all known engines must show no persisted `config.agents.<id>.skills` key (only `expertise`) for >=30 consecutive days, confirming every operator config has been re-saved through the dashboard (which drops the legacy key) or hand-migrated.",
+    "targetRemovalDate": "2026-09-17",
+    "notes": "Safe to remove on or after 2026-09-17 (~3 release windows) once the removal gate clears. Removal scope: drop the `?? agent.skills` / `?? a.skills` fallbacks in engine/playbook.js:950, engine/lifecycle.js:4620-4621, and engine/queries.js:731; drop the `updates.skills` legacy branch + `delete config.agents[id].skills` in dashboard.js:10708-10716; and update docs/named-agents.md to stop mentioning the legacy key. Does NOT touch the unrelated executable-skills system (queries.js harnesses, runtime adapters, dashboard renderSkills, SKILL.md tooling)."
+  },
   {
     "id": "qa-json-sidecars",
     "location": "engine/small-state-store.js _mirrorQaRunsJson + _mirrorQaSessionsJson; engine/shared.js _qaMutator (mirror call); dashboard/js/settings.js set-qaDualWriteJson toggle",

package/docs/named-agents.md

@@ -0,0 +1,216 @@
+# Named Agents — configuration, roles, and skills
+
+Minions dispatches a small roster of **named agents** — personas like Ripley or Dallas
+that own work items, open PRs, and review each other's changes. This doc explains who
+they are, the full per-agent config shape, how work actually routes to one of them, what
+the descriptive `expertise` tags and the real executable `skills` are (and why they used to
+share a name), and how each agent accrues personal memory across dispatches.
+
+> Orientation only — the load-bearing contracts live in code. Cross-references:
+> [`CLAUDE.md`](../CLAUDE.md), [`.github/copilot-instructions.md`](../.github/copilot-instructions.md),
+> [`docs/runtime-adapters.md`](runtime-adapters.md), [`docs/workspace-manifests.md`](workspace-manifests.md),
+> [`docs/team-memory.md`](team-memory.md), and [`docs/skills.md`](skills.md).
+
+## 1. The roster
+
+The five named agents are defined under `agents` in `config.json` (gitignored; the
+shipped `config.template.json` carries no agents — operators populate the roster locally).
+Each entry is keyed by a lowercase agent id (`ripley`, `dallas`, …).
+
+| Id | Name | Emoji | Role | `expertise` (descriptive) | `cli` |
+|----|------|-------|------|------------------------|-------|
+| `ripley` | Ripley | 🏗️ | Lead / Explorer | `architecture`, `codebase-exploration`, `design-review` | `copilot` |
+| `dallas` | Dallas | 🔧 | Engineer | `implementation`, `typescript`, `docker`, `testing` | `copilot` |
+| `lambert` | Lambert | 📊 | Analyst | `gap-analysis`, `requirements`, `documentation` | `copilot` |
+| `rebecca` | Rebecca | 🧠 | Architect | `system-design`, `api-design`, `scalability`, `implementation` | `copilot` |
+| `ralph` | Ralph | ⚙️ | Engineer | `implementation`, `bug-fixes`, `testing`, `scaffolding` | `copilot` |
+
+The `name`, `emoji`, `role`, and `expertise` fields are **human-facing metadata** — they
+label the agent in the dashboard and document intent. They do **not** drive dispatch (see
+§3) and the `expertise` array is not executable (see §4).
+
+## 2. How an agent is configured
+
+The full per-agent config shape supported under `config.agents.<id>`:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `name` | string | Display name (e.g. `"Ripley"`). |
+| `role` | string | Human-facing role label (e.g. `"Lead / Explorer"`). Metadata only. |
+| `emoji` | string | Dashboard glyph. |
+| `expertise` | string[] | Descriptive capability tags. Metadata only — see §4. Legacy configs that still use the old key name `skills` are read transparently. |
+| `cli` | string | Runtime CLI for this agent's spawns: `copilot`, `claude`, or `codex`. |
+| `model` | string | Per-agent model override (omitted → runtime picks its own default). |
+| `maxBudgetUsd` | number | Per-spawn USD cap. **`0` is a valid cap** (read-only / dry-run agents), not "unlimited". |
+| `bareMode` | boolean | Run Claude in `--bare` mode (Claude-runtime knob). |
+| `hermeticHarness` | boolean | Strip user-scope skill/command/MCP roots from the worktree; `--add-dir` resolves to `[minionsDir]` only. |
+| `workspace_manifest` | object | Optional permission scoping — see below. |
+
+### Three-tier resolution chain
+
+Most knobs resolve **per-agent override → `engine.*` fleet default → runtime default**.
+The resolver helpers live in [`engine/shared.js`](../engine/shared.js):
+
+| Helper | Chain |
+|--------|-------|
+| `resolveAgentCli(agent, engine)` | `agent.cli` → `engine.defaultCli` → `ENGINE_DEFAULTS.defaultCli` (`'copilot'`). |
+| `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → `undefined` (adapter omits `--model`, CLI uses its own default). |
+| `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd` → `undefined` (no cap). Nullish-coalesced so `0` is honored. |
+| `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → `false`. Strict null check so a per-agent `false` overrides an engine `true`. |
+| `resolveAgentHermeticHarness(agent, engine)` | `agent.hermeticHarness` → `engine.hermeticHarness` → `false`. Same strict-override semantics. |
+
+Empty string / `null` / `undefined` all count as "unset" for the string knobs, so an agent
+inherits the fleet default rather than blanking the value.
+
+### Agent vs Command Center independence
+
+The Command Center (CC) / doc-chat path is a fleet-wide singleton with **no notion of
+"which agent"**, so it resolves through separate helpers: `resolveCcCli(engine)`
+(`engine.ccCli` → `engine.defaultCli` → fallback) and `resolveCcModel(engine)`
+(`engine.ccModel` → `engine.defaultModel` → `undefined`). These **do not cross over**:
+`ccCli` / `ccModel` never affect a named-agent spawn, and `agent.cli` / `agent.model` never
+affect CC. Both paths share the `engine.defaultCli` / `engine.defaultModel` fleet defaults,
+but only as the middle tier.
+
+### Workspace manifest (optional)
+
+`agents.<id>.workspace_manifest` declares declarative permission scoping. Shape and
+defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/shared.js`):
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `allowed_tools` | `null` (permissive) | Whitelist of tool names; merged into the runtime `--allowedTools` flag. `[]` = deny-all. |
+| `allowed_repos` | `null` (permissive) | Repo allow-list; enforced at dispatch time. `[]` = deny-all. |
+| `allowed_external_urls` | `null` (permissive) | URL allow-list (supports `*.example.com` wildcards). |
+| `memory_scope` | `'shared'` | One of `private`, `shared`, `read-only-shared`. |
+
+Enforcement helpers (also in `engine/shared.js`): `validateWorkspaceManifest`,
+`resolveAgentManifest`, `agentCanUseRepo`, `agentCanUseTool`, `agentCanFetchUrl`,
+`agentMemoryScope`, `mergeManifestAllowedTools`. Today the engine actively enforces (a) the
+**repo gate** at dispatch time in `engine.js spawnAgent`
+(`FAILURE_CLASS.WORKSPACE_MANIFEST_REPO`, non-retryable) and (b) the **tool merge** into the
+runtime `--allowedTools` flag at spawn time. Defaults are permissive — an agent with no
+manifest is unaffected. Full schema and rollout guidance:
+[`docs/workspace-manifests.md`](workspace-manifests.md).
+
+## 3. How roles are defined / how work routes to an agent
+
+The `role` and `expertise` config fields are **descriptive metadata**. The actual dispatch
+decision is **data-driven by [`routing.md`](../routing.md)**, which `engine.js` parses — so
+keep that file's table format exact.
+
+Routing maps a `work_type` to a `preferred` agent and a `fallback`:
+
+| Work Type | Preferred | Fallback |
+|-----------|-----------|----------|
+| implement | dallas | ralph |
+| implement:large | rebecca | dallas |
+| review | ripley | lambert |
+| fix | `_author_` | `_any_` |
+| plan | ripley | rebecca |
+| plan-to-prd | lambert | rebecca |
+| explore | ripley | rebecca |
+| test | dallas | ralph |
+| ask | ripley | rebecca |
+| verify | dallas | ralph |
+| decompose | ripley | rebecca |
+| meeting | ripley | lambert |
+| docs | lambert | `_any_` |
+| setup | dallas | `_any_` |
+| qa-validate / qa-session-* | dallas | ralph |
+
+**Sentinels.** `_author_` routes a `fix` (review-feedback) item back to the PR author for
+context; `_any_` routes to any available idle agent (lowest error rate first).
+`implement:large` is selected for items with `estimated_complexity: "large"`. If both
+preferred and fallback are busy, the engine falls back to any idle agent.
+
+**Dispatch rules** (from `routing.md`):
+
+- **Eager by default** — the engine spawns every agent that can start work, not one at a time.
+- **No self-review** — auto review dispatch always picks a non-author. When no non-author
+  reviewer is idle, the dispatch waits in `dispatch.pending` with
+  `_pendingReason: 'no_non_author_reviewer'` and promotes automatically once one frees up.
+  An explicit operator dispatch (`agent: <author>`) is honored as an override but logged as
+  a warning.
+- **Routing selects an owner; it does not narrow the task.** The assigned agent behaves as
+  if the user typed the same task into a CLI directly — Minions adds only safety, status,
+  and review guardrails.
+
+### Per-agent retry reassignment
+
+Total retries are capped by `ENGINE_DEFAULTS.maxRetries` (default 3). Separately, each work
+item tracks per-agent attempts in `_retriesByAgent: { agentId: count }`. When the **same**
+agent fails the **same** item `maxRetriesPerAgent` times (default 2; overridable via
+`engine.maxRetriesPerAgent` and the dashboard Settings field), discovery force-reassigns to
+a different eligible agent via `resolveAgent(workType, config, { excludeAgent })`. If no
+alternate is available it stays with the same agent and dedups an engine inbox note. Setting
+`agentLock: true` (or `hardAgent: true`) hard-pins the agent and bypasses reassignment —
+operator intent wins. The counter is cleared on successful completion alongside
+`_retryCount`. Helpers: `bumpAgentRetryCount`, `getAgentRetryCount`,
+`resolveMaxRetriesPerAgent` in `engine/shared.js`.
+
+## 4. How skills are defined
+
+Historically "skills" meant two unrelated things in Minions. The descriptive per-agent
+metadata array was renamed `skills` → `expertise` to remove that collision, so the only
+"skills" left are the real executable ones. The two concepts to keep separate:
+
+**(a) The descriptive `expertise` array in config** (`agents.<id>.expertise`). A list of
+capability tags like `architecture` or `bug-fixes`. This is **metadata only** — labels for
+humans, not executable behavior. Nothing in the dispatch path reads it. (This field was
+formerly named `skills`; legacy configs that still use that key are read transparently via
+an `expertise ?? skills` fallback — see [`docs/deprecated.json`](deprecated.json).)
+
+**(b) Real runtime skills** — `SKILL.md` files the runtime CLI actually loads. These are
+auto-extracted from agent output: when an agent emits a fenced ```` ```skill ```` block
+(with YAML frontmatter carrying at least a `name`), `extractSkillsFromOutput` in
+[`engine/lifecycle.js`](../engine/lifecycle.js) writes it out. The engine also scans
+`notes/inbox/` notes for skill blocks, since agents often write them there instead of stdout.
+
+- **`scope: minions`** (the default when `scope` is omitted) → written to the runtime's
+  **personal** skill directory as `<name>/SKILL.md`, so it becomes a user-level skill
+  available in normal runtime windows too.
+- **`scope: project`** (with a `project:` field) → the engine queues a low-priority
+  `implement` work item to **PR the skill into the project repo's** skill directory rather
+  than writing it directly.
+
+Near-duplicate names are flagged to `engine/skills-flagged.json` and skipped (no existing
+skill is deleted or renamed). See [`docs/skills.md`](skills.md) for the block format.
+
+**Runtime differences.** The destination directory is runtime-specific
+(`getSkillRoots` / `getSkillWriteTargets` in the runtime adapters under
+[`engine/runtimes/`](../engine/runtimes/)):
+
+| Runtime | Personal write target | Project write target | Also reads |
+|---------|-----------------------|----------------------|------------|
+| Claude (`claude.js`) | `~/.claude/skills/` | `<repo>/.claude/skills/` | `~/.agents/skills/` |
+| Copilot (`copilot.js`) | `~/.copilot/skills/` | `<repo>/.github/skills/` | `~/.copilot`, `~/.agents/skills/` |
+
+The capability matrix for each runtime is in [`docs/runtime-adapters.md`](runtime-adapters.md).
+
+## 5. Per-agent memory & charters
+
+Each named agent has a personal memory file at
+`knowledge/agents/<agentId>.md` (e.g. `knowledge/agents/dallas.md`) — a personal notebook
+injected into that agent's prompt on every dispatch. The format convention is documented in
+[`knowledge/agents/README.md`](../knowledge/agents/README.md).
+
+**Written exclusively by the consolidation pipeline.** `appendToAgentMemory` in
+[`engine/consolidation.js`](../engine/consolidation.js) routes each `notes/inbox/` finding
+to its author's file. Authorship comes from the inbox note's YAML frontmatter `agent:`
+field, with the **filename prefix** (`<agent>-…md`) as fallback (`extractInboxAgent`). Key
+properties:
+
+- **Append-only** — agents must not edit their own memory files directly; write to
+  `notes/inbox/` and let the sweep route it.
+- **~25 KB cap** (`AGENT_MEMORY_BUDGET_BYTES`) — oldest sections pruned at section
+  boundaries to stay under budget.
+- **Only configured `config.agents` keys get a file** — the agent must be in the known-team
+  set; `temp-*` ids are skipped. This is a strict superset of broadcast consolidation: the
+  shared `notes.md` digest still happens; per-agent routing is *in addition*.
+
+**Prompt injection order.** [`engine/playbook.js`](../engine/playbook.js) injects, in this
+order, `pinned.md` → `notes.md` → `knowledge/agents/<agentId>.md` (when present). Missing
+files are silently skipped. The per-agent file is fenced as `<UNTRUSTED-INPUT>` and capped
+to the notes prompt budget before injection. The companion read-side reference is
+[`docs/team-memory.md`](team-memory.md).

package/docs/specs/agent-configurability.md

@@ -3,32 +3,40 @@
 **Status:** Draft
 **Owner:** @calebt
 **Audience:** Minions contributors working on the dashboard, engine config surface, and playbook/system-prompt rendering.
+**Depends on:** [`agent-rename.md`](agent-rename.md) — a **hard prerequisite**. That spec delivers the "names aren't load-bearing" foundation (stable opaque agent **id**, name-agnostic charters, and the agent rename capability) that this Library builds on. The decoupling sections below (§2.8, §4.1a, §4.3c, §5.4) are **summaries that defer to `agent-rename.md`** for the full treatment.
 
-> Companion reading: [`.github/copilot-instructions.md`](../../.github/copilot-instructions.md) and [`CLAUDE.md`](../../CLAUDE.md) for the engine/dashboard split and config conventions.
+> Companion reading: [`.github/copilot-instructions.md`](../../.github/copilot-instructions.md) and [`CLAUDE.md`](../../CLAUDE.md) for the engine/dashboard split, config conventions, and the feature-flag registry.
 
 ## 1. Motivation
 
-Today a Minions "team" is a fixed roster of five hard-coded agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`) whose personas live in a mix of places: a free-text `role` string in `config.json`, a loosely-related `skills` string array, and a per-agent `charter.md` file. There is **no way to**:
+Today a Minions "team" is a fixed roster of five hard-coded agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`) whose personas live in a mix of places: a free-text `role` string in `config.json`, a loosely-related `skills` string array, and a per-agent `charter.md` file. The charter — the real persona — is **per-agent**, so there is no reusable notion of "what it means to be an Engineer." There is **no way to**:
 
-- See an agent's full definition (persona + skills + runtime) in one place.
-- Treat a "role" as a reusable, editable unit — it is just a label string today.
+- See an agent's full definition (role charter + expertise + runtime) in one place.
+- Treat a "role" as a reusable, editable unit (a durable charter shared across agents) — it is just a label string today.
+- **Rename** an agent's display name.
 - Add a brand-new role, or stand up a new named agent, from the dashboard.
 
-The goal is to make the fleet **user-configurable** through a **Role / Agent Library**, delivered in two phases:
+The goal is to make the fleet **user-configurable** through a **Role / Agent Library** built on one core idea: **the role owns the durable charter ("what it means to be an X") and is the reusable unit; an agent is a thin named instance that points at a role and carries only its identity, its variable expertise, and runtime knobs** (§3). Delivered in phases, with **two cross-cutting constraints on every phase:**
 
-- **Phase 1 — Expose & edit.** Surface the skill + definition for each existing role/agent in one editable library view. No new roles or agents yet; just make what exists first-class and editable.
+- **Backwards compatible.** Existing `config.json` files, per-agent `charter.md` files, `routing.md`, and all agent-keyed state must keep working with zero migration required from the user. New config shapes are additive; back-compat readers are unconditional.
+- **Feature-flagged.** All new surfaces in *this* spec (the Library UI, the role model, CRUD) sit behind a single registry flag `agent-library`, default **OFF**, so the change ships dark and is enabled per-install (see §3.1). The agent **rename** capability is gated separately by its own `agent-rename` flag in the [`agent-rename.md`](agent-rename.md) prerequisite.
+
+Phases:
+
+- **Phase 0 — Prerequisite migrations.** Establish the feature flag and rename the misnamed `skills` field to `expertise`. (The stable-id formalization and name-agnostic charters are delivered by the **[`agent-rename.md`](agent-rename.md) prerequisite**, which must land first.) All additive + flag-aware.
+- **Phase 1 — Expose & edit.** Surface each role's durable charter + each agent's variable expertise in one editable library view; the agent **rename** capability comes from the prerequisite and is surfaced inline here. No new roles or agents yet.
 - **Phase 2 — Create & assign.** Add new roles, and stand up new named agents bound to a role.
 
 ## 2. Current state (grounding)
 
 This section is the factual baseline the design must respect. Citations are `file:line` against the repo at spec-authoring time.
 
-### 2.1 Agent object
+### 2.1 Agent object — already id-keyed
 
-Agents live under `config.agents` keyed by lowercase id. Defaults are hard-coded:
+Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:681-687`). Defaults are hard-coded:
 
 ```js
-// engine/shared.js:4350-4356
+// engine/shared.js:4398-4404
 const DEFAULT_AGENTS = {
   ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', skills: ['architecture', 'codebase-exploration', 'design-review'] },
   dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        skills: ['implementation', 'typescript', 'docker', 'testing'] },
@@ -38,6 +46,8 @@ const DEFAULT_AGENTS = {
 };
 ```
 
+Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/routing.js:160-189`). So `name !== lowercase(id)` is already safe. This is the foundation that makes **rename = change `name`, keep `id`** trivial (see §2.8; full treatment in [`agent-rename.md`](agent-rename.md)).
+
 Runtime / budget fields are **optional per-agent overrides** resolved against `engine.*` fleet defaults via helpers in `engine/shared.js`:
 
 | Field | Resolver | Falls back to |
@@ -47,26 +57,20 @@ Runtime / budget fields are **optional per-agent overrides** resolved against `e
 | `maxBudgetUsd` / `monthlyBudgetUsd` | `resolveAgentMaxBudget` (shared.js:3231) | `engine.maxBudgetUsd` |
 | `bareMode` | `resolveAgentBareMode` (shared.js:3254) | `engine.claudeBareMode` → false |
 
-So the effective agent shape is:
-
-```jsonc
-{ "name": "Dallas", "emoji": "🔧", "role": "Engineer",
-  "skills": ["implementation","testing"],
-  "cli": "claude", "model": "haiku", "monthlyBudgetUsd": 5, "bareMode": false }
-```
-
 ### 2.2 "Role" is a label, not an entity
 
 `role` is a **free-text string** on the agent. There is no role registry, no role schema, and routing does **not** reference roles — it references agent ids. The dashboard edits role as a plain text input (`dashboard/js/settings.js:72`) and persists it verbatim (`dashboard.js:10684`).
 
-### 2.3 `skills` is metadata, not real skills
+### 2.3 `skills` is *expertise*, not real skills
 
-Two unrelated things share the word "skill":
+Two unrelated things share the word "skill" today, and the `agent.skills` field is the **misnamed** one:
 
-1. **`agent.skills`** — a string array, surfaced only as an `Expertise: …` line in the system prompt (`engine/playbook.js:950`). It is **not** linked to any executable capability.
-2. **Real `SKILL.md` files** — discovered from disk (`.claude/skills/`, `~/.claude/skills`, project harness dirs) by `collectSkillFiles()` / `getSkills()` (`engine/queries.js:1263-1400`), scoped global/project/plugin. These are **not** bound to a specific agent or role; every agent sees the same discovered catalog.
+1. **`agent.skills`** — a string array of **expertise tags**. It is *not* linked to any executable capability or on-disk skill file. It has exactly two readers:
+   - **Display:** rendered as the `Expertise: …` line in the system prompt (`engine/playbook.js:950`).
+   - **Soft routing:** `pickReReviewAgentHints()` (`engine/lifecycle.js:4613-4624`) scans `agent.skills` for the tags `code-review` / `design-review` to *prefer* (not require) that agent for re-review. This is the one functional consumer — a rename must update it too, not just the display line.
+2. **Real `SKILL.md` files** — discovered from disk (`.claude/skills/`, `~/.claude/skills`, project harness dirs) by `collectSkillFiles()` / `getSkills()` (`engine/queries.js:1263-1400`), scoped global/project/plugin. These are **not** bound to a specific agent or role; every agent sees the same discovered catalog, and `agent.skills` has **no relationship** to them.
 
-This split is a key source of the "agents aren't really configurable" feeling and must be addressed explicitly (see §4.3).
+Because `agent.skills` is purely expertise metadata (plus a soft reviewer hint), the field is misnamed. **Phase 0b renames it `expertise`** to remove the overload and free the word "skills" for any future real-skill binding (§8).
 
 ### 2.4 Charter = the real "agent definition"
 
@@ -75,7 +79,7 @@ The substantive persona/instructions for an agent is `agents/<id>/charter.md`, r
 ```
 # You are {name} ({role})
 Agent ID: {id}
-Expertise: {skills joined}
+Expertise: {expertise joined}
 
 ## Your Charter
 {charter.md contents}
@@ -84,6 +88,8 @@ Expertise: {skills joined}
 
 Charter is already editable today, but only from the **agent detail panel → Charter tab** (`dashboard/js/detail-panel.js:115-126`) via `POST /api/agents/charter` (`dashboard.js:13205-13211`). It is disconnected from the Settings → Agents table.
 
+**Today's default charters hardcode names.** The shipped charters bake the agent's own name and peers' names directly into the prose — e.g. `agents/ripley/charter.md` opens `# Ripley — Lead / Explorer`, `**Name:** Ripley`, and says "Handing off structured findings to **Dallas** (Engineer) and **Lambert** (Analyst)". This is fine today (names are fixed) but **collides with two new capabilities**: renaming an agent (Phase 1) would leave the old name strewn through the prompt, and a role-level `charter` shared across multiple agents can't bake in any one agent's name. Role charters must become **name-agnostic** (§4.3c).
+
 ### 2.5 Routing
 
 `routing.md` is a markdown table mapping work-type → preferred/fallback **agent id** (`routing.md:8-27`), parsed by `engine/routing.js:31-52`. `resolveAgent()` (`engine/routing.js:192`) resolves the route, honoring `_author_` / `_any_` tokens, idleness, budget, and the self-review ban. Routing is edited via `POST /api/settings/routing`, which overwrites `routing.md` wholesale (`dashboard.js:10799-10805`).
@@ -91,47 +97,71 @@ Charter is already editable today, but only from the **agent detail panel → Ch
 ### 2.6 Config read / write surface
 
 - **Read:** `queries.getConfig()` (`engine/queries.js:181-225`); Settings read endpoint returns `{ engine, claude, agents, projects, routing }` (`dashboard.js:10362-10391`).
-- **Write:** `POST /api/settings` edits `engine`, `claude`, **existing** `agents[id]` (role, skills, cli, model, budget — `dashboard.js:10682-10705`), and projects, then saves `config.json`. **There is no agent create/delete path** — the loop `for (const [id, updates] of Object.entries(body.agents))` skips unknown ids (`dashboard.js:10683`).
+- **Write:** `POST /api/settings` edits `engine`, `claude`, **existing** `agents[id]` (role, skills, cli, model, budget — `dashboard.js:10682-10705`; **note: `name` is NOT editable today**), and projects, then saves `config.json`. **There is no agent create/delete/rename path** — the loop `for (const [id, updates] of Object.entries(body.agents))` skips unknown ids (`dashboard.js:10683`).
 - **Reset:** restores `engine` defaults + `shared.DEFAULT_AGENTS` (`dashboard.js:10808-10815`).
-- **UI:** Settings → Runtime pane has an **edit-only** Agents table (Role, Skills, CLI, Model, Budget) — `dashboard/js/settings.js:152-157`. No add/remove.
+- **UI:** Settings → Runtime pane has an **edit-only** Agents table (Role, Skills, CLI, Model, Budget) — `dashboard/js/settings.js:152-157`. No add/remove/rename.
 
 ### 2.7 Gaps summary
 
 | Capability | Today |
 |------------|-------|
 | View an agent's full definition in one place | ✗ (split across settings table + charter tab) |
-| Role as a reusable, editable unit | ✗ (free-text label) |
-| Edit charter from the library/settings | ✗ (only detail panel) |
-| Bind skills to a role/agent meaningfully | ✗ (metadata only) |
+| Role as a reusable, editable unit (durable charter) | ✗ (free-text label; charter is per-agent) |
+| Reuse one charter across many agents | ✗ (each agent has its own `charter.md`) |
+| Edit a role's charter from the library/settings | ✗ (only the per-agent detail panel) |
+| Rename an agent's display name (+ emoji) | ✗ |
+| `expertise` field named for what it is | ✗ (called `skills`, overloaded) |
 | Add a new role | ✗ |
 | Add a new named agent | ✗ |
 | Delete an agent | ✗ |
 
+### 2.8 Agent identity is a stable opaque id
+
+> **Summary — full treatment in [`agent-rename.md`](agent-rename.md) §2.**
+
+Agents are **already id-keyed**: every piece of agent-scoped state (charter file, per-agent memory, metrics, dispatch/PR records, inbox prefixes, routing) is keyed by the immutable `config.agents` **key**, never the display `name`. The only consumers of `name` are `buildSystemPrompt`'s `# You are {name}` line and dashboard display text. So the id is the stable handle the role model relies on (an agent can be renamed or reassigned to a different role without touching any id-keyed state), and it must never be mutated. The rename prerequisite formalizes this invariant with a guard + tests.
+
 ## 3. Target model: the Role / Agent Library
 
-Introduce a **Role** as a first-class, reusable definition, and make **Agents** named instances that reference a role and optionally override pieces of it.
+**The role is the reusable unit, and the role *is* the durable charter.** An agent's definition splits into two parts along a **durable vs. variable** seam:
+
+- **Durable (role-level, reusable):** the **charter** — "what it means to be an Engineer": responsibilities, working style, ownership, guardrails. Authored once on the role and shared, unchanged, by every agent of that role. Long-form, name-agnostic (§3.3, §4.3c).
+- **Variable (agent-level, per-instance):** the **expertise** — the specialization that distinguishes two agents of the *same* role (e.g. one Engineer focused on TypeScript/Docker, another on bug-fixes/scaffolding). Short-form, part of the agent's identity (§3.3).
+
+So an **agent is a thin named instance**: identity (name, emoji) + **its variable expertise** + a pointer to a role (which supplies the durable charter) + runtime knobs. There is **no** per-agent charter override — if you need a different *persona*, you pick/make a different role; if you only need a different *specialization*, that's expertise.
 
 ```jsonc
-// config.json (additive — see §5 migration)
+// config.json (additive — see §6 migration)
 {
+  "features": { "agent-library": true },     // gates all new surfaces (§3.1)
+
+  // ROLE = the reusable, DURABLE definition. The charter ("what it means to
+  // be an X") + label + runtime defaults live here. Shared across agents.
   "roles": {
     "engineer": {
-      "label": "Engineer",                 // human-facing name
-      "definition": "<markdown persona>",  // the role-level charter (system-prompt body)
-      "skills": ["implementation", "testing", "bug-fixes"],
-      "defaultCli": null,                  // optional role-level runtime defaults
+      "label": "Engineer",                   // human-facing role name
+      "charter": "<markdown persona>",       // THE durable definition — long-form, name-agnostic (§3.3, §4.3c)
+      "defaultCli": null,                     // optional role-level runtime defaults
       "defaultModel": null,
-      "builtin": true                      // seeded from DEFAULT_ROLES; protects from delete in P1
+      "builtin": true                         // seeded from DEFAULT_ROLES — editable but NEVER deletable (§3.2)
     },
-    "architect": { "label": "Architect", "definition": "…", "skills": ["system-design","api-design"] }
+    "architect": { "label": "Architect", "charter": "…" }
   },
+
+  // AGENT = a thin named instance: identity + VARIABLE expertise + role pointer
+  // + runtime overrides. No charter here — the durable charter comes from the role.
   "agents": {
-    "dallas": {
-      "name": "Dallas", "emoji": "🔧",
-      "role": "engineer",                  // now references roles{} key (was free text)
-      "skills": [],                        // agent-level ADDITIONS to the role's skills
-      "definitionOverride": null,          // optional per-agent charter override
-      "cli": null, "model": null, "monthlyBudgetUsd": null, "bareMode": false
+    "dallas": {                               // ← the KEY is the stable opaque id; never mutated
+      "name": "Dallas",                       // ← identity: display name; freely renamable (Phase 1)
+      "emoji": "🔧",                          // ← identity: emoji
+      "role": "engineer",                     // ← supplies the durable charter + label
+      "expertise": ["typescript", "docker", "testing"],  // ← VARIABLE: this instance's specialization
+      "cli": null, "model": null, "monthlyBudgetUsd": null, "bareMode": false   // runtime knobs only
+    },
+    "ralph": {
+      "name": "Ralph", "emoji": "⚙️",
+      "role": "engineer",                     // ← same durable charter as Dallas…
+      "expertise": ["bug-fixes", "scaffolding", "testing"]  // ← …but different variable expertise
     }
   }
 }
@@ -139,133 +169,244 @@ Introduce a **Role** as a first-class, reusable definition, and make **Agents**
 
 **Resolution rules (engine):**
 
-- Effective **definition** = `agent.definitionOverride` ?? `roles[agent.role].definition` ?? legacy `agents/<id>/charter.md`. (Keeps existing charters working — see §5.)
-- Effective **skills** = union of `roles[agent.role].skills` and `agent.skills`.
-- Effective **label** shown in `# You are {name} ({label})` = `roles[agent.role].label` ?? raw `agent.role` string (legacy).
-- Effective **cli/model** chain unchanged, with an inserted role tier: `agent.cli` → `roles[agent.role].defaultCli` → `engine.defaultCli` → `'copilot'`.
+- Effective **charter (durable)** = `roles[agent.role].charter` ?? legacy `agents/<id>/charter.md` (the legacy per-agent file is read only as a back-compat fallback for agents whose role has no charter yet — see §6). Name-agnostic: the agent's name is supplied *only* by the injected `# You are {name} ({label})` identity line, never baked into the charter body (§4.3c).
+- Effective **expertise (variable)** = `agent.expertise` (with `agent.skills` read as a back-compat alias — see §4.2b).
+- Effective **label** shown in `# You are {name} ({label})` = `roles[agent.role].label` ?? raw `agent.role` string (legacy free-text role).
+- Effective **cli/model** chain gains a role tier: `agent.cli` → `roles[agent.role].defaultCli` → `engine.defaultCli` → `'copilot'`.
+
+The **durable** persona resolves entirely from the role; the **variable** expertise and the **identity** (`name`, `emoji`, `id`) are per-agent. These are the two **dimensions** of an agent — see §3.3. This preserves every existing resolver's external behavior when `roles` is absent or `agent.role` is still free-text (legacy), and layers the library in additively.
+
+### 3.1 Feature flag (cross-cutting)
+
+A single registry flag gates everything user-visible in this spec:
+
+- Register `agent-library` in the `FEATURES` registry (`engine/features.js`) as `{ description, default: false, addedIn, expires }`.
+- **Engine** gates new behavior with `features.isFeatureOn('agent-library', config)`; **dashboard JS** gates new UI with `MinionsFeatures.isOn('agent-library')`.
+- Toggle via Settings → Experimental flags, `config.features['agent-library']: true`, or `MINIONS_FEATURE_AGENT_LIBRARY=1`. Resolution order: env → `config.features` → registry default (default OFF).
+- **What the flag gates:** the Library page/API (`/api/roles*`), agent rename UI, role/agent CRUD UI, and the role-tier resolution layer.
+- **What the flag does NOT gate (always on):** the unconditional back-compat *readers* — `agent.expertise ?? agent.skills`, `roles[agent.role].charter ?? agents/<id>/charter.md`, and `roles[agent.role].label ?? agent.role`. These are pure fallbacks that are inert on a legacy config and must work whether or not the flag is set, so an install that flips the flag off after editing never breaks. When the flag is OFF and no `roles` exist, behavior is byte-for-byte identical to today.
+
+When the feature graduates, delete the registry entry + gates (per CLAUDE.md feature-flag lifecycle).
+
+### 3.2 Builtin (pre-installed) roles & agents are protected
+
+The roles and agents seeded from `DEFAULT_ROLES` / `DEFAULT_AGENTS` are **builtin** and **must never be deletable** — they are the fleet's safety net, the targets `routing.md` ships with, and what Settings reset restores. The invariant:
+
+- **Builtin-ness is derived, not user-settable.** A role/agent is builtin iff its key exists in `DEFAULT_ROLES` / `DEFAULT_AGENTS`. The API surfaces this as a read-only `builtin: true` marker; a client cannot clear it by writing `builtin: false` (the write paths ignore the field on input and recompute it from the defaults).
+- **Editable, not deletable.** Builtin roles/agents *can* be edited (a role's charter/label/runtime defaults; an agent's expertise/runtime; and — for agents — the display name via rename). They simply **cannot be deleted**. Every delete endpoint (`POST /api/roles/delete`, `POST /api/agents/delete`) hard-refuses a builtin target with a clear error, independent of the reassignment flow.
+- **Reset restores them.** `POST /api/settings/reset` re-seeds the full builtin set even if a user edited them, so a fleet can always recover a known-good roster (mirrors today's `shared.DEFAULT_AGENTS` reset — `dashboard.js:10808-10815`).
+- **No id reuse to dodge the guard.** Because ids are immutable (§2.8), a user cannot "delete then recreate" a builtin id; the delete is simply refused.
+
+Only **user-created** roles/agents (keys absent from the defaults) are deletable, subject to the in-use guards in §7.
+
+### 3.3 Two dimensions of an agent: identity + expertise (per-agent) vs. charter (role)
+
+An agent's "definition" is **not one blob** — it splits along a **durable vs. variable** seam (§3), surfaced as two dimensions that resolve and render independently. Separating them is what lets the charter be name-agnostic (§4.3c) while each agent stays distinct and knows exactly who it is.
+
+1. **Per-agent — short-form, structured, variable.** The machine-readable card the agent *is aware of*: `name`, `emoji`, role `label`, **`expertise`**, and `id`. The `name`/`emoji`/`expertise` are the agent's own (the **variable** layer — two agents of the same role differ here); `label` is pulled from the role. This is the **single home of the agent's name** and what a rename edits (§5.4). `expertise` is the per-instance specialization.
+2. **Role — long-form, prose, durable.** The resolved markdown **charter** (`roles[agent.role].charter` ?? legacy `charter.md`). Name-agnostic, second person, refers to peers by role (§4.3c) — the **durable** "what it means to be an X," shared unchanged across every agent of that role.
 
-This preserves every existing resolver's external behavior when `roles` is absent or when `agent.role` is still a free-text string (legacy), and layers the library in additively.
+The system prompt renders the per-agent short-form first, then the role's durable charter — so the agent reads its own name/expertise up top and the shared persona below:
 
-## 4. Phase 1 — Expose & edit (no new roles/agents)
+```
+# You are {name} ({label})        ← PER-AGENT short-form. The name lives ONLY here.
+- Agent ID: {id}
+- Emoji: {emoji}
+- Role: {label}                   ← from the role (durable)
+- Expertise: {agent.expertise}    ← VARIABLE, per-agent specialization
+  (optionally also emitted as a compact JSON identity card the agent can parse —
+   so it can reason about itself structurally, not just read prose)
+
+## Your Charter                   ← ROLE charter (durable, long-form), name-agnostic
+{resolved role charter}
+```
+
+Why this matters:
+
+- **The agent always knows its own name** — via the per-agent short-form — even though the charter prose never names it. "Name-agnostic charter" (§4.3c) does **not** mean "name-blind agent"; the name simply moves to the structured short form.
+- **Rename touches only the per-agent identity** (`name`/`emoji`); neither expertise nor the role charter is affected (§5.4).
+- **Two agents of one role share the durable charter but differ in the variable expertise.** Dallas and Ralph both resolve the Engineer charter, yet Dallas carries `typescript/docker` and Ralph `bug-fixes/scaffolding` — the payoff of the durable/variable split (§3).
+
+This formalizes what `buildSystemPrompt` already does loosely today (the `# You are {name}` / `Agent ID` / `Expertise` lines are a proto short-form; `engine/playbook.js:947-955`); the spec elevates it to named dimensions. Whether the short-form is rendered as prose lines or an explicit JSON card is an open question (§9).
+
+## 4. Phase 0 — Prerequisite migrations
+
+Foundational, mostly-invisible work that must land before the Library UI. Each item is additive and back-compatible. **Note:** the stable-id formalization (§4.1a) and name-agnostic charters (§4.3c) are **not** owned here — they ship in the [`agent-rename.md`](agent-rename.md) prerequisite and are summarized below for completeness. The two items this spec owns are the `agent-library` flag (§4.0a) and the `skills`→`expertise` field rename (§4.2b).
+
+### 4.0a Feature flag
+
+Register `agent-library` (§3.1). No behavior change yet — just the gate other phases reference.
+
+### 4.1a Formalize the stable opaque agent id — *delivered by the prerequisite*
+
+> **Owned by [`agent-rename.md`](agent-rename.md) §4.1.** Not re-specified here.
+
+The stable-id invariant (id = immutable key, name = display-only) and its guard + regression tests land in the rename prerequisite. The role model below assumes it: an agent can be reassigned to a different role or renamed without touching any id-keyed state (§2.8).
+
+### 4.2b Rename `skills` → `expertise`
+
+`agent.skills` is expertise, not skills (§2.3). Rename the field across the stack, with an **unconditional** back-compat reader:
 
-**User story:** "For each of the different roles, I want to see and edit the skill and agent definition."
+- **Read shim (always on):** everywhere that reads agent expertise resolves `agent.expertise ?? agent.skills`. Old configs with `skills` keep working untouched — no disk rewrite forced. (Expertise is the per-agent **variable** layer, §3.3 — it lives on the agent, not the role.)
+- **Writers / defaults:** `DEFAULT_AGENTS` use `expertise`. The Settings write path persists `expertise`; if it sees a legacy `skills` key it may migrate it in-memory (mirroring `applyLegacyCcModelMigration`'s no-rewrite pattern).
+- **Update the two readers** named in §2.3: the `Expertise:` line (`engine/playbook.js:950`) and `pickReReviewAgentHints` (`engine/lifecycle.js:4613-4624`) — both read the resolved expertise, so the soft reviewer-preference heuristic keeps matching `code-review`/`design-review`.
+- **Dashboard:** the Agents table column header and its read/write (`dashboard/js/settings.js:73`, `dashboard.js:10685`) move to `expertise`, accepting `skills` on read for compatibility.
+- **Deprecation:** add a `docs/deprecated.json` entry for the `skills` alias with a cleanup path.
 
-### 4.1 Scope
+This rename is independent of the role model and can ship first; it is pure renaming + a back-compat alias, so it is safe even with the feature flag OFF (the alias is unconditional).
 
-- A **Role / Agent Library** view in the dashboard listing the existing roles and the agents bound to each.
-- For each role: edit its **definition** (markdown persona) and **skills** list.
-- For each agent: edit its definition override + skills + runtime (consolidating the Settings table fields and the Charter tab into one place).
+### 4.3c Name-agnostic charters — *delivered by the prerequisite*
+
+> **Owned by [`agent-rename.md`](agent-rename.md) §4.2.** Not re-specified here.
+
+The rename prerequisite sanitizes the shipped `agents/<id>/charter.md` files to be name-agnostic (second person; peers referred to by role, not name) and adds the content/render tests. This Library reuses that work two ways: (1) it seeds `DEFAULT_ROLES[].charter` from the sanitized text (§5.2), and (2) a role-level charter shared across agents *must* be name-agnostic — which the prerequisite guarantees. The agent still knows its name via the per-agent short-form (§3.3) — name-agnostic ≠ name-blind.
+
+## 5. Phase 1 — Expose & edit (no new roles/agents)
+
+**User story:** "For each of the different roles, I want to see and edit the durable charter and per-agent expertise — and rename agents."
+
+All UI/API in this phase is gated by `agent-library` (§3.1). The **rename** capability itself comes from the [`agent-rename.md`](agent-rename.md) prerequisite; Phase 1 surfaces it inline in the Library.
+
+### 5.1 Scope
+
+- A **Role / Agent Library** view listing existing roles and the agents bound to each.
+- For each role: edit its **charter** (durable markdown persona) and label.
+- For each agent: edit its **expertise** (variable specialization) + runtime, reassign its **role**, and **rename** its display name + emoji (id stays fixed) — consolidating the Settings table fields and the Charter tab into one place.
 - **No** create/delete of roles or agents in Phase 1.
 
-### 4.2 Data model (Phase 1)
+### 5.2 Data model (Phase 1)
 
-- Add `DEFAULT_ROLES` to `engine/shared.js`, derived from the distinct `role` strings in `DEFAULT_AGENTS` (`Lead / Explorer`, `Engineer`, `Analyst`, `Architect`). Seed each role's `definition` from the corresponding agent's existing `charter.md` content where a 1:1 mapping exists; otherwise leave a stub.
-- Migrate `agent.role` free-text → role key on first load (in-memory, mirroring `applyLegacyCcModelMigration`'s no-disk-rewrite pattern in shared.js) by slugifying the label and matching against `roles{}`. Unmatched strings remain as legacy free text and are rendered as an ad-hoc role.
-- Introduce the resolution rules in §3 behind the existing resolver helpers so engine behavior is unchanged when `roles` is absent.
+- Add `DEFAULT_ROLES` to `engine/shared.js`, one per distinct `role` label in `DEFAULT_AGENTS` (`Lead / Explorer`, `Engineer`, `Analyst`, `Architect`). Author each role's **durable `charter`** name-agnostic (§4.3c), seeded from the sanitized union of the corresponding agents' existing `charter.md` files. Each agent's current per-agent skills become its **`expertise`** (the variable layer), so two Engineers keep distinct specializations while sharing one role charter. (Where two agents of the same label have materially different *personas* today, split them into two roles instead — but the default four collapse cleanly.)
+- Migrate `agent.role` free-text → role key on first load (in-memory, mirroring `applyLegacyCcModelMigration`'s no-disk-rewrite pattern) by slugifying the label and matching against `roles{}`. Unmatched strings remain legacy free text rendered as an ad-hoc role.
+- Resolution rules (§3) sit behind the existing resolver helpers and the feature flag so engine behavior is unchanged when `roles` is absent or the flag is OFF.
 
-### 4.3 Skills: decide the binding (REQUIRED for this phase)
+### 5.3 Expertise display
 
-Phase 1 must resolve the "two meanings of skill" ambiguity. Proposed: keep `roles[].skills` / `agent.skills` as **skill references** (tags), and in the system prompt render them as the `Expertise:` line **plus** — when a tag matches a discovered `SKILL.md` name from `getSkills()` — surface that skill's description inline. This makes the skills list meaningful without forcing a disk-layout change in P1. (Full per-role skill *scoping* of `collectSkillFiles` is deferred to a later phase; see §7.)
+With §4.2b done, `agent.expertise` renders as the `Expertise:` line and feeds the re-review hint. **Optional P1 enhancement:** when an expertise tag matches a discovered `SKILL.md` name from `getSkills()`, surface that skill's description inline — making the list informative without binding skills to agents. Full per-role skill *scoping* of `collectSkillFiles` stays out of scope (§8).
 
-### 4.4 API (Phase 1)
+### 5.4 Agent rename — *delivered by the prerequisite; surfaced in the Library*
 
-- `GET /api/roles` → `{ roles: { <key>: { label, definition, skills, defaultCli, defaultModel, builtin, agentIds[] } } }`. Aggregates `config.roles` + reverse-maps `config.agents` by role.
-- `POST /api/roles/update` → `{ key, definition?, skills?, defaultCli?, defaultModel? }`. Edits an existing role only (P1). Writes through `mutateJsonFileLocked` on `config.json` (never `safeWrite` — see CLAUDE.md concurrency rules).
-- Extend `POST /api/settings` agent loop to accept `definitionOverride`.
-- Reuse/retire `POST /api/agents/charter`: in P1 it continues to write `agents/<id>/charter.md` for backward-compat, but the library writes `definitionOverride` into config; the resolver prefers the override. (Deprecation tracked in `docs/deprecated.json`.)
+> **Full contract in [`agent-rename.md`](agent-rename.md) §4.3.** Not re-specified here.
 
-### 4.5 UI (Phase 1)
+The agent **rename** capability (`POST /api/agents/rename` → `{ id, name, emoji? }`: validation, idempotency, duplicate-name soft-warning, in-flight safety, cache invalidation, stale-reference behavior, audit log) is owned by the prerequisite and may already be enabled (behind its own `agent-rename` flag) before this Library ships. Phase 1 does **not** redefine it — it simply **surfaces the existing endpoint inline** in the Library (§5.6) so renaming sits next to role/expertise editing. Recap of what callers rely on: rename changes only the display `name`/`emoji`; every id-keyed state (charter/memory/metrics/dispatch/PR/routing/inbox) is untouched (§2.8); a running dispatch is never killed.
 
-- New **Library** entry on the Settings rail (or a top-level sidebar page — decide in review). Layout: left column = role list; right pane = selected role's definition editor (markdown textarea with preview, reusing the Charter tab's editor pattern from `detail-panel.js`) + skills chips + the agents bound to that role (each expandable to its per-agent overrides).
-- Definition editor reuses the existing markdown view/edit toggle and `renderMd()` escaping already used by the Charter tab (`dashboard/js/detail-panel.js:115-126`) to satisfy the no-unsanitized lint gate (`npm run lint`).
-- Settings → Agents table gains a link/affordance into the Library for the definition (so the two surfaces don't drift).
+### 5.5 API (Phase 1)
 
-### 4.6 Phase 1 acceptance criteria
+- `GET /api/roles` → `{ roles: { <key>: { label, charter, defaultCli, defaultModel, builtin, agentIds[] } } }`. Aggregates `config.roles` + reverse-maps `config.agents` by role. Flag-gated.
+- `POST /api/roles/update` → `{ key, label?, charter?, defaultCli?, defaultModel? }`. Edits an existing role's **durable charter** + label + runtime defaults only (P1). Writes through `mutateJsonFileLocked` on `config.json` (never `safeWrite` — CLAUDE.md concurrency rules).
+- `POST /api/agents/rename` → `{ id, name, emoji? }` — **owned by the [`agent-rename.md`](agent-rename.md) prerequisite** (§5.4); the Library calls it, it is not re-specified here.
+- Extend `POST /api/settings` agent loop to accept the agent's **`expertise`** (variable layer) and **`role`** reassignment.
+- `POST /api/agents/charter` is **superseded** by role charters: it still writes `agents/<id>/charter.md` (read only as the legacy fallback, §6), but the Library edits the role's `charter` instead. (Deprecation tracked in `docs/deprecated.json`.)
 
-1. Library view lists every existing role with its definition + skills, and the agents under each.
-2. Editing a role's definition changes the system prompt for every agent bound to that role (verified by `buildSystemPrompt` output).
-3. Editing an agent's definition override wins over the role definition for that agent only.
-4. Engine behavior is **unchanged** when `config.roles` is absent (back-compat).
-5. All writes go through `mutateJsonFileLocked`; no `safeWrite` on `config.json`.
-6. `npm test` green (add source-inspection + resolver unit tests near existing agent/charter tests); `npm run lint` green.
-7. Settings reset still restores a working fleet (now `DEFAULT_ROLES` + `DEFAULT_AGENTS`).
+### 5.6 UI (Phase 1)
 
-## 5. Migration & backward compatibility
+- New **Library** entry on the Settings rail (or a top-level sidebar page — decide in review), shown only when `agent-library` is ON. Layout: left column = role list; right pane = selected role's **charter** editor (markdown textarea + preview, reusing the Charter tab editor pattern from `detail-panel.js`) + the agents bound to that role (each expandable to its per-agent **expertise** chips, role reassignment, runtime, and an inline **rename** field for the display name + emoji).
+- The inline rename field reuses the prerequisite's `POST /api/agents/rename` endpoint with the same inline validation + soft duplicate-name warning (agent-rename.md §4.3); on save it optimistically updates the team/detail display.
+- Charter editors reuse the existing markdown view/edit toggle and `renderMd()` / `escHtml()` escaping already used by the Charter tab (`dashboard/js/detail-panel.js:115-126`) to satisfy the no-unsanitized lint gate (`npm run lint`).
+- Settings → Agents table gains a link/affordance into the Library (so the two surfaces don't drift).
 
-- **Additive config.** `roles` is new and optional. Absent `roles` ⇒ legacy path (free-text role label, per-agent `charter.md`). No forced disk rewrite — migration is in-memory at load, matching `applyLegacyCcModelMigration`.
-- **Charters preserved.** `agents/<id>/charter.md` remains readable and is the lowest-priority definition source. `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that.
-- **Routing unaffected in P1/P2-by-agent.** Routing still targets agent ids. (Routing-by-role is explicitly out of scope; see §7.)
-- **Deprecation.** If `POST /api/agents/charter` is superseded by the library's `definitionOverride`, add a `docs/deprecated.json` entry with a cleanup path.
+### 5.7 Phase 1 acceptance criteria
 
-## 6. Phase 2 — Create & assign
+1. With the flag ON, the Library lists every role with its charter, and the agents (with their per-agent expertise) under each.
+2. Editing a role's charter changes the system prompt for **every** agent bound to that role (verified by `buildSystemPrompt` output) — the durable layer is shared.
+3. Two agents of the same role render the **same** charter but their **own** expertise; editing one agent's expertise does not affect the other (the variable layer is per-agent).
+4. The Library surfaces the prerequisite's rename inline and a rename performed from it behaves per [`agent-rename.md`](agent-rename.md) §6 (display-only change; id-keyed state untouched; in-flight-safe).
+5. With the `agent-library` flag OFF and no `roles`, engine + dashboard behavior is byte-for-byte identical to today.
+6. All writes go through `mutateJsonFileLocked`; no `safeWrite` on `config.json`.
+7. `npm test` green (resolver + durable/variable split tests near existing agent/charter tests); `npm run lint` green.
+8. Settings reset still restores a working fleet (now `DEFAULT_ROLES` + `DEFAULT_AGENTS`).
+
+## 6. Migration & backward compatibility
+
+- **Feature-flagged & dark by default.** New surfaces are OFF until `agent-library` is enabled (§3.1). Back-compat readers are unconditional so toggling the flag off after edits never breaks a fleet.
+- **Additive config.** `roles` (with `charter`) and agent `expertise` are new and optional. Absent ⇒ legacy path (free-text role, `skills`, per-agent `charter.md`). No forced disk rewrite — migration is in-memory at load, matching `applyLegacyCcModelMigration`.
+- **`skills` alias preserved.** Reads resolve `agent.expertise ?? agent.skills`; legacy configs are untouched (§4.2b).
+- **Charters preserved.** `agents/<id>/charter.md` remains readable as the **lowest-priority** charter source (used only when an agent's role has no charter). `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that.
+- **Name decoupling via the prerequisite.** Name-agnostic charters and the stable-id invariant ship in [`agent-rename.md`](agent-rename.md) (§4.1a, §4.3c). This Library assumes them: role charters are shared name-agnostic prose, and agents are reassigned/renamed without re-keying any state. Legacy user charters with names render verbatim (non-breaking).
+- **Routing unaffected.** Routing still targets agent ids. (Routing-by-role is out of scope; see §8.)
+- **Deprecation.** `skills`→`expertise` alias and any superseded `/api/agents/charter` usage get `docs/deprecated.json` entries with cleanup paths.
+
+## 7. Phase 2 — Create & assign
 
 **User story:** "Add new roles, and assign new named agents with these roles."
 
-### 6.1 Scope
+Flag-gated like Phase 1.
+
+### 7.1 Scope
 
-- **Role CRUD:** create/rename/delete roles in the library. Deleting a role is blocked while agents reference it (or offers reassignment). `builtin` roles are delete-protected.
-- **Agent CRUD:** create a new named agent (id + name + emoji + role + optional overrides) and delete a non-builtin agent.
+- **Role CRUD:** create/rename/delete **user-created** roles. Builtin roles (seeded from `DEFAULT_ROLES`) are editable but **never deletable** (§3.2). Deleting a user-created role is additionally blocked while agents reference it (or offers reassignment).
+- **Agent CRUD:** create a new named agent (id + name + emoji + role + optional overrides) and delete a **user-created** agent. Builtin agents (seeded from `DEFAULT_AGENTS`) are **never deletable** (§3.2).
 - New agents become immediately routable (they appear to `resolveAgent` via `config.agents`) and selectable in `routing.md` (manual) — auto-wiring into routing is out of scope.
 
-### 6.2 Data model / engine
+### 7.2 Data model / engine
 
-- New agent ids validated: lowercase slug, unique, not colliding with `temp-*` reserved prefix.
-- `resolveAgent` already iterates `config.agents` generically, so new agents are picked up with no engine change (`engine/routing.js:192-249`). Deleting an agent must also: cancel/skip pending dispatches targeting it, and leave its history intact (mirror the conservative posture of project removal in `engine/projects.js`).
-- A new agent with no `charter.md` and no `definitionOverride` inherits its role's definition — this is the payoff of §3.
+- New agent ids validated: lowercase slug, unique, not colliding with `temp-*` reserved prefix, and **immutable thereafter** (§2.8).
+- `resolveAgent` already iterates `config.agents` generically, so new agents are picked up with no engine change (`engine/routing.js:192-249`). Deleting an agent must also cancel/skip pending dispatches targeting it and leave its history intact (mirror the conservative posture of project removal in `engine/projects.js`).
+- A new agent with no `charter.md` inherits its role's **durable charter** automatically — the payoff of §3 — and carries its own **variable expertise**.
 
-### 6.3 API (Phase 2)
+### 7.3 API (Phase 2)
 
-- `POST /api/roles/create` `{ key, label, definition, skills, defaultCli?, defaultModel? }`.
-- `POST /api/roles/delete` `{ key, reassignTo? }` — refuses if agents reference it and no `reassignTo` given; refuses on `builtin`.
-- `POST /api/agents/create` `{ id, name, emoji, role, overrides? }`.
-- `POST /api/agents/delete` `{ id }` — refuses on builtin; drains/cancels pending dispatches first.
-- Extend `POST /api/settings/reset` semantics: reset clears user-created roles/agents back to `DEFAULT_ROLES`/`DEFAULT_AGENTS`.
+- `POST /api/roles/create` `{ key, label, charter, defaultCli?, defaultModel? }` — the durable definition; no expertise (expertise is per-agent).
+- `POST /api/roles/delete` `{ key, reassignTo? }` — **hard-refuses builtin roles** (§3.2); for user-created roles, refuses if agents reference it and no `reassignTo` is given.
+- `POST /api/agents/create` `{ id, name, emoji, role, expertise?, overrides? }`.
+- `POST /api/agents/delete` `{ id }` — **hard-refuses builtin agents** (§3.2); for user-created agents, drains/cancels pending dispatches first.
+- Extend `POST /api/settings/reset` so reset removes user-created roles/agents and re-seeds the full builtin set (`DEFAULT_ROLES`/`DEFAULT_AGENTS`).
 
-### 6.4 UI (Phase 2)
+### 7.4 UI (Phase 2)
 
-- "+ New role" and "+ New agent" affordances in the Library.
-- Agent creation form (id/name/emoji/role picker + optional runtime overrides).
+- "+ New role" (label + charter editor) and "+ New agent" affordances in the Library.
+- Agent creation form (id/name/emoji/role picker + expertise + optional runtime overrides).
 - Delete with confirmation + reassignment flow for roles in use.
 
-### 6.5 Phase 2 acceptance criteria
+### 7.5 Phase 2 acceptance criteria
 
-1. A user can create a role with a definition + skills and see it in the library.
-2. A user can create a named agent bound to a role; with no override it inherits the role definition; the engine can route work to it.
-3. Deleting a role in use is blocked or forces reassignment; builtin roles/agents cannot be deleted.
+1. A user can create a role with a durable charter and see it in the library.
+2. A user can create a named agent bound to a role; it inherits the role's charter and carries its own expertise; the engine can route work to it.
+3. **Builtin roles and agents (seeded from the defaults) cannot be deleted** — every delete endpoint hard-refuses them, and the `builtin` marker cannot be cleared by a client write (§3.2). Deleting a *user-created* role in use is blocked or forces reassignment.
 4. Deleting an agent cancels its pending dispatches and preserves completed history.
 5. Settings reset returns to the default fleet.
-6. `npm test` + `npm run lint` green; new CRUD covered by unit tests; concurrency via `mutateJsonFileLocked`.
+6. `npm test` + `npm run lint` green; CRUD covered by unit tests; concurrency via `mutateJsonFileLocked`.
 
-## 7. Out of scope (explicitly deferred)
+## 8. Out of scope (explicitly deferred)
 
-- **Routing-by-role** (e.g. `routing.md` rows targeting a role instead of an agent id). Routing stays agent-id-based.
-- **Per-role/per-agent skill *scoping*** of on-disk `SKILL.md` discovery (`collectSkillFiles` stays global/project/plugin). P1 only makes the skills *list* meaningful in the prompt (§4.3).
+- **Agent rename, stable-id, and name-agnostic charters** — owned by the [`agent-rename.md`](agent-rename.md) prerequisite, not this spec (re-keying an id remains out of scope there too).
+- **Routing-by-role** (`routing.md` rows targeting a role instead of an agent id). Routing stays agent-id-based.
+- **Binding real `SKILL.md` files to roles/agents** — `collectSkillFiles` stays global/project/plugin. The freed-up "skills" term is reserved for this future work; P1 only makes the *expertise* list informative (§5.3).
 - **Per-project role overrides** (`projects/<name>/...`).
 - **Importing/sharing role libraries** across installs.
-- Any change to the meeting/plan agent-charter linkage beyond reading the new definition source.
+- Any change to the meeting/plan agent-charter linkage beyond reading the new role-charter source.
 
-## 8. Open questions (resolve in review)
+## 9. Open questions (resolve in review)
 
 1. **Library placement** — Settings rail entry vs. a dedicated top-level sidebar page?
-2. **Role↔agent cardinality framing** — do we surface roles as the primary list (agents nested under them), or keep agents primary with role as an attribute? (Spec assumes roles-primary in the Library; agents-primary stays in Settings.)
-3. **Charter vs definition naming** — adopt "definition" everywhere, or keep "charter" as the user-facing term to avoid churn in existing UI/tests?
-4. **Skills binding (§4.3)** — ship the "tag matches discovered SKILL.md → inline description" behavior in P1, or keep skills purely as the `Expertise:` line until a later phase?
-5. **Default role definitions** — seed from existing per-agent `charter.md`, or author fresh role-level definitions?
-
-## 9. Work breakdown (suggested PRD seeds)
-
-**Phase 1**
-- P1-a: `DEFAULT_ROLES` + in-memory legacy role migration + resolver tiering (engine/shared.js, playbook.js).
-- P1-b: `GET /api/roles`, `POST /api/roles/update`, `definitionOverride` on `POST /api/settings` (dashboard.js).
-- P1-c: Library UI (role list + definition editor + skills + nested agents) reusing the charter editor pattern.
-- P1-d: Tests (resolver unit tests, source-inspection for endpoints/UI) + `docs/deprecated.json` entry if `/api/agents/charter` is superseded + settings parity note in CLAUDE.md.
-
-**Phase 2**
-- P2-a: Role CRUD API + delete-guard/reassignment.
-- P2-b: Agent CRUD API + dispatch-drain on delete + id validation.
-- P2-c: Library create/delete UI flows.
-- P2-d: Tests + reset semantics + docs.
+2. **Role↔agent cardinality framing** — surface roles as the primary list (agents nested), or keep agents primary with role as an attribute? (Spec assumes roles-primary in the Library; agents-primary stays in Settings.)
+3. **"Charter" terminology** — the spec uses **`charter`** as the durable role-level field name (matching today's `charter.md` and the existing Charter tab). Confirm we keep "charter" user-facing everywhere rather than introducing "definition" as a competing term. *(Tentatively resolved: yes, `charter` on the role; "definition" used only as the generic English word.)*
+4. **Expertise→skill enrichment (§5.3)** — ship the "tag matches discovered SKILL.md → inline description" behavior in P1, or keep expertise purely as the `Expertise:` line until later?
+5. **Default role charters** — author fresh name-agnostic role charters, or mechanically sanitize + merge the existing per-agent `charter.md` files? And how to handle two builtin agents sharing a label but differing in persona today (split into two roles vs. unify)?
+6. **`skills`→`expertise` rollout** — ship the §4.2b rename as its own standalone PR (pure rename + alias, flag-independent) ahead of the Library, to de-risk the bigger change?
+7. **Identity rendering (§3.3)** — render the per-agent short-form as the existing prose lines (`# You are …` / `Agent ID` / `Expertise`), or also emit a compact machine-readable JSON identity card the agent can parse to reason about itself? (Prose is the lowest-risk default; JSON is additive.)
+
+## 10. Work breakdown (suggested PRD seeds)
+
+**Prerequisite (separate spec) — [`agent-rename.md`](agent-rename.md)**
+- Stable-id formalization, name-agnostic charters, and the `POST /api/agents/rename` capability ship there (its `AR-a…AR-f` breakdown). This Library's Phase 1 depends on it.
+
+**Phase 0 — prerequisites (owned here)**
+- P0-a: Register `agent-library` feature flag (`engine/features.js`) + Settings toggle.
+- P0-b: Rename `skills`→`expertise` with unconditional back-compat alias; update `playbook.js:950`, `lifecycle.js:4613-4624`, `dashboard.js`/`settings.js`, `DEFAULT_AGENTS`; `docs/deprecated.json` entry.
+
+**Phase 1 — expose & edit**
+- P1-a: `DEFAULT_ROLES` (durable charter per role) + per-agent `expertise` (variable) + in-memory legacy role migration + role-tier resolver (engine/shared.js, playbook.js), flag-gated. Seeds role charters from the prerequisite's sanitized `agents/<id>/charter.md`.
+- P1-b: `GET /api/roles`, `POST /api/roles/update` (charter/label/runtime), agent `expertise`/`role` on `POST /api/settings` (dashboard.js). (Rename endpoint comes from the prerequisite.)
+- P1-c: Library UI (role list + role-charter editor + nested agents with per-agent expertise chips + role reassignment + inline rename surfacing the prerequisite's endpoint) reusing the charter editor pattern, flag-gated.
+- P1-d: Tests (resolver, durable/variable split, source-inspection) + `docs/deprecated.json` updates + settings-parity note in CLAUDE.md.
+
+**Phase 2 — create & assign**
+- P2-a: Role CRUD API + **builtin delete-protection (§3.2)** + user-role delete-guard/reassignment.
+- P2-b: Agent CRUD API + **builtin delete-protection (§3.2)** + dispatch-drain on delete + id validation.
+- P2-c: Library create/delete UI flows (delete affordance hidden/disabled for builtin).
+- P2-d: Tests (incl. builtin-undeletable assertions + `builtin: false` write-ignore) + reset semantics + docs.
 
 ---
 
-_Every new `engine.*`/config surface introduced here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (see CLAUDE.md "Best Practices" #15)._
+_Every new `engine.*`/config surface introduced here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (see CLAUDE.md "Best Practices" #15). New feature flags follow the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gates on graduation._

package/docs/specs/agent-rename.md

@@ -0,0 +1,163 @@
+# Spec: Agent Rename & Name Decoupling
+
+**Status:** Draft
+**Owner:** @calebt
+**Audience:** Minions contributors working on the engine config surface, playbook/system-prompt rendering, and the dashboard agents UI.
+**Prerequisite for:** [`agent-configurability.md`](agent-configurability.md) — the Role / Agent Library builds on the decoupling delivered here.
+
+> Companion reading: [`.github/copilot-instructions.md`](../../.github/copilot-instructions.md) and [`CLAUDE.md`](../../CLAUDE.md) for the engine/dashboard split and config conventions.
+
+## 1. Motivation
+
+You cannot rename an agent today. Worse, an agent's display name is quietly **load-bearing**: it's baked into the shipped `charter.md` prose, and the engine matches some referenced artifacts by agent *name*. Before the fleet can become user-configurable (reusable roles, new named agents — see [`agent-configurability.md`](agent-configurability.md)), names must stop being structurally significant.
+
+This spec delivers exactly that decoupling, in three parts:
+
+1. **Identity decoupling** — formalize the agent's **id** as a stable opaque key, distinct from its display name, so renaming touches a single field and zero state.
+2. **Content decoupling** — make charters **name-agnostic**, so the persona never restates a proper name (which a rename would invalidate).
+3. **The rename capability** — a `POST /api/agents/rename` endpoint + UI that changes the display name (and emoji) safely.
+
+Shipping this first de-risks the larger Role / Agent Library: once names aren't load-bearing, roles can be reused across agents and agents can be renamed/created without name collisions mattering.
+
+## 2. Current state (grounding)
+
+Citations are `file:line` against the repo at spec-authoring time.
+
+### 2.1 Agents are already id-keyed
+
+Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:681-687`).
+
+```js
+// engine/shared.js:4398-4404
+const DEFAULT_AGENTS = {
+  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', skills: [...] },
+  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        skills: [...] },
+  // …
+};
+```
+
+Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/routing.js:160-189`). So `name !== lowercase(id)` is already safe — the foundation that makes **rename = change `name`, keep `id`** trivial.
+
+### 2.2 Every agent-scoped state is keyed by id
+
+| State | Keyed by id at |
+|-------|----------------|
+| Charter file | `agents/<id>/charter.md` (`engine/queries.js:677-679`) |
+| Per-agent memory | `knowledge/agents/<id>.md`; inbox routes by `agent:` frontmatter → filename prefix (`engine/consolidation.js:106-129,159-182`) |
+| Metrics / spend / error rate | `metrics[id]`, `perAgent[id]` (`engine/routing.js:66-92`) |
+| Dispatch records | `dispatch.active[].agent` (`engine/queries.js:587-605`) |
+| PR records | `pr.agent` (`engine/queries.js:431-446`) |
+| Inbox files | `notes/inbox/<id>-…` filename prefix (`engine/queries.js:700-713`) |
+| Routing | preferred/fallback agent ids (`routing.md`, `engine/routing.js:31-52`) |
+
+The **only** consumers of the display `name` are `buildSystemPrompt`'s `# You are {name}` line (`engine/playbook.js:947-950`) and dashboard display text. So renaming the display name is safe and needs no state migration **as long as the id key is never mutated**. Changing the id key would orphan every row above — the id must be immutable.
+
+### 2.3 Names are load-bearing in two places (the part that must change)
+
+1. **Charters hardcode names.** The shipped charters bake the agent's own name and peers' names into the prose — e.g. `agents/ripley/charter.md` opens `# Ripley — Lead / Explorer`, `**Name:** Ripley`, and says "Handing off structured findings to **Dallas** (Engineer) and **Lambert** (Analyst)". A rename would strew the old name through the prompt.
+2. **Playbook context-resolution matches by name.** `engine/playbook.js:163-240` matches referenced plans/notes by **both** agent `id` **and** `name` (e.g. "Ripley's plan"). After a rename, artifacts that referenced the old *name* stop auto-linking (id-based matches still resolve).
+
+These are the two reasons "names are load-bearing" — §4.2 and §4.3 neutralize them.
+
+## 3. Feature flag
+
+- Register `agent-rename` in the `FEATURES` registry (`engine/features.js`) as `{ description, default: false, addedIn, expires }`.
+- **Engine/dashboard** gate the rename **endpoint + UI** with `features.isFeatureOn('agent-rename', config)` / `MinionsFeatures.isOn('agent-rename')`.
+- Toggle via Settings → Experimental flags, `config.features['agent-rename']: true`, or `MINIONS_FEATURE_AGENT_RENAME=1`. Resolution order: env → `config.features` → registry default (default OFF).
+- **What the flag gates:** the `POST /api/agents/rename` endpoint and the rename UI affordance.
+- **What the flag does NOT gate (always on — pure back-compat hygiene):** the stable-id guard/tests (§4.1, invisible) and the name-agnostic **default** charters (§4.2 — a behavior-equivalent content change to the shipped roster). These ship unconditionally so the foundation is in place whether or not rename is enabled; legacy user charters are never touched.
+
+When the feature graduates, delete the registry entry + gate (per CLAUDE.md feature-flag lifecycle).
+
+## 4. The work
+
+### 4.1 Formalize the stable opaque agent id
+
+Agents are **already** id-keyed (§2.1–2.2); this step makes the invariant explicit and rename-safe:
+
+- Document the invariant: the `config.agents` key is the agent's immutable id; the display name lives in `name`.
+- Add a guard so no write path mutates an id key. The rename path (§4.3) changes `name`/`emoji` only; there is deliberately **no** "change id" path. Re-keying would be a dedicated future migration (move `agents/<id>/`, `knowledge/agents/<id>.md`, metrics buckets, rewrite `routing.md`/dispatch/PR refs) — explicitly out of scope (§7).
+- Add unit tests asserting `name !== lowercase(id)` round-trips through `buildSystemPrompt`, `getAgents`, routing, charter/memory paths, and metrics without breakage (most already pass — they lock the invariant against regressions).
+
+### 4.2 Make charters name-agnostic
+
+A charter that hardcodes a proper name (§2.3) breaks the moment an agent is renamed (and later blocks a role-level charter being shared across agents — the configurability payoff). Make the charter body **name-agnostic** so the identity line is the single source of the name:
+
+- **Single source of name.** The agent's name appears *only* in the engine-injected `# You are {name} ({label})` block (`engine/playbook.js:947-950`). The charter prose must use the **second person** ("you", "your") and **never** restate its own proper name (no `# Ripley`, no `**Name:** Ripley`). The agent still knows its name — it reads it from the identity block — so **name-agnostic ≠ name-blind**.
+- **Refer to peers by role, not name.** "hand off to **Dallas** (Engineer)" becomes "hand off to the **Engineer** role" — roles are stable; names are mutable. This keeps a charter valid when *any* agent is renamed.
+- **Rewrite the shipped defaults.** Sanitize the repo's `agents/<id>/charter.md` files name-agnostic. (The configurability spec later seeds role charters from these — but the sanitization lands here, unconditionally.)
+- **Legacy user charters are not auto-rewritten.** A user-authored `charter.md` that still contains a name renders verbatim (back-compat, non-breaking) — it just reads stale after a rename. A **soft, dismissible warning** flags a name embedded in an editable charter, nudging toward second person / role references. No hard block, no silent rewrite of user content.
+- **Tests.** Content check that shipped default charters contain no agent proper names; render test that `buildSystemPrompt` after a rename contains the **new** name and **not** the old one anywhere in the prompt.
+
+### 4.3 The rename capability
+
+A rename changes the agent's **display identity** (`name`, and optionally `emoji`); the id key is never touched (§4.1).
+
+**`POST /api/agents/rename` → `{ id, name, emoji? }`** (flag-gated, §3)
+
+- **Validation:** `name` required, trimmed, non-empty, length-capped (e.g. ≤ 64), may contain Unicode/emoji; control chars rejected. `emoji` optional. Missing `id` → 4xx. Same-name is an idempotent no-op (still 2xx). Builtin agents are renamable (rename ≠ delete).
+- **Uniqueness:** names need **not** be unique (id is the only key), but a collision with another agent's current display name returns a **soft warning** in the response (operator-confusion risk), not a hard block; the UI surfaces it and lets the user proceed.
+- **Concurrency & audit:** writes through `mutateJsonFileLocked` on `config.json` (never `safeWrite`); logs `old → new`.
+
+**What updates (display only, picked up live)**
+- The system-prompt identity line `# You are {name} ({label})` on the **next** dispatch (`engine/playbook.js:947-950`).
+- Dashboard display: team cards, agent detail panel, history attribution, Command Center state preamble — all read `name` live on next render.
+- The rename invalidates the system-prompt / status / CC-preamble caches so the new name surfaces promptly.
+
+**What does NOT change (id-keyed, untouched — §2.2)**
+- Charter/memory paths, metrics/spend/error-rate buckets, dispatch records, PR `agent` refs, inbox prefixes, routing.
+- **Author matching is id-based:** `_author_` routing resolves to the author *agent id* and `pr.agent` groups by id (`engine/queries.js:431-446`), so rename never breaks self-review bans or PR-author follow-ups.
+
+**In-flight dispatches**
+- A currently-running agent finishes under the system prompt it was **already spawned with** — rename does **not** kill or re-spawn it. The new name applies to the **next** dispatch. Live-output, completion reports, and history are id-keyed, so they attribute correctly throughout.
+
+**Stale name references in historical free-text (known, accepted, non-breaking)**
+- Rename does **not** cascade into pre-existing free-text: `notes.md`, `pinned.md`, the knowledge base, per-agent memory, and plan/PRD prose keep the old name (non-breaking — just stale).
+- Concrete engine consequence (§2.3): playbook context-resolution matches referenced plans/notes by both `id` and `name` (`engine/playbook.js:163-240`); after a rename, old-name artifacts stop auto-linking to the agent (id matches still resolve). §4.2's guidance minimizes future name-baking.
+- A **soft, non-blocking** "old name still appears in N place(s)" hint may follow a rename; it **never** auto-rewrites user/historical content.
+
+**UI**
+- The rename affordance lands in the existing surfaces so it's usable before the Library exists: the **Settings → Agents table** first column (Agent) and/or the **agent detail panel** (next to the Charter tab editor it already hosts — `dashboard/js/detail-panel.js:115-126`).
+- Inline validation (non-empty, length) + the soft duplicate-name warning before submit; on save it calls `POST /api/agents/rename` and optimistically updates the team/detail display. Reuse `escHtml()` to satisfy the no-unsanitized lint gate (`npm run lint`).
+
+## 5. Migration & backward compatibility
+
+- **Feature-flagged rename, unconditional foundation.** The rename endpoint + UI are OFF until `agent-rename` is enabled (§3). The stable-id guard (§4.1) and name-agnostic **default** charters (§4.2) ship unconditionally as back-compat hygiene.
+- **Stable id.** The id key is immutable; rename touches `name`/`emoji` only. No agent state is re-keyed.
+- **Charters preserved.** `agents/<id>/charter.md` remains the charter source. `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that. Legacy user charters with names render verbatim and only earn a soft warning.
+- **Routing unaffected.** Routing targets agent ids; rename is invisible to it.
+- **No `name` writer today is broken.** `POST /api/settings` does not edit `name` (`dashboard.js:10672-10758`); the new rename endpoint is the sole `name` writer.
+
+## 6. Acceptance criteria
+
+1. `POST /api/agents/rename` changes only `name` (and optional `emoji`); id key, charter/memory paths, metrics, dispatch/PR refs, routing, and inbox prefixes are untouched (verified by §4.1 tests).
+2. After a rename, the rendered system prompt contains the **new** name and the **old** name appears **nowhere** — because the default charters are name-agnostic and the name comes only from the injected identity line.
+3. Validation holds: empty/whitespace rejected; over-length rejected; same-name no-op; duplicate display name → soft warning but allowed; missing id → 4xx; builtin agents renamable.
+4. Renaming an agent with a live dispatch does **not** kill/re-spawn it; the running agent finishes under its already-built prompt and the new name applies next dispatch.
+5. With `agent-rename` OFF, the endpoint/UI are absent and behavior is identical to today; the name-agnostic default charters and stable-id guard are present regardless.
+6. All writes go through `mutateJsonFileLocked`; no `safeWrite` on `config.json`.
+7. `npm test` green (stable-id invariant, rename validation + in-flight, name-agnostic content/render tests near existing agent/charter tests); `npm run lint` green.
+
+## 7. Out of scope
+
+- **Re-keying an agent id.** Rename changes `name`/`emoji` only; there is no change-id path (§4.1).
+- **The Role / Agent Library** itself (roles, durable charters, expertise field, CRUD) — see [`agent-configurability.md`](agent-configurability.md), which depends on this spec.
+- **`skills`→`expertise` field rename** — a separate cleanup owned by the configurability spec.
+- **Cascading a rename into historical free-text** (notes/KB/memory/plans). Non-goal; only a soft hint is offered.
+
+## 8. Work breakdown (suggested PRD seeds)
+
+- AR-a: Register `agent-rename` feature flag (`engine/features.js`) + Settings toggle.
+- AR-b: Formalize stable-id invariant + rename-safety guard + regression tests (`engine/shared.js`, `engine/queries.js`, tests). *(Unconditional.)*
+- AR-c: Sanitize shipped `agents/<id>/charter.md` to be name-agnostic (second person, peers-by-role) + content test (no proper names) + post-rename render test. *(Unconditional.)*
+- AR-d: `POST /api/agents/rename` (full §4.3 contract: name+emoji, validation, idempotency, duplicate-warning, cache invalidation, in-flight safety, audit log) — flag-gated.
+- AR-e: Rename UI in the Settings agents table / detail panel (inline validation + soft duplicate-name warning) — flag-gated; soft name-in-charter warning.
+- AR-f: Tests (rename validation + in-flight + stale-reference behavior, name-agnostic render) + settings-parity note in CLAUDE.md.
+
+## 9. Relationship to Agent & Role Configurability
+
+This spec is a **hard prerequisite** for [`agent-configurability.md`](agent-configurability.md). It delivers the "names aren't load-bearing" foundation — stable opaque id, name-agnostic charters, and the rename capability — that the Role / Agent Library relies on to make roles reusable and to stand up new named agents without name collisions mattering. The configurability spec references this work rather than redefining it.
+
+---
+
+_Every new config surface here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (CLAUDE.md "Best Practices" #15). The `agent-rename` flag follows the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gate on graduation._

package/engine/lifecycle.js

@@ -4604,10 +4604,10 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config) {
 
 /**
  * W-mpg58wv3 — Soft preference picker for re-review agent assignment. Returns
- * a list of agent IDs whose configured skills include any of
+ * a list of agent IDs whose configured expertise tags include any of
  * REVIEW_SKILL_TAGS; the caller passes this to resolveAgent as `agentHints`,
  * which tries each in order before falling through to the default routing
- * path. Empty list when no configured agent has a review skill — the standard
+ * path. Empty list when no configured agent has a review tag — the standard
  * review route still wins, so no PR ever blocks waiting for a specific agent.
  */
 const REVIEW_SKILL_TAGS = ['code-review', 'design-review'];
@@ -4617,8 +4617,10 @@ function pickReReviewAgentHints(config, opts = {}) {
   const out = [];
   for (const [id, agent] of Object.entries(agents)) {
     if (excludeKey && String(id).toLowerCase() === excludeKey) continue;
-    const skills = Array.isArray(agent?.skills) ? agent.skills : [];
-    const lowered = skills.map(s => String(s || '').toLowerCase());
+    // Read the descriptive expertise tags; tolerate legacy `skills` configs.
+    const tags = Array.isArray(agent?.expertise) ? agent.expertise
+      : (Array.isArray(agent?.skills) ? agent.skills : []);
+    const lowered = tags.map(s => String(s || '').toLowerCase());
     if (REVIEW_SKILL_TAGS.some(tag => lowered.includes(tag))) out.push(id);
   }
   return out;

package/engine/playbook.js

@@ -944,7 +944,7 @@ function renderPlaybook(type, vars) {
 
 // Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
-  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', skills: [] };
+  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', expertise: [] };
   const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
   project = project || getProjects(config)[0] || {};
 
@@ -953,7 +953,7 @@ function buildSystemPrompt(agentId, config, project) {
   // Agent identity
   prompt += `# You are ${agent.name} (${agent.role})\n\n`;
   prompt += `Agent ID: ${agentId}\n`;
-  prompt += `Expertise: ${(agent.skills || []).join(', ')}\n\n`;
+  prompt += `Expertise: ${(agent.expertise ?? agent.skills ?? []).join(', ')}\n\n`;
 
   // Charter (detailed instructions — typically 1-2KB)
   if (charter) {

package/engine/queries.js

@@ -679,7 +679,7 @@ function getAgents(config) {
   const seen = new Set(roster.map(a => a.id));
   for (const d of (dispatch.active || [])) {
     if (d.agent && d.agent.startsWith('temp-') && !seen.has(d.agent)) {
-      roster.push({ id: d.agent, name: d.agentName || d.agent, role: d.agentRole || 'Temp Agent', emoji: '\u{1F4A8}', skills: [], _temp: true });
+      roster.push({ id: d.agent, name: d.agentName || d.agent, role: d.agentRole || 'Temp Agent', emoji: '\u{1F4A8}', expertise: [], _temp: true });
       seen.add(d.agent);
     }
   }
@@ -722,6 +722,9 @@ function getAgents(config) {
     if (lastAction.length > 120) lastAction = lastAction.slice(0, 120) + '...';
     return {
       ...a, runtime, model, status: s.status, lastAction,
+      // Descriptive capability tags; tolerate legacy `skills` configs by
+      // normalizing to `expertise` for the dashboard/settings UI.
+      expertise: a.expertise ?? a.skills ?? [],
       currentTask: (s.task || '').slice(0, 200),
       // P-w2c8d1e7 — Phase 1.2: surface the active dispatch id so watch
       // captureState can snapshot it for currentDispatchId-aware predicates.

package/engine/shared.js

@@ -4443,11 +4443,11 @@ const DEFAULT_AGENT_METRICS = {
 };
 
 const DEFAULT_AGENTS = {
-  ripley:  { name: 'Ripley',  emoji: '\u{1F3D7}\uFE0F',  role: 'Lead / Explorer', skills: ['architecture', 'codebase-exploration', 'design-review'] },
-  dallas:  { name: 'Dallas',  emoji: '\u{1F527}',  role: 'Engineer', skills: ['implementation', 'typescript', 'docker', 'testing'] },
-  lambert: { name: 'Lambert', emoji: '\u{1F4CA}',  role: 'Analyst', skills: ['gap-analysis', 'requirements', 'documentation'] },
-  rebecca: { name: 'Rebecca', emoji: '\u{1F9E0}',  role: 'Architect', skills: ['system-design', 'api-design', 'scalability', 'implementation'] },
-  ralph:   { name: 'Ralph',   emoji: '\u2699\uFE0F',   role: 'Engineer', skills: ['implementation', 'bug-fixes', 'testing', 'scaffolding'] },
+  ripley:  { name: 'Ripley',  emoji: '\u{1F3D7}\uFE0F',  role: 'Lead / Explorer', expertise: ['architecture', 'codebase-exploration', 'design-review'] },
+  dallas:  { name: 'Dallas',  emoji: '\u{1F527}',  role: 'Engineer', expertise: ['implementation', 'typescript', 'docker', 'testing'] },
+  lambert: { name: 'Lambert', emoji: '\u{1F4CA}',  role: 'Analyst', expertise: ['gap-analysis', 'requirements', 'documentation'] },
+  rebecca: { name: 'Rebecca', emoji: '\u{1F9E0}',  role: 'Architect', expertise: ['system-design', 'api-design', 'scalability', 'implementation'] },
+  ralph:   { name: 'Ralph',   emoji: '\u2699\uFE0F',   role: 'Engineer', expertise: ['implementation', 'bug-fixes', 'testing', 'scaffolding'] },
 };
 
 const DEFAULT_CLAUDE = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2221",
+  "version": "0.1.2222",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"