@jjanczur/tyran 0.1.18 → 0.1.20

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.
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  <img src="https://img.shields.io/badge/dependencies-0-success" alt="Zero dependencies">
9
9
  <img src="https://img.shields.io/badge/Claude_Code-plugin-d4a017" alt="Claude Code plugin">
10
10
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache-2.0"></a>
11
- <a href="https://github.com/jjanczur/tyran/releases/latest"><img src="https://img.shields.io/github/v/release/jjanczur/tyran?color=d4a017" alt="Latest release"></a>
11
+ <a href="https://www.npmjs.com/package/@jjanczur/tyran"><img src="https://img.shields.io/npm/v/@jjanczur/tyran?color=d4a017&label=version" alt="Latest version"></a>
12
12
  </p>
13
13
 
14
14
  <p align="center">
@@ -20,464 +20,221 @@
20
20
 
21
21
  <h3 align="center">The more you use it, the better it gets.</h3>
22
22
 
23
- <p align="center">
24
- Never written a skill, spun up a subagent, or run an agent team yourself? Tyran does all
25
- three automatically, on your behalf — and the retrospective it runs after every initiative
26
- means it keeps learning your repo's way of working instead of repeating a generic playbook.
27
- </p>
28
-
29
- <p align="center">
30
- Under the hood: it interviews you, plans, and drives a team of fresh-context agents through
31
- your work, routing every subtask to the cheapest model that can actually do it — so a file
32
- rename doesn't burn through your subscription at top-tier rates.
33
- </p>
34
-
35
- ---
36
-
37
- ## The Problem
38
-
39
- Four failures, all of them ordinary, all of them silent. You will recognise
40
- every one.
41
-
42
-
43
- | | What happens | What it costs you |
23
+ ## What Tyran is
24
+
25
+ Every long Claude Code session ends the same way. The context fills up, the
26
+ plan is somewhere in the scrollback, and *"the tests pass"* is a sentence
27
+ rather than something you can check. Start a new session and you start
28
+ explaining from the beginning.
29
+
30
+ Tyran is a plugin that moves the work off the chat window. You describe a task;
31
+ it interviews you until the goal is unambiguous, sizes it, and drives
32
+ **fresh-context subagents** through it — a scout that only reads, an
33
+ implementer per story on its own branch, a reviewer holding no editing tools so
34
+ it cannot patch what it is grading. Every decision, spawn, report, merge and
35
+ open question is appended to a journal **committed to your repo**, and every
36
+ file you read afterwards is generated from that journal. A restart, a
37
+ compaction and a colleague on another branch all read the same thing.
38
+
39
+ Two rules are what make that worth the trouble. A report containing no raw
40
+ command output is **rejected by a hook**, not by good intentions. And every
41
+ write is classified against a policy file you own **before it happens**, so
42
+ *autonomous* is a setting with a blast radius rather than a promise.
43
+
44
+ ![The Tyran dashboard, recorded live, moving through its four tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost](assets/board-demo.gif)
45
+
46
+ ## What it gives you
47
+
48
+ - **A model tier per role, resolved from one config file.** Model names appear
49
+ in exactly one place; skills, agents and policies are written in role names.
50
+ The expensive tier is kept for security review, arbitration and final
51
+ acceptance, and the first two sit on a floor no profile or risk flag crosses.
52
+ - **Fresh context for every subagent.** Handoffs are self-contained, so the
53
+ conductor holds the plan and never accumulates its agents' transcripts.
54
+ - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
55
+ rejects a report with no raw command output — measured on 55 real reports
56
+ from this project's own agents: 53 pass, and both misses were not reports. It
57
+ blocks silence, not forgery; [the evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) is
58
+ precise about the difference.
59
+ - **State you can read without a session.** The journal is the single source of
60
+ truth; `STATE.md`, `PROGRESS.md`, `BOARD.md`, `board.json` and `board.html`
61
+ are generated projections of it.
62
+ - **A retrospective after every initiative.** It writes durable facts about
63
+ your repo into `.tyran/knowledge/`, and repeated failures graduate out of
64
+ `MISTAKES.md` into rules.
65
+ - **A spend ledger.** `npx @jjanczur/tyran cost` reports what the work cost, in
66
+ the tokens the platform itself reported, per model, per agent type and per
67
+ ticket — read out of the transcripts Claude Code already writes. Money
68
+ appears only under a rate card you write: Tyran does not know what you pay.
69
+ - **It can run overnight, because the usage limit is a wind-down and not a
70
+ crash.** The platform's own behaviour at the limit is a cliff: calls start
71
+ failing mid-flight and agents die between a write and its commit. Near the
72
+ threshold Tyran instead checkpoints, commits the state files, schedules a
73
+ resume and stops — then a watcher wakes at the window reset and continues the
74
+ same session. Leave it working and read the board in the morning. Both
75
+ windows were hit live while the feature was being built; the protocol that
76
+ survived them is what shipped. See [overnight mode](https://jjanczur.github.io/tyran/overnight/).
77
+
78
+ ## Tyran vs. an ordinary session
79
+
80
+ The axis, not the winner — a comparison that can be made without guessing at
81
+ anyone's internals.
82
+
83
+ | | An ordinary agent session | Tyran |
44
84
  |---|---|---|
45
- | 🟥 **Fake green** | *"Done — all tests pass."* Nothing was run. | You find out at review, or at deploy. The report was cheaper to write than the work. |
46
- | 🟥 **Wrong model, wrong job** | The strongest, most expensive model renames a file, changes a button colour, runs a mechanical sweep. | You pay top rate for work any cheap tier does identically. Nobody notices, because it *worked*. |
47
- | 🟥 **Context collapse** | Nobody compacts on purpose. The window fills to 60, 70%. Auto-compact then fires **in the middle of a hard debugging run**. | The fine detail the model had just discovered — the thing that took an hour — is gone, and it does not know it is gone. |
48
- | 🟥 **Amnesia** | State lives in a chat window. Another dev, another branch, tomorrow morning — none of them can see where this got to. | The work is re-derived, or worse, half re-derived. |
49
-
50
- **Context collapse is the expensive one**, and it is worth being precise about
51
- why. Above roughly half the window, the model is carrying so much that it
52
- starts missing things it would have caught at 10%. And the compaction that
53
- should relieve that pressure is the very thing that destroys the detail:
54
-
55
- ```mermaid
56
- flowchart LR
57
- subgraph BAD["❌ one agent carries everything"]
58
- direction LR
59
- B1["0%<br/>sharp"] --> B2["50%<br/>still fine"] --> B3["70%<br/>missing things"] --> B4["auto-compact<br/>mid-debug"] --> B5["detail gone —<br/>and it does not<br/>know it is gone"]
60
- end
61
- classDef bad fill:#7f1d1d,stroke:#f87171,color:#fef2f2
62
- classDef warn fill:#78350f,stroke:#fbbf24,color:#fffbeb
63
- class B3,B4,B5 bad
64
- class B2 warn
65
- ```
85
+ | Where execution state lives | the chat window, and it ends with the window | an append-only journal committed to your repo, with every human-readable file generated from it |
86
+ | What makes a report trustworthy | you read the claim | a hook refuses a report with no raw command output |
87
+ | Which model does which job | one model for the whole session | four tiers resolved from `.tyran/config.yaml`, per role, with a floor under the judgements everything downstream trusts |
88
+ | What happens after the work | nothing | a retrospective writes what this repo taught it back into this repo |
89
+ | What it adds to your install | — | zero runtime dependencies, no build step |
66
90
 
67
- ## The Solution
91
+ ## Tyran vs. other Claude Code orchestrators
68
92
 
69
- **Split the work so nobody has to carry all of it**, and put the state in a
70
- file instead of a window:
93
+ Five rows of eleven, verified against those projects' **code and public issue
94
+ trackers** (July 2026) rather than their READMEs. ✅ shipped and enforced ·
95
+ ⚠️ partial or prompt-only · ❌ absent or broken · 🎯 committed in the design,
96
+ ships test-gated.
71
97
 
72
- ```mermaid
73
- flowchart TB
74
- OP(["you"]) -->|"describes the work"| C["<b>conductor</b><br/>plans · delegates · merges<br/><i>stays lean — it holds the plan,<br/>not the transcripts</i>"]
75
-
76
- C -->|"self-contained handoff"| S["<b>scout</b><br/>fresh context<br/><i>cheap tier</i>"]
77
- C -->|"self-contained handoff"| I["<b>implementer</b><br/>fresh context · own worktree<br/><i>work tier</i>"]
78
- C -->|"self-contained handoff"| R["<b>reviewer</b><br/>fresh context · never the author<br/><i>work tier, top tier on security</i>"]
79
-
80
- S & I & R -->|"report"| G{{"✋ EVIDENCE GATE<br/>raw command output,<br/>or the report is REFUSED"}}
81
- G --> J[("append-only journal<br/>.tyran/ — committed to YOUR repo")]
82
- J -->|"survives restart,<br/>compaction, and you"| C
83
- J --> D["another dev · another branch<br/>· tomorrow morning"]
84
- J --> RT{{"✋ RETRO GATE<br/>the initiative cannot end<br/>without learning something"}}
85
- RT -->|"improves"| C
86
-
87
- classDef gate fill:#7f1d1d,stroke:#f87171,color:#fef2f2
88
- classDef store fill:#064e3b,stroke:#34d399,color:#ecfdf5
89
- class G,RT gate
90
- class J store
91
- ```
92
-
93
-
94
- Each of the four failures gets a mechanism, not a paragraph of advice:
95
-
96
- | Failure | Mechanism | State |
97
- |---|---|---|
98
- | Fake green | A `SubagentStop` hook **rejects** a report with no raw command output. Measured on 55 real reports: 53 pass, and both misses were not reports. | ✅ shipped |
99
- | Wrong model | Every role resolves to a tier from **one config file**. `top` — the expensive one — is reserved for security review, arbitration and acceptance, and a floor stops any profile or flag pushing those down. Effort is a **separate dial**: *same model, think harder* costs nothing extra. | ✅ shipped |
100
- | Context collapse | Work goes to **fresh-context subagents** with self-contained handoffs, so the conductor never accumulates their transcripts. A `PreCompact` hook checkpoints before every compaction and **refuses a manual `/compact` it could not checkpoint**; `SessionStart` re-injects that checkpoint afterwards. | ✅ shipped · 🎯 a trigger that says *"compact now, this section is finished"* is **not built** |
101
- | Amnesia | The journal is an append-only file **in your repo**, not in a window. `STATE.md` and `PROGRESS.md` are generated from it. Another agent, another dev, another branch reads where this got to — including which agent is still running and which lease nobody released. | ✅ shipped |
102
-
103
- **Cheap where it doesn't matter, expensive where it does.** That is the whole
104
- cost argument, and it is why the routing table is a table and not a vibe:
105
-
106
- ```mermaid
107
- flowchart LR
108
- T1["<b>cheap</b><br/>recon · sweeps · bookkeeping"] --- T2["<b>work</b><br/>implementation<br/>ordinary review<br/><i>the default</i>"] --- T3["<b>deep</b><br/>root-cause · hard builds<br/>risky review"] --- T4["<b>top</b><br/>security review<br/>arbitration · acceptance<br/><i>and nothing else</i>"]
109
- classDef c fill:#064e3b,stroke:#34d399,color:#ecfdf5
110
- classDef w fill:#1e3a5f,stroke:#60a5fa,color:#eff6ff
111
- classDef d fill:#78350f,stroke:#fbbf24,color:#fffbeb
112
- classDef t fill:#7f1d1d,stroke:#f87171,color:#fef2f2
113
- class T1 c
114
- class T2 w
115
- class T3 d
116
- class T4 t
117
- ```
118
-
119
- ### And then it gets better on its own
98
+ | Capability | **Tyran** | oh-my-claudecode | metaswarm | pilotfish | pro-workflow |
99
+ |---|:---:|:---:|:---:|:---:|:---:|
100
+ | Evidence contract that **blocks**: no raw command output → report rejected | ✅ | ⚠️ advisory¹ | ⚠️ prompt | ⚠️ prompt | ❌ |
101
+ | Execution state survives restart & compaction (journal + re-inject) | ✅ | ⚠️ | ❌² | ❌ | ⚠️ |
102
+ | Plugin update **never** destroys local learning (3 layers + delta agent) | 🎯 | ❌³ | — | — | ⚠️ |
103
+ | Secret gate on commit/push with verified scan coverage, no `--no-verify` escape | ✅ | ❌ | ❌ | ❌ | ⚠️ |
104
+ | Clean install: 2 commands, **never writes into your `~/.claude`** | ✅ | ❌³ | ⚠️ | ❌ | ⚠️ |
120
105
 
121
- An initiative that ends without a retrospective is **refused one turn** by a
122
- `Stop` hook. The retro reads the ledger, the notes and the agents' own
123
- reports, and changes Tyran itself — through a filter whose default answer is
124
- *change nothing*, which prefers **deleting a rule to adding one**, and which
125
- is explicitly told not to breed agents, because a roster nobody can hold in
126
- their head is its own cognitive tax.
106
+ ¹ Their deliverable check is explicitly non-blocking. ² Their issues
107
+ #32/#33/#36: a crash loses loop state. ³ Open issues #3535/#3536: an update
108
+ deletes user files from `~/.claude`. The other six rows — repo-specific
109
+ learning, cost tiers, independent review, context budget, safe parallelism, OSS
110
+ hygiene — and every footnote in full are in
111
+ [the FAQ](https://jjanczur.github.io/tyran/faq/#how-tyran-compares-to-other-claude-code-orchestrators).
127
112
 
128
- ```text
129
- Initiative 1 Infers your stack, your validation commands, your deployment
130
- style from how the repo is actually worked. Asks once, about
131
- what it genuinely could not establish.
132
- Initiative 5 Knows your shared-file hot zones, your flaky tests, your
133
- review taste. Its retro has already DELETED two of its own
134
- rules that weren't earning their keep.
135
- Initiative 20 Has written repo-specific skills for your recurring work and
136
- merged two agents that overlapped. You mostly approve gates.
137
- ```
113
+ Worth knowing before tuning anything: cache reads were measured at roughly
114
+ three quarters of a real session's cost, and the conductor's own context at
115
+ between 44% and 86% of a tree's tokens — so the lever is context size and turn
116
+ count, not the price of a model.
138
117
 
139
- > **Three things are not built yet:** the update delta-review, cost-profile
140
- > benchmark receipts, and overnight mode. Everything else on this page exists
141
- > in code with tests behind it — nothing here is claimed before it ships, and
142
- > the [roadmap](#roadmap) says which is which.
118
+ ## Install
143
119
 
144
- ## Quick Start
120
+ Inside Claude Code:
145
121
 
146
122
  ```text
147
123
  /plugin marketplace add jjanczur/tyran
148
124
  /plugin install tyran@tyran
149
- /tyran:setup # scans the repo, writes .tyran/, installs /tyran
150
- /tyran # then just describe what you want done
125
+ /tyran:hello
151
126
  ```
152
127
 
153
- **Or paste this into Claude Code and let it install itself.** `/plugin` is a
154
- slash command a human has to type, so this asks for the same two steps
155
- through the `claude` CLI instead, which Claude Code can run on its own —
156
- followed by the restart those steps require, and a walkthrough of what setup
157
- inferred before it is trusted:
128
+ Restart Claude Code afterwards — hooks and agents are read when a session
129
+ starts, so an install you have not restarted into is an install you are not
130
+ running. `/tyran:hello` is the smoke test. The only requirement is **Claude
131
+ Code ≥ 2.1**: the scripts ship with the plugin and Claude Code runs them, so
132
+ there is nothing to install and no version of anything else to match.
133
+ `/plugin` is a slash command a human has to type — the prompt that has Claude
134
+ Code install itself, the npm package for a shell or a CI job, updating and
135
+ uninstalling are all in
136
+ [getting started](https://jjanczur.github.io/tyran/getting-started/).
137
+
138
+ ## Use it
158
139
 
159
140
  ```text
160
- Install the Tyran plugin in this repository and set it up for me.
161
-
162
- 1. Run: claude plugin marketplace add jjanczur/tyran
163
- 2. Run: claude plugin install tyran@tyran
164
- 3. Tell me to restart Claude Code, so the hooks and agents load.
165
- 4. After the restart, run /tyran:setup, then /tyran:doctor. Setup writes the
166
- two files under .tyran/ that Tyran needs - the config, and the autonomy
167
- policy the write gate reads - and doctor proves the install actually
168
- works. Walk me through what setup inferred - especially the validation
169
- commands and the deployment autonomy class - before we commit it.
170
-
171
- Docs: https://jjanczur.github.io/tyran/getting-started/
141
+ /tyran:setup # once per repo: scans it, writes .tyran/, installs /tyran
142
+ /tyran # then describe what you want done
172
143
  ```
173
144
 
174
- Setup infers your stack, your validation commands and your deployment
175
- autonomy class from how the repo is actually worked, annotates every value
176
- with the fact that produced it, and asks you only about what it genuinely
177
- could not establish. It also installs the bare `/tyran` shortcut — plugin
178
- skills are namespaced, so the conductor is `/tyran:run`, and most people
179
- would rather type four letters.
180
-
181
- Then `/tyran` interviews you, sizes the work, and either does it itself
182
- (small changes) or drives the roster — `tyran:scout`, `tyran:implementer`,
183
- `tyran:reviewer`, `tyran:retro` — through it. Also: `/tyran:status`,
145
+ Setup infers your stack, your validation commands and your deployment autonomy
146
+ class from how the repo is actually worked, annotates every value with the fact
147
+ that produced it, and asks only about what it could not establish. `/tyran`
148
+ then interviews you, sizes the work, and either does it itself or drives the
149
+ roster — `tyran:scout`, `tyran:implementer`, `tyran:reviewer`, `tyran:retro` —
150
+ through it, stopping only at genuine decisions. Also `/tyran:status`,
184
151
  `/tyran:doctor`, `/tyran:retro`.
185
152
 
186
- ### It is not only an orchestrator — it ships skills you can use yourself
187
-
188
- Fourteen skills and four agents come with the plugin. Six of the skills are
189
- the conductor's own machinery, but they are **commands, not internals**: you
190
- run `/tyran:doctor` on a repo you are debugging without ever starting an
191
- initiative. The other eight are standalone protocols — most of them have
192
- nothing to do with orchestration and work perfectly well in a session that
193
- never starts an initiative at all.
194
-
195
- | Skill | What it does |
196
- |---|---|
197
- | [`run`](skills/run/SKILL.md) | the conductor — interviews, sizes, plans, delegates, merges |
198
- | [`setup`](skills/setup/SKILL.md) | reads the repo and writes `.tyran/config.yaml`, provenance per value |
199
- | [`status`](skills/status/SKILL.md) | where an initiative got to, from the journal rather than from memory |
200
- | [`doctor`](skills/doctor/SKILL.md) | is any gate installed but unable to fire; is the state self-consistent |
201
- | [`retro`](skills/retro/SKILL.md) | the anti-bloat curator that changes Tyran, never your product code |
202
- | [`hello`](skills/hello/SKILL.md) | proves the plugin is installed and its paths resolve |
203
- | [`code-review`](skills/code-review/SKILL.md) | **standalone.** The dimensions a diff is read against, and the rule that you refute a finding before reporting it |
204
- | [`root-cause`](skills/root-cause/SKILL.md) | **standalone.** Reproduce first, one variable per experiment with the prediction written down, exit by naming the mechanism |
205
- | [`browser-check`](skills/browser-check/SKILL.md) | **standalone.** A UI pass that returns counts — console errors, failed responses, computed styles — instead of "looks fine" |
206
- | [`deslop`](skills/deslop/SKILL.md) | **standalone.** The optimization pass: delete before you add, one smell per pass, behaviour pinned by a test that ran first |
207
- | [`pr-feedback`](skills/pr-feedback/SKILL.md) | **standalone.** All three of GitHub's comment surfaces, a disposition for every comment, push before you reply |
208
- | [`fidelity-gate`](skills/fidelity-gate/SKILL.md) | **standalone.** Build 1:1 against a frozen mockup without drift, measured rather than eyeballed |
209
- | [`prompt-tuning`](skills/prompt-tuning/SKILL.md) | **standalone.** Tune anything whose quality is a non-deterministic model output — noise baseline first, then medians |
210
- | [`skill-writing`](skills/skill-writing/SKILL.md) | **standalone.** What a skill has to earn before it ships, and the activation test that proves it fires |
211
-
212
- Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story,
213
- own branch), `tyran:reviewer` (**no editing tools** — it cannot patch what it
214
- is grading), `tyran:retro`. What each one assumes, and who is expected to
215
- invoke it, is in [skills and agents](docs/skills.md); the tier and effort
216
- routing behind them is in [the roster](docs/agents.md).
217
-
218
- The standalone protocols exist because the rule alone was not enough.
219
- `fidelity-gate` had been inlined into three sentences and lost the inventory
220
- step that does the work; `prompt-tuning` kept its principle and lost
221
- everything the principle was distilled from. The rest were dangling
222
- references — the conductor ordered a browser pass, an optimization pass and a
223
- review without saying what any of them was, so each meant whatever the agent
224
- felt like that afternoon. **A skill is admitted here only when something
225
- already asks for the protocol by name**, which is why there are fourteen and
226
- not forty; the ceiling on their combined description length is enforced in
227
- CI, and raising it is an owner decision rather than a retrospective's.
228
-
229
153
  Hit the brake at any time, from anywhere, without killing the session:
230
154
 
231
155
  ```bash
232
156
  echo "wrong branch — hold everything" > .tyran/STOP
233
157
  ```
234
158
 
235
- ## What makes Tyran different
236
-
237
- - 🧾 **Proof-or-it-didn't-happen.** Agent reports without raw command output
238
- (exit codes, `X passed / Y failed`) are rejected *mechanically* at the
239
- `SubagentStop` hook — not by asking nicely in a prompt. **This gate blocks
240
- SILENCE, not FORGERY:** an agent that invents the text `232 passed / 0
241
- failed` walks straight through it. The gate raises the price of a lie — it
242
- has to be deliberately fabricated rather than simply waved away — and it does
243
- not remove it. Nor is the criterion "raw command output" — mechanically it is
244
- *"a digit next to one of seven test-runner keywords"*, so a build log without
245
- an exit code is refused and a sentence containing `6 / 6 passed` is not.
246
- Measured on 55 real reports from this project's own agents: 53 pass, and both
247
- misses turned out not to be reports at all. Details, numbers in both
248
- directions, and limits in [the evidence gate](docs/evidence-gate.md).
249
- - 🔁 **It learns *your* workflow — and the loop closes itself.** When an
250
- initiative's tickets are all merged with no retrospective recorded since
251
- the last merge, a `Stop` hook refuses **one** turn and names what is owed.
252
- `tyran:retro` then distills your repo's rules into `.tyran/knowledge/` and
253
- tunes Tyran's own playbook, through an anti-bloat filter with four
254
- questions, a hard cap of three edits per retrospective, and a stated
255
- preference for deleting rules over adding them — so *"I changed nothing"*
256
- is a correct outcome, and so is declining the retro entirely. What was
257
- learned reaches the agent that needs it: every handoff carries a budgeted
258
- **knowledge brief** of the entries that apply to the files at hand, and
259
- each agent's report grades the entries it received, so the store is
260
- pruned on evidence. **You are
261
- never blocked twice**, whichever you choose. This is a gate rather than a
262
- sentence in a skill because the retro is the step most easily skipped: it
263
- happens after the merge, when the interesting part is over.
264
- - 🔁 **Survives restarts and compaction.** Execution state lives in an
265
- append-only journal in your repo; a session hook re-injects it after every
266
- compaction or resume. The team forgets nothing.
267
- - 🎯 **Update-safe evolution.** *(designed, not built.)* Three layers:
268
- immutable core plugin · your repo's data (`.tyran/`) · locally evolved
269
- skills. The layout is real — `.tyran/` exists and is never written by the
270
- plugin's own files — but the delta-review agent that reconciles a new core
271
- version with what your repo has learned does not exist yet.
272
- - 💰 **Cost modes that resolve from config, not from habit.** Model names
273
- appear in exactly ONE file. Everything else — skills, agents, policies — is
274
- written in role names, so a model deprecation is a one-line edit instead of
275
- a sweep through every prompt. `node scripts/tiers.mjs --role reviewer`
276
- answers with an alias; `--risk high` escalates one tier. The default puts
277
- everyday work on the mid tier and reserves the expensive ones for calls
278
- where being wrong is both costly and hard to notice — and **security review
279
- and arbitration have a floor no profile or risk flag can push them below**,
280
- because otherwise `eco` would quietly become a one-flag downgrade of the two
281
- judgements everything downstream trusts. A missing alias throws rather than
282
- falling back to the session default: routing that silently does nothing
283
- looks exactly like routing that works.
284
- - 🔒 **Autonomy with a gate on the irreversible step.** Every commit and push
285
- is scanned for secrets before it happens — the gate assembles the payload
286
- itself and verifies the scanner covered all of it, so a `.gitattributes`
287
- line cannot hide anything from it. `--no-verify` (and its abbreviations) and
288
- force-pushes are refused; a push to your production branch is refused at the
289
- strictest autonomy class, including through `HEAD`, `@`, a shell variable or
290
- a `git -c` alias. **What it does not do is stop an agent from raising the
291
- class itself:** the config file holding it is `AUTO` in the shipped policy,
292
- so an agent can edit it. That is deliberate — the same file holds your
293
- validation commands, and an agent that cannot correct a wrong one is an
294
- agent that runs your test suite wrong forever. Set the rule back to `GATED`
295
- in one word if you want the other trade. Autonomy classes are a convention
296
- the gate enforces downward, not a lock. Not a firewall, and
297
- [docs/hooks.md](docs/hooks.md) says exactly where it stops — including the
298
- scanner's own measured false-negative rate.
299
-
300
- ## How it compares
301
-
302
- Verified against competitors' **code and public issue trackers** (July 2026),
303
- not their READMEs. ✅ shipped/enforced · ⚠️ partial or prompt-only · ❌ absent
304
- or broken · — not applicable · 🎯 **committed in the v2 design, ships
305
- test-gated** (flips to ✅ only when the tests exist and pass).
306
-
307
- | Capability | **Tyran v2** | oh-my-claudecode | metaswarm | pilotfish | pro-workflow |
308
- |---|:---:|:---:|:---:|:---:|:---:|
309
- | Evidence contract that **blocks**: no raw command output → report rejected | ✅ | ⚠️ advisory¹ | ⚠️ prompt | ⚠️ prompt | ❌ |
310
- | Learns **your repo's** rules, with an anti-bloat curator + decision ledger | ✅⁹ | ⚠️ | ⚠️ | ❌ by design | ⚠️ regex-based |
311
- | Execution state survives restart & compaction (journal + re-inject) | ✅ | ⚠️ | ❌² | ❌ | ⚠️ |
312
- | Plugin update **never** destroys local learning (3 layers + delta agent) | 🎯 | ❌³ | — | — | ⚠️ |
313
- | Cost modes resolved from repo config (`eco`/`balanced`/`full`, role-based routing, model names in ONE file) | ✅ | ⚠️ docs-only | ❌ | ⚠️ global-only | ❌ |
314
- | Secret gate on commit/push with verified scan coverage, no `--no-verify` escape | ✅ | ❌ | ❌ | ❌ | ⚠️ |
315
- | Independent reviewer that never grades its own homework | ✅⁷ | ⚠️ | ⚠️ prompt | ⚠️ | ❌ |
316
- | Small curated core — no context tax, enforced in CI | ✅ | ❌⁴ | ⚠️ | ✅ | ❌ |
317
- | Safe parallelism: worktree per agent, leases, sequential merge | ✅⁸ | ⚠️ | ❌ | — | ❌⁵ |
318
- | Clean install: 2 commands, **never writes into your `~/.claude`** | ✅ | ❌³ | ⚠️ | ❌ | ⚠️ |
319
- | OSS hygiene: license, changelog, CI validation, pressure tests | ✅ | ⚠️ | ⚠️ | ✅ | ❌⁶ |
320
- | Skills · agents it ships, counted from the repo tree | 14 · 4¹⁰ | 41 · 19 | 14 · 19 | 0 · 8 | 41 · 8 |
321
-
322
- <sub>¹ Their deliverable check is explicitly non-blocking ("never prevents the
323
- agent from stopping"). ² Their issues #32/#33/#36: crash loses loop state.
324
- ³ Open issues #3535/#3536: update deletes user files from `~/.claude`.
325
- ⁴ Their issue #2943: "50+ skills exceeding context description budget."
326
- ⁵ Their issues #73/#74: worktree hook broke isolated spawns. ⁶ "MIT" badge
327
- links to a LICENSE file that does not exist in the repo; the GitHub API
328
- reports no license for it. ⁷ The reviewer agent is granted no editing tools,
329
- so it cannot patch what it is grading — but it keeps `Bash` in order to run
330
- the tests, and `Bash` can write. This raises the price of self-approval; it
331
- does not make it impossible. ⁸ Worktrees, leases and sequential merge are
332
- specified in the conductor skill, and lease events are recorded in the
333
- journal, so `STATE.md` surfaces a lease released by a non-holder. Detection,
334
- not prevention: nothing physically stops a second agent from entering a held
335
- worktree. ⁹ The retrospective is triggered by a `Stop` gate and the curator's
336
- filter is enforced in the agent's own contract, but what it decides to record
337
- is a judgement, not a mechanism — and the gate deliberately accepts "I am
338
- skipping this" as a complete answer. ¹⁰ <b>The one row where a bigger number
339
- is not a better one, printed anyway.</b> Measured on each repo's default
340
- branch, July 2026: files matching <code>skills/*/SKILL.md</code> and
341
- <code>agents/*.md</code>. Two competitors ship three times as many skills as
342
- Tyran does, and that is the point of the "small curated core" row above —
343
- oh-my-claudecode's own issue #2943 is titled "50+ skills exceeding context
344
- description budget", which is the bill that arrives with the larger number.
345
- Tyran's fourteen are held under a description budget CI enforces on every
346
- push (4352 of 5000 characters, and a test fails if this sentence and the
347
- script ever disagree). That ceiling was 4000 for the first eight skills and
348
- was raised once, deliberately, with the reason in the changelog — the
349
- distinction being that #2943 describes a budget that was <i>exceeded</i>, and
350
- an agent here may propose a raise but not perform one. Counting files is not
351
- counting value: what each skill is for is in <a href="skills/">skills/</a>,
352
- one directory each.</sub>
353
-
354
- ## Command-line use (outside Claude Code)
355
-
356
- Published on npm as [`@jjanczur/tyran`](https://www.npmjs.com/package/@jjanczur/tyran)
357
- — scoped, not the bare name `tyran`, which carries an unpublish tombstone from
358
- 2021-03-30 that npm's abuse policy blocks anyone from reusing, permanently. The
359
- command stays `tyran` either way; only the registry name is scoped, the same
360
- pattern as `@angular/cli` giving you `ng`. `bin/tyran.mjs` exposes the same
361
- scripts the plugin's hooks and skills already call — `doctor`, `scan-repo`,
362
- `tiers`, `journal`, `schema`, `knowledge`, `board`, `cost`, `answer`, `overnight`, `statusline`, `stop-check`,
363
- `scan-control-chars`, `desc-budget` — for a shell or a CI job with no Claude
364
- Code session. Zero dependencies; `--help` lists them.
159
+ ## The dashboard
365
160
 
366
161
  ```bash
367
- npx @jjanczur/tyran doctor --hooks # is any gate installed but unable to fire?
368
- npx @jjanczur/tyran scan-repo --dir . # what this repo looks like, with provenance
369
- npx @jjanczur/tyran answer render # the sheet of questions waiting on you
162
+ npx @jjanczur/tyran board --dir .tyran --serve
370
163
  ```
371
164
 
372
- Exit codes propagate to the digit, so a CI step reddens exactly when the
373
- underlying script does.
165
+ A read-only board on loopback, re-rendered on every request. That command is
166
+ the one place a Node version matters — `npx` runs the scripts outside Claude
167
+ Code, and they need **Node ≥ 22**. Four tabs, because the page answers four
168
+ questions:
169
+
170
+ - **Overview** — what is waiting on you, agents running, progress, tickets that
171
+ need a human; then the agent strip, each chip carrying the time since that
172
+ agent last signalled.
173
+ - **Board** — every ticket in exactly one of ten kanban lanes, strongest verdict
174
+ first. Click a card for its initiative, agents, note and spend.
175
+ - **Waiting on you** — the open questions with their recommendations and
176
+ recorded defaults, above the commands that answer them. The count sits in the
177
+ tab label, so a pending question survives being on another tab.
178
+ - **Spend** — tokens, the amount under your rate card, the conductor's share, a
179
+ composition bar across input / cache write / cache read / output, and three
180
+ ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
181
+
182
+ The same page is written to `.tyran/state/board.html` and refreshed after every
183
+ agent, so you can also just open the file. Spend is served rather than embedded
184
+ and absent over `file://` — [the board](https://jjanczur.github.io/tyran/board/) says why.
185
+
186
+ ## What ships
187
+
188
+ Fourteen skills and four agents. Six of the skills are the conductor's own
189
+ machinery, though commands rather than internals — `/tyran:doctor` runs on any
190
+ repo, initiative or not — and the other eight are standalone protocols.
374
191
 
375
- > **This does not install the Claude Code plugin.** For that, run
376
- > `/plugin marketplace add jjanczur/tyran` inside Claude Code — that name is
377
- > the Claude Code marketplace identity, a separate namespace from npm. The npm
378
- > package is the tooling; the plugin is the conductor.
192
+ | Skill | What it does |
193
+ |---|---|
194
+ | `run` | the conductor — interviews, sizes, plans, delegates, merges |
195
+ | `setup` | reads the repo and writes `.tyran/config.yaml`, provenance per value |
196
+ | `status` | where an initiative got to, from the journal rather than from memory |
197
+ | `doctor` | is any gate installed but unable to fire; is the state self-consistent |
198
+ | `retro` | the anti-bloat curator that changes Tyran, never your product code |
199
+ | `hello` | proves the plugin is installed and its paths resolve |
200
+ | `code-review` | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
201
+ | `root-cause` | reproduce first, one variable per experiment, exit by naming the mechanism |
202
+ | `browser-check` | a UI pass that returns counts — console errors, failed responses, computed styles |
203
+ | `deslop` | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
204
+ | `pr-feedback` | all three of GitHub's comment surfaces, a disposition for every comment |
205
+ | `fidelity-gate` | build 1:1 against a frozen mockup, measured rather than eyeballed |
206
+ | `prompt-tuning` | tune a non-deterministic output without chasing noise — noise baseline first |
207
+ | `skill-writing` | what a skill has to earn before it ships, and the test that proves it fires |
208
+
209
+ Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
210
+ branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
211
+ grading), `tyran:retro`. A skill is admitted only when something already asks
212
+ for the protocol by name, and every description is loaded into every session
213
+ whether the skill fires or not — so the combined length is capped and CI
214
+ enforces the cap (4352 of 5000 characters). What each one assumes, when it
215
+ fires and who invokes it, is in
216
+ [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
217
+ themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
218
+ it: 1297 unit tests, run with `node --test "tests/**/*.test.mjs"`.
379
219
 
380
220
  ## Documentation
381
221
 
382
- **Everything below also reads as a site: [jjanczur.github.io/tyran](https://jjanczur.github.io/tyran/)**
383
- — same text, with search, rendered diagrams and per-page status badges.
384
-
385
- - 📖 [Getting started](https://jjanczur.github.io/tyran/getting-started/)
386
- - 🧰 [Skills and agents](https://jjanczur.github.io/tyran/skills/) — all fourteen skills and four agents, what each assumes, and who invokes it
387
- - ⚙️ [Configuration](https://jjanczur.github.io/tyran/configuration/) — `.tyran/config.yaml`, cost profiles, autonomy classes
388
- - 🎭 [The roster and model routing](https://jjanczur.github.io/tyran/agents/) — the four agents, the tier and effort table, dynamic overrides, the `.tyran/STOP` brake (shipped)
389
- - 🏛️ [Architecture](https://jjanczur.github.io/tyran/architecture/) — the three layers, the journal, the hooks
390
- - 📜 [Journal reference](https://jjanczur.github.io/tyran/journal/) — the append-only event schema (shipped)
391
- - 🧾 [Projections](https://jjanczur.github.io/tyran/projections/) — generated `STATE.md` / `PROGRESS.md` and `--check` (shipped)
392
- - 🩺 [Doctor](https://jjanczur.github.io/tyran/doctor/) — `--state` consistency check: drift, orphan leases, dead policy rules (shipped)
393
- - 🪝 [Hook runtime](https://jjanczur.github.io/tyran/hooks/) — gates vs probes, why hooks fail open, and what the deadline really promises (shipped)
394
- - 🧾 [Evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) — the criterion, who it binds, the recorded escape hatch, and the line between silence and forgery (shipped)
395
- - 🛡️ [Policy gate](https://jjanczur.github.io/tyran/policy-gate/) — path classes, the deployment class, the one rule on reads, and where each stops (shipped)
396
- - 🧠 [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) — how Tyran learns your repo, and its guardrails
397
- - ❓ [FAQ](https://jjanczur.github.io/tyran/faq/)
398
- - 🤝 [Contributing](CONTRIBUTING.md) — not a docs-site page, so this one stays a repo link
399
-
400
- ## Strategic principles
401
-
402
- 1. **Native mechanisms only.** Built entirely on Claude Code's plugin surface:
403
- agent frontmatter, hooks, skills-dir plugins. No custom runtime. When the
404
- platform absorbs a capability, Tyran drops a layer instead of competing
405
- with the vendor.
406
- 2. **Enforcement over prompts.** A rule that matters becomes a hook or a
407
- script. Prose is for judgment; mechanisms are for discipline.
408
- 3. **Evidence over claims.** From agent reports to this README's comparison
409
- table: nothing is asserted without receipts.
410
- 4. **The repo is the memory.** All state and learned rules live in *your*
411
- repository as reviewable text files. No hidden databases, no build step,
412
- no silent degradation.
413
- 5. **Local evolution, curated upstream.** Tyran adapts to each repo locally;
414
- generalizable improvements travel to the core as pull requests.
415
- 6. **Autonomy earns trust in layers.** Detected once, confirmed with you, and
416
- enforced downward by the policy gate. Not *"never self-escalated"* — the
417
- file holding the class is `AUTO`, so an agent can edit it, chosen so that
418
- an agent can also repair the validation commands stored beside it.
419
- Measured, not assumed; see [the policy gate](docs/policy-gate.md).
420
-
421
- ## Roadmap
422
-
423
- - [x] Plugin skeleton, marketplace, CI (validate ×2, tests, description
424
- budget, gitleaks, semgrep)
425
- - [x] `.tyran/` state layer: append-only journal, knowledge schema, generated
426
- human-readable projections, `doctor --state`
427
- - [x] Enforcement hooks: evidence gate, secrets gate, policy gate, write
428
- guard, state re-inject, and `doctor --hooks` — which catches a gate
429
- that is installed but cannot fire
430
- - [x] `/tyran:run` conductor + the four-agent roster + role-to-model routing
431
- resolved from `.tyran/config.yaml`, plus the `.tyran/STOP` brake
432
- - [x] `/tyran:setup` repo scanner (never infers `P3`) + `/tyran:doctor`,
433
- `/tyran:status`, `/tyran:retro`, and the bare `/tyran` shortcut
434
- - [x] Self-improvement loop: a `Stop` gate that will not let an initiative
435
- end unretrospected, plus knowledge accumulation into `.tyran/knowledge/`
436
- - [ ] Cost-profile benchmark receipts (three runs per profile on a fixture,
437
- published as numbers rather than as a table of intentions)
438
- - [ ] Update delta-review: reconcile a new core version with what your repo
439
- has learned locally
440
- - [x] Overnight mode: usage-limit pause + scheduled resume — the statusline
441
- telemetry sidecar, a wind-down gate near the subscription window, and a
442
- watcher that resumes (or, on a days-away weekly reset, notifies and
443
- holds) — see [docs/overnight.md](docs/overnight.md)
444
- - [x] Read-only dashboard: the kanban board — `BOARD.md`/`board.json` next to
445
- every journal, one cross-initiative `board.html` in the landing page's
446
- own palette, refreshed on every subagent stop, plus `board.mjs --serve`
447
- - [x] The spend ledger: what the work actually cost, read out of the
448
- transcripts Claude Code already writes — tokens per model, per agent type
449
- and per ticket, money only under a rate card you write, and a Spend
450
- section the board fetches rather than embeds — see
451
- [docs/cost.md](docs/cost.md)
452
- - [x] The mistakes ledger: `MISTAKES.md` at your repo root — what went wrong
453
- here and how often — where three occurrences of one signature graduate a
454
- lesson into `.tyran/knowledge/` and five write a rule into your
455
- `CLAUDE.md`, inside Tyran's own fence — see
456
- [docs/self-improvement.md](docs/self-improvement.md)
457
-
458
- ## Where this came from
459
-
460
- Tyran started as a teaching problem. One of us was mentoring the other
461
- through learning to program, and the mentee kept hitting the same wall — not
462
- with the code, with the *tool*. Claude would ask a pile of hard questions at
463
- once, lose the thread halfway through the answer, and burn a small fortune in
464
- tokens re-deriving what it had already worked out. From the outside it looked
465
- like a skill problem. It was a **context** problem.
466
-
467
- So we sat down and went through how Claude Code actually works underneath —
468
- agent teams, subagents, why a fresh context beats a long one, why the state
469
- has to live somewhere the window cannot take with it. That conversation
470
- turned into a plugin. The first version was **pure prompt**: a long, careful
471
- skill that told the model how to behave. It worked exactly as well as a
472
- written rule ever works — until the run got long, or expensive, or boring.
473
-
474
- That failure is the whole reason for v2. Every rule that mattered got
475
- demoted from a paragraph to a **mechanism**: a hook that refuses a report
476
- with no command output, a gate that will not let an initiative close
477
- unretrospected, a file that decides which model a role gets. The motto on the
478
- conductor skill — *a rule in prose loses to a mechanism that makes the mistake
479
- impossible* — is not a slogan we adopted. It is the lesson v1 taught us, in
480
- the order we learned it.
222
+ Everything below also reads as a site, with search and rendered diagrams:
223
+ [jjanczur.github.io/tyran](https://jjanczur.github.io/tyran/).
224
+
225
+ | | |
226
+ |---|---|
227
+ | [Getting started](https://jjanczur.github.io/tyran/getting-started/) | install, first run, the command line, updating |
228
+ | [Architecture](https://jjanczur.github.io/tyran/architecture/) | the four failures, the three layers, the hooks, the principles, the roadmap |
229
+ | [Skills and agents](https://jjanczur.github.io/tyran/skills/) · [the roster](https://jjanczur.github.io/tyran/agents/) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
230
+ | [Configuration](https://jjanczur.github.io/tyran/configuration/) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
231
+ | [Self-improvement](https://jjanczur.github.io/tyran/self-improvement/) | how Tyran learns your repo, and its guardrails |
232
+ | [Journal](https://jjanczur.github.io/tyran/journal/) · [projections](https://jjanczur.github.io/tyran/projections/) | the append-only event schema, and what is generated from it |
233
+ | [The board](https://jjanczur.github.io/tyran/board/) · [the spend ledger](https://jjanczur.github.io/tyran/cost/) | lanes, answering a question, and what a run cost |
234
+ | [Overnight mode](https://jjanczur.github.io/tyran/overnight/) · [doctor](https://jjanczur.github.io/tyran/doctor/) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
235
+ | [Hook runtime](https://jjanczur.github.io/tyran/hooks/) · [evidence gate](https://jjanczur.github.io/tyran/evidence-gate/) · [policy gate](https://jjanczur.github.io/tyran/policy-gate/) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
236
+ | [FAQ](https://jjanczur.github.io/tyran/faq/) | short answers, the comparison table, and where this came from |
237
+ | [Contributing](CONTRIBUTING.md) | the dev loop, the test commands, the enforced rules |
481
238
 
482
239
  ## License
483
240