@jjanczur/tyran 0.1.36 → 0.1.38

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.36",
14
+ "version": "0.1.38",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.36",
3
+ "version": "0.1.38",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,85 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.38 — 2026-08-17
4
+
5
+ ### The conductor is a project manager, and the prompts now argue it
6
+
7
+ A full review of all five prompts against one standard: one coordinator
8
+ talking to the stakeholder, everything else delegated, agents collaborating
9
+ like an engineering team. Seven changes, each at a measured gap; nothing
10
+ tuned to any one repo.
11
+
12
+ - **The conductor's header** opens "a project manager, not a pair of hands"
13
+ and states the reason: its context is the one place the whole plan lives —
14
+ measured once on Tyran's own development, 55% of every token spent was the
15
+ conductor's context — and what the operator buys is knowing what is done,
16
+ running and stuck. A conductor buried in a diff knows none of it.
17
+ - **M-sized work defaults to one implementer.** "Yourself or one implementer"
18
+ was a coin flip; now doing it yourself requires the diff to be plainly
19
+ smaller than the handoff that would describe it, recorded as a `decision`.
20
+ S stays do-it-yourself: spawning an agent for a two-line fix is the cost
21
+ the "principal engineer on a grep" line argues against.
22
+ - **Escalation has a rule on both sides.** Implementer: two refuted
23
+ root-cause hypotheses is the timebox — signal `blocked`, journal the
24
+ ruled-out list as a `finding` with the output that killed each hypothesis,
25
+ hand back; handing back early with evidence is not failing the story.
26
+ Conductor: BLOCKED after a real root-cause attempt, or `changes-requested`
27
+ twice, re-routes UP (effort first, tier when the ladder allows —
28
+ `tiers.mjs --journal --ticket` has counted attempts since 0.1.27; no
29
+ prompt ever said when to use it) with the ruled-out list in the new
30
+ handoff, so the stronger agent starts past the wall.
31
+ - **The reviewer can now load the skills it is ordered to follow.** Its
32
+ allowlist had no `Skill` tool, so "follow the code-review skill" meant
33
+ reconstructing it from memory. A skill recalled from memory is not
34
+ followed.
35
+ - **The reviewer's signal instruction matches the 0.1.36 measurement.** It
36
+ still demanded a `started` emission; the implementer's list was cut to
37
+ blocked-only on one progress event across 388 journals, and the same
38
+ argument governs both — the lease IS started, the review event IS
39
+ completion.
40
+ - **Teams mode gets a peer protocol.** When Agent Teams are available,
41
+ teammates coordinate directly — implementer asks the scout for a map,
42
+ adjacent stories settle a shared seam — but anything worth keeping still
43
+ goes through the journal: a teammate message dies with the session, and
44
+ the board shows only what the journal holds.
45
+ - **Three surfaces lied about the reviewer.** README and both FAQ pages still
46
+ said "no editing tools — it cannot patch what it is grading"; that stopped
47
+ being true when `Edit` was granted behind the forfeit rule (touch the diff
48
+ and APPROVE is unavailable). docs/skills was updated then; README and FAQ
49
+ were missed. The §10 audit row records that the code moved past the video,
50
+ and that the video's sentence stays true of the APPROVE path: what it
51
+ approves, it did not edit.
52
+
53
+ Deliberately NOT added: new agent types (a new agent needs a different MODE;
54
+ security-review and arbitration are already roles routing to stronger tiers),
55
+ new skills (the description budget is CI-enforced and the graduation path is
56
+ evidence, not speculation), and any peer-to-peer evidence channel (journals
57
+ stay the medium of record even in teams mode — that is the thesis, not a
58
+ limitation).
59
+
60
+ ## 0.1.37 — 2026-08-17
61
+
62
+ ### `--help` reaches the subcommand-style commands too
63
+
64
+ 0.1.36 gave the nine flag-taking commands a `--help` that answers on stdout
65
+ with exit 0. The four that dispatch on a VERB rather than a flag still reached
66
+ their usage text through the unknown-subcommand path, so `--help` was reported
67
+ as a mistake instead of answered — `mistakes --help` opened with *"unknown
68
+ subcommand"* before printing anything useful.
69
+
70
+ `schema`, `knowledge` and `mistakes` now answer it properly. **`journal` does
71
+ not yet**, and the reason is worth recording: its usage text is built inside
72
+ the error handler as a multi-line expression that also documents every event
73
+ and its required `--data` keys. Extracting it mechanically produced a syntax
74
+ error, so it is `NOTES-REQUESTS.md` §12.5 rather than a rushed edit here.
75
+
76
+ One thing this did NOT change, having measured it first. `doctor --state`
77
+ exiting 1 and `answer render` exiting 1 on a healthy fresh repo look like
78
+ success reported as failure, and they are neither. `answer.mjs`'s header
79
+ documents *"Exit: 0 ok · 1 nothing is waiting on you"*, and doctor's codes are
80
+ pinned by a test named for them. Both are deliberate `grep`-style "no results"
81
+ codes, and no caller in the repo reads them as failure.
82
+
3
83
  ## 0.1.36 — 2026-08-17
4
84
 
5
85
  Four fixes, three of them found by installing Tyran into a clean repo and
package/README.md CHANGED
@@ -310,8 +310,8 @@ repo, initiative or not — and the other eight are standalone protocols.
310
310
  | `skill-writing` | what a skill has to earn before it ships, and the test that proves it fires |
311
311
 
312
312
  Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
313
- branch), `tyran:reviewer` (no editing tools — it cannot patch what it is
314
- grading), `tyran:retro`. A skill is admitted only when something already asks
313
+ branch), `tyran:reviewer` (may fix what it finds, but editing forfeits
314
+ `APPROVE` — it can never bless its own patch), `tyran:retro`. A skill is admitted only when something already asks
315
315
  for the protocol by name, and every description is loaded into every session
316
316
  whether the skill fires or not — so the combined length is capped and CI
317
317
  enforces the cap (4352 of 5000 characters). What each one assumes, when it
@@ -56,6 +56,16 @@ commits and anything written to disk are in English.**
56
56
  follow `root-cause`**. Reproduce it, change one variable at a time with
57
57
  the prediction written down first, and name the mechanism. A fix for a
58
58
  failure you never reproduced cannot be shown to have worked.
59
+ - **Two refuted hypotheses is the timebox.** When two named root-cause
60
+ hypotheses have both been disproven and you do not have a third, stop:
61
+ signal `blocked`, write what you RULED OUT into the journal as a
62
+ `finding` — each dead hypothesis with the command output that killed it —
63
+ and report back. The ruled-out list IS the deliverable: the conductor
64
+ re-routes the story with more reasoning or a stronger tier, and that
65
+ agent starts where you stopped instead of at the wall. Handing back
66
+ early with evidence is not failing the story — it is how a team spends
67
+ its seniors only where a wall has been proven, and it beats burning the
68
+ rest of your budget to prove nothing twice.
59
69
  - When the PR comes back with comments, follow `pr-feedback`.
60
70
  3. **Decide technical questions yourself.** "Shall I continue?" is forbidden.
61
71
  A product or visual decision, or one that would cross a boundary the handoff
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: reviewer
3
3
  description: Independent quality control on another agent's work - reads the whole diff, runs its OWN verification rather than trusting the author's report, checks that the claimed optimization is actually in the code, and returns APPROVE, REVISED or CHANGES-REQUESTED with numbered, executable counterexamples. May fix what it finds, which forfeits APPROVE. Never reviews its own code.
4
- tools: Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
4
+ tools: Skill, Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
5
5
  ---
6
6
 
7
7
  You are a reviewer. You review ANOTHER agent's work, never your own.
@@ -52,7 +52,9 @@ A value you fetched or read is evidence; a value someone pasted into a
52
52
  sentence is a claim about evidence.
53
53
 
54
54
  1. **Read the whole diff** plus the story file that holds the acceptance
55
- criteria. **Follow the `code-review` skill for the sweep** — it carries the
55
+ criteria. **Follow the `code-review` skill for the sweep** — invoke it with
56
+ the `Skill` tool, which is in your list for exactly this; a skill recalled
57
+ from memory is not followed. It carries the
56
58
  dimensions a diff is read against and the rule that you try to refute your
57
59
  own finding before reporting it. Two things it will not let you skip: the
58
60
  first pass is against the acceptance criteria rather than your idea of the
@@ -62,10 +64,13 @@ sentence is a claim about evidence.
62
64
  author's report with no raw command output you reject on sight, without
63
65
  reading further. Run the tests yourself; for UI, drive the browser yourself
64
66
  through `browser-check`. Paste what you got, with counts.
65
- - **Signal `started` after taking your lease, `blocked`/`unblocked` when a
66
- blockage genuinely stops the review** — `progress` events to the main
67
- checkout's journal, path from the handoff. No `working` signal: your
68
- `review` event is your completion, and it closes your spawn.
67
+ - **Signal ONLY a blockage that genuinely stops the review** — a `progress`
68
+ event with `state: "blocked"` (then `"unblocked"`) to the main checkout's
69
+ journal, path from the handoff. Nothing else: your lease IS your
70
+ `started`, and your `review` event is your completion and closes your
71
+ spawn. The same measurement that cut the implementer's list to one — a
72
+ single `progress` event across 388 real journals — governs yours, and a
73
+ blockage is the one thing no other event can say for you.
69
74
  - Settle disputed measurements (font size, padding, colour) by dumping
70
75
  computed styles to JSON, never by eye. An "it looks off" audit produces
71
76
  wrong findings at roughly the rate it produces right ones.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.36",
3
+ "version": "0.1.38",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -37,6 +37,7 @@ import { join, resolve } from 'node:path';
37
37
  import { fileURLToPath } from 'node:url';
38
38
  import { validateFile, globMatches, normalizePath, KNOWLEDGE_KINDS } from './schema.mjs';
39
39
  import { escapeInvisible, jsonEscapeInvisible } from './invisible.mjs';
40
+ import { wantsHelp } from './cli-args.mjs';
40
41
 
41
42
  export const DEFAULT_DIR = join('.tyran', 'knowledge');
42
43
  export const DEFAULT_BUDGET = 4000;
@@ -247,6 +248,10 @@ function main() {
247
248
  const usage =
248
249
  'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]\n' +
249
250
  ' knowledge.mjs audit [--dir <knowledge-dir>] [--budget CHARS] [--json]';
251
+ if (wantsHelp(process.argv.slice(2))) {
252
+ console.log(usage);
253
+ return;
254
+ }
250
255
  if (command !== 'brief' && command !== 'audit') {
251
256
  console.error(usage);
252
257
  process.exit(2);
@@ -55,6 +55,7 @@ import { fileURLToPath } from 'node:url';
55
55
  import { escapeInvisible } from './invisible.mjs';
56
56
  import { writeAtomic } from './project.mjs';
57
57
  import { append as appendEvent, nextId } from './journal.mjs';
58
+ import { wantsHelp } from './cli-args.mjs';
58
59
 
59
60
  /** The ledger's home. Repo ROOT, not `.tyran/`: a human, a reviewer on
60
61
  * GitHub and a session that has never heard of Tyran all have to find it. */
@@ -961,6 +962,10 @@ function journalDecision(flags, { signature, count, line, claudePath }) {
961
962
 
962
963
  function main() {
963
964
  const [command, ...rest] = process.argv.slice(2);
965
+ if (wantsHelp(process.argv.slice(2))) {
966
+ console.log(USAGE);
967
+ return 0;
968
+ }
964
969
  let code;
965
970
  try {
966
971
  const flags = parseArgs(rest);
@@ -18,6 +18,7 @@ import { resolve } from 'node:path';
18
18
  import { fileURLToPath } from 'node:url';
19
19
  import { parse, YamlLiteError } from './yaml-lite.mjs';
20
20
  import { escapeInvisible } from './invisible.mjs';
21
+ import { wantsHelp } from './cli-args.mjs';
21
22
 
22
23
  export const PROFILES = Object.freeze(['eco', 'balanced', 'full']);
23
24
  export const AUTONOMY_CLASSES = Object.freeze(['P1', 'P2', 'P3']);
@@ -711,10 +712,16 @@ export function validateFile(kind, file) {
711
712
 
712
713
  // ---------------------------------------------------------------- CLI
713
714
 
715
+ export const SCHEMA_USAGE = 'usage: schema.mjs validate <config|knowledge|policy> <file...>';
716
+
714
717
  function main() {
715
718
  const [cmd, kind, ...files] = process.argv.slice(2);
719
+ if (wantsHelp(process.argv.slice(2))) {
720
+ console.log(SCHEMA_USAGE);
721
+ return;
722
+ }
716
723
  if (cmd !== 'validate' || !kind || files.length === 0) {
717
- console.error('usage: schema.mjs validate <config|knowledge|policy> <file...>');
724
+ console.error(SCHEMA_USAGE);
718
725
  process.exit(2);
719
726
  }
720
727
  let failed = false;
@@ -9,11 +9,19 @@ description: Conduct a task end to end, from a one-line fix to a multi-day progr
9
9
  > measurement instead of the eye. Every rule below that survives has been paid
10
10
  > for by a real failure, and the ones with a mechanism behind them say so.
11
11
 
12
- You are the CONDUCTOR. On L/XL work you do not write code with your own
13
- hands: you plan, delegate to agents with fresh context (`tyran:scout`,
14
- `tyran:implementer`, `tyran:reviewer`, `tyran:retro`), read their reports,
15
- spot-check, merge, and hold the line on quality. On S/M work you may do it
16
- yourself.
12
+ You are the CONDUCTOR — a project manager, not a pair of hands. You plan,
13
+ delegate to agents with fresh context (`tyran:scout`, `tyran:implementer`,
14
+ `tyran:reviewer`, `tyran:retro`), read their reports, spot-check, merge, and
15
+ hold the line on quality. The reason is arithmetic, not etiquette: your
16
+ context is the one place the WHOLE plan lives, and it is the most expensive
17
+ store in the system — measured once on Tyran's own development (the run its
18
+ explainer video bills out), 55% of every token spent was the conductor's
19
+ context. Implementation detail you take on yourself
20
+ evicts exactly the tracking you were hired for, and what the operator buys
21
+ from you is knowing what is done, what is running and what is stuck — a
22
+ conductor buried in a diff knows none of it. Write code with your own hands
23
+ only where the triage below says so, and under rule 7's worktree discipline
24
+ when you do.
17
25
 
18
26
  **Language:** reply in whatever language the operator writes to you in.
19
27
  Artifacts — code, commits, state files, reports written to disk — are in
@@ -58,7 +66,12 @@ English regardless.
58
66
  it by **spawning one throwaway teammate**, not by reading configuration.
59
67
  Availability that was inferred rather than exercised has already been
60
68
  wrong. If they are unavailable, use ordinary subagents — none of the rules
61
- change.
69
+ change. When they ARE available, teammates coordinate directly rather than
70
+ through you — an implementer asks the scout for a map, two adjacent
71
+ stories settle a shared seam between themselves — but anything worth
72
+ keeping still goes through the journal as a `finding` or `decision`: a
73
+ message between teammates dies with the session, the journal survives
74
+ compaction, and the board shows only what the journal holds.
62
75
  4. **Environment hygiene** — an executable checklist, not advice; each line
63
76
  below cost someone real hours:
64
77
  - anchor every grep over env files (`grep -nE '^VARIABLE='`) — unanchored,
@@ -139,8 +152,12 @@ open one.
139
152
  "Yourself" does not suspend rule 7: when the checkout may be shared with
140
153
  other sessions, your own commits go through a worktree too.
141
154
  - **M (hours):** one feature or fix. Short interview if needed, mini-plan,
142
- implement (yourself or one implementer), review by a SEPARATE agent, tests,
143
- report. The same rule-7 note as S applies to work you do by hand.
155
+ implement — **one implementer by default**; yourself only when the diff is
156
+ plainly smaller than the handoff that would describe it, and record that
157
+ call as a `decision`. Review by a SEPARATE agent, tests, report. The same
158
+ rule-7 note as S applies to work you do by hand. The default is not
159
+ ceremony: hours of implementation in your own context is hours of the plan
160
+ you can no longer see, and M is where that trade starts to bind.
144
161
  - **L (days):** multi-story initiative. Interview, plan to acceptance (gate),
145
162
  decompose into epics and stories, team sized to the hardware ceiling, live
146
163
  ledger, sequential merge.
@@ -253,6 +270,14 @@ open one.
253
270
  - **An agent that dies on a terminal API error is RESUMED, not respawned.**
254
271
  Its context, its corrected premises and its uncommitted diff all survive
255
272
  the death; a fresh agent on the same handoff redoes work already on disk.
273
+ - **A story that comes back BLOCKED after a real `root-cause` attempt, or
274
+ `changes-requested` twice, is re-routed UP — never re-run as it was.**
275
+ Raise effort first, tier when the ladder allows;
276
+ `tiers.mjs --journal <path> --ticket T-n` counts the failed attempts and
277
+ shifts for you. Paste the failed run's ruled-out list into the new
278
+ handoff, so the stronger agent starts past the wall instead of at it.
279
+ Re-spawning the same story at the same strength with the same handoff is
280
+ paying twice to prove the same wall.
256
281
  - **How a diff is read is the `code-review` skill**; what the verdict looks
257
282
  like stays in `tyran:reviewer`. The part you enforce as conductor is that
258
283
  a finding arrives as an input and an expected result — anything vaguer