libretto-automata

README

𝄞 Libretto Automata

The libretto is written first. The automaton performs it.

The panel — real terminal output, captured from the binary. tab switches where it acts.

---

An 18th-century automaton was a machine that played music by reading a score. A human wrote the notes; the machine executed them. It never improvised — it did exactly what the paper said. If the performance was wrong, the paper was wrong.

That is how this works. You write the spec. The agent performs it. When the output is bad, you fix the libretto, not the automaton.

What you get

Two things, and the first one is the point:

The payload	an eight-phase spec-driven flow for Claude Code, as skills and commands
The CLI	a Go binary that symlinks the payload into ~/.claude

flowchart LR
    repo["this repository<br/>skills/ agents/ commands/"]
    home["~/.claude<br/>one symlink per item"]
    cc["Claude Code<br/>sessions"]
    repo -->|"libretto install<br/>links, never copies"| home
    home -->|reads| cc

What changes in practice: you say what you want, and before any code exists you get a contract — what "done" means, what is deliberately out of scope, and how each promise will be proven. You approve that, then a plan, then the work happens against it. A fresh reviewer that saw none of the session checks the result, and the last question is always whether to push.

flowchart LR
    f1["1. find the work"] --> f2["2-4. write the spec,<br/>ask what is open"]
    f2 --> s1{"stop: agree<br/>the spec"}
    s1 --> f5["5. write the plan"]
    f5 --> s2{"stop: agree<br/>the plan"}
    s2 --> f6["6. build and check"]
    f6 --> f7["7. review, present"]
    f7 --> f8["8. record"]
    f8 --> s3{"stop:<br/>push?"}

Links are made per item, never per directory, so this coexists with anything else installed into ~/.claude. Anything already there that this tool did not create is left untouched and reported.

Install

Two commands, plus Go 1.26+.

go install github.com/pausf/libretto-automata/cmd/libretto@latest

libretto install   # symlink every item into ~/.claude

That is the whole install. No tarball to fetch, no bootstrap step. Check it landed:

libretto status    # every item's state, changes nothing

Updating

libretto update

Installs the newest version and relinks, so a release that adds a skill arrives linked.

The panel also tells you when a newer version exists, checked once a day and silent when it cannot check.

From a checkout instead

For working on the payload rather than with it:

git clone git@github.com:pausf/libretto-automata.git ~/gitrepos/libretto-automata
cd ~/gitrepos/libretto-automata

make build      # stamps the version from git describe
make link       # puts `libretto` on your PATH via ~/.local/bin

update pulls there instead of downloading, and the tree you are standing in is the installation — why.

Your first run

The CLI is installed and you will not type it again for a while. The flow lives inside Claude Code — what follows are slash commands, not shell commands.

1. Say what you want.

   /libretto-flow add a --json flag to status
   

   It reads the request, names the change, and writes it down before anything else. Hand it a tracker key instead — /libretto-flow EUCAR-1234 — and it reads the ticket.

2. It stops at the spec. You get the contract: outcomes, what is out of scope, the constraints it found in your code, and the test that will prove each promise. This is the cheap place to disagree — a wrong sentence here costs a line, and the same misunderstanding costs a day once it is code.

3. It stops at the plan. An ordered checklist, with what can start now.

4. It builds, marking boxes as it goes, and leaves a proportionate test behind — one runnable check for real logic, none for a one-liner with no logic in it.

5. A fresh reviewer reads the result. It saw none of the session that wrote the code, which is the entire point, and it re-runs every proof the change touched.

6. It reports in the spec's own terms, including what it deliberately did not build and what would bring it back.

7. It asks once about pushing. That answer is always yours.

Those are the three places it waits, and each one is a question your terminal puts in front of you — not a line at the bottom of a report. /libretto-attacca answers all three in advance, for when you want the whole thing to run without you.

Nothing else to learn to start. The rest is knowing which door to use:

/libretto-status              # what is in flight and what is queued — changes nothing
/libretto-flow                # find the work and take it through the phases
/libretto-flow EUCAR-1234     # …starting from a ticket
/libretto-queue               # capture ideas, one after another, and build none of them
/libretto-next                # take the oldest queued idea into the flow
/libretto-review <pr-url>     # review a PR/MR in a workspace that restores itself
/libretto-retro               # spend the lessons ledger — fix what the flow got corrected on
/libretto-attacca             # the same flow, without stopping — straight to a pushed PR

/libretto-attacca answers those stops in advance. Same phases, same spec, same plan, same report — it just does not wait for you at any of them, and it ends with the branch pushed and the request open. What it will not do is answer a gate: a failing check still stops it where it stands, and it never merges, tags or releases. attacca is what a score writes to mean go on to the next movement without pausing.

The flow does not begin at a tracker. Phase 1 asks three sources in order — a change already in flight, a tracker key or URL, and what you said — and the order is the point: starting something new while a change sits half-finished is how the half-finished thing gets abandoned.

	Phase	Skill
1	find the work — in flight, tracker, or asked for	find-work
0·2·3	does a spec even need to exist · the six pillars · one per subtask	write-spec
5	the plan — live state, one writer	write-plan
6	build, with proportionate checks	build-and-check
7	present, including what was left out	present-work
8	commit, and make the spec true again	record-work

Three rules hold at every phase, not one of them:

• ask — with a recommended option, real alternatives, and room to answer otherwise
• commit — per task, so a bisect lands somewhere meaningful
• evidence — nothing is true until it has been observed

Commands

libretto	the panel — needs a terminal
libretto status	every item's state. Read-only, always.
libretto install	link everything. Idempotent; non-zero exit if anything was skipped.
libretto uninstall	show what this repo installed here — changes nothing
libretto uninstall --yes	take it back out
libretto update	install the newest version and relink — or pull, in a checkout
libretto doctor	what needs attention, plus what the payload expects here
libretto prune	show links whose source is gone — changes nothing
libretto prune --yes	remove them
libretto preview	print the panel once, no TUI
libretto models	which model each agent runs on, and how hard it thinks. Read-only.
libretto models set <model> <agent>…	declare the model; --all for every agent
libretto models effort <level> <agent>…	declare the effort; --all for every agent

prune and uninstall are both dry by default — they change nothing until --yes. They are not the same command: prune removes links whose item is gone, uninstall removes links that are working.

Choosing a model per agent

Not every agent needs the same model. The review lenses that pattern-match over prose — design, tests — do the job on a cheap one; the lens looking for what an attacker can reach should not.

libretto models                                  # who runs on what
libretto models set haiku review-lens-design review-lens-tests
libretto models set default work-reviewer        # back to the session's model

And how hard it thinks

The model is the tier. Effort is the depth inside it — how often and how deeply the model reasons on each step. They are two keys, and either moves without the other: keeping an agent on Opus while its effort drops is the case the option exists for.

libretto models effort xhigh review-lens-security   # deeper, on the lens that needs it
libretto models effort low   review-lens-design     # same model, cheaper reasoning
libretto models effort default work-reviewer        # back to the session's effort

Haiku has no effort levels, so a level written there would do nothing. It is refused rather than written and ignored, and moving an agent onto Haiku clears any level it declared — the listing says so on the row it happened to.

And which levels an alias has depends on where your requests go. opus and sonnet do not name the same model on every provider — on Amazon Bedrock sonnet is Sonnet 4.5, which has no effort at all, and on Microsoft Foundry opus is Opus 4.6, which has four of the five. So the alias is resolved from your environment first, and the listing names the provider it resolved for:

$ CLAUDE_CODE_USE_BEDROCK=1 libretto models
  ...
  sonnet     Sonnet 4.5   the everyday working model  — no effort levels
  opus       Opus 5       everyday complex work; Max plans, metered on Pro
  fable      Fable 5      the hardest, longest-running work; priciest per token
  resolved for Amazon Bedrock

That is os.Getenv on variables Claude Code already documents — no request, no credential, and never a variable that holds a secret. An explicit ANTHROPIC_DEFAULT_SONNET_MODEL pin takes precedence over the provider default, and anything this build cannot resolve is treated as capable rather than refused.

The panel has both behind its models row: mark agents with space, or all of them with a, then m for the model and e for the effort.

models acts on the agents of the destination you name — ~/.claude/agents under --global, <cwd>/.claude/agents under --project. Every agent there is listed and editable, not just the ones this repository ships.

The values are aliases. The listing shows what each one resolves to, and when that was last checked:

models available (aliases; versions as of 2026-08):
  default                 the session's model — whatever you are running
  haiku      Haiku 4.5    cheapest; fine for pattern-matching over prose  — no effort levels
  sonnet     Sonnet 5     the everyday working model
  opus       Opus 5       everyday complex work; Max plans, metered on Pro
  fable      Fable 5      the hardest, longest-running work; priciest per token
  resolved for the Anthropic API

effort available (weakest first; as of 2026-08; `models effort <level> <agent>…`):
  default    no key at all: whatever the session runs at
  low        short, scoped work that is not intelligence-sensitive
  medium     cost-sensitive work that can trade off some intelligence
  high       the balance point — and the host's own default
  xhigh      deeper reasoning at higher spend
  max        the deepest; prone to overthinking. Measure before adopting

Where it installs

Two axes, combinable — the tool and the scope:

Tool	--global (default)	--project
--claude (default)	~/.claude	<this directory>/.claude
--codex — skills only	~/.agents	<this directory>/.agents
--opencode — skills only	~/.config/opencode	<this directory>/.opencode

So libretto install --codex --project links the skills into this directory's .agents/, and plain libretto install still means what it always did. A project-local install keeps a flow scoped to one repository without editing the configuration every other project shares.

In the panel the two axes stay separate: the strip shows one row per tool under a scope ▸ global label, tab switches the tool and s flips the scope for all rows at once — the active row is gold.

Codex and OpenCode read the same Claude-compatible SKILL.md format, so the skills link unchanged; agents and commands are simply absent from those destinations, not errors. One detail worth knowing: OpenCode also reads ~/.claude/skills and ~/.agents/skills directly, so a claude or codex install already reaches it — the --opencode tool exists for setups that keep OpenCode's own directory as the source of truth.

Two flags on one axis is an error.

The five states

status reports one of these per item, per target:

State	Meaning	Remedy
linked	our symlink, right destination	none
missing	in the repo, absent from the target	install
wrong target	our symlink, wrong destination	install repoints it
conflict	something foreign in the way	none — reported, never touched
stale	our symlink with no item behind it	prune

Environment

CLAUDE_HOME	Claude Code's root instead of ~/.claude. What makes the test suite safe.
AGENTS_HOME	the Codex destination's root instead of ~/.agents. Libretto-only; Codex does not read it.
OPENCODE_HOME	the OpenCode destination's root instead of ~/.config/opencode. Libretto-only.
LIBRETTO_ROOT	the repo location, instead of deriving it from the binary
LIBRETTO_ASCII=safe	swap the clef's quadrant glyphs for half blocks
LIBRETTO_THEME	dark or light, instead of detecting
COLUMNS	layout width when stdout is not a terminal

There is no configuration file. A value that never varies is not configuration.

Learn more

docs/FLOW.md	the eight phases, where the flow stops and why only there
docs/DESIGN.md	why it is built this way — symlinks, no --force, the palette
.agents/specs/	the specification, one directory per capability
AGENTS.md	working on this repository: the gates, the commit rules, versioning
THIRD-PARTY.md	the vendored skills, their licences and versions

Standing on other people's work

Seven skills ship with this repository, so the flow works on a machine that has nothing else installed. Copied unmodified, licence and version recorded in THIRD-PARTY.md:

• obra/superpowers — writing-plans, test-driven-development, using-git-worktrees. The flow's own skills are thin because they delegate to these, and a thin skill whose delegate is missing is not thin, it is broken.
• DietrichGebert/ponytail — ponytail, ponytail-debt. Decides how much gets built: the ladder runs from does this need to exist at all? down to only then, the minimum that works, and it carries the list of things that are never trimmed: trust boundaries, data loss, security, accessibility. The flow invokes it in phase 2, on requirements, because that is where removing work is cheapest.
• JuliusBrussee/caveman — caveman, caveman-commit. Decides how much gets said. Compresses prose; ponytail compresses what gets built. No overlap.

Shipped is not required: nothing fails without them, and they prune like any other item. Only what the flow calls by name is vendored — the rest of both plugins, including always-on hook mode, stays with the upstream plugins, and the two coexist by namespace.

Not managed here

CLAUDE.md and settings.json. Other tooling rewrites regions of those files, so they stay hand-managed. Linking them would start a fight this tool cannot win.

Licence

MIT. Vendored items keep their own — see THIRD-PARTY.md.