opencode-thrum-pro 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/assets/commands/thrum-compact-extended.md +367 -0
  2. package/assets/commands/thrum-compact.md +301 -0
  3. package/assets/commands/thrum-inbox.md +1 -1
  4. package/assets/commands/thrum-restart-extended.md +85 -16
  5. package/assets/commands/thrum-restart.md +106 -14
  6. package/assets/commands/thrum-send.md +4 -1
  7. package/assets/commands/thrum-sleep-extended.md +68 -51
  8. package/assets/commands/thrum-sleep.md +68 -63
  9. package/assets/commands/thrum-update-project.md +1 -1
  10. package/assets/skills/adversarial-critique/SKILL.md +5 -8
  11. package/assets/skills/brainstorm-steward/SKILL.md +65 -11
  12. package/assets/skills/brainstormer-staying-current/SKILL.md +1 -4
  13. package/assets/skills/choosing-subagent-models/SKILL.md +200 -70
  14. package/assets/skills/closing-findings-while-warm/SKILL.md +1 -2
  15. package/assets/skills/configure-roles/SKILL.md +2 -2
  16. package/assets/skills/conversation-only-context/SKILL.md +11 -11
  17. package/assets/skills/conversation-only-context/resources/driver-subagent-pattern.md +1 -1
  18. package/assets/skills/conversation-only-context/resources/remote-environment-scenarios.md +1 -1
  19. package/assets/skills/coordinator-assessing-agent-completion/SKILL.md +98 -6
  20. package/assets/skills/coordinator-branch-split-on-block/SKILL.md +1 -2
  21. package/assets/skills/coordinator-context-monitoring/SKILL.md +29 -19
  22. package/assets/skills/coordinator-deploying-a-node/SKILL.md +124 -0
  23. package/assets/skills/coordinator-dispatching-work/SKILL.md +26 -14
  24. package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md +65 -21
  25. package/assets/skills/coordinator-interacting-with-the-owner/SKILL.md +1 -2
  26. package/assets/skills/coordinator-maintaining-memory/SKILL.md +1 -1
  27. package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md +7 -8
  28. package/assets/skills/coordinator-merging-code/SKILL.md +43 -22
  29. package/assets/skills/coordinator-philosophy-merge-gate/SKILL.md +29 -9
  30. package/assets/skills/coordinator-plan-reconcile-gate/SKILL.md +4 -5
  31. package/assets/skills/coordinator-rolling-out-to-nodes/SKILL.md +92 -0
  32. package/assets/skills/coordinator-running-autonomous-feature-development/SKILL.md +3 -3
  33. package/assets/skills/coordinator-running-brainstorm-cycles/SKILL.md +25 -25
  34. package/assets/skills/coordinator-running-review-cycles/SKILL.md +16 -6
  35. package/assets/{commands/thrum-_deviations-protocol.md → skills/deviations-protocol/SKILL.md} +6 -12
  36. package/assets/skills/diagnosing-fleet-and-daemon/SKILL.md +0 -2
  37. package/assets/skills/efficient-multi-agent-research/SKILL.md +3 -3
  38. package/assets/skills/generator-idempotency-protocol/SKILL.md +9 -0
  39. package/assets/skills/implementer-maintaining-memory/SKILL.md +3 -4
  40. package/assets/skills/implementer-orchestrating-execution/SKILL.md +12 -16
  41. package/assets/skills/implementer-receiving-dispatch/SKILL.md +15 -17
  42. package/assets/skills/implementer-receiving-review-feedback/SKILL.md +3 -4
  43. package/assets/skills/implementer-status-and-handoff/SKILL.md +1 -14
  44. package/assets/skills/implementer-tdd-and-quality/SKILL.md +2 -2
  45. package/assets/skills/memory-curate/SKILL.md +1 -1
  46. package/assets/skills/memory-write-discipline/SKILL.md +1 -1
  47. package/assets/skills/orchestrate/SKILL.md +77 -36
  48. package/assets/skills/persistent-watcher-archetype/SKILL.md +172 -25
  49. package/assets/skills/persistent-watcher-archetype/resources/capture_archive.py +618 -0
  50. package/assets/skills/persistent-watcher-archetype/resources/jev_watcher_filter.py +837 -0
  51. package/assets/skills/persistent-watcher-archetype/resources/roster-watch.sh +1140 -0
  52. package/assets/skills/persistent-watcher-archetype/resources/roster-watch_test.sh +291 -0
  53. package/assets/skills/persistent-watcher-archetype/resources/thrum-capture-fallback.sh +2 -2
  54. package/assets/skills/persistent-watcher-archetype/resources/thrum-watch-pane-capture.sh +20 -8
  55. package/assets/skills/prime-agent/SKILL.md +10 -0
  56. package/assets/skills/project-hotpath-gate/SKILL.md +1 -2
  57. package/assets/skills/project-philosophy/SKILL.md +1 -2
  58. package/assets/skills/project-rules-protocol/SKILL.md +12 -0
  59. package/assets/skills/project-setup/SKILL.md +27 -22
  60. package/assets/skills/project-setup/resources/implementation-agent.md +55 -35
  61. package/assets/skills/researcher-answering-queries/SKILL.md +1 -2
  62. package/assets/skills/researcher-investigating/SKILL.md +8 -13
  63. package/assets/skills/researcher-maintaining-memory/SKILL.md +1 -1
  64. package/assets/{commands/thrum-_snapshot-protocol.md → skills/snapshot-protocol/SKILL.md} +27 -21
  65. package/assets/{commands/thrum-_stamp-protocol.md → skills/stamp-protocol/SKILL.md} +14 -8
  66. package/assets/skills/thrum/SKILL.md +14 -7
  67. package/assets/skills/thrum/resources/ANTI_PATTERNS.md +16 -18
  68. package/assets/skills/thrum/resources/CLI_REFERENCE.md +17 -11
  69. package/assets/skills/thrum/resources/LISTENER_PATTERN.md +9 -3
  70. package/assets/skills/thrum/resources/MESSAGING.md +18 -11
  71. package/assets/skills/thrum/resources/WORKTREES.md +1 -1
  72. package/assets/skills/thrum-memory/SKILL.md +1 -1
  73. package/assets/skills/trace-spec-to-plan/resources/sweep-agent-prompt.md +1 -1
  74. package/assets/skills/update-queue/SKILL.md +6 -8
  75. package/assets/skills/using-the-dashboard/SKILL.md +30 -0
  76. package/assets/skills/using-the-queue/SKILL.md +76 -5
  77. package/assets/skills/using-thrum-state/SKILL.md +85 -2
  78. package/assets/skills/verify-against-plan/SKILL.md +122 -7
  79. package/assets/skills/watcher-archetype/SKILL.md +18 -0
  80. package/assets/skills/writing-durable-markdown/SKILL.md +5 -0
  81. package/dist/installer-assets.test.js +41 -0
  82. package/dist/installer.js +4 -4
  83. package/dist/permission-fixture.integration.test.js +4 -4
  84. package/package.json +1 -1
  85. package/assets/commands/thrum-_generator-idempotency-protocol.md +0 -15
  86. package/assets/commands/thrum-_project-rules-protocol.md +0 -18
  87. package/assets/commands/thrum-_verify-before-write-protocol.md +0 -27
  88. package/assets/skills/coordinator-deploying-the-fleet/SKILL.md +0 -396
  89. package/dist/allowlist-sync.test.js +0 -44
  90. /package/dist/{allowlist-sync.test.d.ts → installer-assets.test.d.ts} +0 -0
@@ -40,7 +40,7 @@ thrum memory create --kind agent_rule --scope role \
40
40
  ```
41
41
 
42
42
  `--short`/`--full` carry real prose — compose via heredoc or file, never
43
- double-quoted inline; see your role preamble's 🔴 PROSE INTO A COMMAND rule.
43
+ double-quoted inline; see the heredoc-or-file rule in your role preamble.
44
44
 
45
45
  Body shape is uniform across all role-rule writes — see
46
46
  `memory-write-discipline`. The `Why:` line is load-bearing: future-you needs the
@@ -48,9 +48,8 @@ reason to judge edge cases the rule doesn't literally cover.
48
48
 
49
49
  ## Implementer does NOT write
50
50
 
51
- - **Refactoring opportunities discovered mid-task** → file under the project's
52
- refactoring epic, e.g. `<refactor-epic-id>`, NOT memory. Memory is for AGENT
53
- BEHAVIOR rules; bd tracks code work.
51
+ - **Refactoring opportunities discovered mid-task** → report them to the
52
+ coordinator, NOT memory and not bd. Memory is for AGENT BEHAVIOR rules.
54
53
  - **Research findings about the codebase** → ping the researcher; they own
55
54
  `kind: research_note` writes.
56
55
  - **Per-task notes / scratch state** → use the conversation context or task
@@ -6,7 +6,7 @@ description: "Use when starting execution of a scoped implementation task — ab
6
6
  # Implementer: Orchestrating Execution
7
7
 
8
8
  You implement by **orchestrating sub-agents**, not by doing research, edits, and
9
- verification yourself. Your Opus context is for judgment — synthesizing
9
+ verification yourself. Your own context is for judgment — synthesizing
10
10
  research, targeting edits, judging verification against the plan. The legwork
11
11
  goes to cheaper sub-agents. This skill is the procedure; invoke it at the start
12
12
  of executing any scoped task.
@@ -27,10 +27,7 @@ The size bound (~15 lines / 2 files) is the project default; a project-local
27
27
 
28
28
  ## Subagent model selection
29
29
 
30
- > **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
31
- > (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
32
- > operator-ask or a skill step that names it. See the
33
- > `choosing-subagent-models` skill for the full policy.
30
+ > **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
34
31
 
35
32
  ## Step 1 — Dispatch research
36
33
 
@@ -44,13 +41,13 @@ you do not read the code into your own context. Label the dispatch
44
41
  From the report, decide exactly what changes where, then dispatch
45
42
  general-purpose sub-agent(s) to make the edits. Give each the bd task ID, the
46
43
  exact files, the acceptance criteria, and the relevant slice of the report.
47
- Model: `sonnet`; use `sonnet` (low effort) for purely mechanical edits
44
+ Model: per `choosing-subagent-models`; use the cheapest tier for purely mechanical edits
48
45
  (find/replace, rename). Label `description="implement: <what>"`. Parallelize independent
49
46
  edit-targets; serialize edits to shared files.
50
47
 
51
48
  ## Step 3 — Dispatch verification
52
49
 
53
- Spawn a `sonnet` verifier against **the plan the implementation sub-agent was
50
+ Spawn a verifier sub-agent (model per `choosing-subagent-models`) against **the plan the implementation sub-agent was
54
51
  given** — does the diff satisfy the acceptance criteria and honor the plan?
55
52
  Label `description="verify: <what>"`. (For the full code-quality +
56
53
  spec-compliance review at DONE, `implementer-tdd-and-quality` and the
@@ -89,12 +86,12 @@ hard size bound.
89
86
 
90
87
  | Dispatch | Model |
91
88
  | ------------------ | -------------------------------------------------- |
92
- | research / explore | `sonnet` (or the `Explore` agent type) |
93
- | implementation | `sonnet`; `sonnet` (low effort) for purely mechanical edits |
94
- | verification | `sonnet` |
89
+ | research / explore | per `choosing-subagent-models` (or the `Explore` agent type) |
90
+ | implementation | per `choosing-subagent-models`; cheapest tier for purely mechanical edits |
91
+ | verification | per `choosing-subagent-models` |
95
92
 
96
- Use the bare `sonnet` alias (resolves to the current Sonnet); do not hard-pin a
97
- version id. Never let a sub-agent inherit the parent (Opus) model.
93
+ Use the bare alias from `runtime.role_models`; do not hard-pin a version id.
94
+ Never let a sub-agent inherit the parent model.
98
95
 
99
96
  ## Sub-agent label convention (required)
100
97
 
@@ -105,8 +102,8 @@ delegation shape from these labels.
105
102
  ## Anti-patterns
106
103
 
107
104
  ❌ **Inline Worker** — does the research and edits itself instead of
108
- dispatching. Your Opus context is for orchestration judgment, not hand-typing
109
- edits a Sonnet sub-agent should make.
105
+ dispatching. Your own context is for orchestration judgment, not hand-typing
106
+ edits a sub-agent should make.
110
107
 
111
108
  ❌ **Over-orchestrator** — dispatches a sub-agent for a known one-line change,
112
109
  paying more in prompt-composition than the edit costs. The Step-0 scoping gate
@@ -117,8 +114,7 @@ prefix, blinding the evaluation harness.
117
114
 
118
115
  ## Project-specific rules (already loaded)
119
116
 
120
- Read the shared partial at the absolute path:
121
- `claude-plugin/commands/_project-rules-protocol.md`
117
+ Load the /thrum:project-rules-protocol skill and follow it.
122
118
 
123
119
  Capture new rules mid-session via the `implementer-maintaining-memory` skill —
124
120
  it references the `memory-write-discipline` common for the canonical
@@ -38,7 +38,7 @@ config loading, string sanitization, validation), run a targeted grep.
38
38
  something similar exists, use it. If it needs extension, extend it. Only create
39
39
  a new function when nothing exists.
40
40
 
41
- ## Don't refactor for free — log opportunities, don't implement them
41
+ ## Don't refactor for free — report opportunities, don't implement them
42
42
 
43
43
  **Why:** A bug fix doesn't need surrounding cleanup. A one-shot operation
44
44
  doesn't need a helper. Inlining "improvements" into a scoped task expands the
@@ -46,26 +46,25 @@ diff, complicates review, and risks introducing bugs unrelated to the work.
46
46
  Three similar lines is better than a premature abstraction.
47
47
 
48
48
  **How to apply:** When you spot duplicated patterns, hardcoded values that
49
- should be shared, or missed abstractions during implementation, log them to the
50
- project's refactor backlog (a beads epic, e.g. `<refactor-epic-id>`):
49
+ should be shared, or missed abstractions during implementation, report them to
50
+ the coordinator; do not file a bd issue yourself.
51
51
 
52
- `--description` is multi-line prose — never double-quoted inline. On
53
- `scripts/bd-shared`, `--stdin`/`--body-file` are refused (remote-path
54
- resolution + silent-empty-body hazards), so write it to a scratch file and
55
- pass `-d "$(cat <file>)"`; see your role preamble's 🔴 PROSE INTO A COMMAND
56
- rule.
52
+ The report body is multi-line prose — never double-quoted inline; see the
53
+ heredoc-or-file rule in your role preamble.
57
54
 
58
55
  ```bash
59
- cat > /tmp/refactor-task-desc.md <<'EOF'
60
- **Discovered during:** <task-id>
61
- **Files:** <paths>
62
- **Opportunity:** <what could be improved>
63
- **Effort:** small/medium/large
56
+ thrum send --to @<coordinator> --stdin <<'EOF'
57
+ Refactoring opportunity (discovered during <task-id>)
58
+ Files: <paths>
59
+ Opportunity: <what could be improved>
60
+ Effort: small/medium/large
64
61
  EOF
65
- bd create --title="Refactor: <short description>" --type=task \
66
- --parent=<refactor-epic-id> --priority=3 -d "$(cat /tmp/refactor-task-desc.md)"
67
62
  ```
68
63
 
64
+ If the coordinator asks you to file the bead, write the description to a scratch
65
+ file and pass `--body-file <file>` to `scripts/bd-shared` (and
66
+ `comments add <id> -f <file>` for comments).
67
+
69
68
  Then continue with the assigned work. Do not implement the refactoring.
70
69
 
71
70
  ## Flag scope deviations immediately — not in the final report
@@ -96,8 +95,7 @@ related files.
96
95
 
97
96
  ## Project-specific rules (already loaded)
98
97
 
99
- Read the shared partial at the absolute path:
100
- `claude-plugin/commands/_project-rules-protocol.md`
98
+ Load the /thrum:project-rules-protocol skill and follow it.
101
99
 
102
100
  If you accumulate a new rule mid-session (the user corrects you), capture it via
103
101
  the `implementer-maintaining-memory` skill — it references the
@@ -71,8 +71,8 @@ trade-off explicitly:
71
71
  - Is the fix a few lines? Default to fix-now
72
72
  - Does verification require running the same tests as the main fix? Default to
73
73
  fix-now
74
- - Is the fix a meaningful refactor or design change? Defer is legitimate; file
75
- the bd issue and link it in the commit message
74
+ - Is the fix a meaningful refactor or design change? Defer is legitimate; report
75
+ it to the coordinator (not a bd issue) and cite the report in the commit message
76
76
 
77
77
  Don't reach for "deferred" as a shortcut to ship faster.
78
78
 
@@ -117,8 +117,7 @@ list, file them as bd issues — don't slip them into the fix commit.
117
117
 
118
118
  ## Project-specific rules (already loaded)
119
119
 
120
- Read the shared partial at the absolute path:
121
- `claude-plugin/commands/_project-rules-protocol.md`
120
+ Load the /thrum:project-rules-protocol skill and follow it.
122
121
 
123
122
  If you accumulate a new rule mid-session (the user corrects you), capture it via
124
123
  the `implementer-maintaining-memory` skill — it references the
@@ -107,22 +107,9 @@ make test PASS (race), make lint PASS.
107
107
 
108
108
  For first-pass DONE (not review-fix), cite the closing SHA and the test result.
109
109
 
110
- ## Close beads tasks with `--suggest-next` when relevant
111
-
112
- **Why:** `bd close <id>` works fine, but `bd close <id> --suggest-next` prints
113
- newly-unblocked downstream issues immediately. If you're in the middle of an
114
- epic, the next task is often the most useful next move; the flag saves a
115
- `bd ready` round-trip.
116
-
117
- **How to apply:** When closing a task that has dependents, use
118
- `bd close <id> --suggest-next`. For the last task in an epic where you're
119
- stopping at a review gate, plain `bd close` is fine — you're not picking up the
120
- next task anyway.
121
-
122
110
  ## Project-specific rules (already loaded)
123
111
 
124
- Read the shared partial at the absolute path:
125
- `claude-plugin/commands/_project-rules-protocol.md`
112
+ Load the /thrum:project-rules-protocol skill and follow it.
126
113
 
127
114
  If you accumulate a new rule mid-session (the user corrects you), capture it via
128
115
  the `implementer-maintaining-memory` skill — it references the
@@ -86,13 +86,13 @@ that would otherwise come back as findings.
86
86
  package searched -> primitive adopted, or none exists + bounded cost formula
87
87
  (frequency x production cardinality, at production scale). Include it in
88
88
  your DONE report.
89
+ - Before writing a raw read-in-loop, `db.Query`-in-loop, `COUNT(DISTINCT ...)`, or a second transaction or pool acquisition per logical unit under a hot root, search the callee package for an existing targeted, cached, covering or batch primitive.
89
90
 
90
91
  Fix what you find before sending the ping.
91
92
 
92
93
  ## Project-specific rules (already loaded)
93
94
 
94
- Read the shared partial at the absolute path:
95
- `claude-plugin/commands/_project-rules-protocol.md`
95
+ Load the /thrum:project-rules-protocol skill and follow it.
96
96
 
97
97
  If you accumulate a new rule mid-session (the user corrects you), capture it via
98
98
  the `implementer-maintaining-memory` skill — it references the
@@ -108,7 +108,7 @@ thrum memory create --kind comment \
108
108
  ```
109
109
 
110
110
  `--short`/`--full` carry real prose — compose via heredoc or file, never
111
- double-quoted inline; see your role preamble's 🔴 PROSE INTO A COMMAND rule.
111
+ double-quoted inline; see the heredoc-or-file rule in your role preamble.
112
112
 
113
113
  `--parent` shorthand creates the `child_of` edge in the same operation. Author =
114
114
  `agent_id`, timestamp = `created_at`. Threading walks via the daemon's
@@ -25,7 +25,7 @@ thrum memory create --kind <K> --scope <S> \
25
25
  ```
26
26
 
27
27
  `--short`/`--full` carry real prose — compose via heredoc or file, never
28
- double-quoted inline; see the role preamble's 🔴 PROSE INTO A COMMAND rule.
28
+ double-quoted inline; see the heredoc-or-file rule in your role preamble.
29
29
 
30
30
  Three flags are **REQUIRED** (schema NOT NULL): `--kind`, `--title`,
31
31
  `--oneline`. The daemon rejects any `memory.create` call missing these.
@@ -53,8 +53,11 @@ grep "## Review Gate:" <prompt-file-path>
53
53
  # 4. Dependencies configured
54
54
  bd dep tree <epic-id>
55
55
 
56
- # 5. Merge target in config
57
- cat .thrum/config.json | grep merge_target
56
+ # 5. Merge target in config (resolve through .thrum/redirect when present --
57
+ # a worktree's .thrum/ holds only a `redirect` file, not its own config.json)
58
+ CONFIG=.thrum/config.json
59
+ [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"
60
+ cat "$CONFIG" | grep merge_target
58
61
  ```
59
62
 
60
63
  ### Step 2b: Triage CANDIDATE beads (if the dispatch carries any)
@@ -79,8 +82,8 @@ by the result:
79
82
  > `choosing-subagent-models` skill's job, not this one — see it for the tiers. What
80
83
  > matters here is that you pass one at all: the `roleDefault()` backstop in the
81
84
  > daemon covers `thrum tmux launch` of thrum agents, **not** Agent-tool sub-agents,
82
- > which inherit the PARENT model when unspecified. An orchestrator on Opus that
83
- > omits `model:` gets Opus-priced triage.
85
+ > which inherit the PARENT model when unspecified. An orchestrator whose own tier is
86
+ > costly that omits `model:` gets costly-priced triage.
84
87
 
85
88
  | Result | Action |
86
89
  |---|---|
@@ -181,13 +184,15 @@ thrum worktree create <name>
181
184
  # Pin --model on BOTH create AND launch — create's persist to runtime_config.json
182
185
  # is asynchronous and can lose the race to launch's resolution if launch omits
183
186
  # the flag (see CLAUDE.md "Launching an Agent"). There is no create-only shortcut.
184
- # Always launch implementers at --model sonnet. sonnet-medium is the floor;
185
- # no lower tier exists.
187
+ # Always launch implementers pinned to the tier from runtime.role_models, per
188
+ # choosing-subagent-models; that tier is the floor, no lower tier exists.
186
189
  thrum tmux create <name> --cwd <worktree-path> \
187
190
  --name <agent_name> --role implementer --module <module> \
188
191
  --mode ephemeral --identity ephemeral \
189
- --model sonnet
190
- thrum tmux launch <name> --runtime <runtime> --model sonnet
192
+ --model <from runtime.role_models, per choosing-subagent-models> \
193
+ --effort <from runtime.role_models, per choosing-subagent-models>
194
+ thrum tmux launch <name> --runtime <runtime> --model <from runtime.role_models, per choosing-subagent-models> \
195
+ --effort <from runtime.role_models, per choosing-subagent-models>
191
196
  ```
192
197
 
193
198
  > **Implementer lifecycle:** All implementers are ephemeral+stateless (no agent
@@ -215,7 +220,7 @@ it fails again, escalate to the human.
215
220
  ### Step 3b: Verify the model pin took
216
221
 
217
222
  If `--model` is dropped anywhere in the create/launch sequence, the implementer
218
- launches UNPINNED and the runtime defaults to Opus — the exact expensive
223
+ launches UNPINNED and the runtime defaults to its own (costly) model — the exact expensive
219
224
  failure this tier exists to prevent. Confirm the pin landed before assigning
220
225
  work, using `thrum tmux capture --format=annotated` (see CLAUDE.md "Launching
221
226
  an Agent — Verify the Model by Pane, Never by `runtime-config get`" for the
@@ -226,12 +231,12 @@ NBSP fallback trap, and the by-position read):
226
231
  thrum tmux capture <agent-name> --format=annotated --lines 12
227
232
  ```
228
233
 
229
- That prints the runtime's own footer line, e.g. `Model: Sonnet 5`. **Read the
234
+ That prints the runtime's own footer line, e.g. `Model: <resolved model>`. **Read the
230
235
  intended tier from `.thrum/config.json` → `runtime.role_models`, not from memory.**
231
- If the footer shows a different tier (see the BLOCKED note under Step 2 — there is
232
- no valid `haiku` pin), the pin failed silently — re-pin with
233
- `thrum tmux create ... --model sonnet` (or
234
- `thrum agent runtime-config set <agent_name> --model sonnet`) and relaunch BEFORE
236
+ If the footer shows a different tier (see the BLOCKED note under Step 2 — the model ban
237
+ list lives in `choosing-subagent-models`), the pin failed silently — re-pin with
238
+ `thrum tmux create ... --model <from runtime.role_models, per choosing-subagent-models> --effort <from runtime.role_models, per choosing-subagent-models>` (or
239
+ `thrum agent runtime-config set <agent_name> --model <from runtime.role_models, per choosing-subagent-models>`) and relaunch BEFORE
235
240
  assigning work. **Do not dispatch an unpinned implementer** — the daemon's
236
241
  role-default backstop (`jq -r '.runtime.role_models' .thrum/config.json`) is a
237
242
  net for a forgotten pin, not a substitute for this check.
@@ -329,9 +334,9 @@ Handle each message type:
329
334
  2. Dispatch BOTH reviewers IN PARALLEL (one Agent call per reviewer in the same
330
335
  response). Block until BOTH return:
331
336
  - Code-quality: `superpowers:code-reviewer` (or `feature-dev:code-reviewer`
332
- if the project provides one) — `model: "sonnet"`
337
+ if the project provides one) — `model: <per choosing-subagent-models>`
333
338
  - Spec-compliance: `general-purpose` reviewer cross-referencing the plan/
334
- spec — `model: "sonnet"`
339
+ spec — `model: <per choosing-subagent-models>`
335
340
  3. **Verify** every cited `file:line` claim against the actual source before
336
341
  forwarding. Reviewers can misread files; forwarding unverified findings
337
342
  wastes the implementer's time.
@@ -389,10 +394,7 @@ Handle each message type:
389
394
  **Sub-agent model discipline (applies to ALL Agent tool calls in this phase and
390
395
  Phase 5):**
391
396
 
392
- > **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
393
- > (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
394
- > operator-ask or a skill step that names it. See the
395
- > `choosing-subagent-models` skill for the full policy.
397
+ > **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
396
398
 
397
399
  **Blocker:**
398
400
 
@@ -504,11 +506,11 @@ done
504
506
 
505
507
  **C. If conflicts arise:**
506
508
  Reading the conflicted files directly is permitted (merge-conflict carve-out
507
- in Scope Boundaries). Analyze the conflict using your plan/intent context to
509
+ in the Scope section of your preamble). Analyze the conflict using your plan/intent context to
508
510
  determine the correct resolution. Then spawn a targeted edit sub-agent:
509
511
 
510
512
  ```text
511
- Agent(subagent_type="general-purpose", model="sonnet",
513
+ Agent(subagent_type="general-purpose", model="<per choosing-subagent-models>",
512
514
  prompt="Resolve this specific merge conflict.
513
515
  File: <file-path>
514
516
  Conflicted section: <paste the <<<< ==== >>>> block>
@@ -618,18 +620,30 @@ can act on, which is how a guard gets disabled. Classify every hit — only a
618
620
  classifier failure is a real only-copy:
619
621
 
620
622
  ```bash
621
- # STAGE 2 — CLASSIFY every hit from stage 1 against ALL HISTORY, not the tip
622
- # tree (a tip-only check like `git cat-file -e origin/<ref>:<path>` flags
623
- # every file the 19-session sliding window has legitimately trimmed as
624
- # unrecoverable — over-reporting, not under-reporting, but still an alarm
625
- # nobody can act on):
626
- git log --all --oneline -- ".thrum/agents/<path>" | head -1
627
- # NON-EMPTY -> RECOVERABLE (in git history)
628
- # EMPTY -> ONLY-COPY — SALVAGE BEFORE REMOVAL
629
-
630
- # CONTROLS — the classifier must be able to both affirm and refuse:
631
- git log --all --oneline -- ".thrum/agents/<a-real-trimmed-path>" # must be NON-EMPTY
632
- git log --all --oneline -- ".thrum/agents/__nope__/x" # must be EMPTY
623
+ # STAGE 2 — classify every stage-1 hit. Test that a BLOB IS RETRIEVABLE,
624
+ # never that the path merely appears in the log: `git log -- <path>` also
625
+ # matches the commit that DELETED the file, and `| head -1` returns exactly
626
+ # that for a trimmed file.
627
+ git log --all --oneline --name-status -- ".thrum/agents/<path>" # read the A/M/D column; do NOT head -1
628
+ git cat-file -e "<add-or-modify-sha>:.thrum/agents/<path>" # rc=0 proves the BLOB EXISTS
629
+ git show "<that-sha>:.thrum/agents/<path>" > /tmp/x && cmp /tmp/x "<worktree-copy>"
630
+ # blob retrievable AND byte-identical -> RECOVERABLE
631
+ # otherwise -> ONLY-COPY — SALVAGE BEFORE REMOVAL
632
+ # Always check rc explicitly on git show/cat-file; never infer from output size.
633
+ # Form the cmp control from two files KNOWN to differ — comparing an
634
+ # accidentally-empty extraction against /dev/null reports "identical" and
635
+ # reads as a passing control.
636
+
637
+ # CONTROLS — the classifier must be able to both affirm and refuse.
638
+ # Exercise BOTH halves of the decision: existence (cat-file -e) AND
639
+ # byte-identity (cmp). Controlling only existence leaves the cmp step
640
+ # unguarded — and cmp is where an accidentally-empty extraction reads
641
+ # as "identical" and passes.
642
+ git cat-file -e "<add-or-modify-sha>:.thrum/agents/<path>"; echo "rc=$? (must be 0)"
643
+ git cat-file -e "<add-or-modify-sha>:.thrum/agents/__nope__/x"; echo "rc=$? (must be NON-ZERO)"
644
+ printf 'x' > /tmp/ctl-differs
645
+ cmp -s /tmp/x /tmp/ctl-differs; echo "rc=$? (must be NON-ZERO — proves cmp CAN detect a difference)"
646
+ cmp -s /tmp/x /tmp/x; echo "rc=$? (must be 0 — proves cmp CAN affirm)"
633
647
  ```
634
648
 
635
649
  ```bash
@@ -719,7 +733,7 @@ Run review rounds; converge to zero BLOCKING:
719
733
  **Round N:**
720
734
 
721
735
  1. Dispatch BOTH reviewers IN PARALLEL — code-quality (`feature-dev:code-reviewer`,
722
- `model: "sonnet"`) + spec-compliance (`general-purpose`, `model: "sonnet"`).
736
+ `model: <per choosing-subagent-models>`) + spec-compliance (`general-purpose`, `model: <per choosing-subagent-models>`).
723
737
  **In each reviewer dispatch prompt, mandate structured severity:**
724
738
  > "Label every finding BLOCKING / IMPORTANT / MINOR. At least one label per
725
739
  > finding, prefix each finding line."
@@ -775,7 +789,7 @@ them, forward to coordinator at merge-approval.
775
789
  **Hard cap — 2 rounds max:**
776
790
  If BLOCKING findings remain after round 2:
777
791
 
778
- - Step A: REMOVED. sonnet-medium is the implementer floor, so there is no
792
+ - Step A: REMOVED. The implementer tier is the floor, so there is no
779
793
  lower tier to escalate from. A round-2 BLOCKING failure goes straight to
780
794
  Step B.
781
795
  - Step B (escalate up): if the implementer fails to converge, escalate to coordinator
@@ -793,3 +807,30 @@ EOF
793
807
  ```
794
808
 
795
809
  Do not proceed without approval when autonomy is `per_epic`.
810
+
811
+ ### Tier-swap: replace an underperforming implementer in the same worktree
812
+
813
+ Use when the first review shows multiple BLOCKING findings, systematic misunderstanding of the task, or an agent clearly going long. The swap reuses the SAME worktree: retire the underperforming agent and relaunch a fresh one under a NEW name in place. Never `thrum agent delete` (operator-only, gated to the coordinator; orchestrators are refused). The swapped-out agent is retired with `set-phase retired`; its registry row, messages and transcript are retained.
814
+
815
+ Step 1: kill the old agent's tmux session first, so its pid is dead. A live-pid identity file is preserved and not quarantined; a dead pid lets the new create quarantine it.
816
+ thrum tmux kill <same_worktree_name>
817
+ Step 2: retire the old agent. It keeps the registry row (Retired tab). `set-phase` is not operator-gated. Retiring does not free the identity; Step 4's create does.
818
+ thrum agent set-phase retired --agent <underperforming_agent_name>
819
+ Step 3: verify the worktree is intact (WIP code preserved).
820
+ ls <worktree-path>
821
+ Step 4: launch a fresh ephemeral identity under a NEW name in the SAME worktree, pinned on both create and launch from `runtime.role_models` (per `choosing-subagent-models`). `--intent` carries the orient-from-WIP one-liner.
822
+ thrum tmux create <same_worktree_name> --cwd <worktree-path> --name <new_agent_name> --role implementer --module <module> --mode ephemeral --identity ephemeral --model <per runtime.role_models> --effort <per runtime.role_models> --intent "tier-swap: orient in the worktree (WIP + first-review findings) and continue"
823
+ thrum tmux launch <same_worktree_name> --runtime claude --model <per runtime.role_models> --effort <per runtime.role_models>
824
+ Step 5: deliver the WIP pointer and first-review findings (a cold handoff: the code plus the findings).
825
+ thrum send --to @<new_agent_name> --stdin <<'EOF'
826
+ Tier-swap pickup: <WIP summary + first-review findings>
827
+ EOF
828
+
829
+ The pickup prompt (Step 5) must include:
830
+ You are picking up in-progress work from a prior agent that was replaced.
831
+ Context:
832
+ - Worktree: <path> — contains partial implementation, review it with git diff
833
+ - Task: <epic-id> / <task description>
834
+ - First-review findings from the prior pass:
835
+ <paste the consolidated finding list here>
836
+ - Your goal: address all BLOCKING findings + complete the remaining task scope.