opencode-thrum-pro 0.1.0

package/assets/skills/choosing-subagent-models/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: choosing-subagent-models
+description: "Use when about to launch, spawn, or dispatch a subagent, sub-agent, or parallel agent - including the Agent/Task tool, an Explore agent, fanning out research, or any time you choose a model for a subagent. ALSO fires on every REVIEW dispatch - dispatching a reviewer, a code review, a code-quality review, a spec-compliance review, a dual review, a verify-against-plan or verify-against-source pass, or a merge-gate sub-agent. Reviewer dispatch is the HIGHEST-STAKES judgment-tier spawn and is the one most often done from memory. Enforces the role-based model tiering (opus-low orchestrators, sonnet-medium implementers and reviewers, sonnet-low sub-agents) and cheap parallel fan-out."
+---
+
+# Choosing Subagent Models
+
+## Audit, review, or question? Require a file.
+
+**Every subagent you dispatch for an answer must WRITE ITS RESULT TO A FILE
+(e.g. `/tmp/<task>.md`); its reply to you is only a summary. Put this
+in the prompt.**
+
+## Pin every spawn. The floor depends on the agent's ROLE.
+
+Every subagent you spawn MUST pass an explicit `model:` (plus effort where the
+runtime supports it). Omitting it runs the subagent on YOUR model (Opus) — the
+single biggest avoidable cost leak in agent work.
+
+**Haiku is banned entirely.** There is no
+mechanical-task carve-out anymore — lint runs, grep-and-collect, file maps,
+config edits, and all other "simple" work now dispatch at sonnet-low, not Haiku.
+Never select Haiku on own judgment — use sonnet-low instead.
+
+### Agent tiers
+
+Effort tier governs whether an agent does the hard thing or the expedient thing.
+These are the tiers now:
+
+| Role | Model / Effort |
+| ---------------------------- | ------------------- |
+| **Orchestrator** | **`opus` / low** |
+| **Implementer** | **`sonnet` / medium** |
+| **Verifier / reviewer** | **`sonnet` / medium** |
+| **Sub-agent** (investigation, grep, mechanical) | **`sonnet` / low** |
+
+- **`model: "sonnet"` @ low effort — sub-agents ONLY.** Investigation,
+  grep-and-collect, file maps, lint runs, mechanical tasks. This is the floor for
+  a *sub-agent*, NOT for an implementer or a reviewer.
+- **`model: "sonnet"` @ MEDIUM effort — implementers, verifiers, reviewers.**
+  Not low. A reviewer on low effort is a rubber stamp with extra steps, and
+  rubber-stamped reviews are how a merge gate that ran zero tests survived six
+  sessions.
+- **`model: "opus"` @ low — orchestrators.** Not selectable for sub-agents —
+  set by the operator on the agent's runtime-config.
+- **`model: "opus"` — NOT your call.** Allowed only when (a) the operator
+  explicitly asked for a deep review or prose review in this task, or (b) a
+  skill you are running prescribes Opus for the specific step you are currently
+  executing — NOT for every spawn under that skill. "This research is hard /
+  important" is NOT a justification — hard investigation is exactly what Sonnet
+  is for.
+
+## Worked examples — LITERAL ARGUMENTS, AND EFFORT IS TOOL-DEPENDENT
+
+**Pass `model` AND `effort` on every spawn, whichever mechanism you use.** Syntax
+per mechanism — re-check the schema in front of you rather than restating from
+memory, because it can change:
+
+| Mechanism | `model` | `effort` |
+|---|---|---|
+| **Agent tool** | ✅ settable | ✅ **settable — pass it** |
+| **Workflow `agent()`** (opts: label, phase, schema, model, effort, isolation, agentType) | ✅ settable | ✅ settable |
+| **Agent DEFINITION** (`.claude/agents/*.md` / plugin `agents/*.md` frontmatter) | ✅ | ✅ — sets the default for that agent type |
+
+**Agent tool — pass `effort` as a literal argument, alongside `model`.**
+
+```python
+Agent(subagent_type="general-purpose", model="sonnet", effort="low",
+      description="Code-quality review of <branch>",
+      prompt="...")
+```
+
+An agent definition can also carry a default:
+
+```yaml
+# claude-plugin/agents/message-listener.md
+name: message-listener
+model: sonnet
+effort: low
+```
+
+**Workflow `agent()` — effort IS a literal argument. Pass it.**
+
+```javascript
+agent(prompt, { model: "sonnet", effort: "medium" })          // reviewer / implementer
+agent(prompt, { model: "sonnet", effort: "low" })             // mechanical sub-agent
+```
+
+**THE DIRECTIVE, imperative and not a comment: REVIEWERS RUN SONNET AT MEDIUM
+EFFORT.** Pass `effort: "medium"` literally — under Workflow AND under the Agent
+tool. Never dispatch a reviewer "from memory".
+
+**AND VERIFY, DO NOT ASSERT:** any claim about what a tool does or does not expose
+must be checked against the schema in front of you.
+
+Never select Opus or Haiku on own judgment — use Sonnet, at the floor of
+sonnet-low.
+
+## Fleet model-tiering by runtime/role
+
+Different runtimes and roles pin different tiers. Claude tiers are canonical —
+see the Agent tiers table above (orchestrator/implementer/reviewer/sub-agent),
+plus brainstormer → opus-medium and brainstormer's own subagents → sonnet-low
+(except reviewers → sonnet-medium). Other runtimes:
+
+| Runtime      | Role                         | Model / effort                                      |
+| ------------ | ---------------------------- | --------------------------------------------------- |
+| OpenCode     | default                      | GLM-5.2 (fine as-is)                                |
+| Codex        | orchestrator / reviewer      | gpt-5.5-medium                                      |
+| Codex        | implementer                  | gpt-5.5-low                                         |
+| Cursor-agent | default                      | composer-2.5 (fine as-is)                           |
+
+## Pin every spawn explicitly — the floor depends on the ROLE, not the depth
+
+Every orchestrator MUST pass an explicit `model:` and `effort:` on EVERY subagent
+it spawns. An unspecified subagent SILENTLY INHERITS THE PARENT'S MODEL — so an
+Opus orchestrator that forgets the pin just spent Opus tokens on a grep.
+
+**The floor is set by what the agent DOES, not by how deep it sits** — see the
+Agent tiers table above. This applies recursively: an implementer spawning its
+own helpers pins them by THEIR role, not by copying its own tier down.
+
+The check before every spawn: what is this agent's ROLE? Reviewer or implementer?
+sonnet-medium. Pure investigation or mechanical work? sonnet-low. Never leave it
+unspecified.
+
+## Paste the constraint block into the child prompt — the pin is not enough
+
+**A model pin is an ARGUMENT and travels by itself. A behavioural constraint is
+PROSE and reaches the child only if you paste it.** Constrain every level: a rule
+that stops at depth 1 is absent where the work happens.
+
+**Paste verbatim, including the last line:**
+
+```text
+=== CONSTRAINTS — apply to you and anything YOU dispatch (including this line) ===
+- Work SYNCHRONOUSLY. Tests in the FOREGROUND with a bounded `-timeout`.
+- NO POLL LOOPS. Never `until <check>; do sleep N; done`, never
+  `while kill -0 $(cat pid)`, never `$( )` in a loop condition — even when a
+  tool's own guidance suggests it. It trips a permission modal, and A FROZEN
+  PANE EMITS NOTHING, so nobody can tell you are blocked. If you must background
+  work, wait for the completion notification.
+- Every sub-agent YOU spawn gets an explicit `model:` — sonnet (low mechanical,
+  medium judgment). HAIKU IS BANNED. Opus is never yours.
+- READ-ONLY git outside your own worktree. NEVER `checkout`/`reset`/`restore`/
+  `stash`/`clean` in ANY directory — `stash` is one shared stack across all
+  worktrees and the shared tree holds live agents' uncommitted state.
+- Pair every zero/empty result with a control that MUST return non-zero.
+```
+
+⚠️ Never let a child take **"don't ask again"** on a modal — it removes the only
+signal this condition produces.
+
+### Cheap subagents → fan out, don't pile up
+
+Because sonnet-low subagents are cheap, prefer MANY small parallel subagents
+over one subagent handed a pile of tasks. When a research or investigation task
+has independent parts, partition it and dispatch the parts in parallel (use the
+`efficient-multi-agent-research` skill) — smaller scopes are cheaper, run
+concurrently (faster), and keep each subagent's context tight. One subagent
+given ten tasks is the anti-pattern.
+
+## ⚠️ The pin-verification command LIES — do not trust it
+
+`thrum agent runtime-config get <agent>` reports the **configured** value, not the
+**resolved** one.
+
+An implementer ran Opus 4.8 while both the launch flag (`--model sonnet`) and
+`runtime-config get` confirmed sonnet — the check that exists to catch a bad pin
+is itself a false green.
+
+This is the same defect class as every other surface that reports a value it never
+observed (`go test -count=0` reporting PASS while running zero tests; a health RPC
+reporting green off a path that cannot fail; `make ci` swallowing a critical CVE with
+a warning).
+
+**So: after launching an agent, verify with `thrum tmux capture --format=annotated`
+(or `--format=json` for scripting).** It parses the footer server-side into
+NBSP-free fields — no positional-window guessing, no NBSP grep trap, and the
+header states `ok`/`FAILED` explicitly instead of leaving you to infer a failure
+from empty stdout:
+
+```bash
+thrum tmux capture <agent-name> --format=annotated --lines 12
+# ━━━ CAPTURE ok · agent=<name> · runtime=claude · lines=35 ━━━
+# <pane content, verbatim>
+# ─── FOOTER (parsed, NBSP-normalized) ───
+# Model: Sonnet 5 | Ctx: 478.3k | Ctx Used: 48.0%
+# ━━━ END CAPTURE ━━━
+```
+
+The FOOTER block is simply omitted when no footer resolved — never an empty or
+garbage line to misread. For scripting, `--format=json` gives the same data as a
+typed document: `{"agent","runtime","ok","line_count","footer":{"model","ctx","ctx_used_pct"}|null,"lines":[...]["error"]}`
+(`footer` is `null` when none resolved).
+
+```bash
+thrum tmux capture <agent-name> --format=json | python3 -c \
+  'import json,sys; b=json.load(sys.stdin); print(b["footer"]["model"] if b["footer"] else "NO FOOTER")'
+```
+
+Still check the exit status before trusting either form — a FAILED capture exits
+nonzero and the annotated header says `FAILED`, but don't discard that signal by
+piping straight into something that only inspects stdout.
+
+That is the runtime reporting its RESOLVED config, and it is the only check that has
+ever produced a true negative on this defect. If it disagrees with the pin, report it —
+those instances are a real bug and we want them counted.
+
+🔴 **DO NOT substitute "ask the agent what model it is running."** That is a model
+introspecting on its own identity — a categorically weaker instrument.
+**A check built on self-report would be a THIRD instrument that cannot fail in
+the direction we need**, replacing a false green with a confident one. **SETTLED — and the reason is
+categorical, not a reliability judgement: self-report is the WRONG SHAPE for the
+question.** The agent sees exactly ONE value (its resolved model, injected into its own
+system prompt); "does the pin disagree with the resolution?" is a question about a
+RELATION between TWO values. **It cannot report a mismatch however honest it is — the
+disagreement is not representable in what it can observe.** No prompting rescues that.
+Only an outside comparator holding BOTH the pin AND the resolved status line answers it.
+⚠️ A self-report can look right while reading back an injected assertion, so it
+inherits whatever the injection got right or wrong. **A correct answer there is
+survivorship, not validation.**
+
+**Fallback — only if `--format` is unavailable (older binary):** read the bare
+exit status before stdout, then grep the raw pane by position, never by content
+(the raw footer's separators are U+00A0 non-breaking spaces, so `grep "Model: "`
+with a trailing space returns ZERO on a pane that plainly displays a model):
+
+```bash
+out=$(thrum tmux capture <agent-name> --lines 12); rc=$?   # bare, NOT through a pipe
+[ $rc -ne 0 ] && echo "CAPTURE FAILED — this is NOT an empty pane" && exit 1
+printf '%s\n' "$out" | grep -v 'tmux capture' | grep 'Model:' | tail -1
+```
+
+🔴 **PASS `--model` / `--effort` TO BOTH `tmux create` AND `tmux launch`.** They are
+separate cobra commands with separate flags, and **`launch` is what resolves the model**
+(`resolveLaunchSpec` runs in `HandleLaunch`, never in create). `create` persists the pin
+asynchronously, so a create-only pin can lose the race and leave the CLI value empty at
+launch **by construction**.
+
+⚠️ **And any FIX here must be verified with a pin the role default would NOT produce.**
+An implementer pinned to sonnet, with an implementer role-default of sonnet, comes up
+correct whether or not the pin landed — so "pin sonnet, confirm sonnet" passes whether
+or not the fix works.

package/assets/skills/closing-findings-while-warm/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: closing-findings-while-warm
+description: "Use whenever you are about to defer a finding, fix, or cleanup instead of doing it now - proposing a follow-up bead/issue/ticket, catching a sibling defect while wrapping up, feeling something is 'out of scope', or wanting to reach DONE faster. Also use on the manager side, when reviewing a completion report that proposes a deferral. Illustrative (non-exhaustive) phrasing that should trigger this - 'I'll file a follow-up', 'filing this as a P2', 'out of scope for now', 'tracked in a new bead', 'we can pick this up later', 'fast-follow', 'separate PR' - but the trigger is the ACT of deferring, not matching one of these exact phrases."
+---
+
+# Closing Findings While Warm
+
+## The defect this skill fixes
+
+An implementer mid-fix notices a sibling defect, or a reviewer flags a finding
+during a review cycle. The cheap move is to write it down and move on: file a
+bead, note "P2 fast-follow" in the report, close out DONE. That paper trail
+looks like closure but frequently isn't — the bead never gets created, the
+context that made the fix cheap (the file open, the failure mode fresh in
+mind) is gone by the time anyone looks at it again, and "tracked" quietly
+becomes "dropped."
+
+**"A deferral's paper trail is not self-verifying."**
+
+## Role-differentiated resolution
+
+The trigger is the same for every role — a finding just surfaced and someone
+is about to defer it. The correct response differs by who is speaking.
+
+### Implementer: surface, don't self-authorize
+
+An implementer who notices a finding should **surface it to whoever
+dispatched them, while still warm, with the shape of the fix** — what's
+broken, why, and roughly what the fix looks like. Do NOT go fix it
+unilaterally, and do NOT unilaterally decide it's out of scope and drop it.
+
+This is not a failure mode to train out. An implementer proposing a
+follow-up is **correct subordinate behavior** — implementers do not own
+scope, the dispatcher does. The defect this skill targets is never "the
+implementer proposed a deferral instead of just fixing it." Surfacing with
+the fix's shape and stopping there is the right move.
+
+### Manager tier: you make the call, default is fix-now
+
+Whoever dispatched the implementer — orchestrator or coordinator, whichever
+tier is currently managing that thread — owns the fix-now-vs-defer decision.
+The default is: **direct the fix now, while the expert is still warm.**
+Re-dispatching later means re-loading context that's about to evaporate, plus
+a second review cycle, plus a live bead to track in the meantime.
+
+If you're a manager-tier reader of this skill reaching for "just tell the
+implementer to go fix it themselves" as the resolution here — stop. That
+phrasing is the exact defect this skill was written to close out. An
+implementer does not self-authorize scope expansion; only the dispatcher
+directs it. Writing "just go fix it" without you actually making and owning
+that call is exactly the anti-pattern this design pass amended. It will fail
+review.
+
+Only defer when the legitimate-deferral bar below is fully met — and even
+then, the deferral isn't done until its bead is verified to exist.
+
+**Recipient duty, not just reporter duty:** before accepting any deferral,
+independently run `bd show <id>` yourself — do not trust the reporter's
+self-attestation that a bead was filed and confirmed. A cited bead ID is not
+evidence until the RECIPIENT, not the reporter, has confirmed it resolves.
+
+## Legitimate-deferral bar (narrow — do not let this become a rubber stamp)
+
+A deferral is legitimate only when **all three** hold:
+
+**(a) Genuine independence.** The finding touches a genuinely different
+subsystem with no intersection with the current branch's diff, OR the fix is
+blocked on an external dependency (another team's merge, an upstream release,
+a design decision not yet made). "I'd rather not right now" is not
+independence.
+
+**(b) Named assignee and a dispatch date.** Not "someone will pick this up" —
+a specific agent or person, and when it will be dispatched. An unowned
+deferral is a deferral to nobody.
+
+**(c) The bead exists, verified.** Create the bead, then run `bd show <id>`
+and echo the ID back in your report. A deferral is not closed by the
+intention to file a bead — it is closed by the bead existing and being
+confirmed to exist. "I'll file a follow-up" is a promise; `bd show thrum-xyz`
+returning the issue is evidence.
+
+If any of (a)/(b)/(c) is missing, it is not a legitimate deferral — direct
+the fix now instead.
+
+## Worked example: the bead that wasn't there
+
+A fix once split off a sibling defect as a "P2 fast-follow"; the report
+claimed a bead was filed and a later snapshot carried that as settled fact,
+but the bead was never created and nobody ran `bd show` to confirm it. The
+paper trail read as closure; it wasn't.
+
+This is the failure mode part (c) exists to close: verify existence with the
+tool that can prove it, not by trusting the sentence that claims it.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it
+via the `implementer-maintaining-memory` skill (or `coordinator-maintaining-
+memory` if you're operating in a manager tier) — it references the
+`memory-write-discipline` common for the canonical `thrum memory create`
+shape.

package/assets/skills/configure-roles/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: configure-roles
+description: "Detect environment and generate customized role-based preamble templates for your Thrum agents. Creates .thrum/role_templates/ files that auto-apply on agent registration."
+allowed-tools:
+  "Bash(thrum:*), Bash(bd:*), Bash(git:worktree*), Read, Write, Glob,
+  AskUserQuestion"
+---
+
+# Configure Roles
+
+Generate role-based preamble templates customized to your project environment.
+Templates auto-apply when agents register via `thrum quickstart`.
+
+**Announce:** "Using configure-roles to set up preamble templates for your
+team."
+
+## CLI path (AI-free)
+
+A plain-CLI alternative now exists for quick, scriptable role setup without
+requiring an AI agent:
+
+```bash
+thrum roles configure --detect   # configures all roles from registered identities
+thrum roles deploy                # re-renders preambles
+```
+
+This writes **verbatim shipped templates** (faithful ~90% solution, correct for
+the upgrade use case). Use this skill (`/thrum:configure-roles`) for
+environment-tailored templates — injecting project-specific context such as
+`bd` block syntax, MCP guidance, or custom scope wording. The CLI and the skill
+coexist; the skill's output is a superset of the CLI's.
+
+## Interaction Style — MANDATORY
+
+Use **`AskUserQuestion` for ALL interactive prompts.** Do not ask "reply with 1,
+2, or 3" style questions in plain prose. Every choice the user makes goes
+through the structured `AskUserQuestion` UI so answers are unambiguous and
+machine-readable.
+
+## Step 1: Detect Environment
+
+Run these commands and collect the output (suppress errors):
+
+```bash
+thrum runtime list 2>/dev/null          # Installed runtimes
+git worktree list 2>/dev/null           # Worktrees and branches
+bd stats 2>/dev/null                    # Beads task tracker state
+thrum agent list --context 2>/dev/null  # Registered agents
+ls .claude/skills/ 2>/dev/null          # Installed Claude skills
+thrum config show 2>/dev/null           # Thrum configuration
+```
+
+Also check:
+
+- `.claude/settings.json` for MCP servers (context7, etc.)
+- Existing rendered templates in `.thrum/role_templates/`
+- Current saved answers in `.thrum/config.json` under `role_config` (if any)
+
+To inspect a shipped reference template, use the CLI shim — never read directly
+from a filesystem path, since the binary may run from any directory:
+
+```bash
+thrum roles templates print coordinator-autonomous
+thrum roles templates print orchestrator             # single-variant role
+```
+
+## Step 2: Report Findings
+
+Summarize what you detected:
+
+- Runtimes installed
+- Worktrees and branches in use
+- Whether beads is configured
+- Current team composition (agents, roles, modules)
+- Available MCP servers and skills
+- Existing role templates (if re-running)
+- Existing `role_config` in `.thrum/config.json` (if re-running)
+
+## Step 3: Check for Existing Configuration
+
+```bash
+ls .thrum/role_templates/ 2>/dev/null
+thrum config show 2>/dev/null | jq '.role_config' 2>/dev/null
+```
+
+If `role_config` exists, prefill each AskUserQuestion with the saved value (see
+"Re-run Behavior" below) so the user only has to confirm rather than re-enter
+every choice.
+
+## Step 4: Ask Questions
+
+Ask these in sequence using `AskUserQuestion`. Each call should accept exactly
+one answer and surface the available choices structurally.
+
+### 4a: Team Structure
+
+Question: "What roles does your team need?"
+
+Options based on detected agents, plus common defaults:
+
+- coordinator, implementer (most common)
+- coordinator, implementer, planner, researcher
+- coordinator, implementer, reviewer, tester
+- Custom set
+
+Available roles (all have strict and autonomous variants except `orchestrator`,
+which is single-variant):
+
+| Role         | Purpose                                              |
+| ------------ | ---------------------------------------------------- |
+| coordinator  | Orchestrates team, dispatches tasks, reviews/merges  |
+| implementer  | Writes code in assigned worktree                     |
+| planner      | Creates plans, designs architecture, writes specs    |
+| researcher   | Investigates codebases, produces research reports    |
+| reviewer     | Reviews code for quality, security, correctness      |
+| tester       | Writes and runs tests, verifies acceptance criteria  |
+| deployer     | Handles builds, releases, deployment operations      |
+| documenter   | Creates and maintains documentation                  |
+| monitor      | Watches system health, reports anomalies             |
+| orchestrator | Drives plan execution across agents (single-variant) |
+
+### 4b: Autonomy Level Per Role
+
+For each role selected (except `orchestrator`), call `AskUserQuestion`: "What
+autonomy level for the {role} role?"
+
+- **Strict** — waits for coordinator instruction, limited scope
+- **Autonomous** — can self-assign tasks, broader scope
+
+### 4c: Scope Rules
+
+If multiple worktrees detected, ask via `AskUserQuestion`: "Should agents be
+restricted to their own worktree?"
+
+- **single_worktree** — strict scope boundaries
+- **cross_worktree** — can read across worktrees
+
+## Step 5: Generate Templates
+
+For each role:
+
+1. Read the shipped reference via the CLI shim:
+
+   ```bash
+   thrum roles templates print {role}-{autonomy}
+   ```
+
+   For `orchestrator`, omit the autonomy suffix (single-variant):
+
+   ```bash
+   thrum roles templates print orchestrator
+   ```
+
+2. Customize based on environment detection:
+   - If beads detected: include `bd` commands in Task Tracking section
+   - If MCP servers detected: add to Efficiency section
+   - If specific skills detected: reference them
+   - If worktree restrictions: adjust Scope Boundaries
+
+3. Write to `.thrum/role_templates/{role}.md`. Keep per-agent template tokens
+   (`{{.AgentName}}`, `{{.Module}}`, `{{.WorktreePath}}`,
+   `{{.CoordinatorName}}`, `{{.RepoRoot}}`) **literal** — they get substituted
+   per-agent at deploy time, not at template-write time.
+
+## Step 5b: Persist Answers
+
+After writing the templates, persist the user's answers so other code paths
+respect their choices and drift detection can flag plugin upgrades:
+
+```bash
+cat <<'EOF' | thrum roles save-config
+{
+  "schema_version": 1,
+  "roles": {
+    "coordinator": {"autonomy": "{{coord_autonomy}}", "scope": "{{coord_scope}}"},
+    "implementer": {"autonomy": "{{impl_autonomy}}", "scope": "{{impl_scope}}"}
+  }
+}
+EOF
+```
+
+`thrum roles save-config` writes `role_config` into `.thrum/config.json`, fills
+`schema_version` / `plugin_version` / `configured_at` with sensible defaults if
+absent, and backfills `rendered_hash` per role from the current shipped body
+hash so `thrum prime` shows no drift hints.
+
+The save is atomic and preserves every other top-level config key
+(backup/daemon/identity/telegram) byte-identical.
+
+## Step 6: Offer Deploy
+
+If agents are already registered, ask via `AskUserQuestion` whether to deploy
+now:
+
+```bash
+thrum roles deploy --dry-run    # Preview
+thrum roles deploy              # Apply to all agents
+```
+
+## Re-run Behavior
+
+When `role_config` exists in `.thrum/config.json` (the canonical record), load
+the saved answers and use them as the **prefilled values** for each
+`AskUserQuestion` call so the user only has to re-confirm rather than re-enter
+every choice:
+
+1. Show existing roles with their saved autonomy and scope.
+2. Ask via `AskUserQuestion` what to change: add a role, modify an existing
+   role, or remove one.
+3. Only regenerate requested templates.
+4. Always re-run `thrum roles save-config` so `rendered_hash` is refreshed and
+   the saved `plugin_version` / `configured_at` reflect the current run.
+5. Offer deploy for changes.
+
+If the user wants to apply only template-content updates after a plugin upgrade
+(no answer changes), point them at `thrum roles refresh` — it regenerates
+rendered files from saved answers without asking any questions.
+
+## Environment-Specific Customizations
+
+| Detected             | Template Customization                                   |
+| -------------------- | -------------------------------------------------------- |
+| Claude Code runtime  | Add Task tool + sub-agent guidance to Efficiency section |
+| Augment runtime      | Add Augment-specific tool guidance to Efficiency section |
+| Beads installed      | Add `bd` commands to Task Tracking, disable TodoWrite    |
+| Thrum MCP server     | Add MCP tool references, CLI fallback for sub-agents     |
+| Claude plugin skills | List installed skills with usage guidance                |
+| Context7 MCP         | Add library docs guidance to Efficiency section          |
+| Multiple worktrees   | Add worktree scope rules to Scope Boundaries             |