@jjanczur/tyran 0.1.38 → 0.1.40
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 +70 -0
- package/README.md +7 -6
- package/agents/implementer.md +1 -1
- package/agents/retro.md +1 -1
- package/agents/reviewer.md +1 -1
- package/agents/scout.md +1 -1
- 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/browser-check/SKILL.md +1 -1
- package/skills/code-review/SKILL.md +1 -1
- package/skills/deslop/SKILL.md +1 -1
- package/skills/fidelity-gate/SKILL.md +1 -1
- package/skills/pr-feedback/SKILL.md +1 -1
- package/skills/prompt-tuning/SKILL.md +1 -1
- package/skills/retro/SKILL.md +1 -1
- package/skills/root-cause/SKILL.md +1 -1
- package/skills/run/SKILL.md +51 -3
- package/skills/skill-writing/SKILL.md +1 -1
|
@@ -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.40",
|
|
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.40",
|
|
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,75 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.40 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
### Every session pays for these sentences, so they got shorter
|
|
6
|
+
|
|
7
|
+
Fifteen of the nineteen descriptions — ten skills, five agents — rewritten to
|
|
8
|
+
carry only what routes: what it does, when it fires, the one distinguishing
|
|
9
|
+
mechanism. The justifications live in the bodies, which load only when the
|
|
10
|
+
skill fires. Skill total: **4352 → 3868 of 5000** (measured by the same CI
|
|
11
|
+
guard that enforces the cap); the agent descriptions, which the Agent tool
|
|
12
|
+
loads into every session the same way, shed a similar fraction.
|
|
13
|
+
|
|
14
|
+
Nothing lost its trigger — `prompt-tuning` GAINED one (it was the only
|
|
15
|
+
description with no "use when" clause), and `run`'s now names the kanban it
|
|
16
|
+
drives the team from, which 0.1.39 made true.
|
|
17
|
+
|
|
18
|
+
## 0.1.39 — 2026-08-17
|
|
19
|
+
|
|
20
|
+
### A fifth agent, and the conductor plans from the board it shows you
|
|
21
|
+
|
|
22
|
+
The operator challenged all three of 0.1.38's "deliberately NOT added" calls.
|
|
23
|
+
Two survived the challenge with their reasons intact; one did not, and the
|
|
24
|
+
verifier is the result.
|
|
25
|
+
|
|
26
|
+
**`tyran:verifier`** — mechanical validation on the cheapest tier. It runs
|
|
27
|
+
exactly the commands it is handed, reports exit codes and counts verbatim,
|
|
28
|
+
compares them against the last green baseline, and never edits, fixes or
|
|
29
|
+
theorizes. A red suite is its product, not its failure. The routing table
|
|
30
|
+
already priced this mode (`bookkeeping` at cheap in every profile); nothing
|
|
31
|
+
ran on it. Now the conductor's merge-time validation is delegated like
|
|
32
|
+
everything else — a full suite bills the same tokens whoever runs it, and
|
|
33
|
+
running it in the conductor's context spends the plan's own memory on
|
|
34
|
+
watching a progress bar. The evidence gate binds it hardest of all
|
|
35
|
+
(`enforce`): a verifier report without raw output is a verifier that
|
|
36
|
+
verified nothing. A guard test pins the empty tool grant, and the prompt
|
|
37
|
+
owns the absence in a sentence a future "helpful" edit would have to delete.
|
|
38
|
+
|
|
39
|
+
**The conductor now plans FROM the kanban, moves tickets on it, and knows
|
|
40
|
+
the operator is watching the same one.** It wrote the board and never read
|
|
41
|
+
it: the `ready` lane IS the schedulable set (a ticket lands there only when
|
|
42
|
+
every dependency is merged), `blocked` and `changes-requested` are the
|
|
43
|
+
re-route queue, and distributing work from memory is how two agents get one
|
|
44
|
+
story. Moving a ticket is appending an event — the lifecycle moves the
|
|
45
|
+
working lanes on its own, `ticket.status` (with a reason) parks, blocks or
|
|
46
|
+
hands to the operator, a newer override replaces an older one, and the next
|
|
47
|
+
lifecycle event clears it. And there is only ONE board: the dashboard the
|
|
48
|
+
session autostarts runs the same fold over the same journals, so a moved
|
|
49
|
+
ticket is on the operator's screen within one refresh — narrating board
|
|
50
|
+
state in chat that the journal does not hold reads as either a stale
|
|
51
|
+
conductor or a broken board.
|
|
52
|
+
|
|
53
|
+
**Cards say who is on them RIGHT NOW.** The card face showed the historical
|
|
54
|
+
name list — "who ever touched this" — while the operator's question on a
|
|
55
|
+
large ticket is "who is doing what". Live agents join onto cards by
|
|
56
|
+
initiative AND ticket (two initiatives' T-3s never claim each other's
|
|
57
|
+
workers), state-coloured, with BLOCKED said out loud; the historical list
|
|
58
|
+
survives only when nobody is on it now, and the run-by-run record stays in
|
|
59
|
+
the detail panel's execution table.
|
|
60
|
+
|
|
61
|
+
The other two challenges, answered rather than deflected: no new skill —
|
|
62
|
+
the CI cap can indeed be raised, but the barrier was never the cap, it is
|
|
63
|
+
that no repeated need has graduated yet (the verifier is an agent precisely
|
|
64
|
+
because its protocol is its prompt); and no peer-to-peer evidence channel —
|
|
65
|
+
teams mode already gives peer NOTIFICATION, and evidence stays in the
|
|
66
|
+
journal because a teammate message dies with the session while the journal
|
|
67
|
+
survives compaction.
|
|
68
|
+
|
|
69
|
+
Surfaces corrected on the way: README's pitch and both agents-page tables
|
|
70
|
+
still carried the pre-forfeit reviewer ("no editing tools"), wrapped across
|
|
71
|
+
a line break where the earlier grep missed it.
|
|
72
|
+
|
|
3
73
|
## 0.1.38 — 2026-08-17
|
|
4
74
|
|
|
5
75
|
### The conductor is a project manager, and the prompts now argue it
|
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
|
|
|
@@ -311,14 +311,15 @@ repo, initiative or not — and the other eight are standalone protocols.
|
|
|
311
311
|
|
|
312
312
|
Agents: `tyran:scout` (recon, read-only), `tyran:implementer` (one story, own
|
|
313
313
|
branch), `tyran:reviewer` (may fix what it finds, but editing forfeits
|
|
314
|
-
`APPROVE` — it can never bless its own patch), `tyran:
|
|
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
|
-
enforces the cap (
|
|
318
|
+
enforces the cap (3868 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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: implementer
|
|
3
|
-
description: Takes one self-contained story from plan to commit or PR on its own branch, with tests and a self-review. Works only in the directory it was given
|
|
3
|
+
description: Takes one self-contained story from plan to commit or PR on its own branch, with tests and a self-review. Works only in the directory it was given, respects the hardware ceiling and the manifest of shared zones, and reports with raw command output rather than adjectives.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
You are an implementer. You get ONE story and you carry it to the end.
|
package/agents/retro.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: retro
|
|
3
|
-
description: After an initiative closes, reads the ledger, the notes and the agents' reports and
|
|
3
|
+
description: After an initiative closes, reads the ledger, the notes and the agents' reports and improves Tyran itself - skills, agents, scripts and docs, never product code. Defends hard against bloat and overfitting, so the default answer is to change nothing.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
You are the retrospector. Your ONLY product is a **better Tyran**. You do not
|
package/agents/reviewer.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: reviewer
|
|
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,
|
|
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, and returns APPROVE, REVISED or CHANGES-REQUESTED with executable counterexamples. May fix what it finds, which forfeits APPROVE. Never reviews its own code.
|
|
4
4
|
tools: Skill, Read, Grep, Glob, Bash, Edit, WebFetch, WebSearch, mcp__*
|
|
5
5
|
---
|
|
6
6
|
|
package/agents/scout.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: scout
|
|
3
|
-
description: Fast, cheap reconnaissance over a repo, its documentation, its data or external sources, changing nothing. Returns short, concrete findings with the file path or URL that proves each one. Used
|
|
3
|
+
description: Fast, cheap reconnaissance over a repo, its documentation, its data or external sources, changing nothing. Returns short, concrete findings with the file path or URL that proves each one. Used at the start of a task and through the research phase of a large initiative.
|
|
4
4
|
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__*
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -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 against the handoff's baseline, 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 suspect failure.
|
|
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.40",
|
|
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,
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Drive a real browser and come back with a MEASUREMENT rather than an impression -
|
|
2
|
+
description: Drive a real browser and come back with a MEASUREMENT rather than an impression - console errors and >=400 responses as counts, computed styles as JSON when appearance is disputed. Use when work touches UI, when a review must verify one, or when fidelity-gate asks for its measurement.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Browser check — proving a UI works, in numbers
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality
|
|
2
|
+
description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality) and the rule that a finding is refuted before it is reported. The verdict stays with the reviewer agent. Use when reviewing a diff or a pull request.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Code review — reading depth
|
package/skills/deslop/SKILL.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: The optimization pass, defined - delete before you add, one smell class per pass, behaviour pinned by a test that ran BEFORE the edit
|
|
2
|
+
description: The optimization pass, defined - delete before you add, one smell class per pass, behaviour pinned by a test that ran BEFORE the edit. Lints a SKILL.md and prose by the same instinct. Use for the per-story optimization pass or when code has grown noisy without growing capable.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Deslop — the pass that removes rather than adds
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Build a UI against a frozen visual reference without drift
|
|
2
|
+
description: Build a UI against a frozen visual reference without drift - an inventory extracted before any code, a relics list, and a gate that MEASURES computed styles on a fixture carrying the reference's own data. Use when a mockup, design spec or screenshot is the contract.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Fidelity gate — building against a frozen visual reference
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Work a reviewer's comments on a pull request to the end
|
|
2
|
+
description: Work a reviewer's comments on a pull request to the end - all three comment surfaces enumerated before any is triaged, every comment fixed, declined with a reason, or ticketed, push before you reply. Use when a PR comes back with review feedback or a red check.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# PR feedback — closing the loop with a human reviewer
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description:
|
|
2
|
+
description: Tune a prompt, or anything whose quality is measured by non-deterministic model output, without chasing noise - a noise baseline before the first edit, medians over repeated runs, enforcement AFTER generation rather than in the wording. Use when iterating on prompts or model-judged output.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Prompt tuning — working with non-deterministic output
|
package/skills/retro/SKILL.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Close an initiative by learning from it
|
|
2
|
+
description: Close an initiative by learning from it - spawns the retrospective agent over the ledger, the notes and the agents' reports, records what changed and what was rejected, and writes durable repo facts into .tyran/knowledge/. Runs at the end of an initiative; also available as /tyran:retro.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Retro
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Find the mechanism behind a failure instead of patching its symptom
|
|
2
|
+
description: Find the mechanism behind a failure instead of patching its symptom - reproduce first, one variable per experiment with the prediction written before the run, exit by naming the mechanism and pinning it with a failing test. Use for a bug, an unexplained red test, or a failure that will not reproduce.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Root cause — working a failure down to its mechanism
|
package/skills/run/SKILL.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Conduct a task end to end, from a one-line fix to a multi-day programme
|
|
2
|
+
description: Conduct a task end to end, from a one-line fix to a multi-day programme - a short interview, then autonomous execution to the finish. Classifies the task S/M/L/XL, configures itself to the repo, routes each role to a cost tier, drives the agent team from the kanban board, and stops only at genuine decisions. Use for /tyran:run or when asked to carry something "all the way" or "with a team of agents".
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Tyran — the conductor
|
|
@@ -11,7 +11,8 @@ description: Conduct a task end to end, from a one-line fix to a multi-day progr
|
|
|
11
11
|
|
|
12
12
|
You are the CONDUCTOR — a project manager, not a pair of hands. You plan,
|
|
13
13
|
delegate to agents with fresh context (`tyran:scout`, `tyran:implementer`,
|
|
14
|
-
`tyran:reviewer`, `tyran:retro`), read their reports,
|
|
14
|
+
`tyran:reviewer`, `tyran:verifier`, `tyran:retro`), read their reports,
|
|
15
|
+
spot-check, merge, and
|
|
15
16
|
hold the line on quality. The reason is arithmetic, not etiquette: your
|
|
16
17
|
context is the one place the WHOLE plan lives, and it is the most expensive
|
|
17
18
|
store in the system — measured once on Tyran's own development (the run its
|
|
@@ -176,6 +177,42 @@ open one.
|
|
|
176
177
|
`board.json` are part of the set — and the cross-initiative board with
|
|
177
178
|
`scripts/board.mjs`; every one of them is GENERATED — never hand-edit.
|
|
178
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.
|
|
179
216
|
Authored, alongside the journal:
|
|
180
217
|
`PLAN.md` (decomposition plus the **manifest of
|
|
181
218
|
shared zones**) and `NOTES.md` (side observations, defaults you adopted,
|
|
@@ -261,12 +298,23 @@ open one.
|
|
|
261
298
|
carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
|
|
262
299
|
it is forbidden. Tests for every non-trivial change. Repo validation per
|
|
263
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.)
|
|
264
311
|
- **A `Test timed out` measured while another heavy phase was running is
|
|
265
312
|
not evidence of a defect.** Re-run it serially, report the serial result,
|
|
266
313
|
and say the first run was concurrent. The hardware ceiling bounds AGENT
|
|
267
314
|
count, not concurrent heavy phases, so an agent can respect it and still
|
|
268
315
|
produce a red only the machine caused — five such failures in one session,
|
|
269
|
-
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.
|
|
270
318
|
- **An agent that dies on a terminal API error is RESUMED, not respawned.**
|
|
271
319
|
Its context, its corrected premises and its uncommitted diff all survive
|
|
272
320
|
the death; a fresh agent on the same handoff redoes work already on disk.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: How a skill earns its place here
|
|
2
|
+
description: How a skill earns its place here and how it is written so it fires - a three-question admission test, one protocol per skill, the description priced against the CI budget, and an activation test from a cold session. Use when the retrospective proposes a new skill or rewrites one.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Writing a skill for this plugin
|