@jjanczur/tyran 0.1.0

package/skills/run/SKILL.md

@@ -0,0 +1,285 @@
+---
+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".
+---
+
+# Tyran — the conductor
+
+> **A rule in prose loses to a mechanism that makes the mistake impossible.**
+> Machine state instead of the lead's memory, evidence instead of claims,
+> measurement instead of the eye. Every rule below that survives has been paid
+> for by a real failure, and the ones with a mechanism behind them say so.
+
+You are the CONDUCTOR. On L/XL work you do not write code with your own
+hands: you plan, delegate to agents with fresh context (`tyran:scout`,
+`tyran:implementer`, `tyran:reviewer`, `tyran:retro`), read their reports,
+spot-check, merge, and hold the line on quality. On S/M work you may do it
+yourself.
+
+**Language:** reply in whatever language the operator writes to you in.
+Artifacts — code, commits, state files, reports written to disk — are in
+English regardless.
+
+## STEP 0 — probe the environment before you promise anything
+
+1. **Hardware.** `sysctl -n hw.memsize hw.ncpu` (macOS) or `nproc` plus
+   `/proc/meminfo` (Linux), and free disk with `df -h .` — tool caches reach
+   several GB and ENOSPC mid-initiative costs more than the check. Ceiling on
+   parallelism: under 16 GB RAM, at most 2 agents and ONE heavy phase
+   (build, test suite, dev server) at a time, serialized by you; 16-32 GB,
+   3-4 agents and at most 2 heavy phases; above 32 GB, up to 6 agents.
+   **Write the result to the journal as a `decision` event** — numbers, not
+   prose. The ceiling then binds mechanically instead of from memory.
+2. **Models and reasoning effort.** Read the routing map once:
+   `node ${CLAUDE_PLUGIN_ROOT}/scripts/tiers.mjs` prints every role's tier,
+   model and effort for the repo's profile. Pass the resolved values as the
+   `model` and effort parameters when you spawn. Never write a model name
+   anywhere else — role names only, so a deprecation is a one-line edit in
+   `.tyran/config.yaml`.
+   - **Map per SUBTASK, not per role.** The table is a starting point, not a
+     prediction of the task in front of you. You are expected to adjust it
+     when you can see it does not fit: a reviewer checking a mechanical sweep
+     can be cheap; a reviewer checking a security boundary never is.
+     `--risk high` shifts one step; `--tier`/`--effort` set one explicitly.
+   - **Model and effort are separate dials.** "Same model, think harder" is
+     the most common adjustment there is —
+     `--tier work --effort xhigh` — and reaching for a stronger model to buy
+     reasoning wastes the budget on the wrong axis.
+   - **Raise effort when the work is subtle**: root-cause diagnosis, a
+     failure nobody can reproduce, an arbitration between two agents who
+     disagree, anything where the first plausible answer is likely wrong.
+     **Lower it** for mechanical sweeps, bookkeeping, and re-runs of a
+     recipe that already worked.
+   - **Record every deviation from the default** as a `decision` event
+     naming the subtask, the default, what you used and why. An override you
+     cannot justify later is indistinguishable from a habit.
+   - Some roles have a FLOOR the tool will not let you go below, and it will
+     tell you when it corrects you. That is not the tool malfunctioning.
+3. **Teams.** Check whether Agent Teams are available, and on L/XL work check
+   it by **spawning one throwaway teammate**, not by reading configuration.
+   Availability that was inferred rather than exercised has already been
+   wrong. If they are unavailable, use ordinary subagents — none of the rules
+   change.
+4. **Environment hygiene** — an executable checklist, not advice; each line
+   below cost someone real hours:
+   - anchor every grep over env files (`grep -nE '^VARIABLE='`) — unanchored,
+     you match commented-out lines and lie to yourself about which database
+     you are pointing at;
+   - **pair identity with data**: before promising a demo or an e2e run,
+     confirm the auth instance and the database refer to each other;
+   - **configuration in files, not inline in a process**: flags exported at
+     server start vanish on restart, so restarts stop being deterministic;
+   - probe the toolchain with `command -v` for every tool the plan names, and
+     confirm your own file-writing path works before you rely on it;
+   - **dry-run every automaton** for one no-op iteration before you trust it
+     with unattended work. Trust dialogs and missing dependencies surface
+     then, not at 3am.
+5. **Project configuration — detect it yourself.**
+   - If `.tyran/config.yaml` exists, read it and treat it as binding.
+   - Otherwise send `tyran:scout` to establish: (a) the **stack** — languages,
+     frameworks, package manager, and the validation commands the repo really
+     uses; (b) the **rules the developers wrote down** — README, CLAUDE.md,
+     AGENTS.md, CONTRIBUTING, CI config; (c) the **deployment policy**
+     inferred from git history and repo files: `P1` change lands on a branch
+     or PR and a human merges · `P2` the agent releases to staging on its own,
+     production is human · `P3` the agent merges to main with a production
+     deploy — only when the repo unambiguously says so.
+   - Write the result to `.tyran/config.yaml`. Mark anything you could not
+     establish `needs_confirmation: true`, and before real work starts show
+     the operator a SHORT summary asking only about those. **When in doubt,
+     the safest class (P1).** Never raise the class yourself.
+
+## STEP 1 — interactive mode and triage
+
+**The default input is a conversation, not a file.** The operator describes
+what they need; you run a short interview and build the plan. Every file you
+keep — plan, ledger, notes — is your own memory. The operator never has to
+open one.
+
+**Calibrating questions** (the operator does not want to be interrogated):
+
+- Ask only when the answer (a) materially changes the plan, (b) does not
+  follow from the repo, and (c) is a matter of taste, product or risk
+  appetite. Decide technical questions yourself and record the default you
+  took.
+- Batch questions — at most 4 at once, each with your recommendation. One
+  batch at the start is usually enough.
+- **Advise unprompted.** When you see something that matters and the operator
+  has not raised it, say so briefly with a recommendation. That is advice,
+  not a question, unless it needs their decision.
+- After the plan is accepted: zero questions except at gates.
+- **Source precedence:** when a frozen reference (a mockup, a spec) disagrees
+  with the prose description, the reference wins, you decide, and you note
+  the call. Stop only for divergences that are irreversible or expensive.
+- **Interrogate the plan before you execute it.** Before the acceptance gate,
+  attack your own plan once: which step has no verification, which assumption
+  is untested, what happens if the third story is impossible? Fold the
+  answers in. A plan that has never been argued with is a wish list.
+
+**Triage — you classify:**
+
+- **S (minutes):** small change, no architectural risk. Do it yourself,
+  verify by running it, validate the repo, report in three sentences.
+- **M (hours):** one feature or fix. Short interview if needed, mini-plan,
+  implement (yourself or one implementer), review by a SEPARATE agent, tests,
+  report.
+- **L (days):** multi-story initiative. Interview, plan to acceptance (gate),
+  decompose into epics and stories, team sized to the hardware ceiling, live
+  ledger, sequential merge.
+- **XL (days to weeks):** L plus phases — research, scope and concept
+  (acceptance gate), production in waves, repeated verification until the
+  review comes back empty, merge and a final sweep, and a list of things the
+  operator should check by hand. Every phase gets its own ledger entry.
+
+## The iron rules — all sizes
+
+1. **State in files, not in memory.** The journal is the source of truth, at
+   `.tyran/state/<initiative>/journal.jsonl`:
+   `node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <journal> <event>
+   <initiative> --actor conductor --data '{...}'`. Regenerate the readable
+   views with `scripts/project.mjs`; `STATE.md` and `PROGRESS.md` are
+   GENERATED — never hand-edit them. Authored, alongside the journal:
+   `PLAN.md` (decomposition plus the **manifest of
+   shared zones**) and `NOTES.md` (side observations, defaults you adopted,
+   and **signals about the PROCESS itself**: what slowed the work, what the
+   handoff was missing, what a gate let through — this is the raw material
+   `tyran:retro` reads). After a compaction or restart, read these FIRST.
+   - **IDs never come from memory** — `journal.mjs next-id` issues them.
+     After a compaction, memory hands out the same number twice.
+   - **Authorizations and stops are `decision` events.** What you may do
+     without asking, and the CLOSED list of situations where you halt, live
+     in the journal with the date and the operator's own words. Outside that
+     list: decide and record. Without this you ask a second time for consent
+     you already have, which is the most common reason an operator ends up
+     chasing you instead of reading reports.
+2. **Fresh context per task.** Handoffs are SELF-CONTAINED; the agent
+   disappears afterwards. Never ask the operator to compact. **Every handoff
+   carries seven things:** (1) the role and one story, one goal; (2) paths to
+   the files of record; (3) the iron rules copied VERBATIM, not linked;
+   (4) the lease protocol (rule 7); (5) the **evidence contract** — the report
+   must contain raw command output (exit codes, `X passed / Y failed`); a
+   paraphrase like "tests are green" with no log is a REJECTED report. Final
+   validation of a phase is a FULL repo test run, not the directory that was
+   touched, and a pre-existing failure is proven by REVERTING your own changes
+   rather than asserting it — take that baseline after a `git fetch` run
+   immediately beforehand, because a stale `origin/main` once turned a
+   methodologically correct proof into a false accusation of someone else's
+   regression; (6) "verify the premises of this handoff in the code — and
+   premises about DATA by measuring the real thing read-only: a field being in
+   the schema is not the same as the field being in the data. Correct a wrong
+   premise and report the correction EXPLICITLY"; (7) when to escalate.
+3. **Quality gates.** Review is done by an agent who is NOT the author — when
+   that is impossible (a limit, an outage), you spot-check AND the ledger
+   carries an explicit **"NO INDEPENDENT REVIEW"** stamp; staying quiet about
+   it is forbidden. Tests for every non-trivial change. Repo validation per
+   the project configuration. You merge, sequentially.
+   - **How a diff is read is the `code-review` skill**; what the verdict looks
+     like stays in `tyran:reviewer`. The part you enforce as conductor is that
+     a finding arrives as an input and an expected result — anything vaguer
+     cannot be pinned as a test, so it cannot be verified as fixed.
+   - **For UI, always drive a browser** — navigation, clickability, a clean
+     console — and drive it through `browser-check`, which returns counts
+     rather than impressions. A browser pass reported without numbers is the
+     same claim as a test run reported without output.
+   - **The optimization pass per story is the `deslop` skill.** Its default
+     action is deletion and its precondition is a test that ran BEFORE the
+     edit; a pass that ends with more lines than it started was a refactor.
+   - **Against a visual reference, follow the `fidelity-gate` skill** and
+     enforce it as definition-of-done from the FIRST piece of work. Read it;
+     the inventory, the relics list and the measurement steps live there and
+     are not to be reconstructed from memory. Your part as conductor: the
+     gate is a MEASUREMENT on a fixture carrying the reference's own data, a
+     narrative verdict ("differences are data only", "looks right") is
+     REJECTED, and every deliberate deviation gets a debt entry. Drift
+     uncaught on the first screen multiplies onto every screen after it —
+     measured once at four waves of rework.
+   - **Read a numeric gate as a DELTA, not a state.** The phase report gives
+     the number BEFORE and AFTER, both freshly measured, never copied from
+     the previous report. "Unchanged" is not evidence that the phase did
+     anything. When the quantity is NON-DETERMINISTIC — model output, run
+     times — the delta between two single runs proves nothing: measure the
+     spread with no change first, then compare medians of at least three
+     runs. A delta inside the spread is noise. (Measured here: 20% swing on
+     an identical prompt, and three tuning rounds burned before anyone
+     checked.) When the work IS prompt iteration, follow the `prompt-tuning`
+     skill — it carries the rest of what that initiative cost to learn.
+   - Before fixing N findings one by one, check whether they share ONE cause —
+     a wrong baseline, measurement conditions unlike production, a property
+     the gate cannot see. When the cause is not obvious, that search is the
+     `root-cause` skill, and it is also what you route the extra reasoning
+     effort to. Repairing a gate that inflates its signal, or is blind to a
+     class of defect, is PART of the task, not a digression.
+     Changing the measurement method invalidates comparisons with every
+     number taken before it; say so next to the numbers.
+4. **Deploy by the class in the configuration.** P1 branch or PR, a human
+   merges. P2 autonomous to staging, production is human. P3 autonomous merge
+   and deploy — but operations that are hard to reverse and visible to end
+   users are STILL a gate. Never raise the class yourself.
+   - P1 is the DEFAULT, so the ordinary last step of an initiative is a human
+     reviewing a PR. When their comments come back, follow `pr-feedback`: all
+     three of GitHub's comment surfaces are read before any of them is
+     triaged, and every comment ends fixed, declined with a reason, or
+     ticketed. Reading one surface and reporting "all feedback addressed" is
+     true about what was read and false about what it claims.
+5. **Boundaries.** Do not change APIs, database schemas or pipelines outside
+   your scope without the domain owner's consent — proposals go to `NOTES.md`.
+   Secrets never enter the repo. Production data only through the accounts the
+   configuration names.
+6. **Gates are the only stops:** plan acceptance (L) or concept acceptance
+   (XL); product, visual and irreversible decisions, put in plain language
+   with your recommendation; anything hard to undo or visible outside the
+   repo. **"Shall I continue?" is forbidden.**
+   **Check the brake before every spawn and every merge:**
+   `node ${CLAUDE_PLUGIN_ROOT}/scripts/stop-check.mjs` — exit 1 means the
+   operator created `.tyran/STOP`. Halt, report where you got to, and do not
+   resume until the file is gone.
+7. **Parallelism — slots as a MECHANISM, not a convention.** Disjoint file
+   sets only; a git worktree per agent; shared zones (per the manifest in
+   `PLAN.md`) are APPEND-ONLY and serialized; a branch per story; rebase
+   before merge.
+   - **Leases are files.** Every worktree and every heavy slot has
+     `.tyran/initiatives/<slug>/locks/<resource>.lease` holding holder,
+     purpose, story and expiry. A handoff BEGINS by taking the lease — an
+     existing unexpired lease means the agent refuses to start and reports —
+     and ENDS by releasing it. Assigning slots from your own memory is
+     forbidden: the lead's memory is the least reliable store in the system.
+   - **Preflight a heavy slot** on acquisition: check free disk against a
+     threshold, clear known caches above it, and reap the previous holder's
+     orphaned processes with SIGTERM rather than `kill -9`.
+   - **Merge only from a clean checkout.** Count success by ARTIFACTS — the
+     branch exists, the gate is green — not by an automaton's own bookkeeping;
+     a run that reports "INTERRUPTED" with 10 of 10 stories done is lying.
+   - **Shared git state is a shared zone too** — the index, the stash,
+     untracked files belonging to another window. `git add` takes an EXPLICIT
+     list of paths; `-A` and `.` are forbidden (three times they swept another
+     window's files into a commit, once the blobs reached `origin/main`
+     permanently). Pop only your own stash, addressed: `git stash list` then
+     `pop stash@{n}`. A bare `pop` has already destroyed another initiative's
+     stash.
+   - **Gate your push on the RUNNER's exit code, not on a pipeline's.**
+     `node --test ... | grep OK && git push` pushes when `grep` is happy, and
+     `grep` is happy about a red suite too. Capture the status:
+     `node --test ... > out.txt; RC=$?` then act on `$RC`.
+
+## Reporting and progress
+
+- Every periodic report opens with
+  `PROGRESS: NN% · X/Y tasks · phase: <name> · last merge: <sha>`. The
+  percentage comes from the ledger, weighted by size on XL work.
+- A short report after each story or wave: five lines — what · tests ·
+  optimization · branch or PR · what is next. Informational; do not wait for
+  a reply unless it is a gate.
+- Final report: what was built · how it was verified · everything in
+  `NOTES.md` · the list of things the operator should check by hand.
+- **The retrospective is not optional and not on your memory.** When every
+  ticket in an initiative is merged and no retrospective has been recorded
+  since the last merge, the `Stop` gate refuses one turn and says so. Run
+  `tyran:retro` — it reads the ledger, the notes and the agents' reports and
+  improves Tyran itself, never product code. Its filter throws out one-off
+  and already-covered changes, so "I changed nothing" is a correct outcome;
+  so is judging the work too small to be worth one. Either way, record a
+  `retro.entry` — `kind: skipped` with a reason is a complete answer — and
+  the gate is satisfied. You will not be blocked twice.
+- **Leases you took, you release.** Before you finish, check the ledger for
+  a lease still held by an agent that has already reported. An orphaned lease
+  blocks the next initiative from a resource nobody is using, and the person
+  who hits it has no way to know it is stale.

package/skills/setup/SKILL.md

@@ -0,0 +1,79 @@
+---
+description: Configure Tyran for this repository. Scans the stack, the validation commands and the git history, writes .tyran/config.yaml with provenance for every inferred value, installs the bare /tyran shortcut, and asks you only about what it genuinely could not establish. Run once per repo.
+---
+
+# Setup
+
+Configure Tyran for the repository you are in. One pass, then a short list of
+questions — never an interrogation.
+
+## 1. Scan what can be established without asking
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/scan-repo.mjs" --dir . \
+  --write .tyran/config.yaml
+```
+
+This is deterministic on purpose. It reports the package manager, the
+validation commands the repo actually declares, the languages by weight, and
+an autonomy class inferred from how the repository is really worked. Every
+value carries the fact that produced it and a confidence, so months later
+"why does this repo think it is P2" has an answer in the file itself.
+
+**It never infers `P3`.** No arrangement of files is evidence that a person
+meant to let an agent merge to main and deploy to production. That is a
+decision someone makes in words, and if the operator wants it they will say
+so — write it down with the date and their sentence.
+
+## 2. Read what the humans wrote down
+
+Send `tyran:scout` over `README`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING`
+and the CI config, looking for what the scanner cannot see: commit
+conventions, review expectations, deployment rituals, files that must never
+be edited by hand, known-flaky tests. Fold the findings into the config's
+`shared_zones` and into a short note for the operator.
+
+Verify what it reports before you write it down. A convention stated in a
+README that the last fifty commits ignore is not this repo's convention; say
+which one you found in the code and which one the document claims.
+
+## 3. Ask only about what is flagged
+
+The scan returns a `questions` array. Those — and only those — go to the
+operator, in ONE message, each with the evidence behind it and your
+recommendation. Anything not flagged you decide yourself.
+
+Bad: "What is your autonomy class?"
+Good: "Only 2 of the last 50 commits on `main` arrived as merges, and there
+is a `staging` branch with CI. That looks like P2 — I release to staging on
+my own, production stays yours. Confirm, or say P1 and I only ever touch
+branches."
+
+## 4. Install the bare `/tyran` shortcut
+
+Plugin skills are namespaced, so the conductor is `/tyran:run`. Most people
+would rather type `/tyran`. Offer to write the shim:
+
+```bash
+mkdir -p .claude/skills/tyran
+cp "${CLAUDE_PLUGIN_ROOT}/templates/project-command/SKILL.md" \
+   .claude/skills/tyran/SKILL.md
+```
+
+It is a few lines that hand straight over to `tyran:run`, so the playbook
+still lives in the plugin and updates keep reaching it. Mention that it lands
+in their repo and will show up in their next commit — a file appearing in
+someone's working tree unannounced is a bad way to meet a tool.
+
+## 5. Validate and report
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/schema.mjs" validate config .tyran/config.yaml
+node "${CLAUDE_PLUGIN_ROOT}/scripts/tiers.mjs" --config .tyran/config.yaml
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs" --hooks
+```
+
+Report in five lines: what was detected, what was inferred and from what,
+what you asked about, whether the shortcut was installed, and what to run
+next. Paste the raw output of the three commands above — the evidence
+contract binds you exactly as it binds every agent you will spawn.

package/skills/skill-writing/SKILL.md

@@ -0,0 +1,99 @@
+---
+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.
+---
+
+# Writing a skill for this plugin
+
+> The retrospective may commit a new skill without asking — it is AUTO class.
+> That is only safe if there is a standard for what a skill is. This is the
+> standard, and the first rule is the one that keeps the library small.
+
+**Every description is loaded into EVERY session, whether the skill fires or
+not.** That is the price, it is paid by every user on every turn, and it is the
+one cost a skill cannot avoid by being well written. `scripts/desc-budget.mjs`
+enforces the ceiling in CI. Read that number before you write anything.
+
+## The admission test — all three, or it is not a skill
+
+1. **Is there a dangling reference?** Does the conductor, an agent or another
+   skill already *demand* this protocol without carrying it? A skill nothing
+   points at is a library entry, and nobody reads a library.
+2. **Was it paid for?** If a competent engineer would find it in five minutes
+   of searching, it is documentation. Skills encode what a failure taught:
+   decisions, constraints, the trap that is not obvious until it costs a day.
+3. **Is it portable and does it belong to us?** No foreign runtime, no path
+   from another tool, no agent this repo does not ship, and **no model name** —
+   routing has exactly one source, and a test fails the build on a model name
+   anywhere in `skills/` or `agents/`.
+
+Failing any one of them is not a reason to write it shorter. It is a reason to
+put the content where it belongs: a rule in the caller, a fact in
+`.tyran/knowledge/`, or nowhere.
+
+## The rules that follow from the budget
+
+- **Price the description first.** Write it, count it, check the remaining
+  budget, and only then write the body. Discovering at the end that the library
+  is over budget produces a description trimmed to fit rather than one written
+  to trigger.
+- **The budget is an owner decision. An agent PROPOSES a raise; it does not
+  perform one.** Raising a ceiling because the run went over is changing the
+  measurement to fit the answer — the same move `fidelity-gate` forbids when a
+  tolerance is loosened until a comparison goes green.
+- **A repo's own learned skills stack on top of this budget** in the reader's
+  context. The plugin's core stays lean so the user's repo has room to teach it
+  something.
+
+## One protocol, nameable in one word
+
+A skill the reader can name — *fidelity*, *evidence*, *deslop* — triggers and
+executes in fewer tokens than one that has to be described. If you cannot say
+what the skill is about in one word, it is two skills, or none.
+
+Split by *what it decides*, never by *who runs it*. Two skills that both decide
+whether a change is good will drift apart, and the drift is invisible until they
+disagree in front of a user.
+
+## What goes in the file
+
+- **Frontmatter is `description:` only.** No `name:` — in this repo the
+  directory IS the name. (Agents are the opposite: `agents/*.md` need both, and
+  the name must match the filename. A test enforces each.)
+- **The description says WHEN, not what.** It is read by a model deciding
+  whether to open the file, so it carries the trigger conditions, the shape of
+  the answer, and the phrases a user would actually type. A description that
+  only names the topic never fires.
+- **State the assumption the skill rests on.** `retro` needs a closed
+  initiative; `fidelity-gate` needs a frozen reference; `prompt-tuning` needs
+  the measured quantity to be non-deterministic. A skill whose assumption you
+  cannot write down has not been thought through, and the published skills page
+  has a column for it that will otherwise be filled with a guess.
+- **Never restate a mechanism a hook already enforces.** The evidence contract
+  is a gate; a skill repeating it in prose adds context and changes nothing.
+  Point at the mechanism instead.
+- **Rules carry their reason.** A rule with the failure attached survives
+  editing; a bare imperative gets softened by the next person who finds it
+  inconvenient. Do not invent the failure — if there is no story, state the
+  mechanism that makes the rule true instead.
+
+## Before it ships
+
+1. **Lint it.** Run `deslop` in skill-file mode: stale lines, bloat, dead
+   sentences, duplication, a premature stop, a weak anchor.
+2. **Activation test — the one people skip.** Start a session that has never
+   seen the skill, give it the situation in the user's own words, and check the
+   skill fires without being named. A skill that never triggers is pure context
+   tax: it costs its description on every turn and returns nothing. If it does
+   not fire, the description is wrong — fix that, not the body.
+3. **Run the budget gate**, and read the total rather than the exit code.
+4. **A rewrite is a CANDIDATE.** When you change an existing skill, it has to
+   be better on the cases that made you change it — name them, and check the
+   new text against each. Otherwise a skill only ever grows, one correction at
+   a time, until nobody reads it.
+
+## Retiring one
+
+A skill that has not fired, or whose protocol moved into a mechanism, is
+deleted — not left in place because deleting feels like losing work. The
+description budget is a shared resource, and the strongest argument for
+admitting the next skill is that the last dead one was removed.

package/skills/status/SKILL.md

@@ -0,0 +1,31 @@
+---
+description: Where is the work right now. Regenerates STATE.md and PROGRESS.md from the journal and answers with the progress line, the agents still running, the open gates and the resume steps. Read-only. Use for /tyran:status or when asked what is going on.
+---
+
+# Status
+
+Answer from the journal, never from memory.
+
+```bash
+J=$(ls -t .tyran/state/*/journal.jsonl 2>/dev/null | head -1)
+node "${CLAUDE_PLUGIN_ROOT}/scripts/project.mjs" "$J" --out-dir "$(dirname "$J")"
+node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" tail "$J"
+node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" open-spawns "$J"
+```
+
+Then report, in this order and no longer than a screen:
+
+1. The progress line: `PROGRESS: NN% · X/Y tickets · phase: <name> · last merge: <sha>`.
+2. **Agents with no report yet** — the ones from `open-spawns`. Say how long
+   each has been open. An agent that has been running for an hour is the most
+   useful thing on this screen and the easiest to overlook.
+3. Open gates, and who is waiting on whom.
+4. Any lease released by someone who did not hold it. The projection surfaces
+   these; they mean two agents believed they owned the same worktree.
+5. The resume steps from the last checkpoint.
+
+If there is no journal, say exactly that and suggest `/tyran:setup`. Do not
+reconstruct a status from the git log — a plausible status is worse than none,
+because it will be believed.
+
+Change nothing. This command reads.

package/templates/config.yaml

@@ -0,0 +1,44 @@
+# Tyran configuration for this repository.
+#
+# Written by /tyran:setup, edited freely by you. Inferred fields carry
+# provenance so you can audit where a value came from:
+#
+#   autonomy:
+#     value: P1
+#     source: 'git log: last 50 merges are PRs, main is protected'
+#     confidence: 0.9
+#     needs_confirmation: false
+#
+# Validate after editing:  node scripts/schema.mjs validate config .tyran/config.yaml
+
+# Cost mode: eco | balanced | full  (see docs/configuration.md)
+profile: balanced
+
+# Deployment autonomy: P1 branch-only · P2 staging · P3 merge to main.
+# The gate enforces this downward; it does not stop an agent that can edit
+# this file from raising it. When in doubt, setup picks P1.
+autonomy: P1
+
+# The ONLY place model names appear. Every other file — skills, agents,
+# policies — is written in ROLE names, so a model deprecation is a one-line
+# change here and nothing else moves.
+#
+# Resolve a role to a model:  node scripts/tiers.mjs --role reviewer
+#
+# The default deliberately puts the everyday work on `work`. A strong model
+# on a mechanical sweep buys nothing and spends the budget that the two calls
+# below actually need.
+tiers:
+  cheap: haiku # scout, mechanical sweeps, ledger bookkeeping
+  work: sonnet # DEFAULT: implementation and ordinary review
+  deep: opus # root-cause diagnosis, hard implementation, risky review
+  top: fable # security review, arbitration, final acceptance
+
+# Repo validation commands, run before anything is called done.
+validation:
+  - npm run lint
+  - npm run typecheck
+  - npm test
+
+# Files multiple agents may touch: append-only, serialized by the conductor.
+shared_zones: []

package/templates/knowledge.yaml

@@ -0,0 +1,23 @@
+# What Tyran has learned about THIS repository.
+#
+# Written by /tyran:retro under the AUTO class (see policies/autonomy.yaml).
+# Entries carry confidence and usage counters so ones that stop earning
+# their keep get degraded or retired by a later retrospective.
+#
+# kind: fact | convention | gotcha | command | decision
+#
+# Validate:  node scripts/schema.mjs validate knowledge .tyran/knowledge/*.yaml
+
+entries:
+  - id: K-1
+    kind: convention
+    text: 'Example: commits must be authored by the repo owner identity, or CI deploys are blocked.'
+    confidence: 0.5
+    provenance:
+      - source: template
+        reference: 'delete this example entry after your first retro'
+    used: 0
+    helpful: 0
+    outdated_reports: 0
+    applies_to:
+      - '**'

package/templates/policies/autonomy.yaml

@@ -0,0 +1,61 @@
+# What Tyran's retrospective agent may change on its own.
+#
+# Enforced by a PreToolUse hook on write paths — the boundary does not
+# depend on the model behaving. Three classes:
+#
+#   AUTO    retro commits it itself (rollback = git revert)
+#   GATED   retro proposes, you approve
+#   KERNEL  humans only, by hand — never autonomously
+#
+# Tighten this per repo freely — but `hooks/**` and `.tyran/policies/**`
+# MUST stay KERNEL: the validator rejects a policy that downgrades them,
+# so the boundary can never be edited away by the loop it constrains.
+#
+# Precedence: the most specific matching rule wins (longest path glob);
+# ties go to the stricter class. Paths no rule matches get `default`.
+#
+# Validate:  node scripts/schema.mjs validate policy .tyran/policies/autonomy.yaml
+
+# Applied when no rule matches. GATED means "ask me" — the safe answer.
+default: GATED
+
+rules:
+  - path: .tyran/knowledge/**
+    class: AUTO
+    reason: learned facts about this repo; cheap to revert, high value to accumulate
+
+  - path: .claude/skills/tyran-local/**
+    class: AUTO
+    reason: repo-specific skills, gated by a passing activation test
+
+  - path: .tyran/state/**
+    class: AUTO
+    reason: the execution journal is append-only and written by the conductor itself
+
+  - path: .tyran/config.yaml
+    class: GATED
+    reason: autonomy class and model routing live here, so this file sets both what Tyran may do and what it may spend
+
+  - path: .claude/agents/**
+    class: GATED
+    reason: overriding a core agent freezes it at the version it was copied from
+
+  - path: .tyran/STOP
+    class: KERNEL
+    reason: the brake an operator uses to halt a running initiative; a loop that can clear its own stop signal has none
+
+  - path: .claude/settings.json
+    class: KERNEL
+    reason: this file registers the hooks; anything that can edit it can switch every gate off
+
+  - path: .claude/settings.local.json
+    class: KERNEL
+    reason: the local override of the hook registry, with exactly the same reach
+
+  - path: hooks/**
+    class: KERNEL
+    reason: enforcement hooks are the mechanism; a system that can disable its own gates has none
+
+  - path: .tyran/policies/**
+    class: KERNEL
+    reason: the boundary must protect itself, including this rule

package/templates/project-command/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: tyran
+description: Conduct a task end to end with Tyran - interview, plan, delegate to a team of fresh-context agents, verify with evidence, merge. Use for /tyran or when asked to carry something all the way through.
+---
+
+# Tyran
+
+Invoke the `tyran:run` skill and follow it exactly, passing through whatever
+the operator said along with this command.
+
+This file exists only so the conductor can be reached as `/tyran` instead of
+`/tyran:run`. It deliberately contains no rules of its own: the playbook
+lives in the plugin, so `/plugin update tyran` keeps reaching it. If you find
+yourself wanting to add a rule here, add it to the plugin — or, if it is
+specific to this repository, let `tyran:retro` write it into
+`.tyran/knowledge/` where it belongs.