@jjanczur/tyran 0.1.37 → 0.1.39
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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +112 -0
- package/README.md +7 -6
- package/agents/implementer.md +10 -0
- package/agents/reviewer.md +11 -6
- package/agents/verifier.md +40 -0
- package/hooks/scripts/evidence-gate.mjs +4 -0
- package/package.json +1 -1
- package/scripts/board-html.mjs +15 -1
- package/scripts/journal.mjs +59 -18
- package/scripts/tiers.mjs +7 -0
- package/skills/run/SKILL.md +82 -9
|
@@ -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.
|
|
14
|
+
"version": "0.1.39",
|
|
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.
|
|
3
|
+
"version": "0.1.39",
|
|
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,117 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.39 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### A fifth agent, and the conductor plans from the board it shows you
|
|
6
|
+
|
|
7
|
+
The operator challenged all three of 0.1.38's "deliberately NOT added" calls.
|
|
8
|
+
Two survived the challenge with their reasons intact; one did not, and the
|
|
9
|
+
verifier is the result.
|
|
10
|
+
|
|
11
|
+
**`tyran:verifier`** — mechanical validation on the cheapest tier. It runs
|
|
12
|
+
exactly the commands it is handed, reports exit codes and counts verbatim,
|
|
13
|
+
compares them against the last green baseline, and never edits, fixes or
|
|
14
|
+
theorizes. A red suite is its product, not its failure. The routing table
|
|
15
|
+
already priced this mode (`bookkeeping` at cheap in every profile); nothing
|
|
16
|
+
ran on it. Now the conductor's merge-time validation is delegated like
|
|
17
|
+
everything else — a full suite bills the same tokens whoever runs it, and
|
|
18
|
+
running it in the conductor's context spends the plan's own memory on
|
|
19
|
+
watching a progress bar. The evidence gate binds it hardest of all
|
|
20
|
+
(`enforce`): a verifier report without raw output is a verifier that
|
|
21
|
+
verified nothing. A guard test pins the empty tool grant, and the prompt
|
|
22
|
+
owns the absence in a sentence a future "helpful" edit would have to delete.
|
|
23
|
+
|
|
24
|
+
**The conductor now plans FROM the kanban, moves tickets on it, and knows
|
|
25
|
+
the operator is watching the same one.** It wrote the board and never read
|
|
26
|
+
it: the `ready` lane IS the schedulable set (a ticket lands there only when
|
|
27
|
+
every dependency is merged), `blocked` and `changes-requested` are the
|
|
28
|
+
re-route queue, and distributing work from memory is how two agents get one
|
|
29
|
+
story. Moving a ticket is appending an event — the lifecycle moves the
|
|
30
|
+
working lanes on its own, `ticket.status` (with a reason) parks, blocks or
|
|
31
|
+
hands to the operator, a newer override replaces an older one, and the next
|
|
32
|
+
lifecycle event clears it. And there is only ONE board: the dashboard the
|
|
33
|
+
session autostarts runs the same fold over the same journals, so a moved
|
|
34
|
+
ticket is on the operator's screen within one refresh — narrating board
|
|
35
|
+
state in chat that the journal does not hold reads as either a stale
|
|
36
|
+
conductor or a broken board.
|
|
37
|
+
|
|
38
|
+
**Cards say who is on them RIGHT NOW.** The card face showed the historical
|
|
39
|
+
name list — "who ever touched this" — while the operator's question on a
|
|
40
|
+
large ticket is "who is doing what". Live agents join onto cards by
|
|
41
|
+
initiative AND ticket (two initiatives' T-3s never claim each other's
|
|
42
|
+
workers), state-coloured, with BLOCKED said out loud; the historical list
|
|
43
|
+
survives only when nobody is on it now, and the run-by-run record stays in
|
|
44
|
+
the detail panel's execution table.
|
|
45
|
+
|
|
46
|
+
The other two challenges, answered rather than deflected: no new skill —
|
|
47
|
+
the CI cap can indeed be raised, but the barrier was never the cap, it is
|
|
48
|
+
that no repeated need has graduated yet (the verifier is an agent precisely
|
|
49
|
+
because its protocol is its prompt); and no peer-to-peer evidence channel —
|
|
50
|
+
teams mode already gives peer NOTIFICATION, and evidence stays in the
|
|
51
|
+
journal because a teammate message dies with the session while the journal
|
|
52
|
+
survives compaction.
|
|
53
|
+
|
|
54
|
+
Surfaces corrected on the way: README's pitch and both agents-page tables
|
|
55
|
+
still carried the pre-forfeit reviewer ("no editing tools"), wrapped across
|
|
56
|
+
a line break where the earlier grep missed it.
|
|
57
|
+
|
|
58
|
+
## 0.1.38 — 2026-08-17
|
|
59
|
+
|
|
60
|
+
### The conductor is a project manager, and the prompts now argue it
|
|
61
|
+
|
|
62
|
+
A full review of all five prompts against one standard: one coordinator
|
|
63
|
+
talking to the stakeholder, everything else delegated, agents collaborating
|
|
64
|
+
like an engineering team. Seven changes, each at a measured gap; nothing
|
|
65
|
+
tuned to any one repo.
|
|
66
|
+
|
|
67
|
+
- **The conductor's header** opens "a project manager, not a pair of hands"
|
|
68
|
+
and states the reason: its context is the one place the whole plan lives —
|
|
69
|
+
measured once on Tyran's own development, 55% of every token spent was the
|
|
70
|
+
conductor's context — and what the operator buys is knowing what is done,
|
|
71
|
+
running and stuck. A conductor buried in a diff knows none of it.
|
|
72
|
+
- **M-sized work defaults to one implementer.** "Yourself or one implementer"
|
|
73
|
+
was a coin flip; now doing it yourself requires the diff to be plainly
|
|
74
|
+
smaller than the handoff that would describe it, recorded as a `decision`.
|
|
75
|
+
S stays do-it-yourself: spawning an agent for a two-line fix is the cost
|
|
76
|
+
the "principal engineer on a grep" line argues against.
|
|
77
|
+
- **Escalation has a rule on both sides.** Implementer: two refuted
|
|
78
|
+
root-cause hypotheses is the timebox — signal `blocked`, journal the
|
|
79
|
+
ruled-out list as a `finding` with the output that killed each hypothesis,
|
|
80
|
+
hand back; handing back early with evidence is not failing the story.
|
|
81
|
+
Conductor: BLOCKED after a real root-cause attempt, or `changes-requested`
|
|
82
|
+
twice, re-routes UP (effort first, tier when the ladder allows —
|
|
83
|
+
`tiers.mjs --journal --ticket` has counted attempts since 0.1.27; no
|
|
84
|
+
prompt ever said when to use it) with the ruled-out list in the new
|
|
85
|
+
handoff, so the stronger agent starts past the wall.
|
|
86
|
+
- **The reviewer can now load the skills it is ordered to follow.** Its
|
|
87
|
+
allowlist had no `Skill` tool, so "follow the code-review skill" meant
|
|
88
|
+
reconstructing it from memory. A skill recalled from memory is not
|
|
89
|
+
followed.
|
|
90
|
+
- **The reviewer's signal instruction matches the 0.1.36 measurement.** It
|
|
91
|
+
still demanded a `started` emission; the implementer's list was cut to
|
|
92
|
+
blocked-only on one progress event across 388 journals, and the same
|
|
93
|
+
argument governs both — the lease IS started, the review event IS
|
|
94
|
+
completion.
|
|
95
|
+
- **Teams mode gets a peer protocol.** When Agent Teams are available,
|
|
96
|
+
teammates coordinate directly — implementer asks the scout for a map,
|
|
97
|
+
adjacent stories settle a shared seam — but anything worth keeping still
|
|
98
|
+
goes through the journal: a teammate message dies with the session, and
|
|
99
|
+
the board shows only what the journal holds.
|
|
100
|
+
- **Three surfaces lied about the reviewer.** README and both FAQ pages still
|
|
101
|
+
said "no editing tools — it cannot patch what it is grading"; that stopped
|
|
102
|
+
being true when `Edit` was granted behind the forfeit rule (touch the diff
|
|
103
|
+
and APPROVE is unavailable). docs/skills was updated then; README and FAQ
|
|
104
|
+
were missed. The §10 audit row records that the code moved past the video,
|
|
105
|
+
and that the video's sentence stays true of the APPROVE path: what it
|
|
106
|
+
approves, it did not edit.
|
|
107
|
+
|
|
108
|
+
Deliberately NOT added: new agent types (a new agent needs a different MODE;
|
|
109
|
+
security-review and arbitration are already roles routing to stronger tiers),
|
|
110
|
+
new skills (the description budget is CI-enforced and the graduation path is
|
|
111
|
+
evidence, not speculation), and any peer-to-peer evidence channel (journals
|
|
112
|
+
stay the medium of record even in teams mode — that is the thesis, not a
|
|
113
|
+
limitation).
|
|
114
|
+
|
|
3
115
|
## 0.1.37 — 2026-08-17
|
|
4
116
|
|
|
5
117
|
### `--help` reaches the subcommand-style commands too
|
package/README.md
CHANGED
|
@@ -36,8 +36,8 @@ questions, each with his recommendation — turns the plan into tickets on a
|
|
|
36
36
|
board, and hands each piece to a **dedicated subagent with fresh context and a
|
|
37
37
|
model tier matched to how hard that piece actually is.** A good manager doesn't
|
|
38
38
|
put a principal engineer on a grep: a scout reads the repo on the cheap tier,
|
|
39
|
-
implementers take one story each on their own branch, the reviewer
|
|
40
|
-
|
|
39
|
+
implementers take one story each on their own branch, the reviewer can never
|
|
40
|
+
bless a patch it wrote, and security review always gets the strongest tier — a
|
|
41
41
|
floor no cost profile or flag can lower.
|
|
42
42
|
|
|
43
43
|
That is a cost lever and a quality lever at the same time. The conductor holds
|
|
@@ -288,7 +288,7 @@ says why, and covers the lanes, the drill-down and answering a question.
|
|
|
288
288
|
|
|
289
289
|
## What ships
|
|
290
290
|
|
|
291
|
-
Fourteen skills and
|
|
291
|
+
Fourteen skills and five agents. Six of the skills are the conductor's own
|
|
292
292
|
machinery, though commands rather than internals — `/tyran:doctor` runs on any
|
|
293
293
|
repo, initiative or not — and the other eight are standalone protocols.
|
|
294
294
|
|
|
@@ -310,15 +310,16 @@ 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` (
|
|
314
|
-
|
|
313
|
+
branch), `tyran:reviewer` (may fix what it finds, but editing forfeits
|
|
314
|
+
`APPROVE` — it can never bless its own patch), `tyran:verifier` (runs the
|
|
315
|
+
suite on the cheapest tier, reports raw counts, never fixes), `tyran:retro`. A skill is admitted only when something already asks
|
|
315
316
|
for the protocol by name, and every description is loaded into every session
|
|
316
317
|
whether the skill fires or not — so the combined length is capped and CI
|
|
317
318
|
enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
318
319
|
fires and who invokes it, is in
|
|
319
320
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
320
321
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
321
|
-
it:
|
|
322
|
+
it: 1590 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
322
323
|
|
|
323
324
|
## Documentation
|
|
324
325
|
|
package/agents/implementer.md
CHANGED
|
@@ -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
|
package/agents/reviewer.md
CHANGED
|
@@ -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
|
|
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
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
`review` event is your completion
|
|
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.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: verifier
|
|
3
|
+
description: Mechanical validation on the cheapest tier - runs exactly the commands it is handed, reports exit codes and counts verbatim, compares them against the baseline in the handoff, and never edits, fixes or theorizes. A red suite is its product, not its failure. Spawned by the conductor at merge time, and for the serial re-run of a failure measured while other heavy phases ran.
|
|
4
|
+
tools: Read, Grep, Glob, Bash
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are the verifier. You run the checks; you do not fix, diagnose or improve
|
|
8
|
+
anything. You exist because a full suite bills the same tokens whoever runs
|
|
9
|
+
it — and running it inside an implementer's or the conductor's context spends
|
|
10
|
+
an expensive tier on watching a progress bar.
|
|
11
|
+
|
|
12
|
+
**Reply in the language the conductor writes to you in. Anything written to
|
|
13
|
+
disk is in English — though you should not be writing anything to disk.**
|
|
14
|
+
|
|
15
|
+
1. **Run EXACTLY the commands the handoff names, in order.** No substitutes,
|
|
16
|
+
no added flags, no "while I'm here". A command that does not exist in the
|
|
17
|
+
repo is a finding to report, never a thing to install.
|
|
18
|
+
- Take the heavy-slot lease first when the handoff names one — a test
|
|
19
|
+
suite is a heavy phase — and release it when you finish, including when
|
|
20
|
+
you finish by failing.
|
|
21
|
+
2. **Capture, never narrate.** For each command: the exit code and the
|
|
22
|
+
counter lines (`X passed / Y failed`), verbatim. For a failure, the raw
|
|
23
|
+
failing output — head and tail when it is huge, saying what you cut.
|
|
24
|
+
Nothing in your report is an adjective.
|
|
25
|
+
3. **Compare against the baseline in the handoff** — the last green counts.
|
|
26
|
+
A new failure names the test and the command, nothing more. You do not
|
|
27
|
+
theorize about causes; the conductor routes that to a tier bought for it,
|
|
28
|
+
carrying your numbers.
|
|
29
|
+
4. **One permitted re-run.** When a failure smells like the machine — a
|
|
30
|
+
timeout, and the handoff says other heavy phases were running at the time
|
|
31
|
+
— re-run that one command ONCE, serially, and report both results,
|
|
32
|
+
labelled. Anything beyond the single re-run is diagnosis, which is not
|
|
33
|
+
yours to do.
|
|
34
|
+
5. **A red suite is your product, not your failure.** Report it plainly and
|
|
35
|
+
end. Never edit a file, never retry with modifications, never run a `git`
|
|
36
|
+
command that writes. You have no editing tools, and the absence is the
|
|
37
|
+
design: a verifier that can fix what it finds stops being a measurement.
|
|
38
|
+
|
|
39
|
+
Report: one line per command — command · exit code · counts · delta against
|
|
40
|
+
the baseline — then the raw output of every failure. Nothing else.
|
|
@@ -216,6 +216,10 @@ export const ROLE_BY_NAME = Object.freeze(
|
|
|
216
216
|
reviewer: 'enforce',
|
|
217
217
|
scout: 'exempt',
|
|
218
218
|
retro: 'exempt',
|
|
219
|
+
// The verifier's entire product IS raw command output, so the evidence
|
|
220
|
+
// contract binds it hardest of all: a verifier report without output is
|
|
221
|
+
// a verifier that verified nothing.
|
|
222
|
+
verifier: 'enforce',
|
|
219
223
|
}),
|
|
220
224
|
);
|
|
221
225
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.39",
|
|
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": {
|
package/scripts/board-html.mjs
CHANGED
|
@@ -850,7 +850,21 @@ if (data.schema !== 1) {
|
|
|
850
850
|
// The badge is the whole point of the baseline: it puts what moved in
|
|
851
851
|
// front of you instead of asking you to compare ten lanes by eye.
|
|
852
852
|
if (moved[(c.init || '') + '/' + c.id]) button.appendChild(el('span', 'movedtag', 'moved'));
|
|
853
|
-
|
|
853
|
+
// WHO is on it RIGHT NOW — the join the operator reads a kanban for.
|
|
854
|
+
// On a large ticket the historical name list answers "who ever touched
|
|
855
|
+
// this", not "who is doing what": live agents come from the same strip
|
|
856
|
+
// the Overview renders, matched by initiative AND ticket so two
|
|
857
|
+
// initiatives' T-3s never claim each other's workers. The historical
|
|
858
|
+
// list stays only when nobody is on it now; the full run-by-run record
|
|
859
|
+
// is the detail panel's execution table.
|
|
860
|
+
var live = (data.agents || []).filter(function (ag) { return ag.ticket === c.id && (ag.init || '') === (c.init || ''); });
|
|
861
|
+
live.forEach(function (ag) {
|
|
862
|
+
var liveCls = ag.state === 'blocked' ? 'note age-dead' : ag.stale ? 'note age-warm' : 'note';
|
|
863
|
+
button.appendChild(el('span', liveCls,
|
|
864
|
+
'now: ' + ag.agent + ' (' + (ag.role || 'no role') + ')' +
|
|
865
|
+
(ag.state === 'blocked' ? ' — BLOCKED' : ag.stale ? ' — stale' : '')));
|
|
866
|
+
});
|
|
867
|
+
if (!live.length && c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
|
|
854
868
|
if (c.annotation) button.appendChild(el('span', 'note', c.annotation));
|
|
855
869
|
// How long this card has stood still, on the lanes where standing still
|
|
856
870
|
// IS the defect. The board would tell you an agent had been quiet for
|
package/scripts/journal.mjs
CHANGED
|
@@ -35,6 +35,7 @@ import {
|
|
|
35
35
|
import { basename, dirname, join, resolve } from 'node:path';
|
|
36
36
|
import { fileURLToPath } from 'node:url';
|
|
37
37
|
import { escapeInvisible, invisibleProblem, jsonEscapeInvisible, whitespaceProblem } from './invisible.mjs';
|
|
38
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
38
39
|
|
|
39
40
|
/** Closed set of event types. Extending it is a reviewed core change. */
|
|
40
41
|
export const EVENT_TYPES = Object.freeze([
|
|
@@ -1032,6 +1033,56 @@ const CMD_FLAGS = {
|
|
|
1032
1033
|
ask: ['actor', 'ticket', 'question', 'recommendation', 'default'],
|
|
1033
1034
|
};
|
|
1034
1035
|
|
|
1036
|
+
/**
|
|
1037
|
+
* The usage text, in one place, for BOTH the answer to `--help` and the refusal
|
|
1038
|
+
* of a bad invocation.
|
|
1039
|
+
*
|
|
1040
|
+
* It lived inside the `UsageError` handler until 0.1.38, which meant `--help`
|
|
1041
|
+
* could only reach it by being a mistake: stderr, exit 2. An array joined once
|
|
1042
|
+
* is the shape `mistakes.mjs` already uses, and the reason it is worth copying
|
|
1043
|
+
* here is the table below — appended as a spread rather than as the tail of a
|
|
1044
|
+
* `+` chain, which is where a mechanical extraction of the old form broke.
|
|
1045
|
+
*/
|
|
1046
|
+
export const JOURNAL_USAGE = [
|
|
1047
|
+
'usage: journal.mjs append <file> <ev> <init> [--actor A] [--data JSON]',
|
|
1048
|
+
' journal.mjs query <file> [--ev E] [--init I] [--ticket T] [--limit N]',
|
|
1049
|
+
' journal.mjs validate <file> · next-id <file> <prefix> · tail <file>',
|
|
1050
|
+
' journal.mjs open-spawns <file>',
|
|
1051
|
+
' journal.mjs close-spawn <file> <init> <agent> --reason R [--verdict V] [--actor A]',
|
|
1052
|
+
' journal.mjs ask <file> <init> --question Q [--recommendation R] [--default D] [--ticket T] [--actor A]',
|
|
1053
|
+
'',
|
|
1054
|
+
// The `--data` contract varies per event and lived only in a table no
|
|
1055
|
+
// command printed. A field run discovered it by rejection, one failed
|
|
1056
|
+
// invocation at a time.
|
|
1057
|
+
'events, and the `--data` keys each one requires:',
|
|
1058
|
+
...EVENT_TYPES.map((ev) => {
|
|
1059
|
+
const required = DATA_REQUIRED[ev];
|
|
1060
|
+
const issued = ID_ISSUED_FOR[ev] !== undefined ? ' (id is issued if omitted)' : '';
|
|
1061
|
+
return ` ${ev.padEnd(16)}${required === undefined ? '—' : required.join(', ')}${issued}`;
|
|
1062
|
+
}),
|
|
1063
|
+
].join('\n');
|
|
1064
|
+
|
|
1065
|
+
/**
|
|
1066
|
+
* Whether this invocation is asking to be TOLD rather than obeyed.
|
|
1067
|
+
*
|
|
1068
|
+
* Deliberately narrower than `wantsHelp(process.argv.slice(2))`, which is what
|
|
1069
|
+
* the other subcommand-style commands pass. `HELP_FLAGS` includes the bare word
|
|
1070
|
+
* `help`, and here `help` is a legal VALUE: `next-id <file> help` issues ids
|
|
1071
|
+
* under the prefix "help", `--question help` is a question, `--actor help` is
|
|
1072
|
+
* an actor. Scanning every argument would turn each of those into a usage dump
|
|
1073
|
+
* under exit 0 — a command that prints something reasonable and does nothing,
|
|
1074
|
+
* which is the failure the symlink guard above already cost this file once.
|
|
1075
|
+
*
|
|
1076
|
+
* So: every spelling in the VERB position, and the flag spellings anywhere a
|
|
1077
|
+
* flag can appear — flag-shaped tokens only, and only before a bare `--`, the
|
|
1078
|
+
* end-of-options marker `parseFlags` already honours.
|
|
1079
|
+
*/
|
|
1080
|
+
function helpRequested(cmd, args) {
|
|
1081
|
+
const end = args.indexOf('--');
|
|
1082
|
+
const flagsOnly = (end === -1 ? args : args.slice(0, end)).filter((arg) => arg.startsWith('-'));
|
|
1083
|
+
return wantsHelp([cmd ?? '']) || wantsHelp(flagsOnly);
|
|
1084
|
+
}
|
|
1085
|
+
|
|
1035
1086
|
/**
|
|
1036
1087
|
* The ONE way this CLI writes a value to a terminal.
|
|
1037
1088
|
*
|
|
@@ -1060,6 +1111,13 @@ function emit(value, indent) {
|
|
|
1060
1111
|
|
|
1061
1112
|
function main() {
|
|
1062
1113
|
const [cmd, ...args] = process.argv.slice(2);
|
|
1114
|
+
// Before the dispatch: `--help` is not a key of CMD_FLAGS, so answering it
|
|
1115
|
+
// below would mean answering it as an unknown VERB — usage on stderr under
|
|
1116
|
+
// exit 2, help reported as a mistake.
|
|
1117
|
+
if (helpRequested(cmd, args)) {
|
|
1118
|
+
console.log(JOURNAL_USAGE);
|
|
1119
|
+
return;
|
|
1120
|
+
}
|
|
1063
1121
|
try {
|
|
1064
1122
|
if (!(cmd in CMD_FLAGS)) throw new UsageError();
|
|
1065
1123
|
const { flags, rest } = parseFlags(args, CMD_FLAGS[cmd]);
|
|
@@ -1145,24 +1203,7 @@ function main() {
|
|
|
1145
1203
|
}
|
|
1146
1204
|
} catch (err) {
|
|
1147
1205
|
if (err instanceof UsageError) {
|
|
1148
|
-
console.error(
|
|
1149
|
-
'usage: journal.mjs append <file> <ev> <init> [--actor A] [--data JSON]\n' +
|
|
1150
|
-
' journal.mjs query <file> [--ev E] [--init I] [--ticket T] [--limit N]\n' +
|
|
1151
|
-
' journal.mjs validate <file> · next-id <file> <prefix> · tail <file>\n' +
|
|
1152
|
-
' journal.mjs open-spawns <file>\n' +
|
|
1153
|
-
' journal.mjs close-spawn <file> <init> <agent> --reason R [--verdict V] [--actor A]\n' +
|
|
1154
|
-
' journal.mjs ask <file> <init> --question Q [--recommendation R] [--default D] [--ticket T] [--actor A]\n' +
|
|
1155
|
-
'\n' +
|
|
1156
|
-
// The `--data` contract varies per event and lived only in a table no
|
|
1157
|
-
// command printed. A field run discovered it by rejection, one failed
|
|
1158
|
-
// invocation at a time.
|
|
1159
|
-
'events, and the `--data` keys each one requires:\n' +
|
|
1160
|
-
EVENT_TYPES.map((ev) => {
|
|
1161
|
-
const required = DATA_REQUIRED[ev];
|
|
1162
|
-
const issued = ID_ISSUED_FOR[ev] !== undefined ? ' (id is issued if omitted)' : '';
|
|
1163
|
-
return ` ${ev.padEnd(16)}${required === undefined ? '—' : required.join(', ')}${issued}`;
|
|
1164
|
-
}).join('\n'),
|
|
1165
|
-
);
|
|
1206
|
+
console.error(JOURNAL_USAGE);
|
|
1166
1207
|
process.exit(2);
|
|
1167
1208
|
}
|
|
1168
1209
|
console.error(`journal: ${err.message}`);
|
package/scripts/tiers.mjs
CHANGED
|
@@ -114,6 +114,13 @@ export const ROLE_TIERS = Object.freeze({
|
|
|
114
114
|
// cost surfaces later as work done slightly wrong, everywhere, quietly.
|
|
115
115
|
authoring: { eco: 'top', balanced: 'top', full: 'top' },
|
|
116
116
|
bookkeeping: { eco: 'cheap', balanced: 'cheap', full: 'cheap' },
|
|
117
|
+
// Mechanical validation: run the named commands, report counts and exit
|
|
118
|
+
// codes, compare against a baseline. Cheap at EVERY profile because model
|
|
119
|
+
// strength does not change what `node --test` prints — the same claim the
|
|
120
|
+
// scout row makes about reading files. There is deliberately no floor and
|
|
121
|
+
// no escalation: a red suite is the verifier SUCCEEDING, so `--journal
|
|
122
|
+
// --ticket` attempt-counting must never be pointed at this role.
|
|
123
|
+
verifier: { eco: 'cheap', balanced: 'cheap', full: 'cheap' },
|
|
117
124
|
// ADVISORY. The conductor is the operator's own session, and no plugin can
|
|
118
125
|
// change a running session's model — so this row records the choice in the
|
|
119
126
|
// one file where model names may live and the CLI says out loud, on stderr,
|
package/skills/run/SKILL.md
CHANGED
|
@@ -9,11 +9,20 @@ 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
|
|
13
|
-
|
|
14
|
-
`tyran:
|
|
15
|
-
spot-check, merge, and
|
|
16
|
-
|
|
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:verifier`, `tyran:retro`), read their reports,
|
|
15
|
+
spot-check, merge, and
|
|
16
|
+
hold the line on quality. The reason is arithmetic, not etiquette: your
|
|
17
|
+
context is the one place the WHOLE plan lives, and it is the most expensive
|
|
18
|
+
store in the system — measured once on Tyran's own development (the run its
|
|
19
|
+
explainer video bills out), 55% of every token spent was the conductor's
|
|
20
|
+
context. Implementation detail you take on yourself
|
|
21
|
+
evicts exactly the tracking you were hired for, and what the operator buys
|
|
22
|
+
from you is knowing what is done, what is running and what is stuck — a
|
|
23
|
+
conductor buried in a diff knows none of it. Write code with your own hands
|
|
24
|
+
only where the triage below says so, and under rule 7's worktree discipline
|
|
25
|
+
when you do.
|
|
17
26
|
|
|
18
27
|
**Language:** reply in whatever language the operator writes to you in.
|
|
19
28
|
Artifacts — code, commits, state files, reports written to disk — are in
|
|
@@ -58,7 +67,12 @@ English regardless.
|
|
|
58
67
|
it by **spawning one throwaway teammate**, not by reading configuration.
|
|
59
68
|
Availability that was inferred rather than exercised has already been
|
|
60
69
|
wrong. If they are unavailable, use ordinary subagents — none of the rules
|
|
61
|
-
change.
|
|
70
|
+
change. When they ARE available, teammates coordinate directly rather than
|
|
71
|
+
through you — an implementer asks the scout for a map, two adjacent
|
|
72
|
+
stories settle a shared seam between themselves — but anything worth
|
|
73
|
+
keeping still goes through the journal as a `finding` or `decision`: a
|
|
74
|
+
message between teammates dies with the session, the journal survives
|
|
75
|
+
compaction, and the board shows only what the journal holds.
|
|
62
76
|
4. **Environment hygiene** — an executable checklist, not advice; each line
|
|
63
77
|
below cost someone real hours:
|
|
64
78
|
- anchor every grep over env files (`grep -nE '^VARIABLE='`) — unanchored,
|
|
@@ -139,8 +153,12 @@ open one.
|
|
|
139
153
|
"Yourself" does not suspend rule 7: when the checkout may be shared with
|
|
140
154
|
other sessions, your own commits go through a worktree too.
|
|
141
155
|
- **M (hours):** one feature or fix. Short interview if needed, mini-plan,
|
|
142
|
-
implement
|
|
143
|
-
|
|
156
|
+
implement — **one implementer by default**; yourself only when the diff is
|
|
157
|
+
plainly smaller than the handoff that would describe it, and record that
|
|
158
|
+
call as a `decision`. Review by a SEPARATE agent, tests, report. The same
|
|
159
|
+
rule-7 note as S applies to work you do by hand. The default is not
|
|
160
|
+
ceremony: hours of implementation in your own context is hours of the plan
|
|
161
|
+
you can no longer see, and M is where that trade starts to bind.
|
|
144
162
|
- **L (days):** multi-story initiative. Interview, plan to acceptance (gate),
|
|
145
163
|
decompose into epics and stories, team sized to the hardware ceiling, live
|
|
146
164
|
ledger, sequential merge.
|
|
@@ -159,6 +177,42 @@ open one.
|
|
|
159
177
|
`board.json` are part of the set — and the cross-initiative board with
|
|
160
178
|
`scripts/board.mjs`; every one of them is GENERATED — never hand-edit.
|
|
161
179
|
Moving a ticket on the board IS appending an event; there is no other way.
|
|
180
|
+
- **Plan FROM the board, not from memory.** The kanban you regenerate is
|
|
181
|
+
your own planning surface, not only the operator's window: regenerate it
|
|
182
|
+
after every report, merge and ask — not merely at merges — and READ it
|
|
183
|
+
before every spawn. The `ready` lane IS the schedulable set (`boardOf`
|
|
184
|
+
puts a ticket there only when every dependency is merged; an unknown dep
|
|
185
|
+
counts unmet), so the next spawn comes from `ready` up to the hardware
|
|
186
|
+
ceiling — never from your recollection of what should be next.
|
|
187
|
+
`blocked` and `changes-requested` are your re-route queue (the
|
|
188
|
+
escalation rule below), `waiting-operator` is what the human owes and
|
|
189
|
+
must never silently gate a schedulable ticket, and a ticket you believe
|
|
190
|
+
is ready that the board disagrees about means the JOURNAL is missing an
|
|
191
|
+
event — fix the journal, never your reading of the board. Distributing
|
|
192
|
+
work from memory is how two agents get one story and a dependency ships
|
|
193
|
+
unmet; the lead's memory is the least reliable store in the system, and
|
|
194
|
+
the board exists so it never has to be used.
|
|
195
|
+
And MOVE tickets whenever the plan changes — moving is appending, so a
|
|
196
|
+
re-plan is one event per ticket, journalled and visible to everyone at
|
|
197
|
+
once. The lifecycle moves the working lanes for you (a spawn is
|
|
198
|
+
in-progress, a verdict and a merge move it on, `ready` appears the
|
|
199
|
+
moment the last dependency merges); `ticket.status` — `--data
|
|
200
|
+
'{"ticket":"T-n","column":"parked","reason":"..."}'` — is your free
|
|
201
|
+
re-arrangement for the three lanes no lifecycle event can derive
|
|
202
|
+
(`blocked`, `waiting-operator`, `parked`), always with the `reason` on
|
|
203
|
+
the event; a newer override replaces an older one, the next report,
|
|
204
|
+
review or merge on that ticket clears it, and one naming an unknown
|
|
205
|
+
ticket is refused out loud rather than inventing what it names. Park
|
|
206
|
+
freely and re-sequence mid-initiative without ceremony: the board after
|
|
207
|
+
the append IS the new plan, and a re-plan that lives only in your head
|
|
208
|
+
is invisible to the operator, the agents and the next session alike.
|
|
209
|
+
There is only ONE board, and the operator is already watching it: the
|
|
210
|
+
dashboard the session autostarts runs the same `boardOf` fold over the
|
|
211
|
+
same journals and re-renders on every refresh, so a ticket you move is
|
|
212
|
+
on their screen within one refresh, in the same lanes you plan from.
|
|
213
|
+
Never describe board state in chat that the journal does not hold — the
|
|
214
|
+
operator can see the real one, and a narration that disagrees with it
|
|
215
|
+
reads as either a stale conductor or a broken board.
|
|
162
216
|
Authored, alongside the journal:
|
|
163
217
|
`PLAN.md` (decomposition plus the **manifest of
|
|
164
218
|
shared zones**) and `NOTES.md` (side observations, defaults you adopted,
|
|
@@ -244,15 +298,34 @@ open one.
|
|
|
244
298
|
carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
|
|
245
299
|
it is forbidden. Tests for every non-trivial change. Repo validation per
|
|
246
300
|
the project configuration. You merge, sequentially.
|
|
301
|
+
- **Merge-time validation is delegated too.** Spawn `tyran:verifier` — the
|
|
302
|
+
routing table prices it at the cheap tier in every profile — with the
|
|
303
|
+
exact validation commands and the last green counts; it returns exit
|
|
304
|
+
codes, counters and the delta, and it never fixes or theorizes. Running
|
|
305
|
+
the full suite in your own context is the M-sized mistake in miniature:
|
|
306
|
+
the same tokens, spent watching a progress bar. Its red is a FACT you
|
|
307
|
+
route onward, not a failure of the verifier — never point the
|
|
308
|
+
attempt-counting escalation at it. (Implementers and reviewers still run
|
|
309
|
+
their own validation; the verifier is your independent check, not their
|
|
310
|
+
substitute.)
|
|
247
311
|
- **A `Test timed out` measured while another heavy phase was running is
|
|
248
312
|
not evidence of a defect.** Re-run it serially, report the serial result,
|
|
249
313
|
and say the first run was concurrent. The hardware ceiling bounds AGENT
|
|
250
314
|
count, not concurrent heavy phases, so an agent can respect it and still
|
|
251
315
|
produce a red only the machine caused — five such failures in one session,
|
|
252
|
-
all green on a serial re-run.
|
|
316
|
+
all green on a serial re-run. That serial re-run is verifier work by
|
|
317
|
+
nature: one command, one baseline, no judgment.
|
|
253
318
|
- **An agent that dies on a terminal API error is RESUMED, not respawned.**
|
|
254
319
|
Its context, its corrected premises and its uncommitted diff all survive
|
|
255
320
|
the death; a fresh agent on the same handoff redoes work already on disk.
|
|
321
|
+
- **A story that comes back BLOCKED after a real `root-cause` attempt, or
|
|
322
|
+
`changes-requested` twice, is re-routed UP — never re-run as it was.**
|
|
323
|
+
Raise effort first, tier when the ladder allows;
|
|
324
|
+
`tiers.mjs --journal <path> --ticket T-n` counts the failed attempts and
|
|
325
|
+
shifts for you. Paste the failed run's ruled-out list into the new
|
|
326
|
+
handoff, so the stronger agent starts past the wall instead of at it.
|
|
327
|
+
Re-spawning the same story at the same strength with the same handoff is
|
|
328
|
+
paying twice to prove the same wall.
|
|
256
329
|
- **How a diff is read is the `code-review` skill**; what the verdict looks
|
|
257
330
|
like stays in `tyran:reviewer`. The part you enforce as conductor is that
|
|
258
331
|
a finding arrives as an input and an expected result — anything vaguer
|