@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.
@@ -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.38",
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.38",
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 has no
40
- editing tools at all, and security review always gets the strongest tier — a
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 four agents. Six of the skills are the conductor's own
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:retro`. A skill is admitted only when something already asks
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 (4352 of 5000 characters). What each one assumes, when it
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: 1586 unit tests, run with `node --test "tests/**/*.test.mjs"`.
322
+ it: 1590 unit tests, run with `node --test "tests/**/*.test.mjs"`.
322
323
 
323
324
  ## Documentation
324
325
 
@@ -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 (a worktree when the team runs in parallel), respects the hardware ceiling and the manifest of shared zones, and reports with raw command output rather than adjectives.
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 autonomously improves Tyran itself - the conductor skill, the agent roster, new skills, scripts and repo documentation. Its only product is a better Tyran, never product code. Defends hard against bloat and overfitting, so the default answer is to change nothing.
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
@@ -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, 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.
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 by the conductor at the start of a task and through the research phase of a large initiative.
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.38",
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": {
@@ -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
- if (c.agents && c.agents.length) button.appendChild(el('span', 'note', 'agents: ' + c.agents.join(', ')));
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
@@ -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 - deterministic waits instead of sleeps, console errors and >=400 responses as counts, computed styles dumped to JSON when appearance is disputed. Use when work touches UI, when a review must verify one, or when fidelity-gate asks for its measurement.
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, lifecycle) and the rule that a finding is refuted before it is reported. The verdict itself stays with the reviewer agent. Use when reviewing a diff or a pull request.
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
@@ -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 and again after. Lints a SKILL.md and prose by the same instinct. Use for the per-story optimization pass, before promoting a skill, or when code has grown noisy without growing capable.
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. An inventory extracted from the reference before any code, a relics list for what exists but should not, and a gate that MEASURES rather than judges - computed styles on a fixture carrying the reference's own data. Use when a mockup, design spec or screenshot is the contract.
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. Enumerate all three comment surfaces before triaging any, give every comment a disposition - fixed, declined with a reason, or ticketed - push before you reply, and resolve only what you addressed. Use when a PR comes back with review feedback or a red check.
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: Iterate on a prompt, or on 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, and detectors that surface candidates rather than defects.
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
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: Close an initiative by learning from it. Spawns the retrospective agent over the ledger, the notes and the agents reports, records what it changed and what it rejected, and writes durable facts about this repo into .tyran/knowledge/. Runs automatically at the end of an initiative; also available as /tyran:retro.
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. Reproduce first, change one variable per experiment with the prediction written before the run, bisect rather than re-read, and 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.
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
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: Conduct a task end to end, from a one-line fix to a multi-day programme. Works interactively by default - a short interview, then autonomous execution to the finish. Classifies the task (S/M/L/XL), configures itself to the repo (stack, validation commands, deployment policy), routes each role to a cost tier, runs a team of agents whose state lives in files rather than in context, stops only at genuine decisions, and reports with a progress line. Use for /tyran:run or when asked to carry something "all the way" or "with a team of agents".
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, spot-check, merge, and
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, and how one is written so it fires - a three-question admission test, one protocol per skill, a description priced against the CI budget before the body, and an activation test proving it triggers from a cold session. Use when the retrospective proposes a new skill or rewrites one.
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