@jjanczur/tyran 0.1.17 → 0.1.19

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,177 +20,140 @@
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
+ Tyran is a Claude Code plugin that runs a task as a **team of agents instead of
26
+ one long chat**. You describe the work; it interviews you briefly, plans, and
27
+ drives fresh-context subagents through it. Execution state lives in an
28
+ append-only journal committed to your repo rather than in the session window, so
29
+ a restart, a compaction and a colleague on another branch read the same thing.
30
+ Zero runtime dependencies, no build step, Node ≥ 22.
31
+
32
+ ![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)
33
+
34
+ ## What it gives you
35
+
36
+ - **A model tier per role, resolved from one config file.** Model names appear
37
+ in exactly one place; skills, agents and policies are written in role names.
38
+ The expensive tier is kept for security review, arbitration and final
39
+ acceptance, and the first two sit on a floor no profile or risk flag crosses.
40
+ - **Fresh context for every subagent.** Handoffs are self-contained, so the
41
+ conductor holds the plan and never accumulates its agents' transcripts.
42
+ - **Reports that carry evidence, or are refused.** A `SubagentStop` hook
43
+ rejects a report with no raw command output — measured on 55 real reports
44
+ from this project's own agents: 53 pass, and both misses were not reports. It
45
+ blocks silence, not forgery; [the evidence gate](docs/evidence-gate.md) is
46
+ precise about the difference.
47
+ - **State you can read without a session.** The journal is the single source of
48
+ truth; `STATE.md`, `PROGRESS.md`, `BOARD.md`, `board.json` and `board.html`
49
+ are generated projections of it.
50
+ - **A retrospective after every initiative.** It writes durable facts about
51
+ your repo into `.tyran/knowledge/`, and repeated failures graduate out of
52
+ `MISTAKES.md` into rules.
53
+ - **A spend ledger.** `npx @jjanczur/tyran cost` reports what the work cost, in
54
+ the tokens the platform itself reported, per model, per agent type and per
55
+ ticket — read out of the transcripts Claude Code already writes. Money
56
+ appears only under a rate card you write: Tyran does not know what you pay.
57
+ - **It can run overnight, because the usage limit is a wind-down and not a
58
+ crash.** The platform's own behaviour at the limit is a cliff: calls start
59
+ failing mid-flight and agents die between a write and its commit. Near the
60
+ threshold Tyran instead checkpoints, commits the state files, schedules a
61
+ resume and stops — then a watcher wakes at the window reset and continues the
62
+ same session. Leave it working and read the board in the morning. Both
63
+ windows were hit live while the feature was being built; the protocol that
64
+ survived them is what shipped. See [overnight mode](docs/overnight.md).
65
+
66
+ ## Tyran compared
67
+
68
+ The axis, not the winner. These rows compare against an ordinary agent session
69
+ — a comparison that can be made without guessing at another tool's internals.
70
+
71
+ | | An ordinary agent session | Tyran |
44
72
  |---|---|---|
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
- ```
73
+ | 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 |
74
+ | What makes a report trustworthy | you read the claim | a hook refuses a report with no raw command output |
75
+ | 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 |
76
+ | What happens after the work | nothing | a retrospective writes what this repo taught it back into this repo |
77
+ | What it adds to your install | — | zero runtime dependencies, no build step |
78
+ | Skills · agents it ships | — | 14 · 4 |
66
79
 
67
- ## The Solution
80
+ Worth knowing before tuning anything: cache reads were measured at roughly
81
+ three quarters of a real session's cost, and the conductor's own context at
82
+ between 44% and 86% of a tree's tokens — so the lever is context size and turn
83
+ count, not the price of a model. A cell-by-cell comparison against four other
84
+ Claude Code orchestrators, verified against their code and public issue
85
+ trackers, is in
86
+ [the FAQ](docs/faq.md#how-tyran-compares-to-other-claude-code-orchestrators).
68
87
 
69
- **Split the work so nobody has to carry all of it**, and put the state in a
70
- file instead of a window:
88
+ ## Install
71
89
 
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>"]
90
+ Inside Claude Code:
75
91
 
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
92
+ ```text
93
+ /plugin marketplace add jjanczur/tyran
94
+ /plugin install tyran@tyran
95
+ /tyran:hello
117
96
  ```
118
97
 
119
- ### And then it gets better on its own
98
+ Restart Claude Code afterwards — hooks and agents are read when a session
99
+ starts, so an install you have not restarted into is an install you are not
100
+ running. `/tyran:hello` is the smoke test. Requirements: Claude Code ≥ 2.1;
101
+ Tyran's scripts are plain Node ≥ 22 and ship with the plugin, so you never run
102
+ npm. `/plugin` is a slash command a human has to type — the prompt that has
103
+ Claude Code install itself, the npm package for a shell or a CI job, updating
104
+ and uninstalling are all in [getting started](docs/getting-started.md).
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
+ ## Use it
127
107
 
128
108
  ```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.
109
+ /tyran:setup # once per repo: scans it, writes .tyran/, installs /tyran
110
+ /tyran # then describe what you want done
137
111
  ```
138
112
 
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.
113
+ Setup infers your stack, your validation commands and your deployment autonomy
114
+ class from how the repo is actually worked, annotates every value with the fact
115
+ that produced it, and asks only about what it could not establish. `/tyran`
116
+ then interviews you, sizes the work, and either does it itself or drives the
117
+ roster — `tyran:scout`, `tyran:implementer`, `tyran:reviewer`, `tyran:retro` —
118
+ through it, stopping only at genuine decisions. Also `/tyran:status`,
119
+ `/tyran:doctor`, `/tyran:retro`.
143
120
 
144
- ## Quick Start
121
+ Hit the brake at any time, from anywhere, without killing the session:
145
122
 
146
- ```text
147
- /plugin marketplace add jjanczur/tyran
148
- /plugin install tyran@tyran
149
- /tyran:setup # scans the repo, writes .tyran/, installs /tyran
150
- /tyran # then just describe what you want done
123
+ ```bash
124
+ echo "wrong branch — hold everything" > .tyran/STOP
151
125
  ```
152
126
 
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:
127
+ ## The dashboard
158
128
 
159
- ```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/
129
+ ```bash
130
+ npx @jjanczur/tyran board --dir .tyran --serve
172
131
  ```
173
132
 
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.
133
+ A read-only board on loopback, re-rendered on every request. Four tabs, because
134
+ the page answers four questions:
180
135
 
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`,
184
- `/tyran:doctor`, `/tyran:retro`.
136
+ - **Overview** — what is waiting on you, agents running, progress, tickets that
137
+ need a human; then the agent strip, each chip carrying the time since that
138
+ agent last signalled.
139
+ - **Board** — every ticket in exactly one of ten kanban lanes, strongest verdict
140
+ first. Click a card for its initiative, agents, note and spend.
141
+ - **Waiting on you** — the open questions with their recommendations and
142
+ recorded defaults, above the commands that answer them. The count sits in the
143
+ tab label, so a pending question survives being on another tab.
144
+ - **Spend** — tokens, the amount under your rate card, the conductor's share, a
145
+ composition bar across input / cache write / cache read / output, and three
146
+ ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
147
+
148
+ The same page is written to `.tyran/state/board.html` and refreshed after every
149
+ agent, so you can also just open the file. Spend is served rather than embedded
150
+ and absent over `file://` — [the board](docs/board.md) says why.
185
151
 
186
- ### It is not only an orchestrator — it ships skills you can use yourself
152
+ ## What ships
187
153
 
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.
154
+ Fourteen skills and four agents. Six of the skills are the conductor's own
155
+ machinery, though commands rather than internals — `/tyran:doctor` runs on any
156
+ repo, initiative or not — and the other eight are standalone protocols.
194
157
 
195
158
  | Skill | What it does |
196
159
  |---|---|
@@ -200,279 +163,42 @@ never starts an initiative at all.
200
163
  | [`doctor`](skills/doctor/SKILL.md) | is any gate installed but unable to fire; is the state self-consistent |
201
164
  | [`retro`](skills/retro/SKILL.md) | the anti-bloat curator that changes Tyran, never your product code |
202
165
  | [`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
- Hit the brake at any time, from anywhere, without killing the session:
230
-
231
- ```bash
232
- echo "wrong branch — hold everything" > .tyran/STOP
233
- ```
234
-
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`, `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.
365
-
366
- ```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
370
- ```
371
-
372
- Exit codes propagate to the digit, so a CI step reddens exactly when the
373
- underlying script does.
374
-
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.
166
+ | [`code-review`](skills/code-review/SKILL.md) | the dimensions a diff is read against, and the rule that you refute a finding before reporting it |
167
+ | [`root-cause`](skills/root-cause/SKILL.md) | reproduce first, one variable per experiment, exit by naming the mechanism |
168
+ | [`browser-check`](skills/browser-check/SKILL.md) | a UI pass that returns counts — console errors, failed responses, computed styles |
169
+ | [`deslop`](skills/deslop/SKILL.md) | the optimization pass: delete before you add, behaviour pinned by a test that ran first |
170
+ | [`pr-feedback`](skills/pr-feedback/SKILL.md) | all three of GitHub's comment surfaces, a disposition for every comment |
171
+ | [`fidelity-gate`](skills/fidelity-gate/SKILL.md) | build 1:1 against a frozen mockup, measured rather than eyeballed |
172
+ | [`prompt-tuning`](skills/prompt-tuning/SKILL.md) | tune a non-deterministic output without chasing noise — noise baseline first |
173
+ | [`skill-writing`](skills/skill-writing/SKILL.md) | what a skill has to earn before it ships, and the test that proves it fires |
174
+
175
+ Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
176
+ branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
177
+ grading), `tyran:retro`. A skill is admitted only when something already asks
178
+ for the protocol by name, and every description is loaded into every session
179
+ whether the skill fires or not — so the combined length is capped and CI
180
+ enforces the cap (4352 of 5000 characters). What each one assumes, and who
181
+ invokes it, is in [skills and agents](docs/skills.md). Behind all of it: 1289
182
+ unit tests, run with `node --test "tests/**/*.test.mjs"`.
379
183
 
380
184
  ## Documentation
381
185
 
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 mistakes ledger: `MISTAKES.md` at your repo root — what went wrong
448
- here and how often — where three occurrences of one signature graduate a
449
- lesson into `.tyran/knowledge/` and five write a rule into your
450
- `CLAUDE.md`, inside Tyran's own fence — see
451
- [docs/self-improvement.md](docs/self-improvement.md)
452
-
453
- ## Where this came from
454
-
455
- Tyran started as a teaching problem. One of us was mentoring the other
456
- through learning to program, and the mentee kept hitting the same wall — not
457
- with the code, with the *tool*. Claude would ask a pile of hard questions at
458
- once, lose the thread halfway through the answer, and burn a small fortune in
459
- tokens re-deriving what it had already worked out. From the outside it looked
460
- like a skill problem. It was a **context** problem.
461
-
462
- So we sat down and went through how Claude Code actually works underneath —
463
- agent teams, subagents, why a fresh context beats a long one, why the state
464
- has to live somewhere the window cannot take with it. That conversation
465
- turned into a plugin. The first version was **pure prompt**: a long, careful
466
- skill that told the model how to behave. It worked exactly as well as a
467
- written rule ever works — until the run got long, or expensive, or boring.
468
-
469
- That failure is the whole reason for v2. Every rule that mattered got
470
- demoted from a paragraph to a **mechanism**: a hook that refuses a report
471
- with no command output, a gate that will not let an initiative close
472
- unretrospected, a file that decides which model a role gets. The motto on the
473
- conductor skill — *a rule in prose loses to a mechanism that makes the mistake
474
- impossible* — is not a slogan we adopted. It is the lesson v1 taught us, in
475
- the order we learned it.
186
+ Everything below also reads as a site, with search and rendered diagrams:
187
+ [jjanczur.github.io/tyran](https://jjanczur.github.io/tyran/).
188
+
189
+ | | |
190
+ |---|---|
191
+ | [Getting started](docs/getting-started.md) | install, first run, the command line, updating |
192
+ | [Architecture](docs/architecture.md) | the four failures, the three layers, the hooks, the principles, the roadmap |
193
+ | [Skills and agents](docs/skills.md) · [the roster](docs/agents.md) | what each one assumes and who invokes it; the tier and effort table, the `.tyran/STOP` brake |
194
+ | [Configuration](docs/configuration.md) | `.tyran/config.yaml`, cost profiles, the rate card, autonomy classes |
195
+ | [Self-improvement](docs/self-improvement.md) | how Tyran learns your repo, and its guardrails |
196
+ | [Journal](docs/journal.md) · [projections](docs/projections.md) | the append-only event schema, and what is generated from it |
197
+ | [The board](docs/board.md) · [the spend ledger](docs/cost.md) | lanes, answering a question, and what a run cost |
198
+ | [Overnight mode](docs/overnight.md) · [doctor](docs/doctor.md) | usage-limit pause and scheduled resume; the `--state` and `--hooks` checks |
199
+ | [Hook runtime](docs/hooks.md) · [evidence gate](docs/evidence-gate.md) · [policy gate](docs/policy-gate.md) | gates versus probes and why hooks fail open; the criterion and its limits; path classes and where each stops |
200
+ | [FAQ](docs/faq.md) | short answers, the comparison table, and where this came from |
201
+ | [Contributing](CONTRIBUTING.md) | the dev loop, the test commands, the enforced rules |
476
202
 
477
203
  ## License
478
204